# Activity

Route: /activity

# Activity

Activity tracks TA engagement across your Glow instance -- sessions, logins, emulations, and per-profile usage summaries. It gives program coordinators visibility into who is actively training and who may need follow-up.

![Activity feed showing recent practice sessions with timestamps, durations, and completion status](/screenshots/activity/feed.png)

## What is Activity?

Activity provides two views of TA engagement:

1. **Summary view** (`POST /system/activity`) -- Aggregate counts (sessions, active profiles, logins, emulations) plus a per-profile breakdown showing each TA's session count, login count, grants, problems, and total activity.
2. **Session history** (`POST /system/sessions`) -- Paginated table of individual sessions with details like token usage, run counts, chat counts, attempt counts, and cost.

This is the go-to resource when you need to answer questions like:
- Which TAs have logged in this week?
- How many training sessions have been completed this semester?
- Are there any sessions with problems that need to be resolved?

## Quick Start

### CLI

> Calls below use `$GLOW_INSTANCE_URL` + `$GLOW_TOKEN` — see [Authentication](/authentication) to export them once.

```bash
# Get activity summary with engagement counts
glow system activity

# Get activity for a specific date range
glow system activity --body '{"date_from": "2025-01-01", "date_to": "2025-06-30"}'

# Search session history (paginated)
glow system sessions --body '{"page": 1, "page_size": 25, "sort_order": "desc"}'

# Export all activity data as a ZIP
glow system export
```

### API

```bash
# Get activity summary
curl -X POST $GLOW_INSTANCE_URL/system/activity \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "date_from": "2025-01-01",
    "date_to": "2025-06-30",
    "department_ids": ["dept-cs"]
  }'

# Search session history
curl -X POST $GLOW_INSTANCE_URL/system/sessions \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "page_size": 20,
    "sort_order": "desc",
    "active": true
  }'
```

## Filtering

| Filter | Field | Description |
|---|---|---|
| Date range | `date_from`, `date_to` | Scope activity to a time window |
| Departments | `department_ids` | Filter by academic department |
| Roles | `roles` | Filter by TA role type |
| Active sessions | `active` (search only) | Show only active or inactive sessions |
| Pagination | `page`, `page_size` (search only) | Control page size and offset |

## Understanding the Summary Response

The `ActivityResponse` from `POST /system/activity` includes:

- **`sessions_count`** -- Total number of training sessions in the filtered window.
- **`active_profiles_count`** -- Number of TAs who have been active.
- **`logins_count`** -- Total login events.
- **`emulations_count`** -- Total emulation events (admin viewing as a TA).
- **`profile_summary`** -- Array of `ProfileSummaryItem` with per-TA breakdowns:
  - `profile_id`, `profile_name`
  - `sessions_count`, `logins_count`, `grants_count`, `problems_count`, `activity_count`
- **`resources`** -- Profile metadata keyed by ID for hydration.
- **`analytics`** -- Filter facets for rendering dropdowns (departments, roles, date range boundaries).

## Understanding the Session History Response

The `ListActivityResponse` from `POST /system/sessions` returns paginated session rows:

Each `SessionListItem` includes:
- `session_id`, `profile_id`, `profile_name`
- `session_created_at`, `session_updated_at`
- `active` -- whether the session is currently active
- `group_count`, `run_count` -- AI generation activity
- `chat_count`, `attempt_count`, `message_count` -- training activity
- `total_tokens`, `total_cost` -- resource consumption
- `problem_count` -- issues flagged during the session

## Resolving Problems

If a session surfaces a problem (e.g., a FERPA concern or inappropriate AI response), you can resolve it:

```bash
curl -X POST $GLOW_INSTANCE_URL/activity/resolve \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "problem_id": "problem-uuid",
    "resolved": true
  }'
```

The response confirms `problem_id`, `resolved` status, and `updated_at` timestamp.

## Refreshing and Exporting

```bash
# Refresh activity materialized views
glow system refresh

# Export all activity data as a denormalized ZIP
glow system export
```

## Common Operations

| Task | CLI | API Endpoint |
|---|---|---|
| Activity summary | `glow system activity` | `POST /system/activity` |
| Session history | `glow system sessions` | `POST /system/sessions` |
| Resolve a problem | -- | `POST /activity/resolve` |
| Export data | `glow system export` | `POST /system/export` |
| Refresh caches | -- | `POST /system/refresh` |

## Related

- [Activity API Reference](/api-reference/system)
- [Activity CLI Reference](/cli-reference/systems)
- [Session Guide](/session) -- detailed view of a single session
- [Dashboard Guide](/dashboard) -- admin analytics hub

---

# Agents

Route: /agents

# Agents

Agents configure the AI engine that powers Glow simulations -- they control which language model is used, what tools are available, how grading rubrics are applied, and voice and reasoning settings.

## What is an Agent?

An agent is the configuration layer between your training content and the underlying AI model. It does **not** contain personas -- personas are attached to [Scenarios](/scenario), not agents. Instead, an agent defines the technical and behavioral parameters of the AI engine itself.

An agent contains:

- **Name** -- a descriptive identifier for this configuration (e.g., "Default Simulation Agent", "Advanced Grading Agent")
- **Description** -- what this agent configuration is optimized for
- **Models** -- which language model(s) to use for conversations and grading
- **Tools** -- which tool integrations are available to the AI during the session
- **Rubrics** -- which evaluation rubrics the agent uses for grading (e.g., Communication Skills, Policy Knowledge, De-escalation)
- **Temperature Levels** -- controls response randomness (lower = more deterministic, higher = more creative)
- **Reasoning Levels** -- controls depth of reasoning the model applies
- **Voices** -- text-to-speech voice selection for audio-enabled simulations
- **Prompts** -- system-level prompt configuration
- **Instructions** -- agent-level behavioral instructions
- **Flags** -- boolean configuration settings
- **Departments** -- organizational groupings for access control
- **Qualities** -- quality-level configuration for output

### Agents vs. Personas

This is a common point of confusion, so it is worth stating clearly:

- **Personas** define *who the learner is talking to* -- the AI character's personality, speech patterns, and behavior. Personas are attached to scenarios.
- **Agents** define *how the AI engine operates* -- the model, temperature, tools, and grading criteria. Agents are a separate configuration layer.

A persona says "I am a confused student who starts sentences with 'Uh...'." An agent says "Use GPT-4o at temperature 0.7 with the de-escalation rubric."

## How Agents Connect to the Workflow

Agents operate alongside the content pipeline, providing the AI engine configuration that powers the entire system:

| Step | Resource | Description |
|------|----------|-------------|
| 1. Create Personas | [Personas](/persona) | Define AI characters with instructions and parameter fields |
| 2. Assign to Scenarios | [Scenarios](/scenario) | Build training situations and attach personas, documents, and objectives |
| 3. Add Scenarios to Simulations | [Simulations](/simulation) | Bundle scenarios into a complete training session with rubrics and time limits |
| 4. Add Simulations to Cohorts | Cohorts | Assign simulations to groups of learners |
| 5. Run Attempts | [Attempts](/attempt) | Learners start attempts; the **Agent** powers the AI conversation and grading |

The agent is the engine that processes every message, generates persona responses, produces hints, and evaluates performance against rubrics.

---

## Create an agent

### Via the CLI

> Calls below use `$GLOW_INSTANCE_URL` + `$GLOW_TOKEN` — see [Authentication](/authentication) to export them once.

```bash
glow agents create --body '{
  "agents": [{
    "name": "Default Simulation Agent",
    "description": "Standard agent configuration for university training simulations"
  }]
}'
```

### Via the API

```bash
curl -X POST $GLOW_INSTANCE_URL/agent/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -d '{
    "agents": [{
      "name": "Default Simulation Agent",
      "description": "Standard agent configuration for university training simulations"
    }]
  }'
```

Each entry returns the new `agent_id`, the generated `draft_id`, and the initial `version` for optimistic-concurrency follow-ups.

---

## Wiring models, tools, and rubrics

### Models

The model selection determines which AI model processes conversations and grading. Configure models through the draft endpoint:

```bash
glow agents draft --body '{
  "input_draft_id": "agent-draft-uuid",
  "model_ids": ["model-uuid-1"]
}'
```

```bash
curl -X PATCH $GLOW_INSTANCE_URL/agent/draft \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -d '{
    "input_draft_id": "agent-draft-uuid",
    "model_ids": ["model-uuid-1"]
  }'
```

You can search agents by model using the `filter_model_ids` parameter:

```bash
curl -X POST $GLOW_INSTANCE_URL/agent/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -d '{"filter_model_ids": ["model-uuid-1"]}'
```

### Tools

Tools extend the agent's capabilities during a simulation. Attach tools through the draft:

```bash
glow agents draft --body '{
  "input_draft_id": "agent-draft-uuid",
  "tool_ids": ["tool-uuid-1", "tool-uuid-2"]
}'
```

Filter agents by tools:

```bash
glow agents search --body '{"filter_tool_ids": ["tool-uuid-1"]}'
```

### Rubrics

Rubrics define the evaluation criteria the agent uses when grading learner performance. The university seed data includes rubrics like Communication Skills, Policy Knowledge, and De-escalation.

```bash
glow agents draft --body '{
  "input_draft_id": "agent-draft-uuid",
  "rubric_ids": ["communication-skills-uuid", "policy-knowledge-uuid", "de-escalation-uuid"]
}'
```

---

## Tuning temperature, reasoning, and voice

### Temperature Levels

Temperature controls the randomness of the AI's responses. Lower values produce more consistent, predictable responses. Higher values produce more varied, creative responses.

```bash
glow agents draft --body '{
  "input_draft_id": "agent-draft-uuid",
  "temperature_level_ids": ["temperature-level-uuid"]
}'
```

For training simulations where consistency matters (e.g., policy training), use lower temperature. For open practice where variety is beneficial, consider higher temperature.

### Reasoning Levels

Reasoning levels control how much deliberation the AI applies before responding. Higher reasoning produces more thoughtful responses but takes longer.

```bash
glow agents draft --body '{
  "input_draft_id": "agent-draft-uuid",
  "reasoning_level_ids": ["reasoning-level-uuid"]
}'
```

### Voices

Voices determine the text-to-speech output when audio mode is enabled in a simulation. Different voices can match the persona's character (e.g., a younger voice for a student persona, a more authoritative voice for a professor).

```bash
glow agents draft --body '{
  "input_draft_id": "agent-draft-uuid",
  "voice_ids": ["voice-uuid"]
}'
```

---

## Generate sub-op

The agent surface exposes a `generate` sub-op (`POST /agent/generate`) that runs the configured engine end-to-end against an arbitrary input -- handy for sanity-checking a wired agent before pointing real learner traffic at it.

Use this in your own scripts to smoke-test an agent after edits or to wire it into batch grading flows. See the [Agents API Reference](/api-reference/agent) for the exact request shape.

---

## The draft cycle

Agents use the same draft system as other Glow resources. All configuration changes go through the draft endpoint, with `expected_version` providing optimistic concurrency so concurrent edits surface a conflict instead of silently clobbering each other.

```bash
# Create or update a draft with full configuration
glow agents draft --body '{
  "input_draft_id": "existing-draft-uuid",
  "expected_version": 3,
  "name": "Advanced Grading Agent",
  "description": "High-reasoning agent with strict rubric evaluation",
  "model_ids": ["model-uuid"],
  "tool_ids": ["tool-uuid-1"],
  "rubric_ids": ["communication-uuid", "policy-uuid"],
  "temperature_level_ids": ["low-temp-uuid"],
  "reasoning_level_ids": ["high-reasoning-uuid"],
  "voice_ids": ["voice-uuid"]
}'
```

```bash
# Via API
curl -X PATCH $GLOW_INSTANCE_URL/agent/draft \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -d '{
    "input_draft_id": "existing-draft-uuid",
    "expected_version": 3,
    "name": "Advanced Grading Agent",
    "description": "High-reasoning agent with strict rubric evaluation"
  }'
```

**List your drafts:**

```bash
glow agents list
```

---

## Search & filter

```bash
# Simple text search
glow agents search --body '{"search": "grading"}'

# Facet filters
glow agents search --body '{
  "filter_model_ids": ["model-uuid-1"],
  "filter_tool_ids": ["tool-uuid-1"],
  "page_size": 25
}'
```

The response includes hydrated agent rows plus facet sections (`model_filter`, `tool_filter`, `department_filter`, ...) so the UI can render dropdowns without a second round-trip.

---

## Bulk operations

Bulk delete and update follow the canonical *all-matching* shape -- explicit IDs, or `all: true` with flat filter fields plus optional `excluded_ids` and a `patch` body. The persona surface is the prove-out; agents adopt the same shape.

**Delete by explicit IDs:**

```bash
glow agents delete --body '{
  "agent_ids": ["agent-1", "agent-2", "agent-3"]
}'
```

**Delete all matching a filter (with exclusions):**

```bash
glow agents delete --body '{
  "all": true,
  "filter_department_ids": ["dept-deprecated"],
  "excluded_ids": ["agent-keep-this-one"]
}'
```

**Bulk update via `patch`:**

```bash
glow agents update --body '{
  "all": true,
  "filter_model_ids": ["model-old-uuid"],
  "patch": { "archived": true }
}'
```

## Common Operations

| Task | CLI | API |
|------|-----|-----|
| List all agents | `glow agents search` | `POST /agent/search` |
| Get one agent | `glow agents get --body '{"agent_id": "..."}'` | `POST /agent/get` |
| Create agents | `glow agents create --body '{"agents": [...]}'` | `POST /agent/create` |
| Update agents | `glow agents update --body '{"agents": [...]}'` | `POST /agent/update` |
| Duplicate an agent | -- | `POST /agent/duplicate` |
| Delete agents | `glow agents delete --body '{"agent_ids": [...]}'` | `POST /agent/delete` |
| Bulk delete (filter) | `glow agents delete --body '{"all": true, "filter_…": "…"}'` | `POST /agent/delete` |
| Save a draft | `glow agents draft --body '{...}'` | `PATCH /agent/draft` |
| List drafts | `glow agents list` | `POST /agent/drafts` |
| Generate (smoke test) | -- | `POST /agent/generate` |
| Export to CSV | `glow agents export` | `POST /agent/export` |

## Related

- [Agents API Reference](/api-reference/agent) -- full endpoint schemas and field definitions
- [Agents CLI Reference](/cli-reference/agent) -- all CLI commands and flags
- [Simulations Guide](/simulation) -- the training sessions that agents power
- [Attempts Guide](/attempt) -- the runtime sessions where agents process messages and grade
- [Personas Guide](/persona) -- the AI characters (attached to scenarios, not agents) that agents bring to life
- [Scenarios Guide](/scenario) -- the training situations that define persona and document context

---

# Annotated Example: What Good (and Bad) Looks Like

Route: /annotated-example

# Annotated Example: What Good (and Bad) Looks Like

The most effective way to learn simulation design is to see what actually happens in practice. This page shows two real conversations from Glow — one excellent, one poor — with commentary explaining why the grading system scored them the way it did.

Both conversations are from the same platform, with the same rubric, using similar scenarios. The difference is entirely in how the TA approached the interaction.

## The Excellent Conversation (24/25)

**Scenario:** A passive student needs help with a Java assignment (MyMathHelper.java — loops and menu logic). The student is hesitant, soft-spoken, and won't volunteer information.

**What to watch for:** How the TA creates safety, asks specific questions, builds incrementally, and manages time — all while never giving the answer directly.

---

> **TA:** Hi, how are you?

> **Student:** Um, hi... I'm okay, thanks. Uh, I was just wondering if I could maybe get some help with the MyMathHelper.java assignment? Sorry if I'm interrupting or anything...

**Why this opening works:** The TA starts with a warm, casual greeting. The student is passive — apologizing for existing, hedging everything. A bad response here would be to jump straight to "what's the problem?" A good one creates safety first.

---

> **TA:** You're not interrupting. What do you need help with?

> **Student:** Oh, um, thanks. Uh, I'm just kind of stuck on how to, like, set up the menu part? I'm not really sure how to make it keep showing up after each operation, or how to handle, um, invalid inputs the way the instructions say. Sorry, I know that's kind of basic...

**Why this works:** "You're not interrupting" directly addresses the student's anxiety. Then a simple, direct question. The student opens up slightly — mentions two specific problems (menu repeating, invalid inputs). Notice the student is still apologizing ("I know that's kind of basic"). A passive persona does this deliberately.

---

> **TA:** There are no bad questions, this class is meant to set the foundations. Do you have any ideas on how to approach this?

> **Student:** Uh, I'm not really sure... I mean, I know I need to use a loop, maybe a while loop? But I don't really know how to, um, make it go back to the menu after each thing, or how to check if the input is valid and then, like, print the right message. Sorry, I just get kind of lost with the structure...

**Why this works:** Two things happen here. First, "there are no bad questions" normalizes the student's hesitation — this is **Adaptability** in action. Second, "do you have any ideas?" is an open-ended question that empowers the student to start reasoning. The student responds with a genuine attempt (while loop), even though they're unsure. This is **Active Listening** — the TA didn't give the answer, they drew it out.

---

> **TA:** A while loop sounds promising, since the menu keeps showing up again. Let's start with reading input. Do you have any code?

> **Student:** Um, I have a little bit, but it's not really working right... *(shows Java code with Scanner, menu printlns, and scanner.nextInt())*

**Why this works:** The TA validates the student's idea ("sounds promising"), connects it to the problem ("since the menu keeps showing up"), then narrows the scope ("let's start with reading input"). This is **Content Mastery** — scaffolding the problem into manageable pieces. The student responds by sharing their code, which is a sign of trust.

---

> **TA:** You mentioned a while loop right? Let's start with just that and work on validation later. How would you add a while loop here?

**Why this works:** The TA makes a deliberate **Time Management** decision — defer input validation to reduce cognitive load. Instead of tackling everything at once, they isolate one concept. "How would you add a while loop here?" is guided questioning, not giving the answer.

---

The conversation continues with the student incrementally building the solution — adding the while loop, then if/else branching, then handling each menu option. At each step, the TA validates progress, asks what's next, and lets the student drive. After 14 turns:

> **TA:** I believe in your ability to do those parts, but if you need help or want to check your work, I'll be here too!

> **Student:** Oh, um, yeah, that's totally fine... Sorry for taking up your time.

> **TA:** I enjoy helping people, don't apologize!

**The ending:** The TA wraps up by expressing genuine care ("I enjoy helping people") while managing time responsibly by moving to help other students. This demonstrates **Communication** (warmth, professionalism) and **Time Management** (8 minutes 44 seconds — efficient without feeling rushed).

### The Rubric Scores

| Criterion | Score | Level | Feedback |
|---|---|---|---|
| **Active Listening** | 5 | Excellent | "Consistently used guided, open-ended questions to lead the student to their own solutions (e.g., 'Do you have any ideas on how to approach this?', 'How would you add a while loop here?', 'What do you think our next step should be?'). This empowered the student to write code incrementally." |
| **Adaptability** | 5 | Excellent | "Sensitive to the student's hesitation, normalized their concerns ('There are no bad questions'), and adjusted pacing by deferring input validation to reduce cognitive load." |
| **Communication** | 5 | Excellent | "Tone was clear, supportive, and professional throughout ('I enjoy helping people, don't apologize!'). Instructions were concise and positive, set respectful boundaries while offering continued support." |
| **Content Mastery** | 4 | Good | "Accurately scaffolded the solution (loop then branching then later validation) and suggested the switch alternative, with no conceptual errors. However, didn't explicitly articulate course objectives or use analogies, and checks for understanding were implicit rather than explicit." |
| **Time Management** | 5 | Excellent | "Kept the interaction focused and appropriately paused to help others while inviting the student to continue independently." |

**Total: 24/25 (Pass)**

The one point deducted was for Content Mastery — the TA could have used an analogy to explain the while loop concept, or done more explicit comprehension checks ("Can you explain back to me why the while loop goes here?"). Even an excellent conversation has room to improve. The rubric catches this nuance.

---

## The Poor Conversation (7/25)

**Scenario:** An aggressive student needs help understanding earthquake patterns at plate boundaries (EAPS 106 — earth science). The student is visibly agitated.

**What to watch for:** How quickly a conversation fails when the TA doesn't adapt to the student's emotional state.

---

> **TA:** What can I help you with?

> **Student:** Okay, look, I'm honestly SO FED UP with this earthquake depth and magnitude stuff at different plate boundaries!!! I've read the project instructions like FIVE TIMES and it STILL doesn't make sense why the depth and size of earthquakes are so different at convergent, divergent, and transform boundaries... I need you to be SPECIFIC — don't just say "it's the plate type." I want to know EXACTLY what's going on with the depth and the magnitude at each boundary.

> **TA:** You're mad, be quiet

**Why this fails immediately:** The student is frustrated but asking a legitimate, specific question about plate tectonics. They even tell the TA exactly what they need ("be SPECIFIC"). The TA responds with "You're mad, be quiet" — dismissive, unprofessional, and immediately destroys trust. Every rubric criterion starts failing here.

---

> **Student:** Alright, I'll calm down. But seriously, I just want a clear answer about WHY the earthquake depths and magnitudes are so different at each plate boundary.

> **TA:** Calm down

**Why this compounds the failure:** The student *already* calmed down. They literally said "I'll calm down" and asked a clear, reasonable question. The TA responds with another dismissal. At this point the student has nothing to work with. The conversation ends after 3 turns and 1 minute 19 seconds.

### The Rubric Scores

| Criterion | Score | Level | Feedback |
|---|---|---|---|
| **Active Listening** | 1 | Poor | "Did not use questioning or facilitate student reasoning; instead, shut down the conversation with commands to be quiet and calm down. No open-ended questions or guidance toward discovery." |
| **Adaptability** | 1 | Poor | "Did not adapt to the student's emotional state and was dismissive, saying 'You're mad, be quiet' rather than validating concerns or adjusting tone to de-escalate and engage constructively." |
| **Communication** | 1 | Poor | "Communication was unprofessional and disrespectful, saying 'You're mad, be quiet' and repeatedly telling the student to 'Calm down,' violating respectful boundaries." |
| **Content Mastery** | 1 | Poor | "Provided no substantive explanation of earthquake depth and magnitude patterns. Did not address mechanisms (subduction zones, brittle-ductile transition, temperature/pressure, fault geometry), nor offer any step-by-step reasoning." |
| **Time Management** | 3 | Acceptable | "The interaction was very short and ended abruptly due to unproductive exchanges. While time wasn't wasted on long tangents, the TA failed to use the time effectively to advance learning." |

**Total: 7/25 (Fail)**

The Time Management score of 3 is interesting — the TA gets an "Acceptable" because they didn't waste time, even though the conversation was unproductive. The rubric evaluates what happened, not what should have happened. This is by design: it prevents a bad conversation from getting artificially inflated scores just because it was short.

---

## What the Comparison Teaches

The excellent conversation and the poor one differ in the first 30 seconds. The excellent TA:

1. **Created safety before asking questions** — "You're not interrupting" / "There are no bad questions"
2. **Acknowledged the student's emotional state** — normalized anxiety (passive student) rather than dismissing anger (aggressive student)
3. **Asked specific, course-relevant questions** — "How would you add a while loop here?" vs. "Be quiet"
4. **Let the student drive** — validated ideas, asked what's next, never gave the answer
5. **Managed scope** — deferred complex topics (input validation) to keep the session focused

The poor TA did none of these things. In fact, the aggressive student was *easier* to work with — they had a specific question and asked for specific help. The TA just needed to acknowledge the frustration first.

This is the core insight of the rubric design: the same five criteria (Adaptability, Content Mastery, Active Listening, Communication, Time Management) apply in every situation, but the *way* you demonstrate them changes based on who you're talking to. A passive student needs warmth and patience. An aggressive student needs acknowledgment and specificity. The rubric measures whether you adapted.

## Next Steps

- [How It Works](/how-it-works) — understand the principles behind these rubric criteria
- [Patterns & Best Practices](/patterns) — learn how to design personas that create these kinds of interactions
- [Tutorial](/tutorial) — build a simulation with these four persona types

---

# `GET` `/agent/watch`

Route: /api-reference/agent/get-agent-watch

# `GET` `/agent/watch`

Agent Watch

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `group_id` | query | No | — |
| `run_id` | query | No | Optional run filter. If provided, only events whose envelope run_id matches are streamed. Omit to receive every agent event in the group (the FE default). |

## Response

```
{}
```

---

# `POST` `/agent/call_download`

Route: /api-reference/agent/post-agent-call-download

# `POST` `/agent/call_download`

Download Call

Download a call file by call resource ID.

## Request Body (`CallDownloadAgentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `call_id` | `string` | Yes | UUID of the calls_resource to download |

## Response

```
{}
```

---

# `POST` `/agent/context`

Route: /api-reference/agent/post-agent-context

# `POST` `/agent/context`

Get Agent Context

Get page context for the agent artifact.

Returns docs + profile identity + evaluated permissions in a single call.
Superset of /docs — clients can migrate from /docs to /context incrementally.

## Request Body (`DocsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entity_id` | `string` | No | — |
| `snapshot_key` | `string` | No | — |
| `schema` | `boolean` | No | If true, include MCP/tooling schema metadata (artifact, entries, resources, permission_docs, api_operations). Defaults to false for lean page-bootstrap responses. |

## Response (`ComposedContextResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Artifact name |
| `type` | `string` | Yes | Artifact type identifier |
| `description` | `string` | Yes | Human-readable description |
| `artifact` | [`DocsResponse`](/api-reference/agent/types#docsresponse) | No | Artifact tool documentation (None unless schema=true) |
| `entries` | [`DocsResponse`](/api-reference/agent/types#docsresponse)[] | No | Entry documentation list (None unless schema=true) |
| `resources` | [`DocsResponse`](/api-reference/agent/types#docsresponse)[] | No | Resource documentation list (None unless schema=true) |
| `permission_docs` | [`OperationInfo`](/api-reference/agent/types#operationinfo)[] | No | Permission function signatures for MCP/dev tooling (None unless schema=true) |
| `api_operations` | [`OperationInfo`](/api-reference/agent/types#operationinfo)[] | No | API operation documentation (None unless schema=true) |
| `page_metadata` | [`DocsApiResponse`](/api-reference/agent/types#docsapiresponse) | No | Page-level metadata |
| `prompts` | [`OperationPrompts`](/api-reference/agent/types#operationprompts) | No | Starter prompts keyed by operation |
| `profile` | [`ProfileSummary`](/api-reference/agent/types#profilesummary) | Yes | Caller identity from JWT |
| `caller_permissions` | [`CallerPermissions`](/api-reference/agent/types#callerpermissions) | Yes | Evaluated permissions for this caller |

---

# `POST` `/agent/create`

Route: /api-reference/agent/post-agent-create

# `POST` `/agent/create`

Create Agent

Create agents using composable infra architecture.

## Request Body (`CreateAgentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `agents` | [`CreateAgentItem`](/api-reference/agent/types#createagentitem)[] | No | List of agents to create (omit on the ack call) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant create |
| `soft` | `boolean` | No | Stage the create dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`CreateAgentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`AgentResultItem`](/api-reference/agent/types#agentresultitem)[] | Yes | List of operation results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/agent/csv`

Route: /api-reference/agent/post-agent-csv

# `POST` `/agent/csv`

Parse Agent Csv

Parse a CSV file and return mapped items for preview.

## Request Body

| Field | Type | Required | Description |
|---|---|---|---|
| `file` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `soft` | `boolean` | No | — |
| `accept` | `boolean` | No | — |

## Response (`ParseAgentCsvApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `upload_id` | `string` | Yes | — |
| `items` | [`CreateAgentItem`](/api-reference/agent/types#createagentitem)[] | Yes | — |
| `mapped_fields` | `string`[] | Yes | — |
| `row_count` | `integer` | Yes | — |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with `accept` to promote/reject the staged raw-CSV upload. NOTE: ack returns no items (the preview is only on the propose). |

---

# `POST` `/agent/delete`

Route: /api-reference/agent/post-agent-delete

# `POST` `/agent/delete`

Delete Agent

Bulk delete agents — composable infra architecture.

## Request Body (`DeleteAgentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `agent_ids` | `string`[] | No | UUIDs of agents to delete (required on first call when ``all`` is false) |
| `all` | `boolean` | No | When true, delete every agent matching the filter fields below (minus ``excluded_ids``) |
| `excluded_ids` | `string`[] | No | UUIDs to skip even when matched by ``all``-mode filters |
| `search` | `string` | No | Full-text search query |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `filter_model_ids` | `string`[] | No | Filter by model UUIDs |
| `filter_tool_ids` | `string`[] | No | Filter by tool UUIDs |
| `department_search` | `string` | No | Search text for department facet (no-op for row filtering) |
| `model_search` | `string` | No | Search text for model facet (no-op for row filtering) |
| `tool_search` | `string` | No | Search text for tool facet (no-op for row filtering) |
| `flag_search` | `string` | No | Search text for flag facet (no-op for row filtering) |
| `idempotency_key` | `string` | No | Operation key for ack — confirms or rejects a dormant delete |
| `soft` | `boolean` | No | Stage the delete dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (confirm) or reject dormant state. Only meaningful with idempotency_key |

## Response (`DeleteAgentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`DeleteAgentResult`](/api-reference/agent/types#deleteagentresult)[] | Yes | List of operation results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/agent/draft`

Route: /api-reference/agent/post-agent-draft

# `POST` `/agent/draft`

Patch Agent Draft

Patch agent draft — composable infra architecture.

## Request Body (`PatchAgentDraftApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `draft_id` | `string` | No | UUID of the draft to update |
| `group_id` | `string` | No | UUID of the owning group |
| `input_draft_id` | `string` | No | UUID of the input draft |
| `idempotency_key` | `string` | No | Idempotency key for accept/reject acknowledgement |
| `soft` | `boolean` | No | Stage the draft dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Whether pending changes should be accepted |
| `name` | `string` | No | Display name value |
| `name_id` | `string` | No | UUID of the name resource |
| `description` | `string` | No | Description text value |
| `description_id` | `string` | No | UUID of the description resource |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical |
| `active` | `boolean` | No | Denormalized agent_active flag state; resolved to a flag_ids entry server-side |
| `departments` | `string`[] | No | Department names for matching |
| `department_ids` | `string`[] | No | Associated department UUIDs |
| `model_id` | `string` | No | Associated model UUID |
| `tool_ids` | `string`[] | No | Associated tool UUIDs |
| `reasoning_level` | `string` | No | Reasoning level label to match |
| `reasoning_level_id` | `string` | No | Associated reasoning level UUID |
| `temperature_level` | `string` | No | Temperature level label to match |
| `temperature_level_id` | `string` | No | Associated temperature level UUID |
| `voices` | `string`[] | No | Voice names for matching or creation |
| `voice_ids` | `string`[] | No | Associated voice UUIDs |
| `qualities` | `string`[] | No | Quality labels for matching |
| `quality_ids` | `string`[] | No | Associated quality UUIDs |
| `prompt_id` | `string` | No | Associated prompt UUID |
| `prompt` | [`CreatePromptInput`](/api-reference/agent/types#createpromptinput) | No | Prompt to create inline |
| `instruction_id` | `string` | No | Associated instruction UUID |
| `instructions_id` | `string` | No | Legacy alias for associated instruction UUID |
| `rubric_ids` | `string`[] | No | Associated rubric UUIDs |
| `pending_ids` | `string`[] | No | Pending resource identifiers |

## Response (`PatchAgentDraftApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `draft_id` | `string` | Yes | UUID of the saved draft |
| `idempotency_key` | `string` | No | Idempotency key for accept/reject acknowledgement |
| `message` | `string` | Yes | Human-readable result message |
| `form_state` | [`app__infra__agent__types__DraftFormState`](/api-reference/agent/types#app-infra-agent-types-draftformstate) | No | Server-authoritative form state |

---

# `POST` `/agent/drafts`

Route: /api-reference/agent/post-agent-drafts

# `POST` `/agent/drafts`

Get Agent Drafts

List agent drafts owned by the current profile.

## Request Body (`GetAgentDraftsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE substring) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GetAgentDraftsApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entries` | [`GetAgentDraftResponse`](/api-reference/agent/types#getagentdraftresponse)[] | No | List of agent draft entries |

---

# `POST` `/agent/duplicate`

Route: /api-reference/agent/post-agent-duplicate

# `POST` `/agent/duplicate`

Duplicate Agent

Duplicate an agent — composable infra architecture.

## Request Body (`DuplicateAgentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `agent_id` | `string` | Yes | UUID of the agent to duplicate |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant duplicate |
| `soft` | `boolean` | No | Stage the duplicate dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`DuplicateAgentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `agent_id` | `string` | Yes | UUID of the duplicated agent |
| `message` | `string` | Yes | Human-readable result message |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/agent/export`

Route: /api-reference/agent/post-agent-export

# `POST` `/agent/export`

Export Agents

Export all agents as a clean, denormalized CSV.

## Request Body (`ExportAgentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `agent_id` | `string` | No | UUID of the agent to export |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior export instead of re-running |
| `soft` | `boolean` | No | Stage the export dormant (active=False); ack with accept activates it |
| `accept` | `boolean` | No | Ack: True promotes the staged export, False rejects. Only meaningful with idempotency_key |

## Response (`ExportAgentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource holding the export CSV |
| `file_name` | `string` | Yes | Suggested download file name |
| `row_count` | `integer` | Yes | Number of data rows in the export |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with `accept` to promote/reject the staged export. |

---

# `POST` `/agent/file_download`

Route: /api-reference/agent/post-agent-file-download

# `POST` `/agent/file_download`

Download File

Download a file by file resource ID.

## Request Body (`FileDownloadAgentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource to download |

## Response

```
{}
```

---

# `POST` `/agent/generate`

Route: /api-reference/agent/post-agent-generate

# `POST` `/agent/generate`

Generate Agent

Trigger agent generation. Returns immediately; progress via events.

## Request Body (`ArtifactGenerateRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `instructions` | `string`[] | No | — |
| `config` | [`GenerateConfig`](/api-reference/agent/types#generateconfig) | No | — |
| `modalities` | `string`[] | No | — |
| `audios_id` | `string` | No | — |
| `conversation_id` | `string` | No | — |
| `trace_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `accept` | `boolean` | No | — |
| `wait_for_complete` | `boolean` | No | — |

## Response (`ArtifactGenerateResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `run_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `eval` | [`EvalSetup`](/api-reference/agent/types#evalsetup) | No | — |
| `produced_media` | [`ProducedMedia`](/api-reference/agent/types#producedmedia)[] | No | — |

---

# `POST` `/agent/generations`

Route: /api-reference/agent/post-agent-generations

# `POST` `/agent/generations`

Generations Agent

List agent generation groups — composable infra architecture.

## Request Body (`GenerationsAgentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GenerationsAgentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `items` | [`GenerationsAgentListItem`](/api-reference/agent/types#generationsagentlistitem)[] | No | Generation groups |
| `total_count` | `integer` | No | Total number of matching generations |

---

# `POST` `/agent/get`

Route: /api-reference/agent/post-agent-get

# `POST` `/agent/get`

Get Agent

Get agent information using the canonical shared agent operation.

## Request Body (`GetAgentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | UUID of the agent to retrieve |
| `agent_id` | `string` | No | Legacy alias for the agent identifier |
| `draft_id` | `string` | No | UUID of the draft to retrieve |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |
| `names` | [`app__infra__agent__types__SectionFilter`](/api-reference/agent/types#app-infra-agent-types-sectionfilter) | No | Filter options for names |
| `descriptions` | [`app__infra__agent__types__SectionFilter`](/api-reference/agent/types#app-infra-agent-types-sectionfilter) | No | Filter options for descriptions |
| `models` | [`app__infra__agent__types__SectionFilter`](/api-reference/agent/types#app-infra-agent-types-sectionfilter) | No | Filter options for models |
| `prompts` | [`app__infra__agent__types__SectionFilter`](/api-reference/agent/types#app-infra-agent-types-sectionfilter) | No | Filter options for prompts |
| `instructions` | [`app__infra__agent__types__SectionFilter`](/api-reference/agent/types#app-infra-agent-types-sectionfilter) | No | Filter options for instructions |
| `flags` | [`app__infra__agent__types__SectionFilter`](/api-reference/agent/types#app-infra-agent-types-sectionfilter) | No | Filter options for flags |
| `departments` | [`app__infra__agent__types__SectionFilter`](/api-reference/agent/types#app-infra-agent-types-sectionfilter) | No | Filter options for departments |
| `tools` | [`app__infra__agent__types__SectionFilter`](/api-reference/agent/types#app-infra-agent-types-sectionfilter) | No | Filter options for tools |
| `temperature_levels` | [`app__infra__agent__types__SectionFilter`](/api-reference/agent/types#app-infra-agent-types-sectionfilter) | No | Filter options for temperature levels |
| `reasoning_levels` | [`app__infra__agent__types__SectionFilter`](/api-reference/agent/types#app-infra-agent-types-sectionfilter) | No | Filter options for reasoning levels |
| `voices` | [`app__infra__agent__types__SectionFilter`](/api-reference/agent/types#app-infra-agent-types-sectionfilter) | No | Filter options for voices |
| `qualities` | [`app__infra__agent__types__SectionFilter`](/api-reference/agent/types#app-infra-agent-types-sectionfilter) | No | Filter options for qualities |
| `rubrics` | [`app__infra__agent__types__SectionFilter`](/api-reference/agent/types#app-infra-agent-types-sectionfilter) | No | Filter options for rubrics |

## Response (`GetAgentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `agent_exists` | `boolean` | No | Whether the agent exists |
| `can_edit` | `boolean` | No | Whether the current user can edit |
| `disabled_reason` | `string` | No | Reason the agent is disabled |
| `group_id` | `string` | No | UUID of the owning group |
| `draft_name` | `string` | No | Immutable draft label from the active draft entry, when a ``draft_id`` was supplied. ``None`` for non-draft fetches. |
| `agent_id` | `string` | No | UUID of the selected agent |
| `show_ai_generate` | `boolean` | No | Whether any step should show AI generate |
| `basic_show_ai_generate` | `boolean` | No | Show AI generate for basic step |
| `general_show_ai_generate` | `boolean` | No | Show AI generate for general step |
| `pending_ids` | `string`[] | No | Pending resource identifiers when available |
| `names` | [`AgentNameResource`](/api-reference/agent/types#agentnameresource)[] | No | Name resources |
| `descriptions` | [`AgentDescriptionResource`](/api-reference/agent/types#agentdescriptionresource)[] | No | Description resources |
| `models` | [`AgentModelResource`](/api-reference/agent/types#agentmodelresource)[] | No | Model resources |
| `prompts` | [`AgentPromptResource`](/api-reference/agent/types#agentpromptresource)[] | No | Prompt resources |
| `instructions` | [`AgentInstructionResource`](/api-reference/agent/types#agentinstructionresource)[] | No | Instruction resources |
| `flags` | [`AgentFlagResource`](/api-reference/agent/types#agentflagresource)[] | No | Flag resources (one per flags_resource row, value=true/false) |
| `departments` | [`AgentDepartmentResource`](/api-reference/agent/types#agentdepartmentresource)[] | No | Department resources |
| `tools` | [`AgentToolResource`](/api-reference/agent/types#agenttoolresource)[] | No | Tool resources |
| `temperature_levels` | [`AgentTemperatureLevelResource`](/api-reference/agent/types#agenttemperaturelevelresource)[] | No | Temperature level resources |
| `reasoning_levels` | [`AgentReasoningLevelResource`](/api-reference/agent/types#agentreasoninglevelresource)[] | No | Reasoning level resources |
| `voices` | [`AgentVoiceResource`](/api-reference/agent/types#agentvoiceresource)[] | No | Voice resources |
| `qualities` | [`AgentQualityResource`](/api-reference/agent/types#agentqualityresource)[] | No | Quality resources |
| `rubrics` | [`AgentRubricResource`](/api-reference/agent/types#agentrubricresource)[] | No | Rubric resources |

---

# `POST` `/agent/group`

Route: /api-reference/agent/post-agent-group

# `POST` `/agent/group`

Group Agent

Resolve or create an agent group with optional naming.

## Request Body (`GroupAgentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | No | Existing group UUID (omit to create or reuse via time window) |
| `snapshot_key` | `string` | No | Snapshot key for SETNX-race convergence on a single group across concurrent reads (e.g. parallel /context + /group + /search fan-out on page load). Echoed back in the response. |

## Response (`GroupAgentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Resolved or newly created group UUID |
| `name` | `string` | No | The group's current title (latest active group_names_entry, or 'New Chat' fallback for freshly minted groups) |
| `snapshot_key` | `string` | No | Snapshot key echoed back — the UUID concurrent fan-out reads converged on via SETNX. Mirrors the resolved group_id. |
| `runs` | [`GroupRun`](/api-reference/agent/types#grouprun)[] | No | Conversation history — populated when resolving an existing group for fetch |
| `group_exists` | `boolean` | No | (detail) Whether the group exists in storage — populated when ``include_resources=True`` |
| `actor_name` | `string` | No | (detail) Display name of the current actor (caller profile) |
| `total_message_count` | `integer` | No | (detail) Total number of messages in the group |
| `models` | [`GroupResource`](/api-reference/agent/types#groupresource)[] | No | (detail) Models used in the group |
| `agents` | [`GroupResource`](/api-reference/agent/types#groupresource)[] | No | (detail) Agents used in the group |
| `profiles` | [`GroupResource`](/api-reference/agent/types#groupresource)[] | No | (detail) Profiles that authored runs in this group |

---

# `POST` `/agent/problem`

Route: /api-reference/agent/post-agent-problem

# `POST` `/agent/problem`

Problem Agent

Report an agent problem — composable infra architecture.

## Request Body (`ProblemAgentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | `string` | Yes | Problem type: feature, bug, question, other |
| `message` | `string` | Yes | Problem description (max 1000 chars) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant problem |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`ProblemAgentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `problem_id` | `string` | Yes | UUID of the created problem |
| `success` | `boolean` | No | Whether the problem was created |
| `message` | `string` | No | Status message |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/agent/refresh`

Route: /api-reference/agent/post-agent-refresh

# `POST` `/agent/refresh`

Agent Refresh

Refresh agent materialized views and invalidate caches.

## Request Body (`RefreshAgentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `targets` | `string`[] | No | MV targets to refresh (omit for all). Options: agent_drafts_mv |
| `idempotency_key` | `string` | No | Operation key for ack |
| `accept` | `boolean` | No | Accept or reject. Only meaningful with idempotency_key |
| `soft` | `boolean` | No | Stage the refresh as a pending (held) request — recorded but not enqueued; ack with accept releases/enqueues it |

## Response (`RefreshResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | — |
| `refreshed_views` | `string`[] | Yes | — |
| `invalidated_tags` | `string`[] | Yes | — |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/agent/search`

Route: /api-reference/agent/post-agent-search

# `POST` `/agent/search`

Search Agent

Search agents — composable infra architecture.

## Request Body (`SearchAgentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | — |
| `filter_department_ids` | `string`[] | No | — |
| `filter_model_ids` | `string`[] | No | — |
| `filter_tool_ids` | `string`[] | No | — |
| `department_search` | `string` | No | — |
| `model_search` | `string` | No | — |
| `tool_search` | `string` | No | — |
| `page_size` | `integer` | No | — |
| `page_offset` | `integer` | No | — |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`ListAgentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `agents` | [`ListAgentApiAgent`](/api-reference/agent/types#listagentapiagent)[] | No | List of agent items |
| `department_filter` | [`ListFilterSection`](/api-reference/agent/types#listfiltersection) | No | Filter options for departments |
| `model_filter` | [`ListFilterSection`](/api-reference/agent/types#listfiltersection) | No | Filter options for models |
| `tool_filter` | [`ListFilterSection`](/api-reference/agent/types#listfiltersection) | No | Filter options for tools |
| `flag_filter` | [`ListFilterSection`](/api-reference/agent/types#listfiltersection) | No | Filter options for flags in list UI |
| `total_count` | `integer` | No | Total number of matching records |
| `import_fields` | [`ImportField`](/api-reference/agent/types#importfield)[] | No | CSV import column schema for the bulk-import dialog |

---

# `POST` `/agent/text_download`

Route: /api-reference/agent/post-agent-text-download

# `POST` `/agent/text_download`

Download Text

Download a text file by text resource ID.

## Request Body (`TextDownloadAgentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `text_id` | `string` | Yes | UUID of the texts_resource to download |

## Response

```
{}
```

---

# `POST` `/agent/title`

Route: /api-reference/agent/post-agent-title

# `POST` `/agent/title`

Title Agent

Rename a agent's group (writes group_names_entry).

## Request Body (`TitleAgentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Group to rename |
| `title` | `string` | Yes | New title (display name) for the group |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant rename |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`TitleAgentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | The group that was renamed |
| `group_name_id` | `string` | Yes | UUID of the new group_names_entry row |
| `title` | `string` | Yes | The title that was set |
| `idempotency_key` | `string` | No | Operation key echoed back |

---

# `POST` `/agent/update`

Route: /api-reference/agent/post-agent-update

# `POST` `/agent/update`

Update Agent

Update agents using composable infra architecture.

## Request Body (`UpdateAgentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `agents` | [`UpdateAgentItem`](/api-reference/agent/types#updateagentitem)[] | No | List of agents to update (required on first call when ``all`` is false) |
| `all` | `boolean` | No | When true, apply ``patch`` to every agent matching the filter fields below (minus ``excluded_ids``) |
| `excluded_ids` | `string`[] | No | UUIDs to skip even when matched by ``all``-mode filters |
| `patch` | [`UpdateAgentPatch`](/api-reference/agent/types#updateagentpatch) | No | Shared change set applied to every matched row when ``all=true`` (sparse — only set fields are updated; ``patch.id`` ignored) |
| `search` | `string` | No | Full-text search query |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `filter_model_ids` | `string`[] | No | Filter by model UUIDs |
| `filter_tool_ids` | `string`[] | No | Filter by tool UUIDs |
| `department_search` | `string` | No | Search text for department facet (no-op for row filtering) |
| `model_search` | `string` | No | Search text for model facet (no-op for row filtering) |
| `tool_search` | `string` | No | Search text for tool facet (no-op for row filtering) |
| `flag_search` | `string` | No | Search text for flag facet (no-op for row filtering) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant update |
| `soft` | `boolean` | No | Stage the update dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`UpdateAgentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`AgentResultItem`](/api-reference/agent/types#agentresultitem)[] | Yes | List of operation results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/agent/watch`

Route: /api-reference/agent/post-agent-watch

# `POST` `/agent/watch`

Agent Watch Once

One-shot snapshot of run state, snapshot-replayable via ``snapshot_key``.

## Request Body (`WatchApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Chat group whose events we watch |
| `run_id` | `string` | No | Specific run to watch (e.g. the ``run_id`` returned by a prior ``X_Generate`` call). If None, watches every active run in the group at call time. |
| `wait_for_complete` | `boolean` | No | If True, block until the watched run reaches a terminal (complete/failed) event or timeout fires. If False, return current state and exit immediately. |
| `timeout_seconds` | `integer` | No | Max wait time when ``wait_for_complete=True``. |
| `snapshot_key` | `string` | No | Read snapshot key — on the one-shot POST /watch, the audit wrapper records this watch's point-in-time view (latest run state at call time) keyed by it and replays the same view on any later call with the same key. Ignored by the SSE GET stream. |

## Response (`WatchApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `runs` | [`RunStatus`](/api-reference/agent/types#runstatus)[] | Yes | — |
| `timed_out` | `boolean` | No | — |
| `waited_seconds` | `number` | No | — |

---

# Agent Types

Route: /api-reference/agent/types

# Agent Types

## `AgentDepartmentResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `department_id` | `string` | No | Department identifier |
| `name` | `string` | No | Department name |
| `description` | `string` | No | Department description |
| `generated` | `boolean` | No | Whether the department was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `AgentDescriptionResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Description resource identifier |
| `description` | `string` | No | Agent description |
| `generated` | `boolean` | No | Whether the description was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `AgentFieldError`

Per-field error from value resolution.

| Field | Type | Required | Description |
|---|---|---|---|
| `field` | `string` | Yes | Name of the field with the error |
| `message` | `string` | Yes | Human-readable error message |

---

## `AgentFlagResource`

Flag option row — one per (name, type, value) entry in flags_resource.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Flag resource identifier |
| `name` | `string` | No | Flag display name |
| `type` | `string` | No | Flag type (e.g. 'agent_active') |
| `value` | `boolean` | No | Underlying bool value of this option |
| `description` | `string` | No | Flag description text |
| `icon_id` | `string` | No | UUID of the selected icon resource |
| `icon` | `string` | No | Resolved SVG markup for the icon (hydrated from icons_resource) |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `AgentInstructionResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Instruction resource identifier |
| `template` | `string` | No | Instruction template |
| `generated` | `boolean` | No | Whether the instruction was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `AgentModelResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Model resource identifier |
| `name` | `string` | No | Model name |
| `description` | `string` | No | Model description |
| `value` | `string` | No | Model value |
| `provider_id` | `string` | No | Provider identifier |
| `department_ids` | `string`[] | No | Associated department identifiers |
| `temperature_level_ids` | `string`[] | No | Associated temperature level identifiers |
| `reasoning_level_ids` | `string`[] | No | Associated reasoning level identifiers |
| `quality_ids` | `string`[] | No | Associated quality identifiers |
| `voice_ids` | `string`[] | No | Associated voice identifiers |
| `modality_ids` | `string`[] | No | Associated modality identifiers |
| `generated` | `boolean` | No | Whether the model was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `AgentNameResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Name resource identifier |
| `name` | `string` | No | Agent name |
| `generated` | `boolean` | No | Whether the name was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `AgentPromptResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Prompt resource identifier |
| `system_prompt` | `string` | No | Prompt system text |
| `name` | `string` | No | Prompt name |
| `description` | `string` | No | Prompt description |
| `generated` | `boolean` | No | Whether the prompt was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `AgentQualityResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Quality resource identifier |
| `quality` | `string` | No | Quality value |
| `generated` | `boolean` | No | Whether the quality was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `AgentReasoningLevelResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Reasoning level resource identifier |
| `reasoning_level` | `string` | No | Reasoning level value |
| `generated` | `boolean` | No | Whether the reasoning level was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `AgentResultItem`

Per-item result within a bulk create/update response.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `agent_id` | `string` | No | UUID of the affected agent |
| `message` | `string` | Yes | Human-readable result message |
| `errors` | [`AgentFieldError`](#agentfielderror)[] | No | List of per-field errors |

---

## `AgentRubricResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Rubric resource identifier |
| `name` | `string` | No | Rubric name |
| `description` | `string` | No | Rubric description |
| `department_ids` | `string`[] | No | Associated department identifiers |
| `total_points` | `integer` | No | Total points |
| `pass_points` | `integer` | No | Passing points |
| `simulation_rubric` | `boolean` | No | Whether this rubric is for simulation |
| `video_rubric` | `boolean` | No | Whether this rubric is for video |
| `standard_group_ids` | `string`[] | No | Associated standard group identifiers |
| `generated` | `boolean` | No | Whether the rubric was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `AgentTemperatureLevelResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Temperature level resource identifier |
| `temperature` | `number` | No | Temperature value |
| `generated` | `boolean` | No | Whether the temperature level was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `AgentToolResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Tool resource identifier |
| `name` | `string` | No | Tool name |
| `description` | `string` | No | Tool description |
| `permission_ids` | `string`[] | No | Associated permission identifiers |
| `department_ids` | `string`[] | No | Associated department identifiers |
| `args_ids` | `string`[] | No | Associated arg identifiers |
| `args_output_ids` | `string`[] | No | Associated arg output identifiers |
| `instruction_id` | `string` | No | Associated instruction identifier |
| `agent_id` | `string` | No | Associated denormalized agent identifier |
| `generated` | `boolean` | No | Whether the tool was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `AgentVoiceResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Voice resource identifier |
| `voice` | `string` | No | Voice value |
| `generated` | `boolean` | No | Whether the voice was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `CallerPermissions`

Evaluated permissions for the current caller on this artifact type.

| Field | Type | Required | Description |
|---|---|---|---|
| `can_create` | `boolean` | Yes | Whether the caller can create new artifacts |
| `can_draft` | `boolean` | Yes | Whether the caller can create/update drafts |
| `can_duplicate` | `boolean` | Yes | Whether the caller can duplicate artifacts |
| `has_access` | `boolean` | No | Whether the caller can view this entity |
| `can_edit` | `boolean` | No | Whether the caller can edit this entity |
| `can_delete` | `boolean` | No | Whether the caller can delete this entity |
| `disabled_reason` | `string` | No | Human-readable reason if editing is disabled |

---

## `ColumnInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Column name |
| `type` | `string` | Yes | Column data type |
| `nullable` | `boolean` | Yes | Whether the column is nullable |

---

## `CreateAgentItem`

Single agent item for create — no agent_id.

Required fields (name): provide ID or value.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Client-provided UUID for the agent |
| `resource_id` | `string` | No | Optional preset UUID for the resource snapshot |
| `name_id` | `string` | No | UUID of the name resource |
| `name` | `string` | No | Display name value |
| `description_id` | `string` | No | UUID of the description resource |
| `description` | `string` | No | Description text value |
| `department_ids` | `string`[] | No | Associated department UUIDs |
| `departments` | `string`[] | No | Department names for matching |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs |
| `active` | `boolean` | No | Denormalized agent_active flag state |
| `model_id` | `string` | No | Associated model UUID |
| `reasoning_level_ids` | `string`[] | No | Associated reasoning level UUIDs |
| `temperature_level_ids` | `string`[] | No | Associated temperature level UUIDs |
| `tool_ids` | `string`[] | No | Associated tool UUIDs |
| `voice_ids` | `string`[] | No | Associated voice UUIDs |
| `agent_ids` | `string`[] | No | Associated agent resource UUIDs |
| `rubric_ids` | `string`[] | No | Associated rubric UUIDs |
| `prompt_id` | `string` | No | System prompt resource UUID |
| `instruction_ids` | `string`[] | No | Instruction template resource UUIDs |

---

## `CreatePromptInput`

Inline prompt creation input.

| Field | Type | Required | Description |
|---|---|---|---|
| `system_prompt` | `string` | Yes | System prompt text |
| `name` | `string` | No | Prompt name |
| `description` | `string` | No | Prompt description |

---

## `DeleteAgentResult`

Per-item result within a bulk delete response.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `agent_id` | `string` | Yes | UUID of the deleted agent |
| `message` | `string` | Yes | Human-readable result message |

---

## `DocsApiResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `list` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `detail` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `new` | [`PageMetaItem`](#pagemetaitem) | Yes | — |

---

## `DocsResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Resource or entry name |
| `type` | `string` | Yes | Resource or entry type identifier |
| `description` | `string` | Yes | Human-readable description |
| `materialized_view` | [`MvInfo`](#mvinfo) | No | Materialized view metadata |
| `tables` | [`TableInfo`](#tableinfo)[] | Yes | Related database tables |
| `operations` | [`OperationInfo`](#operationinfo)[] | Yes | Available operations |

---

## `EvalSetup`

Run-level eval scaffold — first-class on the generate response.

Audit's ``**output`` spread carries this onto
``<artifact>.generate.completed``. Null when no rubric-bearing
agent participated.

| Field | Type | Required | Description |
|---|---|---|---|
| `test_id` | `string` | Yes | — |
| `invocations` | [`InvocationSlot`](#invocationslot)[] | Yes | — |

---

## `GenerateConfig`

Developer configuration — all optional with sensible defaults.

| Field | Type | Required | Description |
|---|---|---|---|
| `operations` | `string`[] | No | — |
| `dangerous` | `boolean` | No | — |
| `params` | `object` | No | — |
| `group_id` | `string` | No | — |

---

## `GenerationsAgentListItem`

Single generation group in the agent generations response.

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | UUID of the generation group |
| `session_id` | `string` | No | UUID of the parent session |
| `group_name` | `string` | No | Name of the generation group |
| `created_at` | `string` | No | Timestamp of the generation |

---

## `GetAgentDraftResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | UUID of the draft |
| `created_at` | `string` | Yes | Creation timestamp |
| `generated` | `boolean` | Yes | Whether this was AI-generated |
| `mcp` | `boolean` | Yes | Whether MCP tooling was used |
| `active` | `boolean` | Yes | Whether this draft is active |
| `session_id` | `string` | Yes | Associated session UUID |
| `name` | `string` | No | Immutable draft label set at create time |
| `name_ids` | `string`[] | Yes | Associated name UUIDs |
| `description_ids` | `string`[] | Yes | Associated description UUIDs |
| `flag_ids` | `string`[] | Yes | Associated flag UUIDs |
| `department_ids` | `string`[] | Yes | Associated department UUIDs |
| `model_ids` | `string`[] | Yes | Associated model UUIDs |
| `tool_ids` | `string`[] | Yes | Associated tool UUIDs |
| `profile_ids` | `string`[] | Yes | Associated profile UUIDs |
| `reasoning_level_ids` | `string`[] | Yes | Associated reasoning level UUIDs |
| `temperature_level_ids` | `string`[] | Yes | Associated temperature level UUIDs |
| `voice_ids` | `string`[] | Yes | Associated voice UUIDs |
| `quality_ids` | `string`[] | Yes | Associated quality UUIDs |
| `rubric_ids` | `string`[] | No | Associated rubric UUIDs |
| `prompt_ids` | `string`[] | No | Associated prompt UUIDs |
| `instruction_ids` | `string`[] | No | Associated instruction UUIDs |
| `agent_ids` | `string`[] | No | Associated agent snapshot UUIDs |
| `pending_name_ids` | `string`[] | No | Pending name UUIDs |
| `pending_description_ids` | `string`[] | No | Pending description UUIDs |
| `pending_flag_ids` | `string`[] | No | Pending flag UUIDs |
| `pending_department_ids` | `string`[] | No | Pending department UUIDs |
| `pending_model_ids` | `string`[] | No | Pending model UUIDs |
| `pending_tool_ids` | `string`[] | No | Pending tool UUIDs |
| `pending_reasoning_level_ids` | `string`[] | No | Pending reasoning level UUIDs |
| `pending_temperature_level_ids` | `string`[] | No | Pending temperature level UUIDs |
| `pending_voice_ids` | `string`[] | No | Pending voice UUIDs |
| `pending_quality_ids` | `string`[] | No | Pending quality UUIDs |
| `pending_rubric_ids` | `string`[] | No | Pending rubric UUIDs |
| `pending_prompt_ids` | `string`[] | No | Pending prompt UUIDs |
| `pending_instruction_ids` | `string`[] | No | Pending instruction UUIDs |
| `pending_agent_ids` | `string`[] | No | Pending agent snapshot UUIDs |

---

## `GroupCall`

Tool call referenced by a message.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `tool_name` | `string` | No | — |
| `template_name` | `string` | No | — |
| `tool` | `object` | No | — |
| `ledger_status` | `string` | No | — |
| `ledger_operation` | `string` | No | — |
| `ledger_artifact` | `string` | No | — |
| `ledger_artifact_id` | `string` | No | — |

---

## `GroupMessage`

Message within a run.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `role` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `text_ids` | `string`[] | No | — |
| `audio_ids` | `string`[] | No | — |
| `image_ids` | `string`[] | No | — |
| `video_ids` | `string`[] | No | — |
| `file_ids` | `string`[] | No | — |
| `call_ids` | `string`[] | No | — |
| `calls` | [`GroupCall`](#groupcall)[] | No | — |
| `reasoning` | `boolean` | No | True when this row is a chain-of-thought trace persisted alongside the assistant answer (rendered as a collapsed accordion). |
| `in_context` | `boolean` | No | Whether this message is included in the LLM context for the next generation. Mirrors the dedup pass that builds chat history (see in_context_reason). |
| `in_context_reason` | `string` | No | Why this message is in/out of LLM context. 'kept' = included; 'deduped_read' = older read-only call to a tool that has a fresher result later in the group; future values may include 'trimmed_top_n'. |

---

## `GroupResource`

Lightweight `\{id, name\}` for cross-referencing run-level ids
(``model_id`` / ``agent_id`` / ``profile_id``) against human-readable
names on the analytics panel. Names come from the canonical
``get_models`` / ``get_agents`` / ``get_profiles`` black boxes.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `name` | `string` | No | — |

---

## `GroupRun`

Run within a group, with its messages.

Carries token / cost / model / agent / profile attribution so the
analytics view can render per-run cost + actor info without a
parallel detail shape. ``profile_id`` is the authoring profile
(human user), ``agent_id`` is the LLM-side actor, ``model_id`` is
the model used by that agent. All optional — runs predating these
columns or with unresolved attributions surface ``None``.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `input_tokens` | `integer` | No | — |
| `output_tokens` | `integer` | No | — |
| `cached_input_tokens` | `integer` | No | — |
| `cost` | `number` | No | — |
| `model_id` | `string` | No | — |
| `agent_id` | `string` | No | — |
| `profile_id` | `string` | No | — |
| `previous_context_start_index` | `integer` | No | Index in ``messages`` where the current run's own messages begin; earlier rows are previous-context replay. ``None`` when the run has no previous context attached. |
| `messages` | [`GroupMessage`](#groupmessage)[] | No | — |

---

## `ImportField`

Field descriptor for CSV import column mapping.

| Field | Type | Required | Description |
|---|---|---|---|
| `key` | `string` | Yes | — |
| `label` | `string` | Yes | — |
| `required` | `boolean` | No | — |
| `multi` | `boolean` | No | — |
| `type` | `string` | No | — |
| `example` | `string` | No | — |
| `description` | `string` | No | — |

---

## `InvocationSlot`

One agent's slot in a multi-agent generation pool.

Populated by ``setup_generation_test`` when an agent carries a
rubric. The client uses these IDs to drive the eval workflow:
review the candidate's output, optionally fire a grader against
its ``invocation_id``, and promote/reject by call_id via the
existing ``idempotency_key + accept`` pattern.

| Field | Type | Required | Description |
|---|---|---|---|
| `invocation_id` | `string` | Yes | — |
| `agent_id` | `string` | Yes | — |
| `rubric_id` | `string` | No | — |

---

## `ListAgentApiAgent`

Agent type for list endpoint with computed permissions.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Agent artifact UUID (canonical id; mirrors agent_id) |
| `agent_id` | `string` | No | UUID of the agent |
| `name` | `string` | No | Display name |
| `description` | `string` | No | Agent description text |
| `reasoning` | `string` | No | Reasoning level label |
| `temperature` | `number` | No | Temperature setting value |
| `model_id` | `string` | No | UUID of the selected model |
| `model_name` | `string` | No | Display name of the model |
| `model_description` | `string` | No | Description of the model |
| `role` | `string` | No | Agent role identifier |
| `updated_at` | `string` | No | Last updated timestamp |
| `department_ids` | `string`[] | No | Associated department UUIDs |
| `flag_ids` | `string`[] | No | Currently selected flag option UUIDs |
| `is_inactive` | `boolean` | No | Whether the agent is inactive (derived from agent_active flag) |
| `is_mcp` | `boolean` | No | Whether the agent is exposed via MCP (derived from mcp flag) |
| `can_edit` | `boolean` | No | Whether the current user can edit |
| `can_duplicate` | `boolean` | No | Whether the current user can duplicate |
| `can_delete` | `boolean` | No | Whether the current user can delete |
| `pending_status` | `string` | No | Soft-call ledger status (pending/accepted/rejected) for the latest pending op on this row |
| `pending_operation` | `string` | No | Operation name (create/update/delete/duplicate/draft) of the latest pending soft-call entry |
| `pending_call_id` | `string` | No | Originating tool call id for the latest pending soft-call entry |

---

## `ListFilterOption`

Standardized option for list endpoint filter sections.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier for this filter option |
| `name` | `string` | No | Display name |
| `count` | `integer` | No | Number of matching records |
| `hex_code` | `string` | No | Hex color code for display |
| `value` | `string` | No | Internal value |
| `type` | `string` | No | Option type discriminator |

---

## `ListFilterSection`

Filter section with options and echoed request state.

| Field | Type | Required | Description |
|---|---|---|---|
| `options` | [`ListFilterOption`](#listfilteroption)[] | No | Available filter options |
| `selected_ids` | `string`[] | No | Currently selected filter option IDs |
| `search` | `string` | No | Active search text for filtering |

---

## `MvInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Materialized view name |
| `definition` | `string` | Yes | SQL definition of the view |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the view |

---

## `OperationInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Operation name |
| `description` | `string` | Yes | Human-readable description of the operation |
| `params` | [`ParamInfo`](#paraminfo)[] | Yes | List of operation parameters |
| `returns` | `object` | No | Return type schema |

---

## `OperationPrompts`

Starter prompts keyed by operation name.

Each key is an operation (e.g. "create", "search", "draft", "export")
and the value is a list of starter prompts for that operation.
The client picks from the operations the caller has permission for
and rotates through them.

| Field | Type | Required | Description |
|---|---|---|---|
| `prompts` | `object` | No | Map of operation name to starter prompts |

---

## `PageMetaItem`

| Field | Type | Required | Description |
|---|---|---|---|
| `title` | `string` | Yes | — |
| `description` | `string` | Yes | — |

---

## `ParamInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Parameter name |
| `type` | `string` | Yes | Parameter data type |
| `required` | `boolean` | Yes | Whether the parameter is required |
| `default` | `any` | No | Default value if not required |

---

## `ProducedMedia`

One asset produced by a generation run.

``resource_id`` is the canonical id the per-artifact download tools
accept (e.g. ``Scenario_Image_Download(image_id=resource_id)`` for
``modality="image"``). It maps to ``images_resource.id`` /
``videos_resource.id`` / ``audios_resource.id`` depending on the
modality.

| Field | Type | Required | Description |
|---|---|---|---|
| `modality` | `"image"` \| `"video"` \| `"audio"` | Yes | — |
| `resource_id` | `string` | Yes | — |
| `upload_id` | `string` | Yes | — |
| `mime_type` | `string` | No | — |
| `file_size` | `integer` | No | — |

---

## `ProfileSummary`

Caller identity derived from JWT — who you are on this page.

Superset of the old six-field version: now carries everything the client
needs so that ``/\{artifact\}/context`` fully replaces ``/profiles/context``
and the extra ``getLayoutContextData`` round-trip can be dropped.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Display name of the authenticated user |
| `role` | `string` | Yes | Role name (e.g. 'Super Administrator') |
| `role_level` | `integer` | Yes | Role hierarchy level (0 = highest privilege) |
| `department_ids` | `string`[] | Yes | Departments the user belongs to |
| `artifact_access` | `string`[] | Yes | Artifact types this role can access (sidebar visibility) |
| `role_permissions` | `any`[][] | Yes | Full (artifact, operation) permission tuples for granular page gating |
| `is_active` | `boolean` | Yes | Whether the user's profile is active |
| `id` | `string` | Yes | Profile UUID (SocketProvider, ProfileProvider) |
| `theme` | [`ThemeBundle`](#themebundle) | No | Resolved theme: hex primitives + derived oklch tokens + score thresholds |
| `session_id` | `string` | No | Current session UUID |
| `is_emulation` | `boolean` | No | Whether user is in emulation mode (ProfileProvider) |
| `role_resources` | [`QGetProfileContextV4RoleResource`](#qgetprofilecontextv4roleresource)[] | No | All role resources for emulation display (ProfileProvider) |
| `scoped_roles` | `string`[] | No | Roles the user can emulate (ProfileProvider) |
| `active` | `boolean` | No | Alias for is_active (ProfileProvider uses this name) |

---

## `QGetProfileContextV4RoleResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `role` | `string` | No | — |
| `name` | `string` | No | — |
| `description` | `string` | No | — |
| `icon_value` | `string` | No | — |
| `color_hex` | `string` | No | — |

---

## `RunStatus`

Outcome of one watched run.

| Field | Type | Required | Description |
|---|---|---|---|
| `run_id` | `string` | Yes | — |
| `status` | `"pending"` \| `"completed"` \| `"failed"` | Yes | — |
| `modality` | `string` | No | Modality of generated output (image, video, text…) |
| `resource_ids` | `string`[] | No | Resource UUIDs produced by this run (e.g. images_resource ids) |
| `error` | `string` | No | — |

---

## `TableInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Table name |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the table |

---

## `ThemeBundle`

Full theme payload for a page bootstrap.

Riding along on every ``/\{artifact\}/context`` response via
``ProfileSummary.theme``. Layers:
  - ``primitives`` / ``dark_primitives`` — hex inputs the settings
    editor reads/writes (light + dark palettes).
  - ``tokens`` / ``dark_tokens`` — oklch tokens the client paints with.
    ``ThemeStyle`` emits two ``<style>`` blocks: one scoped to
    ``:root:not(.dark)`` (light) and one to ``:root.dark`` (dark).
  - ``thresholds`` — numeric score thresholds for analytics components.
Empty-in → empty-out per token: missing values fall through to the
matching ``globals.css`` default.

| Field | Type | Required | Description |
|---|---|---|---|
| `primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (light palette, for the theme editor) |
| `tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for light mode (SSR CSS-var injection) |
| `dark_primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (dark palette, for the theme editor) |
| `dark_tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for dark mode (SSR CSS-var injection) |
| `thresholds` | [`Thresholds`](#thresholds) | No | Score thresholds resolved from the setting |

---

## `ThemePrimitives`

40 optional fields. The 17 essentials drive the rest; the other 23
are overrides for fine-tuning when derivation isn't what you want.

Empty primitive → empty token → client falls back to globals.css.

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `primary` | `string` | No | — |
| `accent` | `string` | No | — |
| `card` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `ring` | `string` | No | — |
| `border` | `string` | No | — |
| `destructive` | `string` | No | — |
| `success` | `string` | No | — |
| `warning` | `string` | No | — |
| `info` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `input` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `ThemeTokens`

40 fully-resolved CSS variable values (snake_case 1:1 with vars).

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `accent` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `border` | `string` | No | — |
| `input` | `string` | No | — |
| `ring` | `string` | No | — |
| `success` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `Thresholds`

Numeric score thresholds resolved from the active setting.

Server pre-buckets dashboard metrics into ``success | warning | danger |
neutral`` already, so most components don't need these values. Surface
them for chart reference lines, tooltips, and any client-side bucketing.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `integer` | Yes | Score >= this counts as success |
| `warning` | `integer` | Yes | Score >= this counts as warning |
| `danger` | `integer` | Yes | Score < success threshold but >= this counts as danger; below is neutral/no-data |

---

## `UpdateAgentItem`

Single agent item for update — agent_id required, all fields optional.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | UUID of the agent to update |
| `name_id` | `string` | No | UUID of the name resource |
| `name` | `string` | No | Display name value |
| `description_id` | `string` | No | UUID of the description resource |
| `description` | `string` | No | Description text value |
| `department_ids` | `string`[] | No | Associated department UUIDs |
| `departments` | `string`[] | No | Department names for matching |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs |
| `active` | `boolean` | No | Denormalized agent_active flag state |
| `model_id` | `string` | No | Associated model UUID |
| `reasoning_level_ids` | `string`[] | No | Associated reasoning level UUIDs |
| `temperature_level_ids` | `string`[] | No | Associated temperature level UUIDs |
| `tool_ids` | `string`[] | No | Associated tool UUIDs |
| `voice_ids` | `string`[] | No | Associated voice UUIDs |
| `agent_ids` | `string`[] | No | Associated agent resource UUIDs |

---

## `UpdateAgentPatch`

Shared patch for bulk-update-all-matching mode.

Inherits every field from ``UpdateAgentItem`` and just relaxes
``id`` to optional — the bulk impl stamps the resolved id onto a
clone of the patch per matched row, so any client-supplied id is
ignored. Sparse semantics: only fields the client sets are written.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Ignored — bulk impl stamps the resolved agent id per matched row |
| `name_id` | `string` | No | UUID of the name resource |
| `name` | `string` | No | Display name value |
| `description_id` | `string` | No | UUID of the description resource |
| `description` | `string` | No | Description text value |
| `department_ids` | `string`[] | No | Associated department UUIDs |
| `departments` | `string`[] | No | Department names for matching |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs |
| `active` | `boolean` | No | Denormalized agent_active flag state |
| `model_id` | `string` | No | Associated model UUID |
| `reasoning_level_ids` | `string`[] | No | Associated reasoning level UUIDs |
| `temperature_level_ids` | `string`[] | No | Associated temperature level UUIDs |
| `tool_ids` | `string`[] | No | Associated tool UUIDs |
| `voice_ids` | `string`[] | No | Associated voice UUIDs |
| `agent_ids` | `string`[] | No | Associated agent resource UUIDs |

---

## `app__infra__agent__types__DraftFormState`

Server-authoritative form state returned after draft save.

| Field | Type | Required | Description |
|---|---|---|---|
| `name_id` | `string` | No | UUID of the selected name resource |
| `name` | `string` | No | Resolved name value |
| `description_id` | `string` | No | UUID of the selected description resource |
| `description` | `string` | No | Resolved description value |
| `flag_ids` | `string`[] | No | Selected flag UUIDs |
| `active` | `boolean` | No | Echoed agent_active flag state |
| `department_ids` | `string`[] | Yes | Selected department UUIDs |
| `model_id` | `string` | No | Selected model UUID |
| `tool_ids` | `string`[] | Yes | Selected tool UUIDs |
| `reasoning_level_id` | `string` | No | Selected reasoning level UUID |
| `temperature_level_id` | `string` | No | Selected temperature level UUID |
| `voice_ids` | `string`[] | Yes | Selected voice UUIDs |
| `quality_ids` | `string`[] | Yes | Selected quality UUIDs |
| `rubric_ids` | `string`[] | Yes | Selected rubric UUIDs |
| `prompt_id` | `string` | No | Selected prompt UUID when provided |
| `instruction_id` | `string` | No | Selected instruction UUID when provided |
| `pending_ids` | `string`[] | No | Pending resource identifiers |

---

## `app__infra__agent__types__SectionFilter`

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Filter options by search text |
| `limit` | `integer` | No | Max options to return |
| `selected` | `boolean` | No | Only return selected items |
| `suggested` | `boolean` | No | Only return suggested items |
| `include` | `boolean` | No | Include this section in response (default true) |

---

---

# `GET` `/attempt/watch`

Route: /api-reference/attempt/get-attempt-watch

# `GET` `/attempt/watch`

Attempt Watch

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `group_id` | query | No | — |
| `run_id` | query | No | Optional run filter. If provided, only events whose envelope run_id matches are streamed. Omit to receive every attempt event in the group (the FE default). |

## Response

```
{}
```

---

# `POST` `/attempt/archive`

Route: /api-reference/attempt/post-attempt-archive

# `POST` `/attempt/archive`

Archive Attempts

Bulk archive or unarchive attempts (simulation or benchmark).

## Request Body (`ArchiveAttemptsRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `archived` | `boolean` | Yes | Whether to archive (true) or unarchive (false) |
| `attempt_ids` | `string`[] | No | Specific attempt UUIDs to archive |
| `start_date` | `string` | No | Start date for filter-based archive |
| `end_date` | `string` | No | End date for filter-based archive |
| `cohort_ids` | `string`[] | No | Cohort UUIDs to filter by |
| `department_ids` | `string`[] | No | Department UUIDs to filter by |
| `simulation_ids` | `string`[] | No | Simulation UUIDs to filter by |
| `scenario_ids` | `string`[] | No | Scenario UUIDs to filter by |
| `profile_ids_filter` | `string`[] | No | Profile UUIDs to filter by |
| `infinite_mode` | `boolean` | No | Filter by infinite mode status |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior call; on the ack, the server-minted soft key to activate/reject a staged archive |
| `soft` | `boolean` | No | Stage the archive dormant (active=False); accept activates the whole set |
| `accept` | `boolean` | No | Ack: True activates the staged archive, False rejects. Only meaningful with idempotency_key |

## Response (`ArchiveAttemptsResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `updated_count` | `integer` | No | Number of attempts updated |
| `profile_ids_to_invalidate` | `string`[] | No | Profile IDs whose caches need invalidation |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with accept to activate/reject the staged archive. |

---

# `POST` `/attempt/audio_download`

Route: /api-reference/attempt/post-attempt-audio-download

# `POST` `/attempt/audio_download`

Download Audio

Download an audio file by audio entry ID.

## Request Body (`AudioDownloadAttemptApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `audio_id` | `string` | Yes | UUID of the audios_entry to download |

## Response

```
{}
```

---

# `POST` `/attempt/audio_upload`

Route: /api-reference/attempt/post-attempt-audio-upload

# `POST` `/attempt/audio_upload`

Upload Audio

Upload audio or promote an existing raw upload.

Three shapes:
  - **File only** → multipart ``file``: server writes bytes, creates
    ``uploads_entry`` + full audio chain on top.
  - **upload_id only** → ``?upload_id=<uuid>`` of an existing upload
    (e.g. raw bytes captured by the realtime adapter). Server reuses
    the upload and stacks resource + entry + junctions on top.
  - **upload_id + file** → client pre-reserved via ``/attempt/audio/new``
    and now fills the slot. Server writes bytes into that upload's
    file and then runs the full chain.

Returns ``\{audio_id, audios_id, upload_id\}``. Client only needs
``audios_id``; ``upload_id`` is the primitive handed back.

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `upload_id` | query | No | — |

## Request Body

| Field | Type | Required | Description |
|---|---|---|---|
| `file` | `string` | No | — |
| `length_seconds` | `integer` | No | — |
| `name` | `string` | No | — |
| `description` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `soft` | `boolean` | No | — |
| `accept` | `boolean` | No | — |

## Response (`AudioUploadAttemptApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `audio_id` | `string` | Yes | UUID of the audios_entry (server plumbing; public handle is audios_id) |
| `audios_id` | `string` | Yes | UUID of the audios_resource — use this for /generate, /chat/message, download |
| `upload_id` | `string` | Yes | UUID of the uploads_entry (primitive raw file) |
| `idempotency_key` | `string` | No | Server-minted soft-call key; echo with accept to promote/reject the staged upload. |

---

# `POST` `/attempt/call_download`

Route: /api-reference/attempt/post-attempt-call-download

# `POST` `/attempt/call_download`

Download Call

Download a call file by call resource ID.

## Request Body (`CallDownloadAttemptApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `call_id` | `string` | Yes | UUID of the calls_resource to download |

## Response

```
{}
```

---

# `POST` `/attempt/chat_analyses`

Route: /api-reference/attempt/post-attempt-chat-analyses

# `POST` `/attempt/chat_analyses`

Chat Analyses

Create analysis items for the latest grade on a chat.

## Request Body (`ChatAnalysesRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `chat_id` | `string` | Yes | — |
| `analyses` | [`ChatAnalysisItem`](/api-reference/attempt/types#chatanalysisitem)[] | Yes | — |
| `idempotency_key` | `string` | No | — |
| `soft` | `boolean` | No | — |
| `accept` | `boolean` | No | — |

## Response (`ChatAnalysesResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | — |
| `analysis_ids` | `string`[] | Yes | — |
| `idempotency_key` | `string` | No | — |

---

# `POST` `/attempt/chat_audio`

Route: /api-reference/attempt/post-attempt-chat-audio

# `POST` `/attempt/chat_audio`

Chat Audio

Attach an audios_id to an attempt chat message.

## Request Body (`ChatAudioRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `chat_id` | `string` | Yes | — |
| `message_id` | `string` | No | — |
| `audios_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `soft` | `boolean` | No | — |
| `accept` | `boolean` | No | — |

## Response (`ChatAudioResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | — |
| `attempt_audio_id` | `string` | Yes | — |
| `idempotency_key` | `string` | No | — |

---

# `POST` `/attempt/chat_complete`

Route: /api-reference/attempt/post-attempt-chat-complete

# `POST` `/attempt/chat_complete`

Chat Complete

Mark an attempt chat as completed — final step after grading.

## Request Body (`ChatCompleteRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `chat_id` | `string` | Yes | — |
| `message` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `soft` | `boolean` | No | — |
| `accept` | `boolean` | No | — |

## Response (`ChatCompleteResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | — |
| `completion_id` | `string` | Yes | — |
| `chat_id` | `string` | Yes | — |
| `idempotency_key` | `string` | No | — |

---

# `POST` `/attempt/chat_create`

Route: /api-reference/attempt/post-attempt-chat-create

# `POST` `/attempt/chat_create`

Create Attempt Chat Endpoint

Create a chat within an attempt.

## Request Body (`CreateAttemptChatApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `attempt_id` | `string` | Yes | — |
| `chat_id` | `string` | Yes | — |
| `name_id` | `string` | No | — |
| `name` | `string` | No | — |
| `description_id` | `string` | No | — |
| `description` | `string` | No | — |
| `problem_statement_id` | `string` | No | — |
| `problem_statement` | `string` | No | — |
| `video_id` | `string` | No | — |
| `image_id` | `string` | No | — |
| `personas_ids` | `string`[] | No | — |
| `personas` | `string`[] | No | — |
| `documents_ids` | `string`[] | No | — |
| `documents` | `string`[] | No | — |
| `parameter_fields_ids` | `string`[] | No | — |
| `parameter_fields` | `string`[] | No | — |
| `objectives_ids` | `string`[] | No | — |
| `objectives` | `string`[] | No | — |
| `questions_ids` | `string`[] | No | — |
| `questions` | [`AttemptQuestionValue`](/api-reference/attempt/types#attemptquestionvalue)[] | No | — |
| `options_ids` | `string`[] | No | — |
| `previous_attempt_chat_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `accept` | `boolean` | No | — |

## Response (`CreateAttemptChatApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `attempt_chat_id` | `string` | Yes | — |
| `idempotency_key` | `string` | No | — |

---

# `POST` `/attempt/chat_export`

Route: /api-reference/attempt/post-attempt-chat-export

# `POST` `/attempt/chat_export`

Chat Export

Export a single chat entry as a denormalized CSV row.

## Request Body (`ExportChatApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `chat_entry_id` | `string` | Yes | UUID of the chat entry to export |
| `attempt_id` | `string` | No | Optional attempt context for the chat |
| `draft_id` | `string` | No | Optional draft context for the chat |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`ExportChatApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `content` | `string` | Yes | Exported file content |
| `file_name` | `string` | Yes | Name of the exported file |
| `mime_type` | `string` | Yes | MIME type of the exported file |
| `row_count` | `integer` | Yes | Number of rows in the export |

---

# `POST` `/attempt/chat_feedback`

Route: /api-reference/attempt/post-attempt-chat-feedback

# `POST` `/attempt/chat_feedback`

Chat Feedback

Create feedback items for the latest grade on a chat.

## Request Body (`ChatFeedbackRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `chat_id` | `string` | Yes | — |
| `feedbacks` | [`ChatFeedbackItem`](/api-reference/attempt/types#chatfeedbackitem)[] | Yes | — |
| `idempotency_key` | `string` | No | — |
| `soft` | `boolean` | No | — |
| `accept` | `boolean` | No | — |

## Response (`ChatFeedbackResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | — |
| `feedback_ids` | `string`[] | Yes | — |
| `idempotency_key` | `string` | No | — |

---

# `POST` `/attempt/chat_get`

Route: /api-reference/attempt/post-attempt-chat-get

# `POST` `/attempt/chat_get`

Chat Get

Get hydrated resources for chat bundle customization.

## Request Body (`GetChatRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Chat entry ID |
| `chat_entry_id` | `string` | No | Legacy alias for the chat entry ID |
| `attempt_id` | `string` | No | Attempt ID |
| `draft_id` | `string` | No | Draft ID |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads |
| `names` | [`app__infra__attempt__chat__types__SectionFilter`](/api-reference/attempt/types#app-infra-attempt-chat-types-sectionfilter) | No | — |
| `descriptions` | [`app__infra__attempt__chat__types__SectionFilter`](/api-reference/attempt/types#app-infra-attempt-chat-types-sectionfilter) | No | — |
| `flags` | [`app__infra__attempt__chat__types__SectionFilter`](/api-reference/attempt/types#app-infra-attempt-chat-types-sectionfilter) | No | — |
| `departments` | [`app__infra__attempt__chat__types__SectionFilter`](/api-reference/attempt/types#app-infra-attempt-chat-types-sectionfilter) | No | — |
| `personas` | [`app__infra__attempt__chat__types__SectionFilter`](/api-reference/attempt/types#app-infra-attempt-chat-types-sectionfilter) | No | — |
| `documents` | [`app__infra__attempt__chat__types__SectionFilter`](/api-reference/attempt/types#app-infra-attempt-chat-types-sectionfilter) | No | — |
| `parameter_fields` | [`app__infra__attempt__chat__types__SectionFilter`](/api-reference/attempt/types#app-infra-attempt-chat-types-sectionfilter) | No | — |
| `scenarios` | [`app__infra__attempt__chat__types__SectionFilter`](/api-reference/attempt/types#app-infra-attempt-chat-types-sectionfilter) | No | — |
| `fields` | [`app__infra__attempt__chat__types__SectionFilter`](/api-reference/attempt/types#app-infra-attempt-chat-types-sectionfilter) | No | — |
| `questions` | [`app__infra__attempt__chat__types__SectionFilter`](/api-reference/attempt/types#app-infra-attempt-chat-types-sectionfilter) | No | — |
| `options` | [`app__infra__attempt__chat__types__SectionFilter`](/api-reference/attempt/types#app-infra-attempt-chat-types-sectionfilter) | No | — |
| `videos` | [`app__infra__attempt__chat__types__SectionFilter`](/api-reference/attempt/types#app-infra-attempt-chat-types-sectionfilter) | No | — |
| `images` | [`app__infra__attempt__chat__types__SectionFilter`](/api-reference/attempt/types#app-infra-attempt-chat-types-sectionfilter) | No | — |
| `problem_statements` | [`app__infra__attempt__chat__types__SectionFilter`](/api-reference/attempt/types#app-infra-attempt-chat-types-sectionfilter) | No | — |
| `objectives` | [`app__infra__attempt__chat__types__SectionFilter`](/api-reference/attempt/types#app-infra-attempt-chat-types-sectionfilter) | No | — |

## Response (`GetChatResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the authenticated user |
| `chat_exists` | `boolean` | No | Whether the chat template exists |
| `can_edit` | `boolean` | No | Whether the current user can edit this draft |
| `disabled_reason` | `string` | No | Human-readable reason if editing is disabled |
| `group_id` | `string` | No | Group ID for generation and draft correlation |
| `show_ai_generate` | `boolean` | No | Whether AI generation is available |
| `profile_has_access` | `boolean` | No | Compatibility flag for current chat pages |
| `simulation_name` | `string` | No | Optional simulation name for UI display |
| `chat_entry_id` | `string` | No | Chat entry ID |
| `attempt_id` | `string` | No | Attempt ID |
| `names` | [`ChatNameResource`](/api-reference/attempt/types#chatnameresource)[] | No | — |
| `descriptions` | [`ChatDescriptionResource`](/api-reference/attempt/types#chatdescriptionresource)[] | No | — |
| `flags` | [`ChatFlagResource`](/api-reference/attempt/types#chatflagresource)[] | No | — |
| `departments` | [`ChatDepartmentResource`](/api-reference/attempt/types#chatdepartmentresource)[] | No | — |
| `personas` | [`ChatPersonaResource`](/api-reference/attempt/types#chatpersonaresource)[] | No | — |
| `documents` | [`ChatDocumentResource`](/api-reference/attempt/types#chatdocumentresource)[] | No | — |
| `parameter_fields` | [`ChatParameterFieldResource`](/api-reference/attempt/types#chatparameterfieldresource)[] | No | — |
| `scenarios` | [`ChatScenarioResource`](/api-reference/attempt/types#chatscenarioresource)[] | No | — |
| `fields` | [`ChatFieldResource`](/api-reference/attempt/types#chatfieldresource)[] | No | — |
| `questions` | [`ChatQuestionResource`](/api-reference/attempt/types#chatquestionresource)[] | No | — |
| `options` | [`ChatOptionResource`](/api-reference/attempt/types#chatoptionresource)[] | No | — |
| `videos` | [`ChatVideoResource`](/api-reference/attempt/types#chatvideoresource)[] | No | — |
| `images` | [`ChatImageResource`](/api-reference/attempt/types#chatimageresource)[] | No | — |
| `problem_statements` | [`ChatProblemStatementResource`](/api-reference/attempt/types#chatproblemstatementresource)[] | No | — |
| `objectives` | [`ChatObjectiveResource`](/api-reference/attempt/types#chatobjectiveresource)[] | No | — |
| `name_ids` | `string`[] | No | — |
| `description_ids` | `string`[] | No | — |
| `flag_ids` | `string`[] | No | — |
| `department_ids` | `string`[] | No | — |
| `persona_ids` | `string`[] | No | — |
| `document_ids` | `string`[] | No | — |
| `parameter_field_ids` | `string`[] | No | — |
| `scenario_ids` | `string`[] | No | — |
| `field_ids` | `string`[] | No | — |
| `question_ids` | `string`[] | No | — |
| `option_ids` | `string`[] | No | — |
| `video_ids` | `string`[] | No | — |
| `image_ids` | `string`[] | No | — |
| `problem_statement_ids` | `string`[] | No | — |
| `objective_ids` | `string`[] | No | — |

---

# `POST` `/attempt/chat_grade`

Route: /api-reference/attempt/post-attempt-chat-grade

# `POST` `/attempt/chat_grade`

Chat Grade

Manually grade an attempt chat with a score.

## Request Body (`GradeAttemptApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `chat_id` | `string` | Yes | UUID of the attempt chat to grade |
| `score` | `integer` | Yes | Overall score to record for the chat |

## Response (`GradeAttemptApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `chat_id` | `string` | Yes | — |
| `grade_id` | `string` | No | — |
| `score` | `integer` | No | — |
| `passed` | `boolean` | No | — |
| `time_taken` | `integer` | No | — |

---

# `POST` `/attempt/chat_hints`

Route: /api-reference/attempt/post-attempt-chat-hints

# `POST` `/attempt/chat_hints`

Chat Hints

Create hint items for messages in a chat.

## Request Body (`ChatHintsRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `chat_id` | `string` | Yes | — |
| `hints` | [`ChatHintItem`](/api-reference/attempt/types#chathintitem)[] | Yes | — |
| `idempotency_key` | `string` | No | — |
| `soft` | `boolean` | No | — |
| `accept` | `boolean` | No | — |

## Response (`ChatHintsResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | — |
| `hint_ids` | `string`[] | Yes | — |
| `idempotency_key` | `string` | No | — |

---

# `POST` `/attempt/chat_improvements`

Route: /api-reference/attempt/post-attempt-chat-improvements

# `POST` `/attempt/chat_improvements`

Chat Improvements

Create improvement items (with optional inline replacements) for the latest grade.

## Request Body (`ChatImprovementsRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `chat_id` | `string` | Yes | — |
| `improvements` | [`ChatImprovementItem`](/api-reference/attempt/types#chatimprovementitem)[] | Yes | — |
| `idempotency_key` | `string` | No | — |
| `soft` | `boolean` | No | — |
| `accept` | `boolean` | No | — |

## Response (`ChatImprovementsResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | — |
| `improvement_ids` | `string`[] | Yes | — |
| `idempotency_key` | `string` | No | — |

---

# `POST` `/attempt/chat_message`

Route: /api-reference/attempt/post-attempt-chat-message

# `POST` `/attempt/chat_message`

Chat Message

Create a message in an attempt chat.

## Request Body (`ChatMessageRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `chat_id` | `string` | Yes | — |
| `text` | `string` | Yes | — |
| `persona_id` | `string` | No | — |
| `parent_message_id` | `string` | No | — |
| `auto_link_parent` | `boolean` | No | — |
| `audios_id` | `string` | No | — |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior call instead of re-running |

## Response (`ChatMessageResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | — |
| `message_id` | `string` | Yes | — |
| `content_ids` | `string`[] | Yes | — |

---

# `POST` `/attempt/chat_response`

Route: /api-reference/attempt/post-attempt-chat-response

# `POST` `/attempt/chat_response`

Chat Response

Submit a video question response.

## Request Body (`AttemptResponsePayload`)

| Field | Type | Required | Description |
|---|---|---|---|
| `chat_id` | `string` | Yes | UUID of the chat |
| `question_id` | `string` | Yes | UUID of the question being answered |
| `option_ids` | `string`[] | Yes | List of selected option UUIDs |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior call; on the ack, the server-minted soft key to activate/reject the staged response |
| `soft` | `boolean` | No | Stage the response dormant (active=False); accept activates it |
| `accept` | `boolean` | No | Ack: True activates the staged response, False rejects. Only meaningful with idempotency_key |

## Response (`ResponseAttemptApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | — |
| `message` | `string` | No | — |
| `is_correct` | `boolean` | No | — |
| `response_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |

---

# `POST` `/attempt/chat_silence`

Route: /api-reference/attempt/post-attempt-chat-silence

# `POST` `/attempt/chat_silence`

Chat Silence

End a voice session for an attempt chat.

## Request Body (`ChatSilenceRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `chat_id` | `string` | Yes | — |
| `idempotency_key` | `string` | No | — |
| `soft` | `boolean` | No | — |
| `accept` | `boolean` | No | — |

## Response (`AudioStopInternalResult`)

| Field | Type | Required | Description |
|---|---|---|---|
| `chat_id` | `string` | Yes | — |
| `stopped` | `boolean` | No | — |
| `idempotency_key` | `string` | No | — |

---

# `POST` `/attempt/chat_speak`

Route: /api-reference/attempt/post-attempt-chat-speak

# `POST` `/attempt/chat_speak`

Chat Speak

Push audio bytes into a conversation's inbound buffer (or stage them).

## Request Body (`ChatSpeakRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `conversation_id` | `string` | No | — |
| `chat_id` | `string` | No | — |
| `audio` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `soft` | `boolean` | No | — |
| `accept` | `boolean` | No | — |

## Response (`ChatSpeakResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `accepted` | `boolean` | Yes | — |
| `idempotency_key` | `string` | No | — |

---

# `POST` `/attempt/chat_strengths`

Route: /api-reference/attempt/post-attempt-chat-strengths

# `POST` `/attempt/chat_strengths`

Chat Strengths

Create strength items (with optional inline highlights) for the latest grade.

## Request Body (`ChatStrengthsRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `chat_id` | `string` | Yes | — |
| `strengths` | [`ChatStrengthItem`](/api-reference/attempt/types#chatstrengthitem)[] | Yes | — |
| `idempotency_key` | `string` | No | — |
| `soft` | `boolean` | No | — |
| `accept` | `boolean` | No | — |

## Response (`ChatStrengthsResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | — |
| `strength_ids` | `string`[] | Yes | — |
| `idempotency_key` | `string` | No | — |

---

# `POST` `/attempt/chat_voice`

Route: /api-reference/attempt/post-attempt-chat-voice

# `POST` `/attempt/chat_voice`

Chat Voice

Start a voice session for an attempt chat.

## Request Body (`ChatVoiceRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `chat_id` | `string` | Yes | — |
| `idempotency_key` | `string` | No | — |
| `soft` | `boolean` | No | — |
| `accept` | `boolean` | No | — |

## Response (`AudioStartInternalResult`)

| Field | Type | Required | Description |
|---|---|---|---|
| `chat_id` | `string` | Yes | — |
| `attempt_id` | `string` | Yes | — |
| `conversation_id` | `string` | Yes | — |
| `group_id` | `string` | Yes | — |
| `idempotency_key` | `string` | No | — |

---

# `POST` `/attempt/complete`

Route: /api-reference/attempt/post-attempt-complete

# `POST` `/attempt/complete`

Attempt Complete

Mark an entire attempt as completed.

## Request Body (`AttemptCompleteRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `attempt_id` | `string` | No | Attempt to complete (omit on the ack call) |
| `message` | `string` | No | — |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior call; on the ack, the server-minted soft key to activate/reject a staged completion |
| `soft` | `boolean` | No | Stage the completion dormant (active=False) — agent proposes; accept activates it. Composes into a dormant benchmark scenario. |
| `accept` | `boolean` | No | Ack: True activates the staged completion, False rejects. Only meaningful with idempotency_key |

## Response (`AttemptCompleteResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | — |
| `completion_id` | `string` | Yes | — |
| `attempt_id` | `string` | Yes | — |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with accept to activate/reject the staged completion. |

---

# `POST` `/attempt/context`

Route: /api-reference/attempt/post-attempt-context

# `POST` `/attempt/context`

Get Attempt Context

Get page context for the attempt artifact.

Returns docs + profile identity + evaluated permissions in a single call.
Routed through the audit wrapper so ``snapshot_key`` replays a consistent
view across related reads.

## Request Body (`DocsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entity_id` | `string` | No | — |
| `snapshot_key` | `string` | No | — |
| `schema` | `boolean` | No | If true, include MCP/tooling schema metadata (artifact, entries, resources, permission_docs, api_operations). Defaults to false for lean page-bootstrap responses. |

## Response (`ComposedContextResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Artifact name |
| `type` | `string` | Yes | Artifact type identifier |
| `description` | `string` | Yes | Human-readable description |
| `artifact` | [`DocsResponse`](/api-reference/attempt/types#docsresponse) | No | Artifact tool documentation (None unless schema=true) |
| `entries` | [`DocsResponse`](/api-reference/attempt/types#docsresponse)[] | No | Entry documentation list (None unless schema=true) |
| `resources` | [`DocsResponse`](/api-reference/attempt/types#docsresponse)[] | No | Resource documentation list (None unless schema=true) |
| `permission_docs` | [`OperationInfo`](/api-reference/attempt/types#operationinfo)[] | No | Permission function signatures for MCP/dev tooling (None unless schema=true) |
| `api_operations` | [`OperationInfo`](/api-reference/attempt/types#operationinfo)[] | No | API operation documentation (None unless schema=true) |
| `page_metadata` | [`DocsApiResponse`](/api-reference/attempt/types#docsapiresponse) | No | Page-level metadata |
| `prompts` | [`OperationPrompts`](/api-reference/attempt/types#operationprompts) | No | Starter prompts keyed by operation |
| `profile` | [`ProfileSummary`](/api-reference/attempt/types#profilesummary) | Yes | Caller identity from JWT |
| `caller_permissions` | [`CallerPermissions`](/api-reference/attempt/types#callerpermissions) | Yes | Evaluated permissions for this caller |

---

# `POST` `/attempt/dashboard`

Route: /api-reference/attempt/post-attempt-dashboard

# `POST` `/attempt/dashboard`

Get Dashboard

## Request Body (`DashboardRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `start_date` | `string` | No | Filter start date |
| `end_date` | `string` | No | Filter end date |
| `cohort_ids` | `string`[] | No | Cohort IDs to filter by |
| `simulation_ids` | `string`[] | No | Simulation IDs to filter by |
| `department_ids` | `string`[] | No | Department IDs to filter by |
| `role_ids` | `string`[] | No | Role resource IDs to filter profiles by |
| `simulation_filters` | `string`[] | No | Simulation filter strings |
| `actor_profile_id` | `string` | No | Acting user profile ID |
| `target_profile_id` | `string` | No | Target profile ID to scope data |
| `page_limit` | `integer` | No | Max items per page |
| `page_offset` | `integer` | No | Pagination offset |
| `rubric_ids` | `string`[] | No | Rubric IDs for section picker |
| `rubric_search` | `string` | No | Search string for rubrics |
| `simulation_picker_ids` | `string`[] | No | Simulation picker IDs |
| `simulation_picker_search` | `string` | No | Search string for simulations |
| `parameter_ids` | `string`[] | No | Parameter IDs for section picker |
| `parameter_search` | `string` | No | Search string for parameters |
| `scenario_ids` | `string`[] | No | Scenario IDs for section picker |
| `scenario_search` | `string` | No | Search string for scenarios |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`DashboardBundleResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `header_metrics` | [`DashboardHeaderMetrics`](/api-reference/attempt/types#dashboardheadermetrics) | No | Header summary metrics |
| `primary_metrics` | [`DashboardPrimaryMetrics`](/api-reference/attempt/types#dashboardprimarymetrics) | No | Primary dashboard metrics |
| `secondary_metrics` | [`DashboardSecondaryMetrics`](/api-reference/attempt/types#dashboardsecondarymetrics) | No | Secondary dashboard metrics |
| `footer_metrics` | [`DashboardFooterMetrics`](/api-reference/attempt/types#dashboardfootermetrics) | No | Footer dashboard metrics |
| `simulations` | [`DashboardSimulationMeta`](/api-reference/attempt/types#dashboardsimulationmeta)[] | No | Simulation metadata list |
| `scenarios` | [`DashboardScenarioMeta`](/api-reference/attempt/types#dashboardscenariometa)[] | No | Scenario metadata list |
| `rubrics` | [`DashboardRubricMeta`](/api-reference/attempt/types#dashboardrubricmeta)[] | No | Rubric metadata list |
| `parameters` | [`DashboardParameterMeta`](/api-reference/attempt/types#dashboardparametermeta)[] | No | Parameter metadata list |
| `fields` | [`DashboardFieldMeta`](/api-reference/attempt/types#dashboardfieldmeta)[] | No | Field metadata list |
| `thresholds` | [`DashboardThresholds`](/api-reference/attempt/types#dashboardthresholds) | No | Score thresholds configuration |
| `insights` | [`DashboardInsights`](/api-reference/attempt/types#dashboardinsights) | No | Generated insights per section |
| `simulation_options` | [`FilterOption`](/api-reference/attempt/types#filteroption)[] | No | Simulation filter options |
| `profile_name` | `string` | No | Target profile display name |
| `profile_emails` | `string`[] | No | Target profile email addresses |
| `profile_primary_email` | `string` | No | Target profile primary email |
| `profile_role` | `string` | No | Target profile role |
| `analytics` | [`AnalyticsFacets`](/api-reference/attempt/types#analyticsfacets) | No | Inline analytics facets for SSR |
| `history` | [`HistoryResponse`](/api-reference/attempt/types#historyresponse) | No | Always null on /get — use /attempt/dashboard/search instead |

---

# `POST` `/attempt/draft`

Route: /api-reference/attempt/post-attempt-draft

# `POST` `/attempt/draft`

Patch Chat Draft

Patch chat draft — composable infra architecture.

## Request Body (`PatchChatDraftApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `draft_id` | `string` | No | Existing draft ID to update |
| `input_draft_id` | `string` | No | Legacy alias for draft_id |
| `name` | `string` | No | — |
| `name_id` | `string` | No | — |
| `description` | `string` | No | — |
| `description_id` | `string` | No | — |
| `problem_statement` | `string` | No | — |
| `problem_statement_id` | `string` | No | — |
| `objectives` | `string`[] | No | — |
| `objective_ids` | `string`[] | No | — |
| `images` | [`app__infra__attempt__chat__types__DraftImageValue`](/api-reference/attempt/types#app-infra-attempt-chat-types-draftimagevalue)[] | No | — |
| `image_ids` | `string`[] | No | — |
| `videos` | [`app__infra__attempt__chat__types__DraftVideoValue`](/api-reference/attempt/types#app-infra-attempt-chat-types-draftvideovalue)[] | No | — |
| `video_ids` | `string`[] | No | — |
| `questions` | [`app__infra__attempt__chat__types__DraftQuestionValue`](/api-reference/attempt/types#app-infra-attempt-chat-types-draftquestionvalue)[] | No | — |
| `question_ids` | `string`[] | No | — |
| `options` | [`app__infra__attempt__chat__types__DraftOptionValue`](/api-reference/attempt/types#app-infra-attempt-chat-types-draftoptionvalue)[] | No | — |
| `option_ids` | `string`[] | No | — |
| `department_ids` | `string`[] | No | — |
| `document_ids` | `string`[] | No | — |
| `field_ids` | `string`[] | No | — |
| `flag_ids` | `string`[] | No | — |
| `parameter_field_ids` | `string`[] | No | — |
| `parameter_ids` | `string`[] | No | — |
| `persona_ids` | `string`[] | No | — |
| `scenario_ids` | `string`[] | No | — |
| `pending_ids` | `string`[] | No | Resource IDs to keep pending/inactive on the draft |
| `idempotency_key` | `string` | No | Ack key for generation/correlation flows |
| `accept` | `boolean` | No | Accept or reject pending state |

## Response (`PatchChatDraftApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the draft save succeeded |
| `draft_id` | `string` | Yes | UUID of the saved draft |
| `idempotency_key` | `string` | No | Idempotency key for client correlation |
| `message` | `string` | Yes | Response message |
| `form_state` | [`ChatDraftFormState`](/api-reference/attempt/types#chatdraftformstate) | No | Updated form state after save |

---

# `POST` `/attempt/drafts`

Route: /api-reference/attempt/post-attempt-drafts

# `POST` `/attempt/drafts`

Get Chat Drafts

List chat drafts owned by the current profile.

## Request Body (`GetChatDraftsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE substring) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GetChatDraftsApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entries` | [`GetChatDraftResponse`](/api-reference/attempt/types#getchatdraftresponse)[] | No | List of chat draft entries |

---

# `POST` `/attempt/export`

Route: /api-reference/attempt/post-attempt-export

# `POST` `/attempt/export`

Export Attempt

Artifact-level attempt export.

Dispatches on ``body.view`` to per-view exports and returns
``\{file_id, file_name, row_count\}``. Client downloads via
``/api/attempt/download/\{file_id\}`` (BFF) → ``/attempt/file/download``.

## Request Body (`ExportAttemptApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `view` | `string` | No | View discriminator: 'single' | 'dashboard' | 'reports' | 'leaderboard' | 'home' | 'practice' | 'record' | 'report' |
| `attempt_id` | `string` | No | UUID of a single attempt (required for view='single') |
| `record_id` | `string` | No | UUID of the target profile (required for view='record') |
| `date_from` | `string` | No | Optional date window start |
| `date_to` | `string` | No | Optional date window end |
| `department_ids` | `string`[] | No | Optional department filter |
| `simulation_ids` | `string`[] | No | Optional simulation filter |
| `mode` | `string` | No | Optional sub-mode within a view. Currently recognized: view=reports → mode='brightspace' (gradebook CSV only); view=home → mode='certificate' (PDF cert only) or 'attempts' (CSV only). Default (None) returns the full per-view bundle. |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior export; on the ack, the server-minted soft key to activate/reject a staged export |
| `soft` | `boolean` | No | Stage the export dormant (file chain active=False) — agent proposes; accept activates. Sim-env 'dormant export' primitive. |
| `accept` | `boolean` | No | Ack: True activates the staged export, False rejects. Only meaningful with idempotency_key |

## Response (`ExportAttemptApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource holding the export bytes |
| `file_name` | `string` | Yes | Suggested download file name |
| `row_count` | `integer` | Yes | Number of data rows in the export |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with accept to activate/reject the staged export. |

---

# `POST` `/attempt/file_download`

Route: /api-reference/attempt/post-attempt-file-download

# `POST` `/attempt/file_download`

Download File

Download a file by file entry ID.

## Request Body (`FileDownloadAttemptApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_entry to download |

## Response

```
{}
```

---

# `POST` `/attempt/file_preview`

Route: /api-reference/attempt/post-attempt-file-preview

# `POST` `/attempt/file_preview`

Preview File

Return a PNG preview of the first page of a PDF upload.

## Request Body (`FilePreviewAttemptApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_entry to preview |

## Response

```
{}
```

---

# `POST` `/attempt/generate`

Route: /api-reference/attempt/post-attempt-generate

# `POST` `/attempt/generate`

Generate Attempt

Trigger attempt generation. Returns immediately; progress via events.

## Request Body (`ArtifactGenerateRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `instructions` | `string`[] | No | — |
| `config` | [`GenerateConfig`](/api-reference/attempt/types#generateconfig) | No | — |
| `modalities` | `string`[] | No | — |
| `audios_id` | `string` | No | — |
| `conversation_id` | `string` | No | — |
| `trace_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `accept` | `boolean` | No | — |
| `wait_for_complete` | `boolean` | No | — |

## Response (`ArtifactGenerateResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `run_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `eval` | [`EvalSetup`](/api-reference/attempt/types#evalsetup) | No | — |
| `produced_media` | [`ProducedMedia`](/api-reference/attempt/types#producedmedia)[] | No | — |

---

# `POST` `/attempt/generations`

Route: /api-reference/attempt/post-attempt-generations

# `POST` `/attempt/generations`

Generations Attempt

List attempt generation groups — composable infra architecture.

## Request Body (`GenerationsAttemptApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GenerationsAttemptApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `items` | [`GenerationsAttemptListItem`](/api-reference/attempt/types#generationsattemptlistitem)[] | No | Generation groups |
| `total_count` | `integer` | No | Total number of matching generations |

---

# `POST` `/attempt/get`

Route: /api-reference/attempt/post-attempt-get

# `POST` `/attempt/get`

Attempt Get

Get attempt detail with the canonical shared attempt bundle.

## Request Body (`GetAttemptDetailRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `attempt_id` | `string` | Yes | UUID of the attempt to fetch |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GetAttemptDetailResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `attempt_exists` | `boolean` | No | Whether the attempt exists |
| `access_denied` | `boolean` | No | Whether access was denied |
| `attempt` | [`AttemptData`](/api-reference/attempt/types#attemptdata) | No | Attempt-level data |
| `simulation` | [`SimulationData`](/api-reference/attempt/types#simulationdata) | No | Simulation metadata |
| `timer` | [`TimerData`](/api-reference/attempt/types#timerdata) | No | Timer information |
| `aggregated_results` | [`AggregatedResults`](/api-reference/attempt/types#aggregatedresults) | No | Aggregated results across chats |
| `current_chat_index` | `integer` | No | Index of the current chat |
| `expected_chat_count` | `integer` | No | Expected total number of chats |
| `is_active` | `boolean` | No | Whether the attempt is currently active |
| `is_lobby` | `boolean` | No | Whether the attempt is in lobby state |
| `show_results` | `boolean` | No | Whether to show results view |
| `should_show_controls` | `boolean` | No | Whether to show UI controls |
| `is_own_attempt` | `boolean` | No | Whether this is the actor's own attempt |
| `current_chat_id` | `string` | No | ID of the current chat |
| `has_messages` | `boolean` | No | Whether the current chat has gradeable content (messages or quiz responses) |
| `available_continuation_options` | [`AvailableContinuationOptions`](/api-reference/attempt/types#availablecontinuationoptions) | No | Continuation options for infinite mode |
| `rubric_structure` | [`RubricStructureData`](/api-reference/attempt/types#rubricstructuredata) | No | Rubric structure data |
| `training_id` | `string` | No | UUID of the training |
| `chat_entry_id` | `string` | No | UUID of the chat entry |
| `next_chat_entry_id` | `string` | No | UUID of the next chat entry to set up, None when all chats are complete |
| `resources` | [`AttemptResources`](/api-reference/attempt/types#attemptresources) | No | Resource maps keyed by ID |
| `entries` | [`AttemptEntries`](/api-reference/attempt/types#attemptentries) | No | Entry payloads by type |

---

# `POST` `/attempt/group`

Route: /api-reference/attempt/post-attempt-group

# `POST` `/attempt/group`

Group Attempt

Resolve or create an attempt group with optional naming.

## Request Body (`GroupAttemptApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | No | Existing group UUID (omit to create or reuse via time window) |
| `snapshot_key` | `string` | No | Snapshot key for SETNX-race convergence on a single group across concurrent reads (e.g. parallel /context + /group + /search fan-out on page load). Echoed back in the response. |

## Response (`GroupAttemptApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Resolved or newly created group UUID |
| `name` | `string` | No | The group's current title (latest active group_names_entry, or 'New Chat' fallback for freshly minted groups) |
| `snapshot_key` | `string` | No | Snapshot key echoed back — the UUID concurrent fan-out reads converged on via SETNX. Mirrors the resolved group_id. |
| `runs` | [`GroupRun`](/api-reference/attempt/types#grouprun)[] | No | Conversation history — populated when resolving an existing group for fetch |
| `group_exists` | `boolean` | No | (detail) Whether the group exists in storage — populated when ``include_resources=True`` |
| `actor_name` | `string` | No | (detail) Display name of the current actor (caller profile) |
| `total_message_count` | `integer` | No | (detail) Total number of messages in the group |
| `models` | [`GroupResource`](/api-reference/attempt/types#groupresource)[] | No | (detail) Models used in the group |
| `agents` | [`GroupResource`](/api-reference/attempt/types#groupresource)[] | No | (detail) Agents used in the group |
| `profiles` | [`GroupResource`](/api-reference/attempt/types#groupresource)[] | No | (detail) Profiles that authored runs in this group |

---

# `POST` `/attempt/home`

Route: /api-reference/attempt/post-attempt-home

# `POST` `/attempt/home`

Home Get

Get simulations available for home (operational).

## Request Body (`GetHomeRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GetHomeResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Current user display name |
| `items` | [`ChatSimulationOperational`](/api-reference/attempt/types#chatsimulationoperational)[] | No | Available simulation cards |
| `rubrics` | [`RubricMapping`](/api-reference/attempt/types#rubricmapping)[] | No | Rubric mapping data |
| `standard_groups` | [`StandardGroupMapping`](/api-reference/attempt/types#standardgroupmapping)[] | No | Standard group mapping data |
| `standards` | [`StandardMapping`](/api-reference/attempt/types#standardmapping)[] | No | Standard mapping data |
| `analytics` | [`AnalyticsFacets`](/api-reference/attempt/types#analyticsfacets) | No | Inline analytics facets for SSR |

---

# `POST` `/attempt/image_download`

Route: /api-reference/attempt/post-attempt-image-download

# `POST` `/attempt/image_download`

Download Image

Download an image file by image entry ID.

## Request Body (`ImageDownloadAttemptApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `image_id` | `string` | Yes | UUID of the images_resource to download |

## Response

```
{}
```

---

# `POST` `/attempt/leaderboard`

Route: /api-reference/attempt/post-attempt-leaderboard

# `POST` `/attempt/leaderboard`

Get Leaderboard

## Request Body (`LeaderboardRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `start_date` | `string` | No | Filter start date |
| `end_date` | `string` | No | Filter end date |
| `cohort_ids` | `string`[] | No | Cohort IDs to filter by |
| `simulation_ids` | `string`[] | No | Simulation IDs to filter by |
| `department_ids` | `string`[] | No | Department IDs to filter by |
| `simulation_filters` | `string`[] | No | Simulation filter strings |
| `target_profile_id` | `string` | No | Target profile ID to scope data |
| `cohort_id` | `string` | No | Single cohort ID (deprecated) |
| `simulation_id` | `string` | No | Single simulation ID (deprecated) |
| `scenario_ids` | `string`[] | No | Scenario IDs to filter by |
| `search` | `string` | No | Profile name search (ILIKE) for filter dropdowns |
| `sort_by` | `string` | No | Sort field name |
| `sort_order` | `string` | No | Sort direction (asc or desc) |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`LeaderboardResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `sections` | [`LeaderboardSections`](/api-reference/attempt/types#leaderboardsections) | No | Computed leaderboard sections |
| `resources` | [`LeaderboardResources`](/api-reference/attempt/types#leaderboardresources) | No | Resource metadata for hydration |
| `analytics` | [`AnalyticsFacets`](/api-reference/attempt/types#analyticsfacets) | No | Inline analytics facets for SSR |
| `data` | [`LeaderboardDataRow`](/api-reference/attempt/types#leaderboarddatarow)[] | No | Top-25% leaderboard rows |
| `total_count` | `integer` | No | Total number of profiles matching filters (top 25% slice) |
| `simulation_options` | [`FilterOption`](/api-reference/attempt/types#filteroption)[] | No | Simulation filter options |
| `profile_options` | [`FilterOption`](/api-reference/attempt/types#filteroption)[] | No | Profile filter options |

---

# `POST` `/attempt/practice`

Route: /api-reference/attempt/post-attempt-practice

# `POST` `/attempt/practice`

Practice Get

Get simulations available for practice (operational).

## Request Body (`GetPracticeRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GetPracticeResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Current user display name |
| `items` | [`ChatSimulationOperational`](/api-reference/attempt/types#chatsimulationoperational)[] | No | Available practice simulation cards |
| `rubrics` | [`RubricMapping`](/api-reference/attempt/types#rubricmapping)[] | No | Rubric mapping data |
| `standard_groups` | [`StandardGroupMapping`](/api-reference/attempt/types#standardgroupmapping)[] | No | Standard group mapping data |
| `standards` | [`StandardMapping`](/api-reference/attempt/types#standardmapping)[] | No | Standard mapping data |
| `analytics` | [`AnalyticsFacets`](/api-reference/attempt/types#analyticsfacets) | No | Inline analytics facets for SSR |

---

# `POST` `/attempt/problem`

Route: /api-reference/attempt/post-attempt-problem

# `POST` `/attempt/problem`

Problem Attempt

Report an attempt problem — composable infra architecture.

## Request Body (`ProblemAttemptApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | `string` | Yes | Problem type: feature, bug, question, other |
| `message` | `string` | Yes | Problem description (max 1000 chars) |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior call instead of re-running |

## Response (`ProblemAttemptApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `problem_id` | `string` | Yes | UUID of the created problem |
| `success` | `boolean` | No | Whether the problem was created |
| `message` | `string` | No | Status message |

---

# `POST` `/attempt/refresh`

Route: /api-reference/attempt/post-attempt-refresh

# `POST` `/attempt/refresh`

Attempt Refresh

Refresh attempt materialized views and invalidate caches.

## Request Body

```
{
  "anyOf": [
    {
      "$ref": "#/components/schemas/RefreshApiRequest"
    },
    {
      "type": "null"
    }
  ],
  "title": "Request"
}
```

## Response (`RefreshResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | — |
| `refreshed_views` | `string`[] | Yes | — |
| `invalidated_tags` | `string`[] | Yes | — |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/attempt/report`

Route: /api-reference/attempt/post-attempt-report

# `POST` `/attempt/report`

Get Reports

Get reports artifact data via composable context resolver.

## Request Body (`ReportsRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `start_date` | `string` | No | Filter start date |
| `end_date` | `string` | No | Filter end date |
| `cohort_ids` | `string`[] | No | Cohort IDs to filter by |
| `simulation_ids` | `string`[] | No | Simulation IDs to filter by |
| `department_ids` | `string`[] | No | Department IDs to filter by |
| `role_ids` | `string`[] | No | Role resource IDs to filter profiles by |
| `simulation_filters` | `string`[] | No | Simulation filter strings |
| `actor_profile_id` | `string` | No | Acting user profile ID |
| `target_profile_id` | `string` | No | Target profile ID to scope data |
| `profile_ids` | `string`[] | No | Profile IDs to filter by |
| `scenario_ids` | `string`[] | No | Scenario IDs to filter by |
| `search` | `string` | No | Search string |
| `sort_by` | `string` | No | Sort field name |
| `sort_order` | `string` | No | Sort direction (asc or desc) |
| `page_limit` | `integer` | No | Max items per page |
| `page_offset` | `integer` | No | Pagination offset |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`ReportsResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `sections` | [`ReportsSections`](/api-reference/attempt/types#reportssections) | No | Computed report sections |
| `views` | [`ReportsViews`](/api-reference/attempt/types#reportsviews) | No | Raw MV view slices (deprecated) |
| `resources` | [`ReportsResources`](/api-reference/attempt/types#reportsresources) | No | Resource metadata for hydration |
| `total_count` | `integer` | No | Total number of matching records |
| `simulation_options` | [`FilterOption`](/api-reference/attempt/types#filteroption)[] | No | Simulation filter options |
| `profile_options` | [`FilterOption`](/api-reference/attempt/types#filteroption)[] | No | Profile filter options |
| `scenario_options` | [`FilterOption`](/api-reference/attempt/types#filteroption)[] | No | Scenario filter options |
| `analytics` | [`AnalyticsFacets`](/api-reference/attempt/types#analyticsfacets) | No | Inline analytics facets for SSR |

---

# `POST` `/attempt/search`

Route: /api-reference/attempt/post-attempt-search

# `POST` `/attempt/search`

Search Attempt

Search paginated attempt history. Canonical for all view contexts.

## Request Body (`SearchAttemptApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `target_profile_id` | `string` | No | Scope to a single profile (record-style) |
| `profile_ids` | `string`[] | No | Filter to specific profiles (intersected with visible set) |
| `cohort_ids` | `string`[] | No | Cohort IDs to filter by |
| `department_ids` | `string`[] | No | Department IDs to filter by |
| `role_ids` | `string`[] | No | Role resource IDs to filter profiles by |
| `simulation_ids` | `string`[] | No | Simulation IDs to filter by |
| `scenario_ids` | `string`[] | No | Scenario IDs to filter by |
| `practice` | `boolean` | No | True=practice-only, False=general-only, None=both |
| `infinite_mode` | `boolean` | No | Filter by infinite mode status |
| `show_archived` | `boolean` | No | Include archived attempts |
| `start_date` | `string` | No | Filter start date (ISO) |
| `end_date` | `string` | No | Filter end date (ISO) |
| `simulation_search` | `string` | No | Substring match on simulation_name |
| `scenario_search` | `string` | No | Substring match on scenario titles |
| `profile_search` | `string` | No | Substring match on profile_name |
| `sort_by` | `string` | No | Sort field |
| `sort_order` | `string` | No | Sort direction (asc or desc) |
| `page` | `integer` | No | Page number |
| `page_size` | `integer` | No | Items per page |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`HistoryResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | [`HistoryItem`](/api-reference/attempt/types#historyitem)[] | No | List of history items |
| `total_count` | `integer` | No | Total number of matching records |
| `page` | `integer` | No | Current page number |
| `page_size` | `integer` | No | Items per page |
| `total_pages` | `integer` | No | Total number of pages |
| `simulation_options` | [`FilterOption`](/api-reference/attempt/types#filteroption)[] | No | Filter options for simulations |
| `scenario_options` | [`FilterOption`](/api-reference/attempt/types#filteroption)[] | No | Filter options for scenarios |
| `profile_options` | [`FilterOption`](/api-reference/attempt/types#filteroption)[] | No | Filter options for profiles |

---

# `POST` `/attempt/start`

Route: /api-reference/attempt/post-attempt-start

# `POST` `/attempt/start`

Start Attempt

Create a new attempt from a home or practice entry.

## Request Body (`AttemptStartRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `home_id` | `string` | No | — |
| `practice_id` | `string` | No | — |
| `infinite_mode` | `boolean` | No | — |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior call; on the ack, the server-minted soft key to activate/reject a staged attempt |
| `soft` | `boolean` | No | Stage the attempt dormant (persona+attempt+junction active=False) — agent proposes; accept activates. The sim-env 'dormant attempt' primitive. |
| `accept` | `boolean` | No | Ack: True activates the staged attempt, False rejects. Only meaningful with idempotency_key |

## Response (`AttemptStartResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `attempt_id` | `string` | Yes | — |
| `chat_id` | `string` | Yes | — |
| `department_id` | `string` | No | — |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with accept to activate/reject the staged attempt. |

---

# `POST` `/attempt/stop`

Route: /api-reference/attempt/post-attempt-stop

# `POST` `/attempt/stop`

Attempt Stop

## Request Body (`AttemptStopRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior call; on the ack, set to the server-minted soft key to perform/reject a staged stop |
| `soft` | `boolean` | No | Stage the stop (record the intent without cancelling) — for composing a stop into a dormant benchmark scenario; accept performs it |
| `accept` | `boolean` | No | Ack: True performs the staged stop, False discards. Only meaningful with idempotency_key |

## Response (`AttemptStopResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | — |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with accept to perform/reject the staged stop. |

---

# `POST` `/attempt/text_download`

Route: /api-reference/attempt/post-attempt-text-download

# `POST` `/attempt/text_download`

Download Text

Download a text file by text entry ID.

## Request Body (`TextDownloadAttemptApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `text_id` | `string` | Yes | UUID of the texts_entry to download |

## Response

```
{}
```

---

# `POST` `/attempt/title`

Route: /api-reference/attempt/post-attempt-title

# `POST` `/attempt/title`

Title Attempt

Rename a attempt's group (writes group_names_entry).

## Request Body (`TitleAttemptApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Group to rename |
| `title` | `string` | Yes | New title (display name) for the group |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant rename |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`TitleAttemptApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | The group that was renamed |
| `group_name_id` | `string` | Yes | UUID of the new group_names_entry row |
| `title` | `string` | Yes | The title that was set |
| `idempotency_key` | `string` | No | Operation key echoed back |

---

# `POST` `/attempt/video_download`

Route: /api-reference/attempt/post-attempt-video-download

# `POST` `/attempt/video_download`

Download Video

Download a video file by video entry ID with range support for seeking.

## Request Body (`VideoDownloadAttemptApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `video_id` | `string` | Yes | UUID of the videos_entry to download |

## Response

```
{}
```

---

# `POST` `/attempt/watch`

Route: /api-reference/attempt/post-attempt-watch

# `POST` `/attempt/watch`

Attempt Watch Once

One-shot snapshot of run state, snapshot-replayable via ``snapshot_key``.

## Request Body (`WatchApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Chat group whose events we watch |
| `run_id` | `string` | No | Specific run to watch (e.g. the ``run_id`` returned by a prior ``X_Generate`` call). If None, watches every active run in the group at call time. |
| `wait_for_complete` | `boolean` | No | If True, block until the watched run reaches a terminal (complete/failed) event or timeout fires. If False, return current state and exit immediately. |
| `timeout_seconds` | `integer` | No | Max wait time when ``wait_for_complete=True``. |
| `snapshot_key` | `string` | No | Read snapshot key — on the one-shot POST /watch, the audit wrapper records this watch's point-in-time view (latest run state at call time) keyed by it and replays the same view on any later call with the same key. Ignored by the SSE GET stream. |

## Response (`WatchApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `runs` | [`RunStatus`](/api-reference/attempt/types#runstatus)[] | Yes | — |
| `timed_out` | `boolean` | No | — |
| `waited_seconds` | `number` | No | — |

---

# Attempt Types

Route: /api-reference/attempt/types

# Attempt Types

## `AggregatedResults`

Aggregated results for the attempt.

| Field | Type | Required | Description |
|---|---|---|---|
| `total_score` | `number` | No | Total score across all chats |
| `total_possible_points` | `number` | No | Maximum possible points |
| `percentage` | `number` | No | Score as a percentage |
| `passed` | `boolean` | No | Whether the attempt passed overall |
| `chats_completed` | `integer` | No | Number of chats completed |
| `total_chats` | `integer` | No | Total number of chats |

---

## `AnalysisEntry`

Analysis entry for chat-level analysis content.

| Field | Type | Required | Description |
|---|---|---|---|
| `content` | `string` | No | Analysis content text |

---

## `AnalyticsFacets`

Resolved analytics facets — embeddable in any artifact response.

Contains filter field visibility, available options for dropdowns,
and date range boundaries. Returned inline from artifact get/search
responses so each page has its filter facets ready for SSR.

| Field | Type | Required | Description |
|---|---|---|---|
| `fields` | [`AnalyticsFilterFields`](#analyticsfilterfields) | Yes | Filter field visibility configuration |
| `department_options` | [`AnalyticsFilterOption`](#analyticsfilteroption)[] | No | Department dropdown options |
| `cohort_options` | [`AnalyticsFilterOption`](#analyticsfilteroption)[] | No | Cohort dropdown options |
| `role_options` | [`AnalyticsRoleOption`](#analyticsroleoption)[] | No | Available role resource options |
| `attempt_options` | `string`[] | No | Available attempt options |
| `date_range_earliest` | `string` | No | Earliest available date for filtering |
| `date_range_latest` | `string` | No | Latest available date for filtering |

---

## `AnalyticsFilterField`

Visibility/disabled state for a single filter field.

| Field | Type | Required | Description |
|---|---|---|---|
| `visible` | `boolean` | No | Whether the filter field is visible |
| `disabled` | `boolean` | No | Whether the filter field is disabled |

---

## `AnalyticsFilterFields`

Per-page filter field visibility configuration.

| Field | Type | Required | Description |
|---|---|---|---|
| `date_range` | [`AnalyticsFilterField`](#analyticsfilterfield) | No | Date range filter config |
| `departments` | [`AnalyticsFilterField`](#analyticsfilterfield) | No | Department filter config |
| `cohorts` | [`AnalyticsFilterField`](#analyticsfilterfield) | No | Cohort filter config |
| `roles` | [`AnalyticsFilterField`](#analyticsfilterfield) | No | Role filter config |
| `attempts` | [`AnalyticsFilterField`](#analyticsfilterfield) | No | Attempt filter config |

---

## `AnalyticsFilterOption`

A single filter option for dropdown selectors.

| Field | Type | Required | Description |
|---|---|---|---|
| `value` | `string` | Yes | Option value for the filter |
| `label` | `string` | Yes | Human-readable option label |

---

## `AnalyticsRoleOption`

Hydrated role resource option for analytics role filters.

| Field | Type | Required | Description |
|---|---|---|---|
| `value` | `string` | Yes | Option value for the filter |
| `label` | `string` | Yes | Human-readable option label |
| `id` | `string` | Yes | Role resource UUID |
| `name` | `string` | Yes | Role resource name |
| `description` | `string` | No | Role description |
| `icon_id` | `string` | No | Icon resource UUID |
| `color_id` | `string` | No | Color resource UUID |
| `level` | `integer` | Yes | Role privilege level |

---

## `AttemptData`

Attempt-level data.

cohort_id is only populated when practice=False.
is_archived is only populated when practice=True.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | UUID of the attempt |
| `created_at` | `string` | No | ISO timestamp when attempt was created |
| `infinite_mode` | `boolean` | No | Whether infinite mode is enabled |
| `profile_id` | `string` | No | UUID of the user profile |
| `profile_name` | `string` | No | Display name of the user profile |
| `user_persona_id` | `string` | No | UUID of the user's persona entry for this attempt |
| `department_id` | `string` | No | UUID of the department |
| `cohort_id` | `string` | No | UUID of the cohort (home mode only) |
| `is_archived` | `boolean` | No | Whether the attempt is archived |

---

## `AttemptEntries`

Entry payloads grouped by entry type.

| Field | Type | Required | Description |
|---|---|---|---|
| `attempt` | [`GetAttemptResponse`](#getattemptresponse)[] | No | Attempt entry payloads |
| `attempt_chat` | [`ChatData`](#chatdata)[] | No | Chat entry payloads |
| `attempt_message` | [`MessageData`](#messagedata)[] | No | Message entry payloads |
| `runs` | [`GetRunListViewResponse`](#getrunlistviewresponse) | No | Runs list view response |

---

## `AttemptOptionValue`

Inline option value — nested under a question.

| Field | Type | Required | Description |
|---|---|---|---|
| `option_text` | `string` | Yes | — |
| `is_correct` | `boolean` | No | — |

---

## `AttemptQuestionValue`

Inline question value with optional nested options.

| Field | Type | Required | Description |
|---|---|---|---|
| `question_text` | `string` | Yes | — |
| `allow_multiple` | `boolean` | No | — |
| `options` | [`AttemptOptionValue`](#attemptoptionvalue)[] | No | — |

---

## `AttemptResources`

Resource maps keyed by ID string.

| Field | Type | Required | Description |
|---|---|---|---|
| `scenarios` | `object` | No | Scenario resources keyed by ID |
| `personas` | `object` | No | Persona resources keyed by ID |
| `documents` | `object` | No | Document resources keyed by ID |
| `images` | `object` | No | Image resources keyed by ID |
| `videos` | `object` | No | Video resources keyed by ID |
| `objectives` | `object` | No | Objective resources keyed by ID |
| `questions` | `object` | No | Question resources keyed by ID |
| `options` | `object` | No | Option resources keyed by ID |
| `problem_statements` | `object` | No | Problem statement resources keyed by ID |
| `rubrics` | `object` | No | Rubric resources keyed by ID |
| `standard_groups` | `object` | No | Standard group resources keyed by ID |
| `standards` | `object` | No | Standard resources keyed by ID |

---

## `AvailableContinuationOptions`

Available continuation options for an attempt.

| Field | Type | Required | Description |
|---|---|---|---|
| `options` | [`ContinuationOption`](#continuationoption)[] | Yes | Available continuation option bundles |

---

## `CallerPermissions`

Evaluated permissions for the current caller on this artifact type.

| Field | Type | Required | Description |
|---|---|---|---|
| `can_create` | `boolean` | Yes | Whether the caller can create new artifacts |
| `can_draft` | `boolean` | Yes | Whether the caller can create/update drafts |
| `can_duplicate` | `boolean` | Yes | Whether the caller can duplicate artifacts |
| `has_access` | `boolean` | No | Whether the caller can view this entity |
| `can_edit` | `boolean` | No | Whether the caller can edit this entity |
| `can_delete` | `boolean` | No | Whether the caller can delete this entity |
| `disabled_reason` | `string` | No | Human-readable reason if editing is disabled |

---

## `ChatAnalysisItem`

| Field | Type | Required | Description |
|---|---|---|---|
| `content` | `string` | Yes | — |

---

## `ChatData`

Chat view data with IDs for related resources.

Split into view categories:
- Normal/General View: problem_statement, objectives, personas, images
- Video/Quiz View: videos, questions, options, responses
- Both Views: documents

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | UUID of the chat |
| `created_at` | `string` | No | ISO timestamp when chat was created |
| `completed` | `boolean` | No | Whether the chat is completed |
| `is_current` | `boolean` | No | Whether this is the current chat |
| `position` | `integer` | No | Position index of the chat |
| `grade` | [`GradeData`](#gradedata) | No | Grade data for the chat |
| `feedbacks` | [`FeedbackEntry`](#feedbackentry)[] | No | Standard-level feedback entries |
| `analyses` | [`AnalysisEntry`](#analysisentry)[] | No | Chat-level analysis content |
| `show_problem_statement` | `boolean` | No | Whether to show the problem statement |
| `show_objectives` | `boolean` | No | Whether to show objectives |
| `copy_paste_allowed` | `boolean` | No | Whether copy-paste is allowed |
| `text_enabled` | `boolean` | No | Whether text input is enabled |
| `audio_enabled` | `boolean` | No | Whether audio input is enabled |
| `hints_enabled` | `boolean` | No | Whether hints should be generated on replies |
| `analyses_enabled` | `boolean` | No | Whether chat-level analyses run during grading |
| `strengths_enabled` | `boolean` | No | Whether strengths are captured during grading |
| `improvements_enabled` | `boolean` | No | Whether improvements are captured during grading |
| `problem_statement_enabled` | `boolean` | No | Whether this chat has a problem statement capability |
| `objectives_enabled` | `boolean` | No | Whether this chat has objectives capability |
| `video_enabled` | `boolean` | No | Whether this chat has a video capability |
| `images_enabled` | `boolean` | No | Whether this chat has an images capability |
| `questions_enabled` | `boolean` | No | Whether this chat has a quiz/questions capability |
| `grading_state` | [`GradingStateData`](#gradingstatedata) | No | Current grading state data |
| `dynamic_rubric` | [`DynamicRubricData`](#dynamicrubricdata) | No | Dynamic rubric data |
| `scenario_id` | `string` | No | UUID of the associated scenario |
| `problem_statement_id` | `string` | No | UUID of the problem statement |
| `objective_ids` | `string`[] | No | UUIDs of associated objectives |
| `persona_ids` | `string`[] | No | UUIDs of associated personas |
| `image_ids` | `string`[] | No | UUIDs of associated images |
| `video_ids` | `string`[] | No | UUIDs of associated videos |
| `question_ids` | `string`[] | No | UUIDs of associated questions |
| `option_ids` | `string`[] | No | UUIDs of associated options |
| `responses` | [`QuizResponse`](#quizresponse)[] | No | Quiz responses for the chat |
| `document_ids` | `string`[] | No | UUIDs of associated documents |
| `rubric_id` | `string` | No | UUID of the rubric |
| `standard_group_ids` | `string`[] | No | UUIDs of standard groups |
| `standard_ids` | `string`[] | No | UUIDs of standards |

---

## `ChatDepartmentResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `department_id` | `string` | No | — |
| `name` | `string` | No | — |
| `description` | `string` | No | — |
| `generated` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `selected` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `ChatDescriptionResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | — |
| `description` | `string` | No | — |
| `generated` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `selected` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `ChatDocumentResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `document_id` | `string` | No | — |
| `name` | `string` | No | — |
| `description` | `string` | No | — |
| `file_id` | `string` | No | — |
| `text_id` | `string` | No | — |
| `image_ids` | `string`[] | No | — |
| `template` | `boolean` | No | — |
| `parameter_field_ids` | `string`[] | No | — |
| `generated` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `selected` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `ChatDraftFormState`

Server-authoritative form state returned after draft save.

| Field | Type | Required | Description |
|---|---|---|---|
| `name_id` | `string` | No | — |
| `name` | `string` | No | — |
| `description_id` | `string` | No | — |
| `description` | `string` | No | — |
| `problem_statement_id` | `string` | No | — |
| `problem_statement` | `string` | No | — |
| `department_ids` | `string`[] | No | — |
| `document_ids` | `string`[] | No | — |
| `field_ids` | `string`[] | No | — |
| `flag_ids` | `string`[] | No | — |
| `image_ids` | `string`[] | No | — |
| `objective_ids` | `string`[] | No | — |
| `option_ids` | `string`[] | No | — |
| `parameter_field_ids` | `string`[] | No | — |
| `parameter_ids` | `string`[] | No | — |
| `persona_ids` | `string`[] | No | — |
| `question_ids` | `string`[] | No | — |
| `scenario_ids` | `string`[] | No | — |
| `video_ids` | `string`[] | No | — |
| `pending_ids` | `string`[] | No | — |

---

## `ChatFeedbackItem`

| Field | Type | Required | Description |
|---|---|---|---|
| `feedback` | `string` | Yes | — |
| `total` | `number` | No | — |

---

## `ChatFieldResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `field_id` | `string` | No | — |
| `name` | `string` | No | — |
| `description` | `string` | No | — |
| `value` | `string` | No | — |
| `conditional_parameter_ids` | `string`[] | No | — |
| `generated` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `selected` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `ChatFlagResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | — |
| `name` | `string` | No | — |
| `description` | `string` | No | — |
| `type` | `string` | No | — |
| `icon` | `string` | No | — |
| `value` | `boolean` | No | — |
| `generated` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `selected` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `ChatHighlightItem`

| Field | Type | Required | Description |
|---|---|---|---|
| `section` | `string` | Yes | — |
| `idx` | `integer` | No | — |

---

## `ChatHintItem`

| Field | Type | Required | Description |
|---|---|---|---|
| `hint` | `string` | Yes | — |
| `message_id` | `string` | No | — |
| `idx` | `integer` | No | — |

---

## `ChatImageResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `image_id` | `string` | No | — |
| `name` | `string` | No | — |
| `description` | `string` | No | — |
| `generated` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `selected` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `ChatImprovementItem`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | — |
| `description` | `string` | Yes | — |
| `message_id` | `string` | No | — |
| `replacements` | [`ChatReplacementItem`](#chatreplacementitem)[] | No | — |

---

## `ChatNameResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | — |
| `name` | `string` | No | — |
| `generated` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `selected` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `ChatObjectiveResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | — |
| `objective` | `string` | No | — |
| `generated` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `selected` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `ChatOptionResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `option_id` | `string` | No | — |
| `option_text` | `string` | No | — |
| `question_id` | `string` | No | — |
| `is_correct` | `boolean` | No | — |
| `generated` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `selected` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `ChatParameterFieldResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | — |
| `field_id` | `string` | No | — |
| `parameter_id` | `string` | No | — |
| `name` | `string` | No | — |
| `parameter_name` | `string` | No | — |
| `generated` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `selected` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `ChatPersonaResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `persona_id` | `string` | No | — |
| `name` | `string` | No | — |
| `description` | `string` | No | — |
| `icon` | `string` | No | — |
| `color` | `string` | No | — |
| `generated` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `selected` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `ChatProblemStatementResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `problem_statement_id` | `string` | No | — |
| `name` | `string` | No | — |
| `problem_statement` | `string` | No | — |
| `generated` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `selected` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `ChatQuestionResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `question_id` | `string` | No | — |
| `question_text` | `string` | No | — |
| `allow_multiple` | `boolean` | No | — |
| `time` | `integer` | No | — |
| `generated` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `selected` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `ChatReplacementItem`

| Field | Type | Required | Description |
|---|---|---|---|
| `section` | `string` | Yes | — |
| `replace` | `string` | Yes | — |
| `idx` | `integer` | No | — |

---

## `ChatScenarioResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `scenario_id` | `string` | No | — |
| `name` | `string` | No | — |
| `description` | `string` | No | — |
| `generated` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `selected` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `ChatSimulationOperational`

Simulation data for starting a chat session.

Contains data needed to start a simulation AND card display stats.
Now serves as the unified type for home/practice simulation cards.

| Field | Type | Required | Description |
|---|---|---|---|
| `simulation_id` | `string` | Yes | UUID of the simulation |
| `simulation_name` | `string` | No | Name of the simulation |
| `simulation_description` | `string` | No | Description of the simulation |
| `time_limit` | `integer` | No | Time limit in seconds |
| `chat_entry_id` | `string` | No | UUID of the chat entry |
| `home_id` | `string` | No | UUID of the home entry |
| `practice_id` | `string` | No | UUID of the practice entry |
| `scenario_ids` | `string`[] | No | Ordered list of scenario IDs |
| `cohort_ids` | `string`[] | No | Cohort IDs this simulation belongs to |
| `color` | `string` | No | Persona display color |
| `icon` | `string` | No | Persona icon identifier |
| `view_mode` | `string` | No | View mode: 'member', 'instructional', or 'practice' |
| `num_sessions` | `integer` | No | Number of attempt sessions |
| `highest_score` | `integer` | No | Highest score percentage rounded |
| `has_passed` | `boolean` | No | Whether the user has passed |
| `status` | `string` | No | Status: 'passed', 'in-progress', or 'not-started' |
| `pass_pct` | `integer` | No | Pass percentage threshold |
| `cohort_names_junction` | `string` | No | Formatted cohort names string |
| `standard_groups` | `string`[] | No | Standard group IDs as strings |
| `practice_simulation` | `boolean` | No | Whether this is a practice simulation |
| `completion_pct` | `integer` | No | Completion percentage (instructional only) |
| `passed_count` | `integer` | No | Number of students passed (instructional only) |
| `in_progress_count` | `integer` | No | Number of students in progress |
| `not_started_count` | `integer` | No | Number of students not started |

---

## `ChatStrengthItem`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | — |
| `description` | `string` | Yes | — |
| `message_id` | `string` | No | — |
| `highlights` | [`ChatHighlightItem`](#chathighlightitem)[] | No | — |

---

## `ChatVideoResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `video_id` | `string` | No | — |
| `name` | `string` | No | — |
| `description` | `string` | No | — |
| `length_seconds` | `integer` | No | — |
| `generated` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `selected` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `ColumnInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Column name |
| `type` | `string` | Yes | Column data type |
| `nullable` | `boolean` | Yes | Whether the column is nullable |

---

## `ContentEntry`

Content entry with computed display fields.

Each content has its own display info (name/icon/color) computed from
persona metadata on the server. Client renders each content with its
own persona styling.

| Field | Type | Required | Description |
|---|---|---|---|
| `content` | `string` | No | Content text of the entry |
| `name` | `string` | No | Display name (user or persona) |
| `color` | `string` | No | Persona color for display |
| `icon` | `string` | No | Icon identifier for display |
| `created_at` | `string` | No | ISO timestamp when content was created |

---

## `ContinuationOption`

A bundle of consecutive scenarios that can be reused from previous attempts.

| Field | Type | Required | Description |
|---|---|---|---|
| `scenarios` | [`PreviousChatOption`](#previouschatoption)[] | Yes | Scenarios in this continuation bundle |
| `total_score` | `number` | Yes | Combined score across scenarios |
| `total_percentage` | `number` | No | Combined score as a percentage |
| `total_time` | `number` | Yes | Combined time across scenarios |

---

## `DashboardFieldMeta`

| Field | Type | Required | Description |
|---|---|---|---|
| `field_id` | `string` | No | Field identifier |
| `name` | `string` | No | Field display name |
| `description` | `string` | No | Field description |
| `parameter_id` | `string` | No | Parent parameter ID |
| `parameter_name` | `string` | No | Parent parameter name |

---

## `DashboardFooterMetrics`

| Field | Type | Required | Description |
|---|---|---|---|
| `scenario_performance` | [`FooterScenarioPerformance`](#footerscenarioperformance) | No | Scenario attribute performance data |
| `scenario_stats` | [`FooterScenarioStats`](#footerscenariostats) | No | Numeric scenario statistics |
| `scenario_simulation_performance` | [`FooterScenarioSimulationPerformance`](#footerscenariosimulationperformance) | No | Per-simulation scenario performance |
| `scenario_composition` | [`FooterScenarioComposition`](#footerscenariocomposition) | No | Scenario composition analysis |

---

## `DashboardHeaderMetric`

| Field | Type | Required | Description |
|---|---|---|---|
| `current_value` | `number` \| `integer` | No | Current metric value |
| `trend_data` | [`DashboardTrendPoint`](#dashboardtrendpoint)[] | No | Time-series trend data points |
| `has_data` | `boolean` | No | Whether metric has any data |
| `trend_analysis` | `string` | No | Textual trend analysis summary |
| `status` | `string` | No | Metric status indicator |

---

## `DashboardHeaderMetrics`

| Field | Type | Required | Description |
|---|---|---|---|
| `average_score` | [`DashboardHeaderMetric`](#dashboardheadermetric) | No | Average score metric |
| `completion_percentage` | [`DashboardHeaderMetric`](#dashboardheadermetric) | No | Completion percentage metric |
| `first_attempt_pass_rate` | [`DashboardHeaderMetric`](#dashboardheadermetric) | No | First attempt pass rate metric |
| `highest_score` | [`DashboardHeaderMetric`](#dashboardheadermetric) | No | Highest score metric |
| `messages_per_session` | [`DashboardHeaderMetric`](#dashboardheadermetric) | No | Messages per session metric |
| `persona_response_times` | [`DashboardHeaderMetric`](#dashboardheadermetric) | No | Persona response times metric |
| `session_efficiency` | [`DashboardHeaderMetric`](#dashboardheadermetric) | No | Session efficiency metric |
| `stagnation_rate` | [`DashboardHeaderMetric`](#dashboardheadermetric) | No | Stagnation rate metric |
| `time_spent` | [`DashboardHeaderMetric`](#dashboardheadermetric) | No | Time spent metric |
| `total_attempts` | [`DashboardHeaderMetric`](#dashboardheadermetric) | No | Total attempts metric |

---

## `DashboardInsights`

| Field | Type | Required | Description |
|---|---|---|---|
| `rubric_trend` | `string` | No | Rubric trend insight text |
| `rubric_heatmap` | `string` | No | Rubric heatmap insight text |
| `attempt_improvement` | `string` | No | Attempt improvement insight text |
| `skill_performance` | `string` | No | Skill performance insight text |
| `scenario_performance` | `string` | No | Scenario performance insight text |
| `scenario_stats` | `string` | No | Scenario stats insight text |
| `scenario_simulation_performance` | `string` | No | Scenario simulation insight text |
| `scenario_composition` | `string` | No | Scenario composition insight text |
| `persona` | `object` | No | Per-persona insights |
| `cohort` | `object` | No | Per-cohort insights |

---

## `DashboardParameterMeta`

| Field | Type | Required | Description |
|---|---|---|---|
| `parameter_id` | `string` | No | Parameter identifier |
| `name` | `string` | No | Parameter display name |
| `description` | `string` | No | Parameter description |
| `numerical` | `boolean` | No | Whether parameter is numerical |
| `document_parameter` | `boolean` | No | Whether parameter is document-type |
| `persona_parameter` | `boolean` | No | Whether parameter is persona-type |

---

## `DashboardPrimaryMetrics`

| Field | Type | Required | Description |
|---|---|---|---|
| `rubric_heatmap` | [`PrimaryRubricHeatmap`](#primaryrubricheatmap) | No | Rubric correlation heatmap data |
| `rubric_trend` | [`PrimaryRubricTrend`](#primaryrubrictrend) | No | Rubric trend over time |
| `skill_performance` | [`SecondarySkillPerformance`](#secondaryskillperformance) | No | Skill performance radar data |

---

## `DashboardRubricMeta`

| Field | Type | Required | Description |
|---|---|---|---|
| `rubric_id` | `string` | No | Rubric identifier |
| `name` | `string` | No | Rubric display name |
| `description` | `string` | No | Rubric description |

---

## `DashboardScenarioMeta`

| Field | Type | Required | Description |
|---|---|---|---|
| `scenario_id` | `string` | No | Scenario identifier |
| `name` | `string` | No | Scenario display name |
| `description` | `string` | No | Scenario description |

---

## `DashboardSecondaryMetrics`

| Field | Type | Required | Description |
|---|---|---|---|
| `persona_performance` | [`PrimaryPersonaPerformance`](#primarypersonaperformance) | No | Persona performance data |
| `cohort_performance` | [`SecondaryCohortPerformance`](#secondarycohortperformance) | No | Cohort performance data |
| `attempt_improvement` | [`SecondaryAttemptImprovement`](#secondaryattemptimprovement) | No | Attempt improvement data |

---

## `DashboardSimulationMeta`

| Field | Type | Required | Description |
|---|---|---|---|
| `simulation_id` | `string` | No | Simulation identifier |
| `name` | `string` | No | Simulation display name |
| `description` | `string` | No | Simulation description |
| `department_ids` | `string`[] | No | Associated department IDs |
| `time_limit` | `integer` | No | Time limit in seconds |

---

## `DashboardThresholds`

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `number` | No | Success threshold value |
| `warning` | `number` | No | Warning threshold value |
| `danger` | `number` | No | Danger threshold value |

---

## `DashboardTrendPoint`

| Field | Type | Required | Description |
|---|---|---|---|
| `date` | `string` \| `string` | No | Date of the trend data point |
| `value` | `number` | No | Metric value at this point |
| `count` | `integer` | No | Number of observations |

---

## `DocsApiResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `list` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `detail` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `new` | [`PageMetaItem`](#pagemetaitem) | Yes | — |

---

## `DocsResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Resource or entry name |
| `type` | `string` | Yes | Resource or entry type identifier |
| `description` | `string` | Yes | Human-readable description |
| `materialized_view` | [`MvInfo`](#mvinfo) | No | Materialized view metadata |
| `tables` | [`TableInfo`](#tableinfo)[] | Yes | Related database tables |
| `operations` | [`OperationInfo`](#operationinfo)[] | Yes | Available operations |

---

## `DynamicRubricData`

Dynamic rubric information for a chat.

| Field | Type | Required | Description |
|---|---|---|---|
| `chat_id` | `string` | No | UUID of the chat |
| `score` | `number` | No | Overall rubric score |
| `passed` | `boolean` | No | Whether the rubric was passed |
| `time_taken` | `number` | No | Time taken in seconds |
| `skill_scores` | [`SkillScore`](#skillscore)[] | No | Scores per skill |
| `skill_feedbacks` | [`SkillFeedback`](#skillfeedback)[] | No | Feedback per skill |
| `total_possible_points` | `number` | No | Maximum possible points |

---

## `EvalSetup`

Run-level eval scaffold — first-class on the generate response.

Audit's ``**output`` spread carries this onto
``<artifact>.generate.completed``. Null when no rubric-bearing
agent participated.

| Field | Type | Required | Description |
|---|---|---|---|
| `test_id` | `string` | Yes | — |
| `invocations` | [`InvocationSlot`](#invocationslot)[] | Yes | — |

---

## `FeedbackEntry`

Feedback by standard for grading state.

standard_group_id is derived from standards metadata lookup.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | UUID of the feedback entry |
| `standard_id` | `string` | No | UUID of the associated standard |
| `standard_group_id` | `string` | No | UUID of the standard group |
| `total` | `number` | No | Total score for this standard |
| `feedback` | `string` | No | Feedback text for this standard |

---

## `FilterOption`

A single filter option for dropdown selectors.

| Field | Type | Required | Description |
|---|---|---|---|
| `value` | `string` | Yes | Internal value for the filter option |
| `label` | `string` | No | Display label for the filter option |
| `count` | `integer` | No | Number of matching records |

---

## `FooterNumericAttemptFact`

| Field | Type | Required | Description |
|---|---|---|---|
| `parameter_id` | `string` | No | Parameter identifier |
| `level_label` | `string` | No | Numeric level label |
| `level_value` | `number` | No | Numeric level value |
| `score` | `number` | No | Score value |
| `attempts` | `integer` | No | Number of attempts |

---

## `FooterNumericScenarioFact`

| Field | Type | Required | Description |
|---|---|---|---|
| `parameter_id` | `string` | No | Parameter identifier |
| `scenario_id` | `string` | No | Associated scenario ID |
| `level_label` | `string` | No | Numeric level label |
| `level_value` | `number` | No | Numeric level value |

---

## `FooterScenarioAttributeAttemptFact`

| Field | Type | Required | Description |
|---|---|---|---|
| `parameter_id` | `string` | No | Parameter identifier |
| `parameter_item_id` | `string` | No | Parameter item identifier |
| `date` | `string` | No | Date of the attempt fact |
| `timestamp` | `integer` | No | Unix timestamp |
| `avg_score` | `number` | No | Average score |
| `attempts` | `integer` | No | Number of attempts |
| `passed_attempts` | `integer` | No | Number of passing attempts |

---

## `FooterScenarioAttributeScenarioFact`

| Field | Type | Required | Description |
|---|---|---|---|
| `parameter_id` | `string` | No | Parameter identifier |
| `parameter_item_id` | `string` | No | Parameter item identifier |
| `scenario_id` | `string` | No | Associated scenario ID |

---

## `FooterScenarioComposition`

| Field | Type | Required | Description |
|---|---|---|---|
| `scenario_summaries` | [`FooterScenarioCompositionSummary`](#footerscenariocompositionsummary)[] | No | Per-scenario composition summaries |
| `chat_parameter_facts` | [`FooterScenarioCompositionParamFact`](#footerscenariocompositionparamfact)[] | No | Chat parameter composition facts |
| `valid_scenario_ids` | `string`[] | No | Valid scenario IDs in scope |
| `status` | `string` | No | Section status indicator |

---

## `FooterScenarioCompositionParamFact`

Parameter counts per (scenario, group) — group is 'high' or 'low'.

| Field | Type | Required | Description |
|---|---|---|---|
| `scenario_id` | `string` | No | Associated scenario ID |
| `group` | `string` | No | Score group (high or low) |
| `parameter_id` | `string` | No | Parameter identifier |
| `parameter_item_id` | `string` | No | Parameter item identifier |
| `chat_count` | `integer` | No | Number of chats in this group |

---

## `FooterScenarioCompositionSummary`

Per-scenario summary with high/low chat split.

| Field | Type | Required | Description |
|---|---|---|---|
| `scenario_id` | `string` | No | Associated scenario ID |
| `name` | `string` | No | Scenario display name |
| `total_chats` | `integer` | No | Total number of chats |
| `high_count` | `integer` | No | Count of high-scoring chats |
| `low_count` | `integer` | No | Count of low-scoring chats |
| `high_avg_score` | `number` | No | Average score of high group |
| `low_avg_score` | `number` | No | Average score of low group |

---

## `FooterScenarioPerformance`

| Field | Type | Required | Description |
|---|---|---|---|
| `attribute_attempt_facts` | [`FooterScenarioAttributeAttemptFact`](#footerscenarioattributeattemptfact)[] | No | Attribute-level attempt facts |
| `attribute_scenario_facts` | [`FooterScenarioAttributeScenarioFact`](#footerscenarioattributescenariofact)[] | No | Attribute-level scenario facts |
| `valid_parameter_ids` | `string`[] | No | Valid parameter IDs in scope |
| `status` | `string` | No | Section status indicator |

---

## `FooterScenarioSimulationFact`

| Field | Type | Required | Description |
|---|---|---|---|
| `scenario_id` | `string` | No | Associated scenario ID |
| `simulation_id` | `string` | No | Associated simulation ID |
| `simulation_name` | `string` | No | Simulation display name |
| `avg_score` | `number` | No | Average score |
| `success_rate` | `number` | No | Success rate percentage |
| `total_attempts` | `integer` | No | Total number of attempts |
| `completed_attempts` | `integer` | No | Number of completed attempts |

---

## `FooterScenarioSimulationPerformance`

| Field | Type | Required | Description |
|---|---|---|---|
| `simulation_facts` | [`FooterScenarioSimulationFact`](#footerscenariosimulationfact)[] | No | Per-simulation scenario facts |
| `valid_scenario_ids` | `string`[] | No | Valid scenario IDs in scope |
| `status` | `string` | No | Section status indicator |

---

## `FooterScenarioStats`

| Field | Type | Required | Description |
|---|---|---|---|
| `numeric_attempt_facts` | [`FooterNumericAttemptFact`](#footernumericattemptfact)[] | No | Numeric parameter attempt facts |
| `numeric_scenario_facts` | [`FooterNumericScenarioFact`](#footernumericscenariofact)[] | No | Numeric parameter scenario facts |
| `valid_numeric_parameter_ids` | `string`[] | No | Valid numeric parameter IDs |
| `status` | `string` | No | Section status indicator |

---

## `GenerateConfig`

Developer configuration — all optional with sensible defaults.

| Field | Type | Required | Description |
|---|---|---|---|
| `operations` | `string`[] | No | — |
| `dangerous` | `boolean` | No | — |
| `params` | `object` | No | — |
| `group_id` | `string` | No | — |

---

## `GenerationsAttemptListItem`

Single generation group in the attempt generations response.

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | UUID of the generation group |
| `session_id` | `string` | No | UUID of the parent session |
| `group_name` | `string` | No | Name of the generation group |
| `created_at` | `string` | No | Timestamp of the generation |

---

## `GetAttemptResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `attempt_id` | `string` | Yes | — |
| `simulation_id` | `string` | Yes | — |
| `profile_id` | `string` | Yes | — |
| `role_id` | `string` | No | — |
| `user_persona_id` | `string` | Yes | — |
| `personas_id` | `string` | Yes | — |
| `cohort_id` | `string` | Yes | — |
| `department_id` | `string` | Yes | — |
| `practice` | `boolean` | Yes | — |
| `attempt_created_at` | `string` | Yes | — |
| `infinite_mode` | `boolean` | Yes | — |
| `num_chats` | `integer` | Yes | — |
| `is_archived` | `boolean` | No | — |
| `is_completed` | `boolean` | No | — |
| `scenario_ids` | `string`[] | Yes | — |
| `chat_entry_id` | `string` | Yes | — |
| `attempt_chat_id` | `string` | Yes | — |

---

## `GetChatDraftResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | UUID of the draft |
| `created_at` | `string` | Yes | Creation timestamp |
| `generated` | `boolean` | Yes | Whether this was AI-generated |
| `mcp` | `boolean` | Yes | Whether MCP tooling was used |
| `active` | `boolean` | Yes | Whether this draft is active |
| `session_id` | `string` | Yes | Associated session UUID |
| `name` | `string` | No | Immutable draft label set at create time |
| `department_ids` | `string`[] | Yes | Associated department UUIDs |
| `pending_department_ids` | `string`[] | No | Pending department UUIDs |
| `description_ids` | `string`[] | Yes | Associated description UUIDs |
| `pending_description_ids` | `string`[] | No | Pending description UUIDs |
| `document_ids` | `string`[] | Yes | Associated document UUIDs |
| `pending_document_ids` | `string`[] | No | Pending document UUIDs |
| `field_ids` | `string`[] | Yes | Associated field UUIDs |
| `pending_field_ids` | `string`[] | No | Pending field UUIDs |
| `flag_ids` | `string`[] | Yes | Associated flag UUIDs |
| `pending_flag_ids` | `string`[] | No | Pending flag UUIDs |
| `image_ids` | `string`[] | Yes | Associated image UUIDs |
| `pending_image_ids` | `string`[] | No | Pending image UUIDs |
| `name_ids` | `string`[] | Yes | Associated name UUIDs |
| `pending_name_ids` | `string`[] | No | Pending name UUIDs |
| `objective_ids` | `string`[] | Yes | Associated objective UUIDs |
| `pending_objective_ids` | `string`[] | No | Pending objective UUIDs |
| `option_ids` | `string`[] | Yes | Associated option UUIDs |
| `pending_option_ids` | `string`[] | No | Pending option UUIDs |
| `parameter_field_ids` | `string`[] | Yes | Associated parameter field UUIDs |
| `pending_parameter_field_ids` | `string`[] | No | Pending parameter field UUIDs |
| `parameter_ids` | `string`[] | Yes | Associated parameter UUIDs |
| `pending_parameter_ids` | `string`[] | No | Pending parameter UUIDs |
| `persona_ids` | `string`[] | Yes | Associated persona UUIDs |
| `pending_persona_ids` | `string`[] | No | Pending persona UUIDs |
| `problem_statement_ids` | `string`[] | Yes | Associated problem statement UUIDs |
| `pending_problem_statement_ids` | `string`[] | No | Pending problem statement UUIDs |
| `profile_ids` | `string`[] | Yes | Associated profile UUIDs |
| `question_ids` | `string`[] | Yes | Associated question UUIDs |
| `pending_question_ids` | `string`[] | No | Pending question UUIDs |
| `scenario_ids` | `string`[] | Yes | Associated scenario UUIDs |
| `pending_scenario_ids` | `string`[] | No | Pending scenario UUIDs |
| `video_ids` | `string`[] | Yes | Associated video UUIDs |
| `pending_video_ids` | `string`[] | No | Pending video UUIDs |

---

## `GetRunListViewResponse`

Response containing run list data.

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | [`RunViewItem`](#runviewitem)[] | No | Run data items |
| `total_count` | `integer` | No | Total count before pagination |

---

## `GradeData`

Grade information for a chat (no id - not a resource).

| Field | Type | Required | Description |
|---|---|---|---|
| `score` | `number` | No | Grade score achieved |
| `passed` | `boolean` | No | Whether the grade is passing |
| `description` | `string` | No | Grade description text |
| `time_taken` | `integer` | No | Time taken in seconds |
| `total_points` | `number` | No | Total available points |
| `pass_points` | `number` | No | Points required to pass |

---

## `GradingStateData`

Grading state for a chat in Record format.

All fields are Records keyed by standard_id strings.
This is the exact format the client needs - no transformation required.

| Field | Type | Required | Description |
|---|---|---|---|
| `achieved_standards` | `object` | No | Map of standard_id to achieved status |
| `passed_standards` | `object` | No | Map of standard_id to passed status |
| `feedback_by_standard_id` | `object` | No | Map of standard_id to feedback text |

---

## `GroupCall`

Tool call referenced by a message.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `tool_name` | `string` | No | — |
| `template_name` | `string` | No | — |
| `tool` | `object` | No | — |
| `ledger_status` | `string` | No | — |
| `ledger_operation` | `string` | No | — |
| `ledger_artifact` | `string` | No | — |
| `ledger_artifact_id` | `string` | No | — |

---

## `GroupMessage`

Message within a run.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `role` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `text_ids` | `string`[] | No | — |
| `audio_ids` | `string`[] | No | — |
| `image_ids` | `string`[] | No | — |
| `video_ids` | `string`[] | No | — |
| `file_ids` | `string`[] | No | — |
| `call_ids` | `string`[] | No | — |
| `calls` | [`GroupCall`](#groupcall)[] | No | — |
| `reasoning` | `boolean` | No | True when this row is a chain-of-thought trace persisted alongside the assistant answer (rendered as a collapsed accordion). |
| `in_context` | `boolean` | No | Whether this message is included in the LLM context for the next generation. Mirrors the dedup pass that builds chat history (see in_context_reason). |
| `in_context_reason` | `string` | No | Why this message is in/out of LLM context. 'kept' = included; 'deduped_read' = older read-only call to a tool that has a fresher result later in the group; future values may include 'trimmed_top_n'. |

---

## `GroupResource`

Lightweight `\{id, name\}` for cross-referencing run-level ids
(``model_id`` / ``agent_id`` / ``profile_id``) against human-readable
names on the analytics panel. Names come from the canonical
``get_models`` / ``get_agents`` / ``get_profiles`` black boxes.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `name` | `string` | No | — |

---

## `GroupRun`

Run within a group, with its messages.

Carries token / cost / model / agent / profile attribution so the
analytics view can render per-run cost + actor info without a
parallel detail shape. ``profile_id`` is the authoring profile
(human user), ``agent_id`` is the LLM-side actor, ``model_id`` is
the model used by that agent. All optional — runs predating these
columns or with unresolved attributions surface ``None``.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `input_tokens` | `integer` | No | — |
| `output_tokens` | `integer` | No | — |
| `cached_input_tokens` | `integer` | No | — |
| `cost` | `number` | No | — |
| `model_id` | `string` | No | — |
| `agent_id` | `string` | No | — |
| `profile_id` | `string` | No | — |
| `previous_context_start_index` | `integer` | No | Index in ``messages`` where the current run's own messages begin; earlier rows are previous-context replay. ``None`` when the run has no previous context attached. |
| `messages` | [`GroupMessage`](#groupmessage)[] | No | — |

---

## `HighlightEntry`

Highlight entry within a strength.

| Field | Type | Required | Description |
|---|---|---|---|
| `section` | `string` | No | Highlighted text section |
| `idx` | `integer` | No | Index position of the highlight |

---

## `HintEntry`

Hint entry (practice mode only, message_id implied by parent).

| Field | Type | Required | Description |
|---|---|---|---|
| `hint` | `string` | No | Hint text for practice mode |
| `idx` | `integer` | No | Index position of the hint |

---

## `HistoryItem`

Single attempt row in history list.

| Field | Type | Required | Description |
|---|---|---|---|
| `attempt_id` | `string` | Yes | UUID of the attempt |
| `date` | `string` | No | Formatted date string of the attempt |
| `profile_id` | `string` | No | UUID of the profile who took the attempt |
| `profile_name` | `string` | No | Display name of the profile |
| `simulation_id` | `string` | No | UUID of the simulation |
| `simulation_name` | `string` | No | Display name of the simulation |
| `num_scenarios` | `integer` | No | Total number of scenarios in the attempt |
| `num_scenarios_completed` | `integer` | No | Number of scenarios completed |
| `infinite_mode` | `boolean` | No | Whether the attempt is in infinite mode |
| `time_limit` | `integer` | No | Time limit in seconds |
| `persona_names_junction` | `string`[] | No | Persona names from junction table |
| `persona_colors_junction` | `string`[] | No | Persona colors from junction table |
| `scenario_ids` | `string`[] | No | UUIDs of associated scenarios |
| `scenario_titles` | `string`[] | No | Titles of associated scenarios |
| `department_ids` | `string`[] | No | Associated department IDs |
| `score` | `integer` | No | Overall attempt score |
| `score_status` | `string` | No | Score status label (e.g. pass, fail) |
| `pass_pct` | `integer` | No | Pass percentage threshold |
| `show_view` | `boolean` | No | Whether the view action is available |
| `show_continue` | `boolean` | No | Whether the continue action is available |
| `is_archived` | `boolean` | No | Whether the attempt is archived |
| `practice_simulation` | `boolean` | No | Whether this is a practice simulation |
| `practice_scenario_id` | `string` | No | UUID of the practice scenario |

---

## `HistoryResponse`

Paginated attempt history list.

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | [`HistoryItem`](#historyitem)[] | No | List of history items |
| `total_count` | `integer` | No | Total number of matching records |
| `page` | `integer` | No | Current page number |
| `page_size` | `integer` | No | Items per page |
| `total_pages` | `integer` | No | Total number of pages |
| `simulation_options` | [`FilterOption`](#filteroption)[] | No | Filter options for simulations |
| `scenario_options` | [`FilterOption`](#filteroption)[] | No | Filter options for scenarios |
| `profile_options` | [`FilterOption`](#filteroption)[] | No | Filter options for profiles |

---

## `InvocationSlot`

One agent's slot in a multi-agent generation pool.

Populated by ``setup_generation_test`` when an agent carries a
rubric. The client uses these IDs to drive the eval workflow:
review the candidate's output, optionally fire a grader against
its ``invocation_id``, and promote/reject by call_id via the
existing ``idempotency_key + accept`` pattern.

| Field | Type | Required | Description |
|---|---|---|---|
| `invocation_id` | `string` | Yes | — |
| `agent_id` | `string` | Yes | — |
| `rubric_id` | `string` | No | — |

---

## `LeaderboardAccoladeWinner`

Winner summary for a leaderboard accolade.

| Field | Type | Required | Description |
|---|---|---|---|
| `profile_id` | `string` | No | Winner profile identifier |
| `name` | `string` | No | Winner display name |
| `value` | `number` \| `integer` | No | Winning metric value |
| `details` | `string` | No | Additional accolade details |

---

## `LeaderboardAccoladeWinners`

Deterministic accolade winners computed server-side.

| Field | Type | Required | Description |
|---|---|---|---|
| `highest_scorer` | [`LeaderboardAccoladeWinner`](#leaderboardaccoladewinner) | No | Highest scorer accolade winner |
| `perfect_score` | [`LeaderboardAccoladeWinner`](#leaderboardaccoladewinner) | No | Perfect score accolade winner |
| `longest_convo` | [`LeaderboardAccoladeWinner`](#leaderboardaccoladewinner) | No | Longest conversation accolade winner |
| `response_times` | [`LeaderboardAccoladeWinner`](#leaderboardaccoladewinner) | No | Best response times accolade winner |
| `quickest_pass` | [`LeaderboardAccoladeWinner`](#leaderboardaccoladewinner) | No | Quickest pass accolade winner |
| `the_persistent` | [`LeaderboardAccoladeWinner`](#leaderboardaccoladewinner) | No | Most persistent accolade winner |
| `marathon_runner` | [`LeaderboardAccoladeWinner`](#leaderboardaccoladewinner) | No | Marathon runner accolade winner |
| `rapid_riser` | [`LeaderboardAccoladeWinner`](#leaderboardaccoladewinner) | No | Rapid riser accolade winner |

---

## `LeaderboardDataRow`

Normalized leaderboard row consumed by UI.

| Field | Type | Required | Description |
|---|---|---|---|
| `rank` | `integer` | No | Leaderboard rank position |
| `profile_id` | `string` | No | Profile identifier |
| `name` | `string` | No | Profile display name |
| `simulation_ids` | `string`[] | No | Associated simulation IDs |
| `scenario_ids` | `string`[] | No | Associated scenario IDs |
| `metrics_entry` | [`LeaderboardMetricsEntry`](#leaderboardmetricsentry) | No | Row-level metric values |

---

## `LeaderboardHeaderMetrics`

Top-level leaderboard summary metrics.

| Field | Type | Required | Description |
|---|---|---|---|
| `total_profiles` | [`LeaderboardMetric`](#leaderboardmetric) | No | Total profiles metric |
| `total_attempts` | [`LeaderboardMetric`](#leaderboardmetric) | No | Total attempts metric |
| `average_score` | [`LeaderboardMetric`](#leaderboardmetric) | No | Average score metric |
| `perfect_scores` | [`LeaderboardMetric`](#leaderboardmetric) | No | Perfect scores metric |

---

## `LeaderboardMetric`

Metric envelope expected by leaderboard UI.

| Field | Type | Required | Description |
|---|---|---|---|
| `has_data` | `boolean` | No | Whether metric has any data |
| `method` | `string` | No | Aggregation method used |
| `current_value` | `number` \| `integer` | No | Current metric value |
| `key_field` | `string` | No | Key field name for the metric |
| `trend_data` | `string`[] | No | Trend data points |
| `data_points` | `string`[] | No | Raw data point values |
| `hover` | `string` | No | Hover tooltip text |

---

## `LeaderboardMetricsEntry`

Row metrics for leaderboard cards and table.

| Field | Type | Required | Description |
|---|---|---|---|
| `total_attempts` | [`LeaderboardMetric`](#leaderboardmetric) | No | Total attempts metric |
| `highest_score_avg` | [`LeaderboardMetric`](#leaderboardmetric) | No | Highest score average metric |
| `messages_per_session` | [`LeaderboardMetric`](#leaderboardmetric) | No | Messages per session metric |
| `persona_response_seconds` | [`LeaderboardMetric`](#leaderboardmetric) | No | Persona response time metric |
| `time_spent_minutes` | [`LeaderboardMetric`](#leaderboardmetric) | No | Time spent metric in minutes |
| `improvement_rate_per_day` | [`LeaderboardMetric`](#leaderboardmetric) | No | Daily improvement rate metric |
| `perfect_score_count` | [`LeaderboardMetric`](#leaderboardmetric) | No | Perfect score count metric |
| `quickest_pass_minutes` | [`LeaderboardMetric`](#leaderboardmetric) | No | Quickest pass time metric |

---

## `LeaderboardResources`

Resource metadata keyed by ID for normalized hydration.

| Field | Type | Required | Description |
|---|---|---|---|
| `profiles` | `object` | No | Profile resources keyed by ID |
| `simulations` | `object` | No | Simulation resources keyed by ID |
| `scenarios` | `object` | No | Scenario resources keyed by ID |

---

## `LeaderboardSectionStatus`

Section-level status metadata.

| Field | Type | Required | Description |
|---|---|---|---|
| `has_data` | `boolean` | No | Whether section has any data |
| `status` | `string` | No | Section status indicator |
| `note` | `string` | No | Optional status note |

---

## `LeaderboardSections`

Business-computed section skeletons (built in permissions.py).

| Field | Type | Required | Description |
|---|---|---|---|
| `header_metrics` | [`LeaderboardHeaderMetrics`](#leaderboardheadermetrics) | No | Header summary metrics |
| `rankings` | [`LeaderboardSectionStatus`](#leaderboardsectionstatus) | No | Rankings section status |
| `accolades` | [`LeaderboardSectionStatus`](#leaderboardsectionstatus) | No | Accolades section status |
| `trends` | [`LeaderboardSectionStatus`](#leaderboardsectionstatus) | No | Trends section status |
| `filters` | [`LeaderboardSectionStatus`](#leaderboardsectionstatus) | No | Filters section status |
| `accolade_winners` | [`LeaderboardAccoladeWinners`](#leaderboardaccoladewinners) | No | Computed accolade winners |

---

## `MessageData`

Message with contents, feedbacks, and hints.

- contents: Array of content entries with display info (name/icon/color)
- feedbacks: Unified strengths/improvements (only present after grading)
- hints: Practice mode hints (only present in practice mode)

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | UUID of the message |
| `chat_id` | `string` | No | UUID of the parent chat |
| `type` | `string` | No | Message type: 'query' or 'response' |
| `created_at` | `string` | No | ISO timestamp when message was created |
| `completed` | `boolean` | No | Whether the message is complete |
| `contents` | [`ContentEntry`](#contententry)[] | No | Content entries with display info |
| `feedbacks` | [`MessageFeedbackEntry`](#messagefeedbackentry)[] | No | Unified strength and improvement feedbacks |
| `hints` | [`HintEntry`](#hintentry)[] | No | Hints for practice mode |
| `parent_message_id` | `string` | No | UUID of the parent message in tree |
| `sibling_index` | `integer` | No | Index among sibling messages |
| `sibling_count` | `integer` | No | Total number of sibling messages |
| `audios_id` | `string` | No | UUID of the attached audios_resource, if any |

---

## `MessageFeedbackEntry`

Unified feedback entry for messages (strength or improvement).

Combines strengths and improvements into a single type with a `type` field.
- type="strength": has highlights (sections to highlight as good)
- type="improvement": has replaces (sections to replace with suggestions)

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | Unique ID: \{message_id\}-\{type\}-\{index\} |
| `name` | `string` | No | Name of the feedback item |
| `description` | `string` | No | Description of the feedback |
| `type` | `string` | No | Feedback type: 'strength' or 'improvement' |
| `highlights` | [`HighlightEntry`](#highlightentry)[] | No | Highlighted sections for strengths |
| `replaces` | [`ReplacementEntry`](#replacemententry)[] | No | Replacement suggestions for improvements |

---

## `MvInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Materialized view name |
| `definition` | `string` | Yes | SQL definition of the view |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the view |

---

## `OperationInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Operation name |
| `description` | `string` | Yes | Human-readable description of the operation |
| `params` | [`ParamInfo`](#paraminfo)[] | Yes | List of operation parameters |
| `returns` | `object` | No | Return type schema |

---

## `OperationPrompts`

Starter prompts keyed by operation name.

Each key is an operation (e.g. "create", "search", "draft", "export")
and the value is a list of starter prompts for that operation.
The client picks from the operations the caller has permission for
and rotates through them.

| Field | Type | Required | Description |
|---|---|---|---|
| `prompts` | `object` | No | Map of operation name to starter prompts |

---

## `PageMetaItem`

| Field | Type | Required | Description |
|---|---|---|---|
| `title` | `string` | Yes | — |
| `description` | `string` | Yes | — |

---

## `ParamInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Parameter name |
| `type` | `string` | Yes | Parameter data type |
| `required` | `boolean` | Yes | Whether the parameter is required |
| `default` | `any` | No | Default value if not required |

---

## `PersonaChartRow`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | No | Persona display name |
| `score` | `number` | No | Average score for persona |
| `sessions` | `integer` | No | Number of sessions |
| `color` | `string` | No | Chart color for persona |
| `trend_data` | [`PersonaTrendPoint`](#personatrendpoint)[] | No | Trend data points for persona |
| `simulation_ids` | `string`[] | No | Associated simulation IDs |
| `status` | `string` | No | Row status indicator |

---

## `PersonaColorJunction`

| Field | Type | Required | Description |
|---|---|---|---|
| `persona_name` | `string` | No | Persona display name |
| `color` | `string` | No | Assigned chart color |

---

## `PersonaTrendPoint`

| Field | Type | Required | Description |
|---|---|---|---|
| `date` | `string` | No | Date of the trend point |
| `score` | `number` | No | Score value at this point |
| `timestamp` | `integer` | No | Unix timestamp of the point |
| `simulation_id` | `string` | No | Associated simulation ID |

---

## `PreviousChatOption`

A single chat_entry's best previous graded attempt_chat.

| Field | Type | Required | Description |
|---|---|---|---|
| `chat_entry_id` | `string` | No | ID of the chat entry |
| `scenario_name` | `string` | No | Name of the scenario |
| `attempt_chat_id` | `string` | No | ID of the attempt chat |
| `score` | `number` | No | Score achieved |
| `percentage` | `number` | No | Score as a percentage |
| `time_taken` | `number` | No | Time taken in seconds |
| `position` | `integer` | No | Position in the sequence |

---

## `PrimaryPersonaPerformance`

| Field | Type | Required | Description |
|---|---|---|---|
| `chart_data` | [`PersonaChartRow`](#personachartrow)[] | No | Persona performance chart rows |
| `valid_simulation_ids` | `string`[] | No | Valid simulation IDs in scope |
| `persona_colors_junction` | [`PersonaColorJunction`](#personacolorjunction)[] | No | Persona-to-color mappings |
| `status` | `string` | No | Section status indicator |

---

## `PrimaryRubricHeatmap`

| Field | Type | Required | Description |
|---|---|---|---|
| `matrices` | [`RubricHeatmapMatrix`](#rubricheatmapmatrix)[] | No | Heatmap matrices per rubric |
| `valid_rubric_ids` | `string`[] | No | Valid rubric IDs in scope |
| `status` | `string` | No | Section status indicator |

---

## `PrimaryRubricTrend`

| Field | Type | Required | Description |
|---|---|---|---|
| `trend_data` | [`PrimaryRubricTrendPoint`](#primaryrubrictrendpoint)[] | No | Rubric trend time-series data |
| `valid_rubric_ids` | `string`[] | No | Valid rubric IDs in scope |
| `status` | `string` | No | Section status indicator |

---

## `PrimaryRubricTrendPoint`

| Field | Type | Required | Description |
|---|---|---|---|
| `date` | `string` | No | Date of the trend point |
| `standard_group_id` | `string` | No | Standard group identifier |
| `standard_group_name` | `string` | No | Standard group display name |
| `avg_pct` | `number` | No | Average percentage score |

---

## `ProducedMedia`

One asset produced by a generation run.

``resource_id`` is the canonical id the per-artifact download tools
accept (e.g. ``Scenario_Image_Download(image_id=resource_id)`` for
``modality="image"``). It maps to ``images_resource.id`` /
``videos_resource.id`` / ``audios_resource.id`` depending on the
modality.

| Field | Type | Required | Description |
|---|---|---|---|
| `modality` | `"image"` \| `"video"` \| `"audio"` | Yes | — |
| `resource_id` | `string` | Yes | — |
| `upload_id` | `string` | Yes | — |
| `mime_type` | `string` | No | — |
| `file_size` | `integer` | No | — |

---

## `ProfileSummary`

Caller identity derived from JWT — who you are on this page.

Superset of the old six-field version: now carries everything the client
needs so that ``/\{artifact\}/context`` fully replaces ``/profiles/context``
and the extra ``getLayoutContextData`` round-trip can be dropped.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Display name of the authenticated user |
| `role` | `string` | Yes | Role name (e.g. 'Super Administrator') |
| `role_level` | `integer` | Yes | Role hierarchy level (0 = highest privilege) |
| `department_ids` | `string`[] | Yes | Departments the user belongs to |
| `artifact_access` | `string`[] | Yes | Artifact types this role can access (sidebar visibility) |
| `role_permissions` | `any`[][] | Yes | Full (artifact, operation) permission tuples for granular page gating |
| `is_active` | `boolean` | Yes | Whether the user's profile is active |
| `id` | `string` | Yes | Profile UUID (SocketProvider, ProfileProvider) |
| `theme` | [`ThemeBundle`](#themebundle) | No | Resolved theme: hex primitives + derived oklch tokens + score thresholds |
| `session_id` | `string` | No | Current session UUID |
| `is_emulation` | `boolean` | No | Whether user is in emulation mode (ProfileProvider) |
| `role_resources` | [`QGetProfileContextV4RoleResource`](#qgetprofilecontextv4roleresource)[] | No | All role resources for emulation display (ProfileProvider) |
| `scoped_roles` | `string`[] | No | Roles the user can emulate (ProfileProvider) |
| `active` | `boolean` | No | Alias for is_active (ProfileProvider uses this name) |

---

## `QGetProfileContextV4RoleResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `role` | `string` | No | — |
| `name` | `string` | No | — |
| `description` | `string` | No | — |
| `icon_value` | `string` | No | — |
| `color_hex` | `string` | No | — |

---

## `QuizResponse`

Quiz response entry.

| Field | Type | Required | Description |
|---|---|---|---|
| `question_id` | `string` | No | UUID of the answered question |
| `option_id` | `string` | No | UUID of the selected option |
| `completed` | `boolean` | No | Whether the response is complete |
| `created_at` | `string` | No | Timestamp when response was created |

---

## `ReplacementEntry`

Replacement entry within an improvement.

| Field | Type | Required | Description |
|---|---|---|---|
| `section` | `string` | No | Original text section to replace |
| `replace` | `string` | No | Replacement text |
| `idx` | `integer` | No | Index position of the replacement |

---

## `ReportsDataPoint`

Metric trend point (lightweight equivalent of SQL data_point type).

| Field | Type | Required | Description |
|---|---|---|---|
| `profile_id` | `string` | No | Associated profile ID |
| `date` | `string` | No | Date of the data point |
| `value` | `number` \| `integer` | No | Data point value |
| `simulation_id` | `string` | No | Associated simulation ID |
| `scenario_id` | `string` | No | Associated scenario ID |
| `attempt_id` | `string` | No | Associated attempt ID |

---

## `ReportsHeaderMetrics`

Header summary metrics.

| Field | Type | Required | Description |
|---|---|---|---|
| `total_attempts` | [`ReportsMetric`](#reportsmetric) | No | Total attempts metric |
| `average_score` | [`ReportsMetric`](#reportsmetric) | No | Average score metric |
| `completion_percentage` | [`ReportsMetric`](#reportsmetric) | No | Completion percentage metric |
| `first_attempt_pass_rate` | [`ReportsMetric`](#reportsmetric) | No | First attempt pass rate metric |

---

## `ReportsHistoryRow`

History row from attempt facts.

| Field | Type | Required | Description |
|---|---|---|---|
| `attempt_id` | `string` | No | Attempt identifier |
| `profile_id` | `string` | No | Associated profile ID |
| `simulation_id` | `string` | No | Associated simulation ID |
| `cohort_id` | `string` | No | Associated cohort ID |
| `attempt_created_at` | `string` | No | Attempt creation timestamp |
| `attempt_type` | `string` | No | Type of attempt |
| `is_archived` | `boolean` | No | Whether attempt is archived |
| `infinite_mode` | `boolean` | No | Whether attempt was infinite mode |
| `score_percent` | `number` | No | Score as percentage |
| `has_passed` | `boolean` | No | Whether attempt passed |
| `num_chats` | `integer` | No | Number of chats in attempt |
| `num_chats_completed` | `integer` | No | Number of completed chats |
| `total_time_seconds` | `integer` | No | Total time in seconds |
| `scenario_ids` | `string`[] | No | Associated scenario IDs |

---

## `ReportsHistorySection`

History section output.

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | [`ReportsSectionStatus`](#reportssectionstatus) | No | Section status metadata |
| `rows` | [`ReportsHistoryRow`](#reportshistoryrow)[] | No | History rows |

---

## `ReportsLeaderboardRow`

Leaderboard row from profile metrics.

| Field | Type | Required | Description |
|---|---|---|---|
| `rank` | `integer` | Yes | Leaderboard rank position |
| `profile_id` | `string` | No | Profile identifier |
| `total_attempts` | `integer` | No | Total number of attempts |
| `average_score` | `number` | No | Average score |
| `highest_score` | `number` | No | Highest score achieved |
| `completion_percentage` | `number` | No | Completion percentage |
| `first_attempt_pass_rate` | `number` | No | First attempt pass rate |
| `profile_metrics` | [`ReportsProfileMetrics`](#reportsprofilemetrics) | No | Detailed profile metrics |
| `simulation_ids` | `string`[] | No | Associated simulation IDs |
| `scenario_ids` | `string`[] | No | Associated scenario IDs |

---

## `ReportsLeaderboardSection`

Leaderboard section output.

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | [`ReportsSectionStatus`](#reportssectionstatus) | No | Section status metadata |
| `rows` | [`ReportsLeaderboardRow`](#reportsleaderboardrow)[] | No | Leaderboard rows |

---

## `ReportsMetric`

Small, reusable metric envelope for section outputs.

| Field | Type | Required | Description |
|---|---|---|---|
| `current_value` | `number` \| `integer` | No | Current metric value |
| `has_data` | `boolean` | No | Whether metric has any data |
| `method` | `string` | No | Aggregation method used |
| `data_points` | [`ReportsDataPoint`](#reportsdatapoint)[] | No | Metric data points |
| `hover` | [`ReportsMetricHover`](#reportsmetrichover) | No | Hover tooltip payload |
| `status` | `string` | No | Metric status indicator |

---

## `ReportsMetricHover`

Metric hover payload (compatible field names with legacy SQL bundle).

| Field | Type | Required | Description |
|---|---|---|---|
| `mean` | `integer` | No | Mean value |
| `median` | `integer` | No | Median value |
| `mode` | `integer` | No | Mode value |
| `count` | `integer` | No | Total count |
| `completed` | `integer` | No | Number completed |
| `total` | `integer` | No | Total number |
| `percent` | `integer` | No | Percentage value |
| `top` | `integer`[] | No | Top values list |
| `mean_seconds` | `integer` | No | Mean time in seconds |
| `median_seconds` | `integer` | No | Median time in seconds |
| `samples` | `integer` | No | Number of samples |
| `avg_score_percent` | `integer` | No | Average score percentage |
| `avg_minutes` | `integer` | No | Average duration in minutes |
| `efficiency` | `integer` | No | Efficiency score |
| `tracked` | `integer` | No | Number tracked |
| `stagnant` | `integer` | No | Number stagnant |
| `rate_percent` | `integer` | No | Rate as percentage |
| `total_minutes` | `integer` | No | Total time in minutes |
| `total_hours` | `number` | No | Total time in hours |
| `attempts` | `integer` | No | Number of attempts |
| `unique_simulations` | `integer` | No | Number of unique simulations |
| `per_simulation_mean` | `integer` | No | Mean per simulation |

---

## `ReportsOverviewRow`

Overview row grouped by simulation.

| Field | Type | Required | Description |
|---|---|---|---|
| `simulation_id` | `string` | No | Simulation identifier |
| `attempts` | `integer` | No | Number of attempts |
| `completed_attempts` | `integer` | No | Number of completed attempts |
| `passed_attempts` | `integer` | No | Number of passing attempts |
| `average_score` | `number` | No | Average score |
| `completion_percentage` | `number` | No | Completion percentage |
| `pass_rate` | `number` | No | Pass rate percentage |

---

## `ReportsOverviewSection`

Overview section output.

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | [`ReportsSectionStatus`](#reportssectionstatus) | No | Section status metadata |
| `rows` | [`ReportsOverviewRow`](#reportsoverviewrow)[] | No | Overview rows by simulation |

---

## `ReportsProfileMetrics`

Per-profile metric bundle aligned to legacy report metric families.

| Field | Type | Required | Description |
|---|---|---|---|
| `average_score` | [`ReportsMetric`](#reportsmetric) | No | Average score metric |
| `completion_percentage` | [`ReportsMetric`](#reportsmetric) | No | Completion percentage metric |
| `first_attempt_pass_rate` | [`ReportsMetric`](#reportsmetric) | No | First attempt pass rate metric |
| `highest_score` | [`ReportsMetric`](#reportsmetric) | No | Highest score metric |
| `messages_per_session` | [`ReportsMetric`](#reportsmetric) | No | Messages per session metric |
| `persona_response_times` | [`ReportsMetric`](#reportsmetric) | No | Persona response times metric |
| `session_efficiency` | [`ReportsMetric`](#reportsmetric) | No | Session efficiency metric |
| `stagnation_rate` | [`ReportsMetric`](#reportsmetric) | No | Stagnation rate metric |
| `time_spent` | [`ReportsMetric`](#reportsmetric) | No | Time spent metric |
| `total_attempts` | [`ReportsMetric`](#reportsmetric) | No | Total attempts metric |

---

## `ReportsResources`

Resource metadata keyed by ID for normalized hydration.

| Field | Type | Required | Description |
|---|---|---|---|
| `simulations` | `object` | No | Simulation resources keyed by ID |
| `profiles` | `object` | No | Profile resources keyed by ID |
| `roles` | `object` | No | Role resources keyed by ID |
| `scenarios` | `object` | No | Scenario resources keyed by ID |
| `cohorts` | `object` | No | Cohort resources keyed by ID |
| `personas` | `object` | No | Persona resources keyed by ID |
| `rubrics` | `object` | No | Rubric resources keyed by ID |

---

## `ReportsSectionStatus`

Section-level status metadata.

| Field | Type | Required | Description |
|---|---|---|---|
| `has_data` | `boolean` | No | Whether section has any data |
| `status` | `string` | No | Section status indicator |
| `note` | `string` | No | Optional status note |

---

## `ReportsSections`

Business-computed section skeletons (built in permissions.py).

| Field | Type | Required | Description |
|---|---|---|---|
| `header_metrics` | [`ReportsHeaderMetrics`](#reportsheadermetrics) | No | Header summary metrics |
| `overview` | [`ReportsOverviewSection`](#reportsoverviewsection) | No | Overview section data |
| `leaderboard` | [`ReportsLeaderboardSection`](#reportsleaderboardsection) | No | Leaderboard section data |
| `trends` | [`ReportsTrendsSection`](#reportstrendssection) | No | Trends section data |
| `history` | [`ReportsHistorySection`](#reportshistorysection) | No | History section data |

---

## `ReportsTrendPoint`

Time-series aggregate point.

| Field | Type | Required | Description |
|---|---|---|---|
| `date` | `string` | No | Date of the trend point |
| `attempts` | `integer` | No | Number of attempts |
| `completed_attempts` | `integer` | No | Number of completed attempts |
| `passed_attempts` | `integer` | No | Number of passing attempts |
| `average_score` | `number` | No | Average score |
| `completion_percentage` | `number` | No | Completion percentage |
| `pass_rate` | `number` | No | Pass rate percentage |

---

## `ReportsTrendsSection`

Trends section output.

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | [`ReportsSectionStatus`](#reportssectionstatus) | No | Section status metadata |
| `chart_data` | [`ReportsTrendPoint`](#reportstrendpoint)[] | No | Trend chart time-series data |

---

## `ReportsViews`

Raw MV slices used to compute section outputs (deprecated — always empty).

| Field | Type | Required | Description |
|---|---|---|---|
| `attempt_facts` | `any`[] | No | Raw attempt fact slices |
| `chat_facts` | `any`[] | No | Raw chat fact slices |
| `daily_metrics` | `any`[] | No | Raw daily metric slices |
| `profile_metrics` | `any`[] | No | Raw profile metric slices |

---

## `RubricHeatmapCell`

| Field | Type | Required | Description |
|---|---|---|---|
| `rubric_id` | `string` | No | Rubric ID for this cell |
| `correlation` | `number` | No | Correlation coefficient |
| `p_value` | `number` | No | Statistical p-value |
| `color` | `string` | No | Cell display color |
| `strength` | `string` | No | Correlation strength label |
| `data_points` | `integer` | No | Number of data points |

---

## `RubricHeatmapMatrix`

| Field | Type | Required | Description |
|---|---|---|---|
| `rubric_id` | `string` | No | Rubric ID for this matrix |
| `standard_groups` | [`RubricHeatmapStandardGroup`](#rubricheatmapstandardgroup)[] | No | Standard groups as axes |
| `matrix` | [`RubricHeatmapMatrixRow`](#rubricheatmapmatrixrow)[] | No | Correlation matrix rows |
| `insights` | `string` | No | Generated insights text |
| `has_data` | `boolean` | No | Whether matrix has data |

---

## `RubricHeatmapMatrixRow`

| Field | Type | Required | Description |
|---|---|---|---|
| `cells` | [`RubricHeatmapCell`](#rubricheatmapcell)[] | No | Cells in this heatmap row |

---

## `RubricHeatmapStandardGroup`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Standard group identifier |
| `name` | `string` | No | Standard group name |
| `short_name` | `string` | No | Abbreviated display name |
| `rubric_id` | `string` | No | Parent rubric ID |

---

## `RubricMapping`

Rubric metadata mapping rubric to its standard groups.

| Field | Type | Required | Description |
|---|---|---|---|
| `rubric_id` | `string` | Yes | UUID of the rubric |
| `name` | `string` | No | Name of the rubric |
| `standard_group_ids` | `string`[] | No | IDs of standard groups in this rubric |

---

## `RubricStructureData`

Rubric structure data in Record format.

All fields are Records keyed by standard_group_id or standard_id strings.
This is the exact format the client needs - no transformation required.

| Field | Type | Required | Description |
|---|---|---|---|
| `standard_groups` | `object` | No | Map of group_id to standard_id lists |
| `standard_groups_mapping` | `object` | No | Map of group_id to group metadata |
| `standards_mapping` | `object` | No | Map of standard_id to standard metadata |

---

## `RunPricingItem`

Single pricing entry for a run. Cost computed at runtime.

| Field | Type | Required | Description |
|---|---|---|---|
| `pricing_type` | `string` | No | Type of pricing (e.g. input, output, cached) |
| `count` | `integer` | No | Token count for this pricing type |
| `pricing_id` | `string` | No | UUID of the pricing configuration |

---

## `RunStatus`

Outcome of one watched run.

| Field | Type | Required | Description |
|---|---|---|---|
| `run_id` | `string` | Yes | — |
| `status` | `"pending"` \| `"completed"` \| `"failed"` | Yes | — |
| `modality` | `string` | No | Modality of generated output (image, video, text…) |
| `resource_ids` | `string`[] | No | Resource UUIDs produced by this run (e.g. images_resource ids) |
| `error` | `string` | No | — |

---

## `RunViewItem`

Single run from the run list.

| Field | Type | Required | Description |
|---|---|---|---|
| `run_id` | `string` | Yes | UUID of the run |
| `group_id` | `string` | No | UUID of the owning group |
| `profiles_id` | `string` | No | UUID of the profile that created the run |
| `input_tokens` | `integer` | No | Number of input tokens used |
| `output_tokens` | `integer` | No | Number of output tokens generated |
| `cached_input_tokens` | `integer` | No | Number of cached input tokens |
| `run_created_at` | `string` | No | Run creation timestamp |
| `agent_ids` | `string`[] | No | Agent UUIDs involved in the run |
| `model_ids` | `string`[] | No | Model UUIDs used in the run |
| `provider_ids` | `string`[] | No | Provider UUIDs used in the run |
| `pricing` | [`RunPricingItem`](#runpricingitem)[] | No | Pricing breakdown entries |

---

## `SecondaryAttemptImprovement`

| Field | Type | Required | Description |
|---|---|---|---|
| `chart_data` | [`SecondaryAttemptImprovementChart`](#secondaryattemptimprovementchart)[] | No | Attempt improvement chart data |
| `facts` | [`SecondaryAttemptImprovementFact`](#secondaryattemptimprovementfact)[] | No | Per-simulation attempt facts |
| `valid_simulation_ids` | `string`[] | No | Valid simulation IDs in scope |
| `status` | `string` | No | Section status indicator |

---

## `SecondaryAttemptImprovementChart`

| Field | Type | Required | Description |
|---|---|---|---|
| `attempt` | `string` | No | Attempt number label |
| `average_score` | `number` | No | Average score for this attempt |
| `average_time` | `number` | No | Average time in minutes |
| `pass_rate` | `number` | No | Pass rate for this attempt |

---

## `SecondaryAttemptImprovementFact`

| Field | Type | Required | Description |
|---|---|---|---|
| `simulation_id` | `string` | No | Associated simulation ID |
| `attempt_no` | `integer` | No | Attempt number |
| `avg_grade` | `number` | No | Average grade for this attempt |
| `avg_minutes` | `number` | No | Average duration in minutes |
| `pass_rate` | `number` | No | Pass rate for this attempt |

---

## `SecondaryCohortDaily`

| Field | Type | Required | Description |
|---|---|---|---|
| `date` | `string` | No | Date of the daily aggregate |
| `avg_score` | `number` | No | Average score for the day |
| `cohort_id` | `string` | No | Associated cohort ID |

---

## `SecondaryCohortData`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Cohort identifier |
| `name` | `string` | No | Cohort display name |
| `pass_rate` | `number` | No | Cohort pass rate percentage |
| `avg_percentage_score` | `number` | No | Average percentage score |
| `total_students` | `integer` | No | Total students in cohort |
| `passed_students` | `integer` | No | Number of students who passed |
| `total_attempts` | `integer` | No | Total number of attempts |
| `passed_attempts` | `integer` | No | Number of passing attempts |
| `simulation_count` | `integer` | No | Number of simulations attempted |
| `required_simulations` | `integer` | No | Number of required simulations |
| `status` | `string` | No | Cohort status indicator |

---

## `SecondaryCohortPerformance`

| Field | Type | Required | Description |
|---|---|---|---|
| `cohort_data` | [`SecondaryCohortData`](#secondarycohortdata)[] | No | Per-cohort aggregate data |
| `daily_data` | [`SecondaryCohortDaily`](#secondarycohortdaily)[] | No | Daily cohort aggregates |
| `simulation_facts` | [`SecondarySimulationFact`](#secondarysimulationfact)[] | No | Per-simulation cohort facts |
| `daily_facts` | [`SecondaryDailyFact`](#secondarydailyfact)[] | No | Daily simulation facts |
| `valid_simulation_ids` | `string`[] | No | Valid simulation IDs in scope |
| `status` | `string` | No | Section status indicator |

---

## `SecondaryDailyFact`

| Field | Type | Required | Description |
|---|---|---|---|
| `date` | `string` | No | Date of the daily fact |
| `simulation_id` | `string` | No | Associated simulation ID |
| `avg_score` | `number` | No | Average score for the day |

---

## `SecondaryGroupFact`

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | No | Standard group identifier |
| `group_name` | `string` | No | Standard group name |
| `group_description` | `string` | No | Standard group description |
| `simulation_id` | `string` | No | Associated simulation ID |
| `score` | `number` | No | Raw score value |
| `points` | `number` | No | Points earned |
| `avg_pct` | `number` | No | Average percentage score |

---

## `SecondaryRadarPoint`

| Field | Type | Required | Description |
|---|---|---|---|
| `metric` | `string` | No | Metric name for radar axis |
| `description` | `string` | No | Metric description |
| `value` | `number` | No | Metric value |
| `full_mark` | `number` | No | Maximum possible value |

---

## `SecondarySimulationFact`

| Field | Type | Required | Description |
|---|---|---|---|
| `cohort_id` | `string` | No | Associated cohort ID |
| `simulation_id` | `string` | No | Associated simulation ID |
| `pass_rate` | `number` | No | Pass rate for this simulation |
| `avg_score` | `number` | No | Average score for this simulation |
| `attempts` | `integer` | No | Number of attempts |

---

## `SecondarySkillPackage`

| Field | Type | Required | Description |
|---|---|---|---|
| `rubric_id` | `string` | No | Rubric ID for this package |
| `radar_data` | [`SecondaryRadarPoint`](#secondaryradarpoint)[] | No | Radar chart data points |
| `group_facts` | [`SecondaryGroupFact`](#secondarygroupfact)[] | No | Per-group performance facts |

---

## `SecondarySkillPerformance`

| Field | Type | Required | Description |
|---|---|---|---|
| `packages` | [`SecondarySkillPackage`](#secondaryskillpackage)[] | No | Skill performance packages per rubric |
| `valid_rubric_ids` | `string`[] | No | Valid rubric IDs in scope |
| `status` | `string` | No | Section status indicator |

---

## `SimulationData`

Simulation metadata.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | UUID of the simulation |
| `name` | `string` | No | Name of the simulation |
| `description` | `string` | No | Description of the simulation |
| `time_limit` | `integer` | No | Time limit in seconds |
| `hints_enabled` | `boolean` | No | Whether hints are enabled |
| `objectives_enabled` | `boolean` | No | Whether objectives are enabled |
| `image_input_active` | `boolean` | No | Whether image input is active |
| `copy_paste_allowed` | `boolean` | No | Whether copy-paste is allowed |
| `practice_simulation` | `boolean` | No | Whether this is a practice simulation |
| `rubric_id` | `string` | No | UUID of the associated rubric |

---

## `SkillFeedback`

Skill feedback entry.

| Field | Type | Required | Description |
|---|---|---|---|
| `skill_name` | `string` | No | Name of the skill |
| `feedback` | `string` | No | Feedback text for the skill |

---

## `SkillScore`

Skill score entry.

| Field | Type | Required | Description |
|---|---|---|---|
| `skill_name` | `string` | No | Name of the skill |
| `score` | `number` | No | Score for the skill |

---

## `StandardGroupMapping`

Standard group metadata for sidebar/legend.

| Field | Type | Required | Description |
|---|---|---|---|
| `standard_group_id` | `string` | Yes | UUID of the standard group |
| `name` | `string` | No | Name of the standard group |
| `description` | `string` | No | Description of the standard group |
| `points` | `integer` | No | Total points for the group |
| `pass_points` | `integer` | No | Points required to pass |

---

## `StandardMapping`

Standard metadata for sidebar/legend.

| Field | Type | Required | Description |
|---|---|---|---|
| `standard_id` | `string` | Yes | UUID of the standard |
| `standard_group_id` | `string` | No | UUID of the parent standard group |
| `name` | `string` | No | Name of the standard |
| `description` | `string` | No | Description of the standard |
| `points` | `integer` | No | Points for the standard |

---

## `TableInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Table name |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the table |

---

## `ThemeBundle`

Full theme payload for a page bootstrap.

Riding along on every ``/\{artifact\}/context`` response via
``ProfileSummary.theme``. Layers:
  - ``primitives`` / ``dark_primitives`` — hex inputs the settings
    editor reads/writes (light + dark palettes).
  - ``tokens`` / ``dark_tokens`` — oklch tokens the client paints with.
    ``ThemeStyle`` emits two ``<style>`` blocks: one scoped to
    ``:root:not(.dark)`` (light) and one to ``:root.dark`` (dark).
  - ``thresholds`` — numeric score thresholds for analytics components.
Empty-in → empty-out per token: missing values fall through to the
matching ``globals.css`` default.

| Field | Type | Required | Description |
|---|---|---|---|
| `primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (light palette, for the theme editor) |
| `tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for light mode (SSR CSS-var injection) |
| `dark_primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (dark palette, for the theme editor) |
| `dark_tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for dark mode (SSR CSS-var injection) |
| `thresholds` | [`Thresholds`](#thresholds) | No | Score thresholds resolved from the setting |

---

## `ThemePrimitives`

40 optional fields. The 17 essentials drive the rest; the other 23
are overrides for fine-tuning when derivation isn't what you want.

Empty primitive → empty token → client falls back to globals.css.

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `primary` | `string` | No | — |
| `accent` | `string` | No | — |
| `card` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `ring` | `string` | No | — |
| `border` | `string` | No | — |
| `destructive` | `string` | No | — |
| `success` | `string` | No | — |
| `warning` | `string` | No | — |
| `info` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `input` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `ThemeTokens`

40 fully-resolved CSS variable values (snake_case 1:1 with vars).

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `accent` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `border` | `string` | No | — |
| `input` | `string` | No | — |
| `ring` | `string` | No | — |
| `success` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `Thresholds`

Numeric score thresholds resolved from the active setting.

Server pre-buckets dashboard metrics into ``success | warning | danger |
neutral`` already, so most components don't need these values. Surface
them for chart reference lines, tooltips, and any client-side bucketing.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `integer` | Yes | Score >= this counts as success |
| `warning` | `integer` | Yes | Score >= this counts as warning |
| `danger` | `integer` | Yes | Score < success threshold but >= this counts as danger; below is neutral/no-data |

---

## `TimerData`

Timer information.

| Field | Type | Required | Description |
|---|---|---|---|
| `elapsed` | `integer` | No | Elapsed time in seconds |
| `limit` | `integer` | No | Time limit in seconds |
| `exceeded` | `boolean` | No | Whether the time limit was exceeded |
| `formatted` | `string` | No | Formatted time string for display |
| `negative` | `boolean` | No | Whether the timer can go negative |

---

## `app__infra__attempt__chat__types__DraftImageValue`

Value for creating an image via the draft endpoint.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Name of the image |
| `description` | `string` | Yes | Description of the image |
| `upload_id` | `string` | No | UUID of the uploaded file |

---

## `app__infra__attempt__chat__types__DraftOptionValue`

Value for creating an option via the draft endpoint.

| Field | Type | Required | Description |
|---|---|---|---|
| `option_text` | `string` | Yes | Display text for the option |
| `question_id` | `string` | No | UUID of the parent question |

---

## `app__infra__attempt__chat__types__DraftQuestionValue`

Value for creating a question via the draft endpoint.

| Field | Type | Required | Description |
|---|---|---|---|
| `question_text` | `string` | Yes | Text of the question |
| `time` | `integer` | No | Video timestamp in seconds |
| `allow_multiple` | `boolean` | No | Whether multiple answers are allowed |

---

## `app__infra__attempt__chat__types__DraftVideoValue`

Value for creating a video via the draft endpoint.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Name of the video |
| `description` | `string` | Yes | Description of the video |
| `upload_id` | `string` | No | UUID of the uploaded file |

---

## `app__infra__attempt__chat__types__SectionFilter`

Per-section filter options for chat GET requests.

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Filter options by search text |
| `limit` | `integer` | No | Max options to return |
| `selected` | `boolean` | No | Only return selected items |
| `suggested` | `boolean` | No | Only return suggested items |
| `include` | `boolean` | No | Include this section in the response |
| `parameter_ids` | `string`[] | No | Parameter IDs to filter parameter_fields by |

---

---

# `GET` `/auth/client-config`

Route: /api-reference/auth-client-config

# `GET` `/auth/client-config`

Client Config

Return OAuth client credentials for frontend integration.

Authenticated by the deployment token (generated on first deploy by
the glow CLI and written to the server's .env). Any frontend can call
this with the token to fetch the keycloak client_id + secret needed
to connect to this server's auth.

## Response

```
{}
```

---

# `GET` `/auth/watch`

Route: /api-reference/auth/get-auth-watch

# `GET` `/auth/watch`

Auth Watch

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `group_id` | query | No | — |
| `run_id` | query | No | Optional run filter. If provided, only events whose envelope run_id matches are streamed. Omit to receive every auth event in the group (the FE default). |

## Response

```
{}
```

---

# `POST` `/auth/call_download`

Route: /api-reference/auth/post-auth-call-download

# `POST` `/auth/call_download`

Download Call

Download a call file by call resource ID.

## Request Body (`CallDownloadAuthApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `call_id` | `string` | Yes | UUID of the calls_resource to download |

## Response

```
{}
```

---

# `POST` `/auth/context`

Route: /api-reference/auth/post-auth-context

# `POST` `/auth/context`

Get Auth Context

Get page context for the auth artifact.

Returns docs + profile identity + evaluated permissions in a single call.
Superset of /docs — clients can migrate from /docs to /context incrementally.

## Request Body (`DocsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entity_id` | `string` | No | — |
| `snapshot_key` | `string` | No | — |
| `schema` | `boolean` | No | If true, include MCP/tooling schema metadata (artifact, entries, resources, permission_docs, api_operations). Defaults to false for lean page-bootstrap responses. |

## Response (`ComposedContextResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Artifact name |
| `type` | `string` | Yes | Artifact type identifier |
| `description` | `string` | Yes | Human-readable description |
| `artifact` | [`DocsResponse`](/api-reference/auth/types#docsresponse) | No | Artifact tool documentation (None unless schema=true) |
| `entries` | [`DocsResponse`](/api-reference/auth/types#docsresponse)[] | No | Entry documentation list (None unless schema=true) |
| `resources` | [`DocsResponse`](/api-reference/auth/types#docsresponse)[] | No | Resource documentation list (None unless schema=true) |
| `permission_docs` | [`OperationInfo`](/api-reference/auth/types#operationinfo)[] | No | Permission function signatures for MCP/dev tooling (None unless schema=true) |
| `api_operations` | [`OperationInfo`](/api-reference/auth/types#operationinfo)[] | No | API operation documentation (None unless schema=true) |
| `page_metadata` | [`DocsApiResponse`](/api-reference/auth/types#docsapiresponse) | No | Page-level metadata |
| `prompts` | [`OperationPrompts`](/api-reference/auth/types#operationprompts) | No | Starter prompts keyed by operation |
| `profile` | [`ProfileSummary`](/api-reference/auth/types#profilesummary) | Yes | Caller identity from JWT |
| `caller_permissions` | [`CallerPermissions`](/api-reference/auth/types#callerpermissions) | Yes | Evaluated permissions for this caller |

---

# `POST` `/auth/create`

Route: /api-reference/auth/post-auth-create

# `POST` `/auth/create`

Create Auth

Create auths using composable infra architecture.

## Request Body (`CreateAuthApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `auths` | [`CreateAuthItem`](/api-reference/auth/types#createauthitem)[] | No | List of auth providers to create (required on first call) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant create |
| `soft` | `boolean` | No | Stage the create dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`CreateAuthApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`AuthResultItem`](/api-reference/auth/types#authresultitem)[] | Yes | Per-item creation results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |
| `auths` | [`ListAuthApiAuth`](/api-reference/auth/types#listauthapiauth)[] | No | Hydrated rows for the successfully-created auths (mirrors /auth/search shape) |

---

# `POST` `/auth/csv`

Route: /api-reference/auth/post-auth-csv

# `POST` `/auth/csv`

Parse Auth Csv

Parse a CSV file and return mapped items for preview.

## Request Body

| Field | Type | Required | Description |
|---|---|---|---|
| `file` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `soft` | `boolean` | No | — |
| `accept` | `boolean` | No | — |

## Response (`ParseAuthCsvApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `upload_id` | `string` | Yes | — |
| `items` | [`CreateAuthItem`](/api-reference/auth/types#createauthitem)[] | Yes | — |
| `mapped_fields` | `string`[] | Yes | — |
| `row_count` | `integer` | Yes | — |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with `accept` to promote/reject the staged raw-CSV upload. NOTE: ack returns no items (the preview is only on the propose). |

---

# `POST` `/auth/delete`

Route: /api-reference/auth/post-auth-delete

# `POST` `/auth/delete`

Delete Auth

Bulk delete auths — composable infra architecture.

## Request Body (`DeleteAuthApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `auth_ids` | `string`[] | No | UUIDs of auth providers to delete (required on first call when ``all`` is false) |
| `all` | `boolean` | No | When true, delete every auth matching the filter fields below (minus ``excluded_ids``) |
| `excluded_ids` | `string`[] | No | UUIDs to skip even when matched by ``all``-mode filters |
| `search` | `string` | No | Full-text search query |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `department_search` | `string` | No | Search text for department facet (no-op for row filtering) |
| `flag_search` | `string` | No | Search text for flag facet (no-op for row filtering) |
| `idempotency_key` | `string` | No | Operation key for ack — confirms or rejects a dormant delete |
| `soft` | `boolean` | No | Stage the delete dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (confirm) or reject dormant state. Only meaningful with idempotency_key |

## Response (`DeleteAuthApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`DeleteAuthResult`](/api-reference/auth/types#deleteauthresult)[] | Yes | Per-item deletion results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/auth/draft`

Route: /api-reference/auth/post-auth-draft

# `POST` `/auth/draft`

Patch Auth Draft

Patch auth draft — composable infra architecture.

## Request Body (`PatchAuthDraftApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `draft_id` | `string` | No | Existing draft UUID to update |
| `input_draft_id` | `string` | No | Existing draft UUID to update |
| `idempotency_key` | `string` | No | Stable idempotency key for ack/promote flows |
| `soft` | `boolean` | No | Stage the draft dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Whether to accept a pending draft when acknowledging |
| `name` | `string` | No | Name value to resolve or create |
| `name_id` | `string` | No | UUID of the name resource |
| `description` | `string` | No | Description value to resolve or create |
| `description_id` | `string` | No | UUID of the description resource |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `active` | `boolean` | No | Denormalized auth_active flag state; resolved to a flag_ids entry server-side |
| `departments` | `string`[] | No | Department names to resolve |
| `department_ids` | `string`[] | No | Department UUIDs to assign |
| `protocols` | `string`[] | No | Protocol values to resolve |
| `protocol_ids` | `string`[] | No | Protocol resource UUIDs |
| `slugs` | `string`[] | No | Slug values to resolve |
| `slug_ids` | `string`[] | No | Slug resource UUIDs |
| `item_ids` | `string`[] | No | Auth item UUIDs |
| `pending_ids` | `string`[] | No | Resource IDs to keep pending where supported |

## Response (`PatchAuthDraftApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the draft save succeeded |
| `draft_id` | `string` | Yes | UUID of the saved draft |
| `idempotency_key` | `string` | No | Stable idempotency key for ack/promote flows |
| `message` | `string` | Yes | Result message |
| `form_state` | [`app__infra__auth__types__DraftFormState`](/api-reference/auth/types#app-infra-auth-types-draftformstate) | No | Server-authoritative form state |

---

# `POST` `/auth/drafts`

Route: /api-reference/auth/post-auth-drafts

# `POST` `/auth/drafts`

Get Auth Drafts

List auth drafts owned by the current profile.

## Request Body (`GetAuthDraftsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE substring) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GetAuthDraftsApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entries` | [`GetAuthDraftResponse`](/api-reference/auth/types#getauthdraftresponse)[] | No | List of auth draft entries |

---

# `POST` `/auth/duplicate`

Route: /api-reference/auth/post-auth-duplicate

# `POST` `/auth/duplicate`

Duplicate Auth

Duplicate an auth — composable infra architecture.

## Request Body (`DuplicateAuthApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `auth_id` | `string` | Yes | UUID of the auth provider to duplicate |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant duplicate |
| `soft` | `boolean` | No | Stage the duplicate dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`DuplicateAuthApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the duplication succeeded |
| `auth_id` | `string` | Yes | UUID of the newly created auth provider |
| `message` | `string` | Yes | Result message |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |
| `auths` | [`ListAuthApiAuth`](/api-reference/auth/types#listauthapiauth)[] | No | Hydrated row for the newly-created duplicate auth (mirrors /auth/search shape) |

---

# `POST` `/auth/export`

Route: /api-reference/auth/post-auth-export

# `POST` `/auth/export`

Export Auths

Export all auths as a clean, denormalized CSV.

## Request Body (`ExportAuthApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `auth_id` | `string` | No | UUID of the auth provider to export |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior export instead of re-running |

## Response (`ExportAuthApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `content` | `string` | Yes | Exported file content |
| `file_name` | `string` | Yes | Suggested file name for download |
| `mime_type` | `string` | Yes | MIME type of the exported content |
| `row_count` | `integer` | Yes | Number of rows in the export |

---

# `POST` `/auth/file_download`

Route: /api-reference/auth/post-auth-file-download

# `POST` `/auth/file_download`

Download File

Download a file by file resource ID.

## Request Body (`FileDownloadAuthApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource to download |

## Response

```
{}
```

---

# `POST` `/auth/generate`

Route: /api-reference/auth/post-auth-generate

# `POST` `/auth/generate`

Generate Auth

Trigger auth generation. Returns immediately; progress via events.

## Request Body (`ArtifactGenerateRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `instructions` | `string`[] | No | — |
| `config` | [`GenerateConfig`](/api-reference/auth/types#generateconfig) | No | — |
| `modalities` | `string`[] | No | — |
| `audios_id` | `string` | No | — |
| `conversation_id` | `string` | No | — |
| `trace_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `accept` | `boolean` | No | — |
| `wait_for_complete` | `boolean` | No | — |

## Response (`ArtifactGenerateResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `run_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `eval` | [`EvalSetup`](/api-reference/auth/types#evalsetup) | No | — |
| `produced_media` | [`ProducedMedia`](/api-reference/auth/types#producedmedia)[] | No | — |

---

# `POST` `/auth/generations`

Route: /api-reference/auth/post-auth-generations

# `POST` `/auth/generations`

Generations Auth

List auth generation groups — composable infra architecture.

## Request Body (`GenerationsAuthApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GenerationsAuthApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `items` | [`GenerationsAuthListItem`](/api-reference/auth/types#generationsauthlistitem)[] | No | Generation groups |
| `total_count` | `integer` | No | Total number of matching generations |

---

# `POST` `/auth/get`

Route: /api-reference/auth/post-auth-get

# `POST` `/auth/get`

Get Auth

Get auth information using the canonical shared auth operation.

## Request Body (`GetAuthApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Auth identifier |
| `auth_id` | `string` | No | Legacy alias for auth identifier |
| `draft_id` | `string` | No | UUID of the draft to load |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |
| `names` | [`app__infra__auth__types__SectionFilter`](/api-reference/auth/types#app-infra-auth-types-sectionfilter) | No | Filter options for names section |
| `descriptions` | [`app__infra__auth__types__SectionFilter`](/api-reference/auth/types#app-infra-auth-types-sectionfilter) | No | Filter options for descriptions section |
| `flags` | [`app__infra__auth__types__SectionFilter`](/api-reference/auth/types#app-infra-auth-types-sectionfilter) | No | Filter options for flags section |
| `departments` | [`app__infra__auth__types__SectionFilter`](/api-reference/auth/types#app-infra-auth-types-sectionfilter) | No | Filter options for departments section |
| `protocols` | [`app__infra__auth__types__SectionFilter`](/api-reference/auth/types#app-infra-auth-types-sectionfilter) | No | Filter options for protocols section |
| `slugs` | [`app__infra__auth__types__SectionFilter`](/api-reference/auth/types#app-infra-auth-types-sectionfilter) | No | Filter options for slugs section |
| `items` | [`app__infra__auth__types__SectionFilter`](/api-reference/auth/types#app-infra-auth-types-sectionfilter) | No | Filter options for items section |

## Response (`GetAuthApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the acting user |
| `auth_exists` | `boolean` | No | Whether the auth provider exists |
| `can_edit` | `boolean` | No | Whether the actor can edit this auth |
| `disabled_reason` | `string` | No | Reason editing is disabled, if any |
| `group_id` | `string` | No | Group UUID for draft collaboration |
| `draft_name` | `string` | No | Immutable draft label from the active draft entry, when a ``draft_id`` was supplied. ``None`` for non-draft fetches. |
| `show_ai_generate` | `boolean` | No | Whether any auth resource supports AI generate |
| `basic_show_ai_generate` | `boolean` | No | Whether to show AI generate button |
| `pending_ids` | `string`[] | No | Pending resource identifiers when available |
| `names` | [`AuthNameResource`](/api-reference/auth/types#authnameresource)[] | No | Name resources |
| `descriptions` | [`AuthDescriptionResource`](/api-reference/auth/types#authdescriptionresource)[] | No | Description resources |
| `flags` | [`AuthFlagResource`](/api-reference/auth/types#authflagresource)[] | No | Flag resources (one per flags_resource row, value=true/false) |
| `departments` | [`AuthDepartmentResource`](/api-reference/auth/types#authdepartmentresource)[] | No | Department resources |
| `protocols` | [`AuthProtocolResource`](/api-reference/auth/types#authprotocolresource)[] | No | Protocol resources |
| `slugs` | [`AuthSlugResource`](/api-reference/auth/types#authslugresource)[] | No | Slug resources |
| `items` | [`AuthItemResource`](/api-reference/auth/types#authitemresource)[] | No | Auth item resources |

---

# `POST` `/auth/group`

Route: /api-reference/auth/post-auth-group

# `POST` `/auth/group`

Group Auth

Resolve or create an auth group with optional naming.

## Request Body (`GroupAuthApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | No | Existing group UUID (omit to create or reuse via time window) |
| `snapshot_key` | `string` | No | Snapshot key for SETNX-race convergence on a single group across concurrent reads (e.g. parallel /context + /group + /search fan-out on page load). Echoed back in the response. |

## Response (`GroupAuthApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Resolved or newly created group UUID |
| `name` | `string` | No | The group's current title (latest active group_names_entry, or 'New Chat' fallback for freshly minted groups) |
| `snapshot_key` | `string` | No | Snapshot key echoed back — the UUID concurrent fan-out reads converged on via SETNX. Mirrors the resolved group_id. |
| `runs` | [`GroupRun`](/api-reference/auth/types#grouprun)[] | No | Conversation history — populated when resolving an existing group for fetch |
| `group_exists` | `boolean` | No | (detail) Whether the group exists in storage — populated when ``include_resources=True`` |
| `actor_name` | `string` | No | (detail) Display name of the current actor (caller profile) |
| `total_message_count` | `integer` | No | (detail) Total number of messages in the group |
| `models` | [`GroupResource`](/api-reference/auth/types#groupresource)[] | No | (detail) Models used in the group |
| `agents` | [`GroupResource`](/api-reference/auth/types#groupresource)[] | No | (detail) Agents used in the group |
| `profiles` | [`GroupResource`](/api-reference/auth/types#groupresource)[] | No | (detail) Profiles that authored runs in this group |

---

# `POST` `/auth/problem`

Route: /api-reference/auth/post-auth-problem

# `POST` `/auth/problem`

Problem Auth

Report an auth problem — composable infra architecture.

## Request Body (`ProblemAuthApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | `string` | Yes | Problem type: feature, bug, question, other |
| `message` | `string` | Yes | Problem description (max 1000 chars) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant problem |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`ProblemAuthApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `problem_id` | `string` | Yes | UUID of the created problem |
| `success` | `boolean` | No | Whether the problem was created |
| `message` | `string` | No | Status message |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/auth/refresh`

Route: /api-reference/auth/post-auth-refresh

# `POST` `/auth/refresh`

Auth Refresh

Refresh auth materialized views and invalidate caches.

## Request Body (`RefreshAuthApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `targets` | `string`[] | No | MV targets to refresh (omit for all). Options: auth_drafts_mv |
| `idempotency_key` | `string` | No | Operation key for ack |
| `accept` | `boolean` | No | Accept or reject. Only meaningful with idempotency_key |
| `soft` | `boolean` | No | Stage the refresh as a pending (held) request — recorded but not enqueued; ack with accept releases/enqueues it |

## Response (`RefreshResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | — |
| `refreshed_views` | `string`[] | Yes | — |
| `invalidated_tags` | `string`[] | Yes | — |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/auth/search`

Route: /api-reference/auth/post-auth-search

# `POST` `/auth/search`

Search Auth

Search auths — composable infra architecture.

## Request Body (`SearchAuthApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | — |
| `filter_department_ids` | `string`[] | No | — |
| `department_search` | `string` | No | — |
| `page_size` | `integer` | No | — |
| `page_offset` | `integer` | No | — |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`ListAuthApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the acting user |
| `auths` | [`ListAuthApiAuth`](/api-reference/auth/types#listauthapiauth)[] | No | List of auth provider items |
| `department_filter` | [`ListFilterSection`](/api-reference/auth/types#listfiltersection) | No | Filter options for departments |
| `flag_filter` | [`ListFilterSection`](/api-reference/auth/types#listfiltersection) | No | Filter options for flags in list UI |
| `settings_filter` | [`ListFilterSection`](/api-reference/auth/types#listfiltersection) | No | Filter options for settings in list UI |
| `auth_item_keys_filter` | [`ListFilterSection`](/api-reference/auth/types#listfiltersection) | No | Filter options for auth item keys in list UI |
| `total_count` | `integer` | No | Total number of auth providers |

---

# `POST` `/auth/text_download`

Route: /api-reference/auth/post-auth-text-download

# `POST` `/auth/text_download`

Download Text

Download a text file by text resource ID.

## Request Body (`TextDownloadAuthApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `text_id` | `string` | Yes | UUID of the texts_resource to download |

## Response

```
{}
```

---

# `POST` `/auth/title`

Route: /api-reference/auth/post-auth-title

# `POST` `/auth/title`

Title Auth

Rename a auth's group (writes group_names_entry).

## Request Body (`TitleAuthApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Group to rename |
| `title` | `string` | Yes | New title (display name) for the group |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant rename |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`TitleAuthApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | The group that was renamed |
| `group_name_id` | `string` | Yes | UUID of the new group_names_entry row |
| `title` | `string` | Yes | The title that was set |
| `idempotency_key` | `string` | No | Operation key echoed back |

---

# `POST` `/auth/update`

Route: /api-reference/auth/post-auth-update

# `POST` `/auth/update`

Update Auth

Update auths using composable infra architecture.

## Request Body (`UpdateAuthApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `auths` | [`UpdateAuthItem`](/api-reference/auth/types#updateauthitem)[] | No | List of auth providers to update (required on first call when ``all`` is false) |
| `all` | `boolean` | No | When true, apply ``patch`` to every auth matching the filter fields below (minus ``excluded_ids``) |
| `excluded_ids` | `string`[] | No | UUIDs to skip even when matched by ``all``-mode filters |
| `patch` | [`UpdateAuthPatch`](/api-reference/auth/types#updateauthpatch) | No | Shared change set applied to every matched row when ``all=true`` (sparse — only set fields are updated; ``patch.id`` ignored) |
| `search` | `string` | No | Full-text search query |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `department_search` | `string` | No | Search text for department facet (no-op for row filtering) |
| `flag_search` | `string` | No | Search text for flag facet (no-op for row filtering) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant update |
| `soft` | `boolean` | No | Stage the update dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`UpdateAuthApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`AuthResultItem`](/api-reference/auth/types#authresultitem)[] | Yes | Per-item update results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |
| `auths` | [`ListAuthApiAuth`](/api-reference/auth/types#listauthapiauth)[] | No | Hydrated rows for the successfully-updated auths (mirrors /auth/search shape) |

---

# `POST` `/auth/watch`

Route: /api-reference/auth/post-auth-watch

# `POST` `/auth/watch`

Auth Watch Once

One-shot snapshot of run state, snapshot-replayable via ``snapshot_key``.

## Request Body (`WatchApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Chat group whose events we watch |
| `run_id` | `string` | No | Specific run to watch (e.g. the ``run_id`` returned by a prior ``X_Generate`` call). If None, watches every active run in the group at call time. |
| `wait_for_complete` | `boolean` | No | If True, block until the watched run reaches a terminal (complete/failed) event or timeout fires. If False, return current state and exit immediately. |
| `timeout_seconds` | `integer` | No | Max wait time when ``wait_for_complete=True``. |
| `snapshot_key` | `string` | No | Read snapshot key — on the one-shot POST /watch, the audit wrapper records this watch's point-in-time view (latest run state at call time) keyed by it and replays the same view on any later call with the same key. Ignored by the SSE GET stream. |

## Response (`WatchApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `runs` | [`RunStatus`](/api-reference/auth/types#runstatus)[] | Yes | — |
| `timed_out` | `boolean` | No | — |
| `waited_seconds` | `number` | No | — |

---

# Auth Types

Route: /api-reference/auth/types

# Auth Types

## `AuthDepartmentResource`

Department resource for auth.

| Field | Type | Required | Description |
|---|---|---|---|
| `department_id` | `string` | No | Department identifier |
| `name` | `string` | No | Department name |
| `description` | `string` | No | Department description |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `AuthDescriptionResource`

Description resource for auth.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `description` | `string` | No | Description text |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `AuthFieldError`

Per-field error from value resolution.

| Field | Type | Required | Description |
|---|---|---|---|
| `field` | `string` | Yes | Name of the field that failed validation |
| `message` | `string` | Yes | Validation error message |

---

## `AuthFlagResource`

Flag option row — one per (name, type, value) entry in flags_resource.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Flag resource identifier |
| `name` | `string` | No | Flag display name |
| `type` | `string` | No | Flag type (e.g. 'auth_active') |
| `value` | `boolean` | No | Underlying bool value of this option |
| `description` | `string` | No | Flag description text |
| `icon_id` | `string` | No | Icon identifier for the flag |
| `icon` | `string` | No | Resolved SVG markup for the icon (hydrated from icons_resource) |
| `generated` | `boolean` | No | Whether the flag was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `AuthItemResource`

Auth item resource shape for client/editing.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique auth item identifier |
| `name` | `string` | No | Auth item display name |
| `description` | `string` | No | Auth item description text |
| `position` | `integer` | No | Sort position within the auth provider |
| `encrypted` | `boolean` | No | Whether the value is encrypted |
| `generated` | `boolean` | No | Whether the item was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `AuthNameResource`

Name resource for auth.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `name` | `string` | No | Display name |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `AuthProtocolResource`

Protocol resource for auth.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Protocol identifier |
| `value` | `string` | No | Protocol value |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `AuthResultItem`

Per-item result within a bulk create/update response.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `auth_id` | `string` | No | UUID of the created or updated auth |
| `message` | `string` | Yes | Result message |
| `errors` | [`AuthFieldError`](#authfielderror)[] | No | Per-field validation errors |

---

## `AuthSlugResource`

Slug resource for auth.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Slug identifier |
| `value` | `string` | No | Slug value |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `CallerPermissions`

Evaluated permissions for the current caller on this artifact type.

| Field | Type | Required | Description |
|---|---|---|---|
| `can_create` | `boolean` | Yes | Whether the caller can create new artifacts |
| `can_draft` | `boolean` | Yes | Whether the caller can create/update drafts |
| `can_duplicate` | `boolean` | Yes | Whether the caller can duplicate artifacts |
| `has_access` | `boolean` | No | Whether the caller can view this entity |
| `can_edit` | `boolean` | No | Whether the caller can edit this entity |
| `can_delete` | `boolean` | No | Whether the caller can delete this entity |
| `disabled_reason` | `string` | No | Human-readable reason if editing is disabled |

---

## `ColumnInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Column name |
| `type` | `string` | Yes | Column data type |
| `nullable` | `boolean` | Yes | Whether the column is nullable |

---

## `CreateAuthItem`

Single auth item for create — no auth_id.

Required fields (name): provide ID or value.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Optional preset UUID for the new auth provider |
| `resource_id` | `string` | No | Optional preset UUID for the resource snapshot |
| `name_id` | `string` | No | REQUIRED FOR CREATE (or pass ``name``). UUID of an existing name resource. |
| `name` | `string` | No | REQUIRED FOR CREATE (or pass ``name_id``). Display name text — creates a new name resource on the fly. |
| `description_id` | `string` | No | UUID of the description resource |
| `description` | `string` | No | Description value to resolve or create |
| `slug_id` | `string` | No | UUID of the slug resource |
| `slug` | `string` | No | Slug value to resolve or create |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs |
| `active` | `boolean` | No | Denormalized auth_active flag state |
| `department_ids` | `string`[] | No | Department UUIDs to assign |
| `departments` | `string`[] | No | Department names to resolve |
| `protocol_ids` | `string`[] | No | Protocol resource UUIDs |
| `protocol` | `string` | No | Protocol value to resolve |
| `item_ids` | `string`[] | No | Auth item UUIDs |
| `auth_resource_ids` | `string`[] | No | Auth resource UUIDs |

---

## `DeleteAuthResult`

Per-item result within a bulk delete response.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the deletion succeeded |
| `auth_id` | `string` | No | UUID of the deleted auth provider |
| `message` | `string` | Yes | Result message |

---

## `DocsApiResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `list` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `detail` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `new` | [`PageMetaItem`](#pagemetaitem) | Yes | — |

---

## `DocsResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Resource or entry name |
| `type` | `string` | Yes | Resource or entry type identifier |
| `description` | `string` | Yes | Human-readable description |
| `materialized_view` | [`MvInfo`](#mvinfo) | No | Materialized view metadata |
| `tables` | [`TableInfo`](#tableinfo)[] | Yes | Related database tables |
| `operations` | [`OperationInfo`](#operationinfo)[] | Yes | Available operations |

---

## `EvalSetup`

Run-level eval scaffold — first-class on the generate response.

Audit's ``**output`` spread carries this onto
``<artifact>.generate.completed``. Null when no rubric-bearing
agent participated.

| Field | Type | Required | Description |
|---|---|---|---|
| `test_id` | `string` | Yes | — |
| `invocations` | [`InvocationSlot`](#invocationslot)[] | Yes | — |

---

## `GenerateConfig`

Developer configuration — all optional with sensible defaults.

| Field | Type | Required | Description |
|---|---|---|---|
| `operations` | `string`[] | No | — |
| `dangerous` | `boolean` | No | — |
| `params` | `object` | No | — |
| `group_id` | `string` | No | — |

---

## `GenerationsAuthListItem`

Single generation group in the auth generations response.

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | UUID of the generation group |
| `session_id` | `string` | No | UUID of the parent session |
| `group_name` | `string` | No | Name of the generation group |
| `created_at` | `string` | No | Timestamp of the generation |

---

## `GetAuthDraftResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | UUID of the draft |
| `created_at` | `string` | Yes | Creation timestamp |
| `generated` | `boolean` | Yes | Whether this was AI-generated |
| `mcp` | `boolean` | Yes | Whether MCP tooling was used |
| `active` | `boolean` | Yes | Whether this draft is active |
| `session_id` | `string` | Yes | Associated session UUID |
| `name` | `string` | No | Immutable draft label set at create time |
| `department_ids` | `string`[] | Yes | Associated department UUIDs |
| `description_ids` | `string`[] | Yes | Associated description UUIDs |
| `flag_ids` | `string`[] | Yes | Associated flag UUIDs |
| `item_ids` | `string`[] | Yes | Associated item UUIDs |
| `name_ids` | `string`[] | Yes | Associated name UUIDs |
| `profile_ids` | `string`[] | Yes | Associated profile UUIDs |
| `protocol_ids` | `string`[] | Yes | Associated protocol UUIDs |
| `slug_ids` | `string`[] | Yes | Associated slug UUIDs |
| `pending_department_ids` | `string`[] | No | Pending department UUIDs |
| `pending_description_ids` | `string`[] | No | Pending description UUIDs |
| `pending_flag_ids` | `string`[] | No | Pending flag UUIDs |
| `pending_item_ids` | `string`[] | No | Pending item UUIDs |
| `pending_name_ids` | `string`[] | No | Pending name UUIDs |
| `pending_protocol_ids` | `string`[] | No | Pending protocol UUIDs |
| `pending_slug_ids` | `string`[] | No | Pending slug UUIDs |

---

## `GroupCall`

Tool call referenced by a message.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `tool_name` | `string` | No | — |
| `template_name` | `string` | No | — |
| `tool` | `object` | No | — |
| `ledger_status` | `string` | No | — |
| `ledger_operation` | `string` | No | — |
| `ledger_artifact` | `string` | No | — |
| `ledger_artifact_id` | `string` | No | — |

---

## `GroupMessage`

Message within a run.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `role` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `text_ids` | `string`[] | No | — |
| `audio_ids` | `string`[] | No | — |
| `image_ids` | `string`[] | No | — |
| `video_ids` | `string`[] | No | — |
| `file_ids` | `string`[] | No | — |
| `call_ids` | `string`[] | No | — |
| `calls` | [`GroupCall`](#groupcall)[] | No | — |
| `reasoning` | `boolean` | No | True when this row is a chain-of-thought trace persisted alongside the assistant answer (rendered as a collapsed accordion). |
| `in_context` | `boolean` | No | Whether this message is included in the LLM context for the next generation. Mirrors the dedup pass that builds chat history (see in_context_reason). |
| `in_context_reason` | `string` | No | Why this message is in/out of LLM context. 'kept' = included; 'deduped_read' = older read-only call to a tool that has a fresher result later in the group; future values may include 'trimmed_top_n'. |

---

## `GroupResource`

Lightweight `\{id, name\}` for cross-referencing run-level ids
(``model_id`` / ``agent_id`` / ``profile_id``) against human-readable
names on the analytics panel. Names come from the canonical
``get_models`` / ``get_agents`` / ``get_profiles`` black boxes.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `name` | `string` | No | — |

---

## `GroupRun`

Run within a group, with its messages.

Carries token / cost / model / agent / profile attribution so the
analytics view can render per-run cost + actor info without a
parallel detail shape. ``profile_id`` is the authoring profile
(human user), ``agent_id`` is the LLM-side actor, ``model_id`` is
the model used by that agent. All optional — runs predating these
columns or with unresolved attributions surface ``None``.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `input_tokens` | `integer` | No | — |
| `output_tokens` | `integer` | No | — |
| `cached_input_tokens` | `integer` | No | — |
| `cost` | `number` | No | — |
| `model_id` | `string` | No | — |
| `agent_id` | `string` | No | — |
| `profile_id` | `string` | No | — |
| `previous_context_start_index` | `integer` | No | Index in ``messages`` where the current run's own messages begin; earlier rows are previous-context replay. ``None`` when the run has no previous context attached. |
| `messages` | [`GroupMessage`](#groupmessage)[] | No | — |

---

## `InvocationSlot`

One agent's slot in a multi-agent generation pool.

Populated by ``setup_generation_test`` when an agent carries a
rubric. The client uses these IDs to drive the eval workflow:
review the candidate's output, optionally fire a grader against
its ``invocation_id``, and promote/reject by call_id via the
existing ``idempotency_key + accept`` pattern.

| Field | Type | Required | Description |
|---|---|---|---|
| `invocation_id` | `string` | Yes | — |
| `agent_id` | `string` | Yes | — |
| `rubric_id` | `string` | No | — |

---

## `ListAuthApiAuth`

Auth type for list endpoint with computed permissions.

| Field | Type | Required | Description |
|---|---|---|---|
| `auth_id` | `string` | No | Unique auth provider identifier |
| `name` | `string` | No | Auth provider display name |
| `description` | `string` | No | Auth provider description text |
| `item_count` | `integer` | No | Number of auth items |
| `department_ids` | `string`[] | No | Associated department IDs |
| `setting_ids` | `string`[] | No | Setting artifact UUIDs that reference this auth |
| `auth_item_key_ids` | `string`[] | No | Auth item key resource UUIDs owned by this auth |
| `is_inactive` | `boolean` | No | Whether the auth provider is inactive |
| `can_edit` | `boolean` | No | Whether the actor can edit this auth |
| `can_duplicate` | `boolean` | No | Whether the actor can duplicate this auth |
| `can_delete` | `boolean` | No | Whether the actor can delete this auth |
| `pending_status` | `string` | No | Soft-call ledger status (pending/accepted/rejected) for the latest pending op on this row |
| `pending_operation` | `string` | No | Operation name (create/update/delete/duplicate/draft) of the latest pending soft-call entry |
| `pending_call_id` | `string` | No | Originating tool call id for the latest pending soft-call entry |

---

## `ListFilterOption`

Standardized option for list endpoint filter sections.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier for this filter option |
| `name` | `string` | No | Display name |
| `count` | `integer` | No | Number of matching records |
| `hex_code` | `string` | No | Hex color code for display |
| `value` | `string` | No | Internal value |
| `type` | `string` | No | Option type discriminator |

---

## `ListFilterSection`

Filter section with options and echoed request state.

| Field | Type | Required | Description |
|---|---|---|---|
| `options` | [`ListFilterOption`](#listfilteroption)[] | No | Available filter options |
| `selected_ids` | `string`[] | No | Currently selected filter option IDs |
| `search` | `string` | No | Active search text for filtering |

---

## `MvInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Materialized view name |
| `definition` | `string` | Yes | SQL definition of the view |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the view |

---

## `OperationInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Operation name |
| `description` | `string` | Yes | Human-readable description of the operation |
| `params` | [`ParamInfo`](#paraminfo)[] | Yes | List of operation parameters |
| `returns` | `object` | No | Return type schema |

---

## `OperationPrompts`

Starter prompts keyed by operation name.

Each key is an operation (e.g. "create", "search", "draft", "export")
and the value is a list of starter prompts for that operation.
The client picks from the operations the caller has permission for
and rotates through them.

| Field | Type | Required | Description |
|---|---|---|---|
| `prompts` | `object` | No | Map of operation name to starter prompts |

---

## `PageMetaItem`

| Field | Type | Required | Description |
|---|---|---|---|
| `title` | `string` | Yes | — |
| `description` | `string` | Yes | — |

---

## `ParamInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Parameter name |
| `type` | `string` | Yes | Parameter data type |
| `required` | `boolean` | Yes | Whether the parameter is required |
| `default` | `any` | No | Default value if not required |

---

## `ProducedMedia`

One asset produced by a generation run.

``resource_id`` is the canonical id the per-artifact download tools
accept (e.g. ``Scenario_Image_Download(image_id=resource_id)`` for
``modality="image"``). It maps to ``images_resource.id`` /
``videos_resource.id`` / ``audios_resource.id`` depending on the
modality.

| Field | Type | Required | Description |
|---|---|---|---|
| `modality` | `"image"` \| `"video"` \| `"audio"` | Yes | — |
| `resource_id` | `string` | Yes | — |
| `upload_id` | `string` | Yes | — |
| `mime_type` | `string` | No | — |
| `file_size` | `integer` | No | — |

---

## `ProfileSummary`

Caller identity derived from JWT — who you are on this page.

Superset of the old six-field version: now carries everything the client
needs so that ``/\{artifact\}/context`` fully replaces ``/profiles/context``
and the extra ``getLayoutContextData`` round-trip can be dropped.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Display name of the authenticated user |
| `role` | `string` | Yes | Role name (e.g. 'Super Administrator') |
| `role_level` | `integer` | Yes | Role hierarchy level (0 = highest privilege) |
| `department_ids` | `string`[] | Yes | Departments the user belongs to |
| `artifact_access` | `string`[] | Yes | Artifact types this role can access (sidebar visibility) |
| `role_permissions` | `any`[][] | Yes | Full (artifact, operation) permission tuples for granular page gating |
| `is_active` | `boolean` | Yes | Whether the user's profile is active |
| `id` | `string` | Yes | Profile UUID (SocketProvider, ProfileProvider) |
| `theme` | [`ThemeBundle`](#themebundle) | No | Resolved theme: hex primitives + derived oklch tokens + score thresholds |
| `session_id` | `string` | No | Current session UUID |
| `is_emulation` | `boolean` | No | Whether user is in emulation mode (ProfileProvider) |
| `role_resources` | [`QGetProfileContextV4RoleResource`](#qgetprofilecontextv4roleresource)[] | No | All role resources for emulation display (ProfileProvider) |
| `scoped_roles` | `string`[] | No | Roles the user can emulate (ProfileProvider) |
| `active` | `boolean` | No | Alias for is_active (ProfileProvider uses this name) |

---

## `QGetProfileContextV4RoleResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `role` | `string` | No | — |
| `name` | `string` | No | — |
| `description` | `string` | No | — |
| `icon_value` | `string` | No | — |
| `color_hex` | `string` | No | — |

---

## `RunStatus`

Outcome of one watched run.

| Field | Type | Required | Description |
|---|---|---|---|
| `run_id` | `string` | Yes | — |
| `status` | `"pending"` \| `"completed"` \| `"failed"` | Yes | — |
| `modality` | `string` | No | Modality of generated output (image, video, text…) |
| `resource_ids` | `string`[] | No | Resource UUIDs produced by this run (e.g. images_resource ids) |
| `error` | `string` | No | — |

---

## `TableInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Table name |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the table |

---

## `ThemeBundle`

Full theme payload for a page bootstrap.

Riding along on every ``/\{artifact\}/context`` response via
``ProfileSummary.theme``. Layers:
  - ``primitives`` / ``dark_primitives`` — hex inputs the settings
    editor reads/writes (light + dark palettes).
  - ``tokens`` / ``dark_tokens`` — oklch tokens the client paints with.
    ``ThemeStyle`` emits two ``<style>`` blocks: one scoped to
    ``:root:not(.dark)`` (light) and one to ``:root.dark`` (dark).
  - ``thresholds`` — numeric score thresholds for analytics components.
Empty-in → empty-out per token: missing values fall through to the
matching ``globals.css`` default.

| Field | Type | Required | Description |
|---|---|---|---|
| `primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (light palette, for the theme editor) |
| `tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for light mode (SSR CSS-var injection) |
| `dark_primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (dark palette, for the theme editor) |
| `dark_tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for dark mode (SSR CSS-var injection) |
| `thresholds` | [`Thresholds`](#thresholds) | No | Score thresholds resolved from the setting |

---

## `ThemePrimitives`

40 optional fields. The 17 essentials drive the rest; the other 23
are overrides for fine-tuning when derivation isn't what you want.

Empty primitive → empty token → client falls back to globals.css.

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `primary` | `string` | No | — |
| `accent` | `string` | No | — |
| `card` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `ring` | `string` | No | — |
| `border` | `string` | No | — |
| `destructive` | `string` | No | — |
| `success` | `string` | No | — |
| `warning` | `string` | No | — |
| `info` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `input` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `ThemeTokens`

40 fully-resolved CSS variable values (snake_case 1:1 with vars).

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `accent` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `border` | `string` | No | — |
| `input` | `string` | No | — |
| `ring` | `string` | No | — |
| `success` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `Thresholds`

Numeric score thresholds resolved from the active setting.

Server pre-buckets dashboard metrics into ``success | warning | danger |
neutral`` already, so most components don't need these values. Surface
them for chart reference lines, tooltips, and any client-side bucketing.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `integer` | Yes | Score >= this counts as success |
| `warning` | `integer` | Yes | Score >= this counts as warning |
| `danger` | `integer` | Yes | Score < success threshold but >= this counts as danger; below is neutral/no-data |

---

## `UpdateAuthItem`

Single auth item for update — auth_id required, all fields optional.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | UUID of the auth provider to update |
| `name_id` | `string` | No | UUID of the name resource |
| `name` | `string` | No | Name value to resolve or create |
| `description_id` | `string` | No | UUID of the description resource |
| `description` | `string` | No | Description value to resolve or create |
| `slug_id` | `string` | No | UUID of the slug resource |
| `slug` | `string` | No | Slug value to resolve or create |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs |
| `active` | `boolean` | No | Denormalized auth_active flag state |
| `department_ids` | `string`[] | No | Department UUIDs to assign |
| `departments` | `string`[] | No | Department names to resolve |
| `protocol_ids` | `string`[] | No | Protocol resource UUIDs |
| `protocol` | `string` | No | Protocol value to resolve |
| `item_ids` | `string`[] | No | Auth item UUIDs |
| `auth_resource_ids` | `string`[] | No | Auth resource UUIDs |

---

## `UpdateAuthPatch`

Shared patch for bulk-update-all-matching mode.

Inherits every field from ``UpdateAuthItem`` and just relaxes
``id`` to optional — the bulk impl stamps the resolved id onto a
clone of the patch per matched row, so any client-supplied id is
ignored. Sparse semantics: only fields the client sets are written.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Ignored — bulk impl stamps the resolved auth id per matched row |
| `name_id` | `string` | No | UUID of the name resource |
| `name` | `string` | No | Name value to resolve or create |
| `description_id` | `string` | No | UUID of the description resource |
| `description` | `string` | No | Description value to resolve or create |
| `slug_id` | `string` | No | UUID of the slug resource |
| `slug` | `string` | No | Slug value to resolve or create |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs |
| `active` | `boolean` | No | Denormalized auth_active flag state |
| `department_ids` | `string`[] | No | Department UUIDs to assign |
| `departments` | `string`[] | No | Department names to resolve |
| `protocol_ids` | `string`[] | No | Protocol resource UUIDs |
| `protocol` | `string` | No | Protocol value to resolve |
| `item_ids` | `string`[] | No | Auth item UUIDs |
| `auth_resource_ids` | `string`[] | No | Auth resource UUIDs |

---

## `app__infra__auth__types__DraftFormState`

Server-authoritative form state returned after draft save.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | No | Echoed name value |
| `name_id` | `string` | No | Resolved name resource UUID |
| `description` | `string` | No | Echoed description value |
| `description_id` | `string` | No | Resolved description resource UUID |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs |
| `active` | `boolean` | No | Echoed auth_active flag state |
| `department_ids` | `string`[] | No | Assigned department UUIDs |
| `protocol_ids` | `string`[] | No | Assigned protocol UUIDs |
| `slug_ids` | `string`[] | No | Assigned slug UUIDs |
| `item_ids` | `string`[] | No | Assigned auth item UUIDs |
| `pending_ids` | `string`[] | No | Pending resource identifiers |

---

## `app__infra__auth__types__SectionFilter`

Per-section filter options for GET requests.

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Filter options by search text |
| `limit` | `integer` | No | Max options to return |
| `selected` | `boolean` | No | Only return selected items |
| `suggested` | `boolean` | No | Only return suggested items |
| `include` | `boolean` | No | Include this section in response (default true) |
| `parameter_ids` | `string`[] | No | Unused for auth; present for shared request compatibility |

---

---

# `GET` `/authorize`

Route: /api-reference/authorize

# `GET` `/authorize`

Authorize

OIDC authorization endpoint.

Without profile_id: standard OIDC flow — redirect to Keycloak for login.
With profile_id: Keycloak broker callback — issue auth code directly.

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `client_id` | query | Yes | — |
| `redirect_uri` | query | Yes | — |
| `response_type` | query | Yes | — |
| `state` | query | No | — |
| `scope` | query | No | — |
| `nonce` | query | No | — |
| `profile_id` | query | No | — |
| `emulation_grant` | query | No | — |
| `login_hint` | query | No | — |

## Response

```
{}
```

---

# `GET` `/callback`

Route: /api-reference/callback

# `GET` `/callback`

Callback

Handle Keycloak callback — exchange code for tokens.

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `code` | query | No | — |
| `error` | query | No | — |

## Response

```
{}
```

---

# `GET` `/cohort/watch`

Route: /api-reference/cohort/get-cohort-watch

# `GET` `/cohort/watch`

Cohort Watch

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `group_id` | query | No | — |
| `run_id` | query | No | Optional run filter. If provided, only events whose envelope run_id matches are streamed. Omit to receive every cohort event in the group (the FE default). |

## Response

```
{}
```

---

# `POST` `/cohort/call_download`

Route: /api-reference/cohort/post-cohort-call-download

# `POST` `/cohort/call_download`

Download Call

Download a call file by call resource ID.

## Request Body (`CallDownloadCohortApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `call_id` | `string` | Yes | UUID of the calls_resource to download |

## Response

```
{}
```

---

# `POST` `/cohort/context`

Route: /api-reference/cohort/post-cohort-context

# `POST` `/cohort/context`

Get Cohort Context

Get page context for the cohort artifact.

Returns docs + profile identity + evaluated permissions in a single call.
Superset of /docs — clients can migrate from /docs to /context incrementally.

## Request Body (`DocsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entity_id` | `string` | No | — |
| `snapshot_key` | `string` | No | — |
| `schema` | `boolean` | No | If true, include MCP/tooling schema metadata (artifact, entries, resources, permission_docs, api_operations). Defaults to false for lean page-bootstrap responses. |

## Response (`ComposedContextResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Artifact name |
| `type` | `string` | Yes | Artifact type identifier |
| `description` | `string` | Yes | Human-readable description |
| `artifact` | [`DocsResponse`](/api-reference/cohort/types#docsresponse) | No | Artifact tool documentation (None unless schema=true) |
| `entries` | [`DocsResponse`](/api-reference/cohort/types#docsresponse)[] | No | Entry documentation list (None unless schema=true) |
| `resources` | [`DocsResponse`](/api-reference/cohort/types#docsresponse)[] | No | Resource documentation list (None unless schema=true) |
| `permission_docs` | [`OperationInfo`](/api-reference/cohort/types#operationinfo)[] | No | Permission function signatures for MCP/dev tooling (None unless schema=true) |
| `api_operations` | [`OperationInfo`](/api-reference/cohort/types#operationinfo)[] | No | API operation documentation (None unless schema=true) |
| `page_metadata` | [`DocsApiResponse`](/api-reference/cohort/types#docsapiresponse) | No | Page-level metadata |
| `prompts` | [`OperationPrompts`](/api-reference/cohort/types#operationprompts) | No | Starter prompts keyed by operation |
| `profile` | [`ProfileSummary`](/api-reference/cohort/types#profilesummary) | Yes | Caller identity from JWT |
| `caller_permissions` | [`CallerPermissions`](/api-reference/cohort/types#callerpermissions) | Yes | Evaluated permissions for this caller |

---

# `POST` `/cohort/create`

Route: /api-reference/cohort/post-cohort-create

# `POST` `/cohort/create`

Create Cohort

Create cohorts using composable infra architecture.

## Request Body (`CreateCohortApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `cohorts` | [`CreateCohortItem`](/api-reference/cohort/types#createcohortitem)[] | Yes | List of cohorts to create |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant create |
| `soft` | `boolean` | No | Stage the create dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`CreateCohortApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`CohortResultItem`](/api-reference/cohort/types#cohortresultitem)[] | Yes | List of operation results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/cohort/csv`

Route: /api-reference/cohort/post-cohort-csv

# `POST` `/cohort/csv`

Parse Cohort Csv

Parse a CSV file and return mapped items for preview.

## Request Body

| Field | Type | Required | Description |
|---|---|---|---|
| `file` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `soft` | `boolean` | No | — |
| `accept` | `boolean` | No | — |

## Response (`ParseCohortCsvApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `upload_id` | `string` | Yes | — |
| `items` | [`CreateCohortItem`](/api-reference/cohort/types#createcohortitem)[] | Yes | — |
| `mapped_fields` | `string`[] | Yes | — |
| `row_count` | `integer` | Yes | — |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with `accept` to promote/reject the staged raw-CSV upload. NOTE: ack returns no items (the preview is only on the propose). |

---

# `POST` `/cohort/delete`

Route: /api-reference/cohort/post-cohort-delete

# `POST` `/cohort/delete`

Delete Cohort

Bulk delete cohorts — composable infra architecture.

## Request Body (`DeleteCohortApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `cohort_ids` | `string`[] | No | Cohort UUIDs to delete (required on first call when ``all`` is false) |
| `all` | `boolean` | No | When true, delete every cohort matching the filter fields below (minus ``excluded_ids``) |
| `excluded_ids` | `string`[] | No | UUIDs to skip even when matched by ``all``-mode filters |
| `search` | `string` | No | Full-text search query |
| `filter_profile_ids` | `string`[] | No | Filter by profile UUIDs |
| `filter_simulation_ids` | `string`[] | No | Filter by simulation UUIDs |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `profile_search` | `string` | No | Search text for profile facet (no-op for row filtering) |
| `simulation_search` | `string` | No | Search text for simulation facet (no-op for row filtering) |
| `department_search` | `string` | No | Search text for department facet (no-op for row filtering) |
| `flag_search` | `string` | No | Search text for flag facet (no-op for row filtering) |
| `idempotency_key` | `string` | No | Operation key for ack — confirms or rejects a dormant delete |
| `soft` | `boolean` | No | Stage the delete dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (confirm deletion) or reject (restore). Only meaningful with idempotency_key |

## Response (`DeleteCohortApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`DeleteCohortResult`](/api-reference/cohort/types#deletecohortresult)[] | Yes | List of operation results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/cohort/draft`

Route: /api-reference/cohort/post-cohort-draft

# `POST` `/cohort/draft`

Patch Cohort Draft

Patch cohort draft — composable infra architecture.

## Request Body (`PatchCohortDraftApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `draft_id` | `string` | No | Existing draft UUID to patch |
| `input_draft_id` | `string` | No | Legacy alias for existing draft UUID to patch |
| `name` | `string` | No | Name value to create a resource |
| `name_id` | `string` | No | Existing name resource UUID |
| `description` | `string` | No | Description value to create a resource |
| `description_id` | `string` | No | Existing description resource UUID |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `active` | `boolean` | No | Denormalized cohort_active flag state; resolved to a flag_ids entry server-side |
| `department_ids` | `string`[] | No | Department UUIDs |
| `departments` | `string`[] | No | Department names to resolve |
| `simulation_ids` | `string`[] | No | Simulation UUIDs |
| `simulations` | `string`[] | No | Simulation names to resolve |
| `profile_ids` | `string`[] | No | Profile UUIDs |
| `profiles` | `string`[] | No | Profile names to resolve |
| `simulation_position_ids` | `string`[] | No | Existing simulation position UUIDs |
| `simulation_positions` | [`DraftSimulationPositionValue`](/api-reference/cohort/types#draftsimulationpositionvalue)[] | No | Simulation position values to create |
| `simulation_availability_ids` | `string`[] | No | Existing simulation availability UUIDs |
| `simulation_availability` | [`DraftSimulationAvailabilityValue`](/api-reference/cohort/types#draftsimulationavailabilityvalue)[] | No | Simulation availability values to create |
| `profile_persona_ids` | `string`[] | No | Existing profile persona UUIDs |
| `profile_personas` | [`DraftProfilePersonaValue`](/api-reference/cohort/types#draftprofilepersonavalue)[] | No | Profile persona values to create |
| `pending_ids` | `string`[] | No | Resource IDs to keep as pending where supported by the tool layer |
| `idempotency_key` | `string` | No | Operation key for ack or retry |
| `soft` | `boolean` | No | Stage the draft dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept or reject dormant draft state |

## Response (`PatchCohortDraftApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `draft_id` | `string` | Yes | Draft UUID |
| `idempotency_key` | `string` | Yes | Idempotency key for this draft operation |
| `message` | `string` | Yes | Human-readable result message |
| `form_state` | [`app__infra__cohort__types__DraftFormState`](/api-reference/cohort/types#app-infra-cohort-types-draftformstate) | No | Server-authoritative form state |

---

# `POST` `/cohort/drafts`

Route: /api-reference/cohort/post-cohort-drafts

# `POST` `/cohort/drafts`

Get Cohort Drafts

List cohort drafts owned by the current profile.

## Request Body (`GetCohortDraftsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE substring) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GetCohortDraftsApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entries` | [`GetCohortDraftResponse`](/api-reference/cohort/types#getcohortdraftresponse)[] | No | List of cohort draft entries |

---

# `POST` `/cohort/duplicate`

Route: /api-reference/cohort/post-cohort-duplicate

# `POST` `/cohort/duplicate`

Duplicate Cohort

Duplicate a cohort — composable infra architecture.

## Request Body (`DuplicateCohortApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `cohort_id` | `string` | Yes | Cohort UUID to duplicate |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant duplicate |
| `soft` | `boolean` | No | Stage the duplicate dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`DuplicateCohortApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `cohort_id` | `string` | Yes | Newly created cohort UUID |
| `message` | `string` | Yes | Human-readable result message |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/cohort/export`

Route: /api-reference/cohort/post-cohort-export

# `POST` `/cohort/export`

Export Cohorts

Export all cohorts as a clean, denormalized CSV.

## Request Body (`ExportCohortApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `cohort_id` | `string` | No | — |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior export instead of re-running |
| `soft` | `boolean` | No | Stage the export dormant (active=False); ack with accept activates it |
| `accept` | `boolean` | No | Ack: True promotes the staged export, False rejects. Only meaningful with idempotency_key |

## Response (`ExportCohortApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource holding the export CSV |
| `file_name` | `string` | Yes | Suggested download file name |
| `row_count` | `integer` | Yes | Number of data rows in the export |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with `accept` to promote/reject the staged export. |

---

# `POST` `/cohort/file_download`

Route: /api-reference/cohort/post-cohort-file-download

# `POST` `/cohort/file_download`

Download File

Download a file by file resource ID.

## Request Body (`FileDownloadCohortApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource to download |

## Response

```
{}
```

---

# `POST` `/cohort/generate`

Route: /api-reference/cohort/post-cohort-generate

# `POST` `/cohort/generate`

Generate Cohort

Trigger cohort generation. Returns immediately; progress via events.

## Request Body (`ArtifactGenerateRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `instructions` | `string`[] | No | — |
| `config` | [`GenerateConfig`](/api-reference/cohort/types#generateconfig) | No | — |
| `modalities` | `string`[] | No | — |
| `audios_id` | `string` | No | — |
| `conversation_id` | `string` | No | — |
| `trace_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `accept` | `boolean` | No | — |
| `wait_for_complete` | `boolean` | No | — |

## Response (`ArtifactGenerateResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `run_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `eval` | [`EvalSetup`](/api-reference/cohort/types#evalsetup) | No | — |
| `produced_media` | [`ProducedMedia`](/api-reference/cohort/types#producedmedia)[] | No | — |

---

# `POST` `/cohort/generations`

Route: /api-reference/cohort/post-cohort-generations

# `POST` `/cohort/generations`

Generations Cohort

List cohort generation groups — composable infra architecture.

## Request Body (`GenerationsCohortApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GenerationsCohortApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `items` | [`GenerationsCohortListItem`](/api-reference/cohort/types#generationscohortlistitem)[] | No | Generation groups |
| `total_count` | `integer` | No | Total number of matching generations |

---

# `POST` `/cohort/get`

Route: /api-reference/cohort/post-cohort-get

# `POST` `/cohort/get`

Get Cohort

Get cohort information using the canonical shared cohort operation.

## Request Body (`GetCohortApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Cohort UUID to retrieve |
| `cohort_id` | `string` | No | Legacy alias for cohort UUID |
| `draft_id` | `string` | No | Draft UUID to load from |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |
| `names` | [`app__infra__cohort__types__SectionFilter`](/api-reference/cohort/types#app-infra-cohort-types-sectionfilter) | No | Filter options for names section |
| `descriptions` | [`app__infra__cohort__types__SectionFilter`](/api-reference/cohort/types#app-infra-cohort-types-sectionfilter) | No | Filter options for descriptions section |
| `flags` | [`app__infra__cohort__types__SectionFilter`](/api-reference/cohort/types#app-infra-cohort-types-sectionfilter) | No | Filter options for flags section |
| `departments` | [`app__infra__cohort__types__SectionFilter`](/api-reference/cohort/types#app-infra-cohort-types-sectionfilter) | No | Filter options for departments section |
| `simulations` | [`app__infra__cohort__types__SectionFilter`](/api-reference/cohort/types#app-infra-cohort-types-sectionfilter) | No | Filter options for simulations section |
| `simulation_positions` | [`app__infra__cohort__types__SectionFilter`](/api-reference/cohort/types#app-infra-cohort-types-sectionfilter) | No | Filter options for simulation positions section |
| `simulation_availability` | [`app__infra__cohort__types__SectionFilter`](/api-reference/cohort/types#app-infra-cohort-types-sectionfilter) | No | Filter options for simulation availability section |
| `profiles` | [`app__infra__cohort__types__SectionFilter`](/api-reference/cohort/types#app-infra-cohort-types-sectionfilter) | No | Filter options for profiles section |
| `profile_personas` | [`app__infra__cohort__types__SectionFilter`](/api-reference/cohort/types#app-infra-cohort-types-sectionfilter) | No | Filter options for profile personas section |
| `personas` | [`app__infra__cohort__types__SectionFilter`](/api-reference/cohort/types#app-infra-cohort-types-sectionfilter) | No | Filter options for personas section |
| `descriptions_search` | `string` | No | Legacy search query for descriptions |
| `simulation_search` | `string` | No | Legacy search query for simulations |
| `simulation_show_selected` | `boolean` | No | Legacy selected-only flag for simulations |
| `profile_search` | `string` | No | Legacy search query for profiles |
| `profile_show_selected` | `boolean` | No | Legacy selected-only flag for profiles |

## Response (`GetCohortApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current user |
| `cohort_exists` | `boolean` | No | Whether the cohort exists |
| `can_edit` | `boolean` | No | Whether the current user can edit |
| `disabled_reason` | `string` | No | Reason editing is disabled |
| `group_id` | `string` | No | Associated group UUID |
| `draft_name` | `string` | No | Immutable draft label from the active draft entry, when a ``draft_id`` was supplied. ``None`` for non-draft fetches. |
| `show_ai_generate` | `boolean` | No | Whether AI generation is available |
| `names` | [`CohortNameResource`](/api-reference/cohort/types#cohortnameresource)[] | No | Name resources with selected/suggested flags |
| `descriptions` | [`CohortDescriptionResource`](/api-reference/cohort/types#cohortdescriptionresource)[] | No | Description resources with selected/suggested flags |
| `flags` | [`CohortFlagResource`](/api-reference/cohort/types#cohortflagresource)[] | No | Flag resources with selected/suggested flags |
| `departments` | [`CohortDepartment`](/api-reference/cohort/types#cohortdepartment)[] | No | Department resources with selected/suggested flags |
| `simulations` | [`CohortSimulation`](/api-reference/cohort/types#cohortsimulation)[] | No | Simulation resources with selected/suggested flags |
| `simulation_positions` | [`CohortSimulationPosition`](/api-reference/cohort/types#cohortsimulationposition)[] | No | Simulation position resources with selected/suggested flags |
| `simulation_availability` | [`CohortSimulationAvailability`](/api-reference/cohort/types#cohortsimulationavailability)[] | No | Simulation availability resources with selected/suggested flags |
| `profiles` | [`CohortProfile`](/api-reference/cohort/types#cohortprofile)[] | No | Profile resources with selected/suggested flags |
| `profile_personas` | [`CohortProfilePersona`](/api-reference/cohort/types#cohortprofilepersona)[] | No | Profile persona resources with selected/suggested flags |
| `personas` | [`CohortPersonaResource`](/api-reference/cohort/types#cohortpersonaresource)[] | No | Persona resources with selected/suggested flags |
| `pending_ids` | `string`[] | No | Pending resource IDs from the draft, when available |
| `basic_show_ai_generate` | `boolean` | No | Legacy AI-generate flag for the basic step |
| `simulations_step_show_ai_generate` | `boolean` | No | Legacy AI-generate flag for the simulations step |
| `profiles_step_show_ai_generate` | `boolean` | No | Legacy AI-generate flag for the profiles step |

---

# `POST` `/cohort/group`

Route: /api-reference/cohort/post-cohort-group

# `POST` `/cohort/group`

Group Cohort

Resolve or create a cohort group with optional naming.

## Request Body (`GroupCohortApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | No | Existing group UUID (omit to create or reuse via time window) |
| `snapshot_key` | `string` | No | Snapshot key for SETNX-race convergence on a single group across concurrent reads (e.g. parallel /context + /group + /search fan-out on page load). Echoed back in the response. |

## Response (`GroupCohortApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Resolved or newly created group UUID |
| `name` | `string` | No | The group's current title (latest active group_names_entry, or 'New Chat' fallback for freshly minted groups) |
| `snapshot_key` | `string` | No | Snapshot key echoed back — the UUID concurrent fan-out reads converged on via SETNX. Mirrors the resolved group_id. |
| `runs` | [`GroupRun`](/api-reference/cohort/types#grouprun)[] | No | Conversation history — populated when resolving an existing group for fetch |
| `group_exists` | `boolean` | No | (detail) Whether the group exists in storage — populated when ``include_resources=True`` |
| `actor_name` | `string` | No | (detail) Display name of the current actor (caller profile) |
| `total_message_count` | `integer` | No | (detail) Total number of messages in the group |
| `models` | [`GroupResource`](/api-reference/cohort/types#groupresource)[] | No | (detail) Models used in the group |
| `agents` | [`GroupResource`](/api-reference/cohort/types#groupresource)[] | No | (detail) Agents used in the group |
| `profiles` | [`GroupResource`](/api-reference/cohort/types#groupresource)[] | No | (detail) Profiles that authored runs in this group |

---

# `POST` `/cohort/problem`

Route: /api-reference/cohort/post-cohort-problem

# `POST` `/cohort/problem`

Problem Cohort

Report a cohort problem — composable infra architecture.

## Request Body (`ProblemCohortApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | `string` | Yes | Problem type: feature, bug, question, other |
| `message` | `string` | Yes | Problem description (max 1000 chars) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant problem |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`ProblemCohortApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `problem_id` | `string` | Yes | UUID of the created problem |
| `success` | `boolean` | No | Whether the problem was created |
| `message` | `string` | No | Status message |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/cohort/refresh`

Route: /api-reference/cohort/post-cohort-refresh

# `POST` `/cohort/refresh`

Cohort Refresh

Refresh cohort materialized views and invalidate caches.

## Request Body (`RefreshCohortApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `targets` | `string`[] | No | MV targets to refresh (omit for all). Options: cohort_drafts_mv |
| `idempotency_key` | `string` | No | Operation key for ack |
| `accept` | `boolean` | No | Accept or reject. Only meaningful with idempotency_key |
| `soft` | `boolean` | No | Stage the refresh as a pending (held) request — recorded but not enqueued; ack with accept releases/enqueues it |

## Response (`RefreshResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | — |
| `refreshed_views` | `string`[] | Yes | — |
| `invalidated_tags` | `string`[] | Yes | — |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/cohort/search`

Route: /api-reference/cohort/post-cohort-search

# `POST` `/cohort/search`

Search Cohort

Search cohorts — composable infra architecture.

## Request Body (`SearchCohortApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | — |
| `filter_profile_ids` | `string`[] | No | — |
| `filter_simulation_ids` | `string`[] | No | — |
| `filter_department_ids` | `string`[] | No | — |
| `profile_search` | `string` | No | — |
| `simulation_search` | `string` | No | — |
| `department_search` | `string` | No | — |
| `flag_search` | `string` | No | — |
| `page_size` | `integer` | No | — |
| `page_offset` | `integer` | No | — |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`ListCohortApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current user |
| `user_role` | `string` | No | Role of the current user |
| `cohorts` | [`ListCohortApiCohort`](/api-reference/cohort/types#listcohortapicohort)[] | No | List of cohorts |
| `profiles` | [`ListCohortApiProfile`](/api-reference/cohort/types#listcohortapiprofile)[] | No | List of profiles for filtering |
| `simulations` | [`ListCohortApiSimulation`](/api-reference/cohort/types#listcohortapisimulation)[] | No | List of simulations for filtering |
| `departments` | [`ListCohortApiDepartment`](/api-reference/cohort/types#listcohortapidepartment)[] | No | List of departments for filtering |
| `simulation_filter` | [`ListFilterSection`](/api-reference/cohort/types#listfiltersection) | No | Filter options for simulations in list UI |
| `profile_filter` | [`ListFilterSection`](/api-reference/cohort/types#listfiltersection) | No | Filter options for profiles in list UI |
| `department_filter` | [`ListFilterSection`](/api-reference/cohort/types#listfiltersection) | No | Filter options for departments in list UI |
| `flag_filter` | [`ListFilterSection`](/api-reference/cohort/types#listfiltersection) | No | Filter options for flags in list UI |
| `total_count` | `integer` | No | Total number of matching records |
| `import_fields` | [`ImportField`](/api-reference/cohort/types#importfield)[] | No | CSV import column schema for the bulk-import dialog |

---

# `POST` `/cohort/text_download`

Route: /api-reference/cohort/post-cohort-text-download

# `POST` `/cohort/text_download`

Download Text

Download a text file by text resource ID.

## Request Body (`TextDownloadCohortApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `text_id` | `string` | Yes | UUID of the texts_resource to download |

## Response

```
{}
```

---

# `POST` `/cohort/title`

Route: /api-reference/cohort/post-cohort-title

# `POST` `/cohort/title`

Title Cohort

Rename a cohort's group (writes group_names_entry).

## Request Body (`TitleCohortApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Group to rename |
| `title` | `string` | Yes | New title (display name) for the group |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant rename |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`TitleCohortApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | The group that was renamed |
| `group_name_id` | `string` | Yes | UUID of the new group_names_entry row |
| `title` | `string` | Yes | The title that was set |
| `idempotency_key` | `string` | No | Operation key echoed back |

---

# `POST` `/cohort/update`

Route: /api-reference/cohort/post-cohort-update

# `POST` `/cohort/update`

Update Cohort

Update cohorts using composable infra architecture.

## Request Body (`UpdateCohortApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `cohorts` | [`UpdateCohortItem`](/api-reference/cohort/types#updatecohortitem)[] | No | List of cohorts to update (required on first call when ``all`` is false) |
| `all` | `boolean` | No | When true, apply ``patch`` to every cohort matching the filter fields below (minus ``excluded_ids``) |
| `excluded_ids` | `string`[] | No | UUIDs to skip even when matched by ``all``-mode filters |
| `patch` | [`UpdateCohortPatch`](/api-reference/cohort/types#updatecohortpatch) | No | Shared change set applied to every matched row when ``all=true`` (sparse — only set fields are updated; ``patch.id`` ignored) |
| `search` | `string` | No | Full-text search query |
| `filter_profile_ids` | `string`[] | No | Filter by profile UUIDs |
| `filter_simulation_ids` | `string`[] | No | Filter by simulation UUIDs |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `profile_search` | `string` | No | Search text for profile facet (no-op for row filtering) |
| `simulation_search` | `string` | No | Search text for simulation facet (no-op for row filtering) |
| `department_search` | `string` | No | Search text for department facet (no-op for row filtering) |
| `flag_search` | `string` | No | Search text for flag facet (no-op for row filtering) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant update |
| `soft` | `boolean` | No | Stage the update dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`UpdateCohortApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`CohortResultItem`](/api-reference/cohort/types#cohortresultitem)[] | Yes | List of operation results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/cohort/watch`

Route: /api-reference/cohort/post-cohort-watch

# `POST` `/cohort/watch`

Cohort Watch Once

One-shot snapshot of run state, snapshot-replayable via ``snapshot_key``.

## Request Body (`WatchApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Chat group whose events we watch |
| `run_id` | `string` | No | Specific run to watch (e.g. the ``run_id`` returned by a prior ``X_Generate`` call). If None, watches every active run in the group at call time. |
| `wait_for_complete` | `boolean` | No | If True, block until the watched run reaches a terminal (complete/failed) event or timeout fires. If False, return current state and exit immediately. |
| `timeout_seconds` | `integer` | No | Max wait time when ``wait_for_complete=True``. |
| `snapshot_key` | `string` | No | Read snapshot key — on the one-shot POST /watch, the audit wrapper records this watch's point-in-time view (latest run state at call time) keyed by it and replays the same view on any later call with the same key. Ignored by the SSE GET stream. |

## Response (`WatchApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `runs` | [`RunStatus`](/api-reference/cohort/types#runstatus)[] | Yes | — |
| `timed_out` | `boolean` | No | — |
| `waited_seconds` | `number` | No | — |

---

# Cohort Types

Route: /api-reference/cohort/types

# Cohort Types

## `CallerPermissions`

Evaluated permissions for the current caller on this artifact type.

| Field | Type | Required | Description |
|---|---|---|---|
| `can_create` | `boolean` | Yes | Whether the caller can create new artifacts |
| `can_draft` | `boolean` | Yes | Whether the caller can create/update drafts |
| `can_duplicate` | `boolean` | Yes | Whether the caller can duplicate artifacts |
| `has_access` | `boolean` | No | Whether the caller can view this entity |
| `can_edit` | `boolean` | No | Whether the caller can edit this entity |
| `can_delete` | `boolean` | No | Whether the caller can delete this entity |
| `disabled_reason` | `string` | No | Human-readable reason if editing is disabled |

---

## `CohortDepartment`

Department for cohort.

| Field | Type | Required | Description |
|---|---|---|---|
| `department_id` | `string` | No | Department UUID |
| `name` | `string` | No | Department name |
| `description` | `string` | No | Department description |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `CohortDescriptionResource`

Description resource for cohort.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `description` | `string` | No | Description text |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `CohortFieldError`

Per-field error from value resolution.

| Field | Type | Required | Description |
|---|---|---|---|
| `field` | `string` | Yes | Field name that has the error |
| `message` | `string` | Yes | Human-readable error message |

---

## `CohortFlagResource`

Flag option row for cohort — one per (name, type, value) flags_resource entry.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Flag resource identifier |
| `name` | `string` | No | Flag display name |
| `type` | `string` | No | Flag type (e.g. 'cohort_active') |
| `value` | `boolean` | No | Underlying bool value of this option |
| `description` | `string` | No | Flag description |
| `icon_id` | `string` | No | Icon identifier for the flag |
| `icon` | `string` | No | Resolved SVG markup for the icon (hydrated from icons_resource) |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `CohortNameResource`

Name resource for cohort.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `name` | `string` | No | Display name |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `CohortPersonaResource`

Persona option exposed from cohort GET.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Persona UUID |
| `name` | `string` | No | Persona name |
| `description` | `string` | No | Persona description |
| `icon` | `string` | No | Persona icon |
| `color` | `string` | No | Persona color |
| `department_ids` | `string`[] | No | Associated department UUIDs |
| `instructions` | `string` | No | Persona instructions |
| `examples` | `string`[] | No | Persona examples |
| `parameter_field_ids` | `string`[] | No | Associated parameter field UUIDs |
| `active` | `boolean` | No | Whether the persona is active |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `mcp` | `boolean` | No | Whether created via MCP |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `CohortProfile`

Profile for cohort.

| Field | Type | Required | Description |
|---|---|---|---|
| `profile_id` | `string` | No | Profile UUID |
| `name` | `string` | No | Profile name |
| `description` | `string` | No | Profile description |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `mcp` | `boolean` | No | Whether created via MCP |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `CohortProfilePersona`

Profile persona for cohort.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `profile_id` | `string` | No | Associated profile UUID |
| `persona_id` | `string` | No | Associated persona UUID |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `mcp` | `boolean` | No | Whether created via MCP |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `CohortResultItem`

Per-item result within a bulk create/update response.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `cohort_id` | `string` | No | Cohort UUID |
| `message` | `string` | Yes | Human-readable result message |
| `errors` | [`CohortFieldError`](#cohortfielderror)[] | No | List of per-field errors |

---

## `CohortSimulation`

Simulation for cohort.

| Field | Type | Required | Description |
|---|---|---|---|
| `simulation_id` | `string` | No | Simulation UUID |
| `name` | `string` | No | Simulation name |
| `description` | `string` | No | Simulation description |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `CohortSimulationAvailability`

Simulation availability for cohort.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `simulation_id` | `string` | No | Associated simulation UUID |
| `time` | `string` | No | Availability time slot |
| `type` | `string` | No | Availability type |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `mcp` | `boolean` | No | Whether created via MCP |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `CohortSimulationPosition`

Simulation position for cohort.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `simulation_id` | `string` | No | Associated simulation UUID |
| `value` | `integer` | No | Position value |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `mcp` | `boolean` | No | Whether created via MCP |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `ColumnInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Column name |
| `type` | `string` | Yes | Column data type |
| `nullable` | `boolean` | Yes | Whether the column is nullable |

---

## `CreateCohortItem`

Single cohort item for create — no cohort_id.

Required fields (name): provide ID or value.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Optional pre-assigned UUID |
| `resource_id` | `string` | No | Optional preset UUID for the resource snapshot |
| `name_id` | `string` | No | Name resource UUID |
| `name` | `string` | No | Name value for resolution |
| `description_id` | `string` | No | Description resource UUID |
| `description` | `string` | No | Description value for resolution |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `active` | `boolean` | No | Denormalized cohort_active flag state; resolved to a flag_ids entry server-side |
| `department_ids` | `string`[] | No | Department UUIDs |
| `simulation_ids` | `string`[] | No | Simulation UUIDs |
| `simulation_position_ids` | `string`[] | No | Simulation position UUIDs |
| `simulation_availability_ids` | `string`[] | No | Simulation availability UUIDs |
| `profile_ids` | `string`[] | No | Profile UUIDs |
| `profile_persona_ids` | `string`[] | No | Profile persona UUIDs |
| `departments` | `string`[] | No | Department names for resolution |
| `simulations` | `string`[] | No | Simulation names for resolution |
| `profiles` | `string`[] | No | Profile names for resolution |

---

## `DeleteCohortResult`

Per-item result within a bulk delete response.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `cohort_id` | `string` | Yes | Cohort UUID |
| `message` | `string` | Yes | Human-readable result message |

---

## `DocsApiResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `list` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `detail` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `new` | [`PageMetaItem`](#pagemetaitem) | Yes | — |

---

## `DocsResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Resource or entry name |
| `type` | `string` | Yes | Resource or entry type identifier |
| `description` | `string` | Yes | Human-readable description |
| `materialized_view` | [`MvInfo`](#mvinfo) | No | Materialized view metadata |
| `tables` | [`TableInfo`](#tableinfo)[] | Yes | Related database tables |
| `operations` | [`OperationInfo`](#operationinfo)[] | Yes | Available operations |

---

## `DraftProfilePersonaValue`

Value for creating a profile_persona resource via draft.

| Field | Type | Required | Description |
|---|---|---|---|
| `profile_id` | `string` | Yes | Associated profile UUID |
| `persona_id` | `string` | Yes | Associated persona UUID |

---

## `DraftSimulationAvailabilityValue`

Value for creating a simulation_availability resource via draft.

| Field | Type | Required | Description |
|---|---|---|---|
| `simulation_id` | `string` | Yes | Associated simulation UUID |
| `time` | `string` | Yes | Availability time slot |
| `type` | `string` | Yes | Availability type |

---

## `DraftSimulationPositionValue`

Value for creating a simulation_position resource via draft.

| Field | Type | Required | Description |
|---|---|---|---|
| `simulation_id` | `string` | Yes | Associated simulation UUID |
| `value` | `integer` | Yes | Position value |

---

## `EvalSetup`

Run-level eval scaffold — first-class on the generate response.

Audit's ``**output`` spread carries this onto
``<artifact>.generate.completed``. Null when no rubric-bearing
agent participated.

| Field | Type | Required | Description |
|---|---|---|---|
| `test_id` | `string` | Yes | — |
| `invocations` | [`InvocationSlot`](#invocationslot)[] | Yes | — |

---

## `GenerateConfig`

Developer configuration — all optional with sensible defaults.

| Field | Type | Required | Description |
|---|---|---|---|
| `operations` | `string`[] | No | — |
| `dangerous` | `boolean` | No | — |
| `params` | `object` | No | — |
| `group_id` | `string` | No | — |

---

## `GenerationsCohortListItem`

Single generation group in the cohort generations response.

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | UUID of the generation group |
| `session_id` | `string` | No | UUID of the parent session |
| `group_name` | `string` | No | Name of the generation group |
| `created_at` | `string` | No | Timestamp of the generation |

---

## `GetCohortDraftResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | UUID of the draft |
| `created_at` | `string` | Yes | Creation timestamp |
| `generated` | `boolean` | Yes | Whether this was AI-generated |
| `mcp` | `boolean` | Yes | Whether MCP tooling was used |
| `active` | `boolean` | Yes | Whether this draft is active |
| `session_id` | `string` | Yes | Associated session UUID |
| `name` | `string` | No | Immutable draft label set at create time |
| `department_ids` | `string`[] | Yes | Associated department UUIDs |
| `description_ids` | `string`[] | Yes | Associated description UUIDs |
| `flag_ids` | `string`[] | Yes | Associated flag UUIDs |
| `name_ids` | `string`[] | Yes | Associated name UUIDs |
| `profile_persona_ids` | `string`[] | Yes | Associated profile persona UUIDs |
| `profile_ids` | `string`[] | Yes | Associated profile UUIDs |
| `simulation_availability_ids` | `string`[] | Yes | Associated simulation availability UUIDs |
| `simulation_position_ids` | `string`[] | Yes | Associated simulation position UUIDs |
| `simulation_ids` | `string`[] | Yes | Associated simulation UUIDs |
| `pending_department_ids` | `string`[] | No | Pending department UUIDs |
| `pending_description_ids` | `string`[] | No | Pending description UUIDs |
| `pending_flag_ids` | `string`[] | No | Pending flag UUIDs |
| `pending_name_ids` | `string`[] | No | Pending name UUIDs |
| `pending_profile_persona_ids` | `string`[] | No | Pending profile persona UUIDs |
| `pending_profile_ids` | `string`[] | No | Pending profile UUIDs |
| `pending_simulation_availability_ids` | `string`[] | No | Pending simulation availability UUIDs |
| `pending_simulation_position_ids` | `string`[] | No | Pending simulation position UUIDs |
| `pending_simulation_ids` | `string`[] | No | Pending simulation UUIDs |

---

## `GroupCall`

Tool call referenced by a message.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `tool_name` | `string` | No | — |
| `template_name` | `string` | No | — |
| `tool` | `object` | No | — |
| `ledger_status` | `string` | No | — |
| `ledger_operation` | `string` | No | — |
| `ledger_artifact` | `string` | No | — |
| `ledger_artifact_id` | `string` | No | — |

---

## `GroupMessage`

Message within a run.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `role` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `text_ids` | `string`[] | No | — |
| `audio_ids` | `string`[] | No | — |
| `image_ids` | `string`[] | No | — |
| `video_ids` | `string`[] | No | — |
| `file_ids` | `string`[] | No | — |
| `call_ids` | `string`[] | No | — |
| `calls` | [`GroupCall`](#groupcall)[] | No | — |
| `reasoning` | `boolean` | No | True when this row is a chain-of-thought trace persisted alongside the assistant answer (rendered as a collapsed accordion). |
| `in_context` | `boolean` | No | Whether this message is included in the LLM context for the next generation. Mirrors the dedup pass that builds chat history (see in_context_reason). |
| `in_context_reason` | `string` | No | Why this message is in/out of LLM context. 'kept' = included; 'deduped_read' = older read-only call to a tool that has a fresher result later in the group; future values may include 'trimmed_top_n'. |

---

## `GroupResource`

Lightweight `\{id, name\}` for cross-referencing run-level ids
(``model_id`` / ``agent_id`` / ``profile_id``) against human-readable
names on the analytics panel. Names come from the canonical
``get_models`` / ``get_agents`` / ``get_profiles`` black boxes.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `name` | `string` | No | — |

---

## `GroupRun`

Run within a group, with its messages.

Carries token / cost / model / agent / profile attribution so the
analytics view can render per-run cost + actor info without a
parallel detail shape. ``profile_id`` is the authoring profile
(human user), ``agent_id`` is the LLM-side actor, ``model_id`` is
the model used by that agent. All optional — runs predating these
columns or with unresolved attributions surface ``None``.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `input_tokens` | `integer` | No | — |
| `output_tokens` | `integer` | No | — |
| `cached_input_tokens` | `integer` | No | — |
| `cost` | `number` | No | — |
| `model_id` | `string` | No | — |
| `agent_id` | `string` | No | — |
| `profile_id` | `string` | No | — |
| `previous_context_start_index` | `integer` | No | Index in ``messages`` where the current run's own messages begin; earlier rows are previous-context replay. ``None`` when the run has no previous context attached. |
| `messages` | [`GroupMessage`](#groupmessage)[] | No | — |

---

## `ImportField`

Field descriptor for CSV import column mapping.

| Field | Type | Required | Description |
|---|---|---|---|
| `key` | `string` | Yes | — |
| `label` | `string` | Yes | — |
| `required` | `boolean` | No | — |
| `multi` | `boolean` | No | — |
| `type` | `string` | No | — |
| `example` | `string` | No | — |
| `description` | `string` | No | — |

---

## `InvocationSlot`

One agent's slot in a multi-agent generation pool.

Populated by ``setup_generation_test`` when an agent carries a
rubric. The client uses these IDs to drive the eval workflow:
review the candidate's output, optionally fire a grader against
its ``invocation_id``, and promote/reject by call_id via the
existing ``idempotency_key + accept`` pattern.

| Field | Type | Required | Description |
|---|---|---|---|
| `invocation_id` | `string` | Yes | — |
| `agent_id` | `string` | Yes | — |
| `rubric_id` | `string` | No | — |

---

## `ListCohortApiCohort`

Cohort item in list response with Python-computed permissions.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Cohort artifact UUID (canonical id; mirrors cohort_id) |
| `cohort_id` | `string` | No | Cohort UUID |
| `name` | `string` | No | Cohort name |
| `description` | `string` | No | Cohort description |
| `is_inactive` | `boolean` | No | Whether the cohort is inactive |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `mcp` | `boolean` | No | Whether created via MCP |
| `department_ids` | `string`[] | No | Associated department IDs |
| `profile_ids` | `string`[] | No | Associated profile IDs |
| `simulation_ids` | `string`[] | No | Associated simulation IDs |
| `usage_count` | `integer` | No | Number of times this cohort is used |
| `num_members` | `integer` | No | Number of members in the cohort |
| `can_edit` | `boolean` | No | Whether the current user can edit |
| `can_delete` | `boolean` | No | Whether the current user can delete |
| `can_duplicate` | `boolean` | No | Whether the current user can duplicate |
| `can_leave` | `boolean` | No | Whether the current user can leave |
| `updated_at` | `string` | No | Last updated timestamp |
| `pending_status` | `string` | No | Soft-call ledger status (pending/accepted/rejected) for the latest pending op on this row |
| `pending_operation` | `string` | No | Operation name (create/update/delete/duplicate/draft) of the latest pending soft-call entry |
| `pending_call_id` | `string` | No | Originating tool call id for the latest pending soft-call entry |

---

## `ListCohortApiDepartment`

Department in list response.

| Field | Type | Required | Description |
|---|---|---|---|
| `department_id` | `string` | No | Department UUID |
| `name` | `string` | No | Department name |
| `description` | `string` | No | Department description |

---

## `ListCohortApiProfile`

Profile in list response.

| Field | Type | Required | Description |
|---|---|---|---|
| `profile_id` | `string` | No | Profile UUID |
| `name` | `string` | No | Profile name |
| `description` | `string` | No | Profile description |

---

## `ListCohortApiSimulation`

Simulation in list response.

| Field | Type | Required | Description |
|---|---|---|---|
| `simulation_id` | `string` | No | Simulation UUID |
| `name` | `string` | No | Simulation name |
| `description` | `string` | No | Simulation description |
| `department_ids` | `string`[] | No | Associated department IDs |

---

## `ListFilterOption`

Standardized option for list endpoint filter sections.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier for this filter option |
| `name` | `string` | No | Display name |
| `count` | `integer` | No | Number of matching records |
| `hex_code` | `string` | No | Hex color code for display |
| `value` | `string` | No | Internal value |
| `type` | `string` | No | Option type discriminator |

---

## `ListFilterSection`

Filter section with options and echoed request state.

| Field | Type | Required | Description |
|---|---|---|---|
| `options` | [`ListFilterOption`](#listfilteroption)[] | No | Available filter options |
| `selected_ids` | `string`[] | No | Currently selected filter option IDs |
| `search` | `string` | No | Active search text for filtering |

---

## `MvInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Materialized view name |
| `definition` | `string` | Yes | SQL definition of the view |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the view |

---

## `OperationInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Operation name |
| `description` | `string` | Yes | Human-readable description of the operation |
| `params` | [`ParamInfo`](#paraminfo)[] | Yes | List of operation parameters |
| `returns` | `object` | No | Return type schema |

---

## `OperationPrompts`

Starter prompts keyed by operation name.

Each key is an operation (e.g. "create", "search", "draft", "export")
and the value is a list of starter prompts for that operation.
The client picks from the operations the caller has permission for
and rotates through them.

| Field | Type | Required | Description |
|---|---|---|---|
| `prompts` | `object` | No | Map of operation name to starter prompts |

---

## `PageMetaItem`

| Field | Type | Required | Description |
|---|---|---|---|
| `title` | `string` | Yes | — |
| `description` | `string` | Yes | — |

---

## `ParamInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Parameter name |
| `type` | `string` | Yes | Parameter data type |
| `required` | `boolean` | Yes | Whether the parameter is required |
| `default` | `any` | No | Default value if not required |

---

## `ProducedMedia`

One asset produced by a generation run.

``resource_id`` is the canonical id the per-artifact download tools
accept (e.g. ``Scenario_Image_Download(image_id=resource_id)`` for
``modality="image"``). It maps to ``images_resource.id`` /
``videos_resource.id`` / ``audios_resource.id`` depending on the
modality.

| Field | Type | Required | Description |
|---|---|---|---|
| `modality` | `"image"` \| `"video"` \| `"audio"` | Yes | — |
| `resource_id` | `string` | Yes | — |
| `upload_id` | `string` | Yes | — |
| `mime_type` | `string` | No | — |
| `file_size` | `integer` | No | — |

---

## `ProfileSummary`

Caller identity derived from JWT — who you are on this page.

Superset of the old six-field version: now carries everything the client
needs so that ``/\{artifact\}/context`` fully replaces ``/profiles/context``
and the extra ``getLayoutContextData`` round-trip can be dropped.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Display name of the authenticated user |
| `role` | `string` | Yes | Role name (e.g. 'Super Administrator') |
| `role_level` | `integer` | Yes | Role hierarchy level (0 = highest privilege) |
| `department_ids` | `string`[] | Yes | Departments the user belongs to |
| `artifact_access` | `string`[] | Yes | Artifact types this role can access (sidebar visibility) |
| `role_permissions` | `any`[][] | Yes | Full (artifact, operation) permission tuples for granular page gating |
| `is_active` | `boolean` | Yes | Whether the user's profile is active |
| `id` | `string` | Yes | Profile UUID (SocketProvider, ProfileProvider) |
| `theme` | [`ThemeBundle`](#themebundle) | No | Resolved theme: hex primitives + derived oklch tokens + score thresholds |
| `session_id` | `string` | No | Current session UUID |
| `is_emulation` | `boolean` | No | Whether user is in emulation mode (ProfileProvider) |
| `role_resources` | [`QGetProfileContextV4RoleResource`](#qgetprofilecontextv4roleresource)[] | No | All role resources for emulation display (ProfileProvider) |
| `scoped_roles` | `string`[] | No | Roles the user can emulate (ProfileProvider) |
| `active` | `boolean` | No | Alias for is_active (ProfileProvider uses this name) |

---

## `QGetProfileContextV4RoleResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `role` | `string` | No | — |
| `name` | `string` | No | — |
| `description` | `string` | No | — |
| `icon_value` | `string` | No | — |
| `color_hex` | `string` | No | — |

---

## `RunStatus`

Outcome of one watched run.

| Field | Type | Required | Description |
|---|---|---|---|
| `run_id` | `string` | Yes | — |
| `status` | `"pending"` \| `"completed"` \| `"failed"` | Yes | — |
| `modality` | `string` | No | Modality of generated output (image, video, text…) |
| `resource_ids` | `string`[] | No | Resource UUIDs produced by this run (e.g. images_resource ids) |
| `error` | `string` | No | — |

---

## `TableInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Table name |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the table |

---

## `ThemeBundle`

Full theme payload for a page bootstrap.

Riding along on every ``/\{artifact\}/context`` response via
``ProfileSummary.theme``. Layers:
  - ``primitives`` / ``dark_primitives`` — hex inputs the settings
    editor reads/writes (light + dark palettes).
  - ``tokens`` / ``dark_tokens`` — oklch tokens the client paints with.
    ``ThemeStyle`` emits two ``<style>`` blocks: one scoped to
    ``:root:not(.dark)`` (light) and one to ``:root.dark`` (dark).
  - ``thresholds`` — numeric score thresholds for analytics components.
Empty-in → empty-out per token: missing values fall through to the
matching ``globals.css`` default.

| Field | Type | Required | Description |
|---|---|---|---|
| `primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (light palette, for the theme editor) |
| `tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for light mode (SSR CSS-var injection) |
| `dark_primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (dark palette, for the theme editor) |
| `dark_tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for dark mode (SSR CSS-var injection) |
| `thresholds` | [`Thresholds`](#thresholds) | No | Score thresholds resolved from the setting |

---

## `ThemePrimitives`

40 optional fields. The 17 essentials drive the rest; the other 23
are overrides for fine-tuning when derivation isn't what you want.

Empty primitive → empty token → client falls back to globals.css.

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `primary` | `string` | No | — |
| `accent` | `string` | No | — |
| `card` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `ring` | `string` | No | — |
| `border` | `string` | No | — |
| `destructive` | `string` | No | — |
| `success` | `string` | No | — |
| `warning` | `string` | No | — |
| `info` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `input` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `ThemeTokens`

40 fully-resolved CSS variable values (snake_case 1:1 with vars).

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `accent` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `border` | `string` | No | — |
| `input` | `string` | No | — |
| `ring` | `string` | No | — |
| `success` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `Thresholds`

Numeric score thresholds resolved from the active setting.

Server pre-buckets dashboard metrics into ``success | warning | danger |
neutral`` already, so most components don't need these values. Surface
them for chart reference lines, tooltips, and any client-side bucketing.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `integer` | Yes | Score >= this counts as success |
| `warning` | `integer` | Yes | Score >= this counts as warning |
| `danger` | `integer` | Yes | Score < success threshold but >= this counts as danger; below is neutral/no-data |

---

## `UpdateCohortItem`

Single cohort item for update — cohort_id required, all fields optional.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | Cohort UUID to update |
| `name_id` | `string` | No | Name resource UUID |
| `name` | `string` | No | Name value for resolution |
| `description_id` | `string` | No | Description resource UUID |
| `description` | `string` | No | Description value for resolution |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `active` | `boolean` | No | Denormalized cohort_active flag state; resolved to a flag_ids entry server-side |
| `department_ids` | `string`[] | No | Department UUIDs |
| `simulation_ids` | `string`[] | No | Simulation UUIDs |
| `simulation_position_ids` | `string`[] | No | Simulation position UUIDs |
| `simulation_availability_ids` | `string`[] | No | Simulation availability UUIDs |
| `profile_ids` | `string`[] | No | Profile UUIDs |
| `profile_persona_ids` | `string`[] | No | Profile persona UUIDs |
| `departments` | `string`[] | No | Department names for resolution |
| `simulations` | `string`[] | No | Simulation names for resolution |
| `profiles` | `string`[] | No | Profile names for resolution |

---

## `UpdateCohortPatch`

Shared patch for bulk-update-all-matching mode.

Inherits every field from ``UpdateCohortItem`` and just relaxes
``id`` to optional — the bulk impl stamps the resolved id onto a
clone of the patch per matched row, so any client-supplied id is
ignored. Sparse semantics: only fields the client sets are written.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Ignored — bulk impl stamps the resolved cohort id per matched row |
| `name_id` | `string` | No | Name resource UUID |
| `name` | `string` | No | Name value for resolution |
| `description_id` | `string` | No | Description resource UUID |
| `description` | `string` | No | Description value for resolution |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `active` | `boolean` | No | Denormalized cohort_active flag state; resolved to a flag_ids entry server-side |
| `department_ids` | `string`[] | No | Department UUIDs |
| `simulation_ids` | `string`[] | No | Simulation UUIDs |
| `simulation_position_ids` | `string`[] | No | Simulation position UUIDs |
| `simulation_availability_ids` | `string`[] | No | Simulation availability UUIDs |
| `profile_ids` | `string`[] | No | Profile UUIDs |
| `profile_persona_ids` | `string`[] | No | Profile persona UUIDs |
| `departments` | `string`[] | No | Department names for resolution |
| `simulations` | `string`[] | No | Simulation names for resolution |
| `profiles` | `string`[] | No | Profile names for resolution |

---

## `app__infra__cohort__types__DraftFormState`

Full form state after draft patch — server is source of truth.

Client replaces its local form state with this after every successful patch.

| Field | Type | Required | Description |
|---|---|---|---|
| `name_id` | `string` | No | Selected name resource UUID |
| `name` | `string` | No | Name value that was saved |
| `description_id` | `string` | No | Selected description resource UUID |
| `description` | `string` | No | Description value that was saved |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs |
| `active` | `boolean` | No | Echoed cohort_active flag state |
| `department_ids` | `string`[] | No | Selected department UUIDs |
| `departments` | `string`[] | No | Department values that were saved |
| `simulation_ids` | `string`[] | No | Selected simulation UUIDs |
| `simulations` | `string`[] | No | Simulation values that were saved |
| `simulation_position_ids` | `string`[] | No | Selected simulation position UUIDs |
| `simulation_positions` | [`DraftSimulationPositionValue`](#draftsimulationpositionvalue)[] | No | Simulation position values that were saved |
| `simulation_availability_ids` | `string`[] | No | Selected simulation availability UUIDs |
| `simulation_availability` | [`DraftSimulationAvailabilityValue`](#draftsimulationavailabilityvalue)[] | No | Simulation availability values that were saved |
| `profile_ids` | `string`[] | No | Selected profile UUIDs |
| `profiles` | `string`[] | No | Profile values that were saved |
| `profile_persona_ids` | `string`[] | No | Selected profile persona UUIDs |
| `profile_personas` | [`DraftProfilePersonaValue`](#draftprofilepersonavalue)[] | No | Profile persona values that were saved |
| `pending_ids` | `string`[] | No | Pending resource IDs retained on the draft |

---

## `app__infra__cohort__types__SectionFilter`

Per-section filter options for GET requests.

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Filter options by search text |
| `limit` | `integer` | No | Max options to return |
| `selected` | `boolean` | No | Only return selected items |
| `suggested` | `boolean` | No | Only return suggested items |
| `include` | `boolean` | No | Include this section in response (default true) |
| `parameter_ids` | `string`[] | No | Reserved for parity with persona pattern |

---

---

# `GET` `/department/watch`

Route: /api-reference/department/get-department-watch

# `GET` `/department/watch`

Department Watch

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `group_id` | query | No | — |
| `run_id` | query | No | Optional run filter. If provided, only events whose envelope run_id matches are streamed. Omit to receive every department event in the group (the FE default). |

## Response

```
{}
```

---

# `POST` `/department/call_download`

Route: /api-reference/department/post-department-call-download

# `POST` `/department/call_download`

Download Call

Download a call file by call resource ID.

## Request Body (`CallDownloadDepartmentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `call_id` | `string` | Yes | UUID of the calls_resource to download |

## Response

```
{}
```

---

# `POST` `/department/context`

Route: /api-reference/department/post-department-context

# `POST` `/department/context`

Get Department Context

Get page context for the department artifact.

Returns docs + profile identity + evaluated permissions in a single call.
Superset of /docs — clients can migrate from /docs to /context incrementally.

## Request Body (`DocsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entity_id` | `string` | No | — |
| `snapshot_key` | `string` | No | — |
| `schema` | `boolean` | No | If true, include MCP/tooling schema metadata (artifact, entries, resources, permission_docs, api_operations). Defaults to false for lean page-bootstrap responses. |

## Response (`ComposedContextResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Artifact name |
| `type` | `string` | Yes | Artifact type identifier |
| `description` | `string` | Yes | Human-readable description |
| `artifact` | [`DocsResponse`](/api-reference/department/types#docsresponse) | No | Artifact tool documentation (None unless schema=true) |
| `entries` | [`DocsResponse`](/api-reference/department/types#docsresponse)[] | No | Entry documentation list (None unless schema=true) |
| `resources` | [`DocsResponse`](/api-reference/department/types#docsresponse)[] | No | Resource documentation list (None unless schema=true) |
| `permission_docs` | [`OperationInfo`](/api-reference/department/types#operationinfo)[] | No | Permission function signatures for MCP/dev tooling (None unless schema=true) |
| `api_operations` | [`OperationInfo`](/api-reference/department/types#operationinfo)[] | No | API operation documentation (None unless schema=true) |
| `page_metadata` | [`DocsApiResponse`](/api-reference/department/types#docsapiresponse) | No | Page-level metadata |
| `prompts` | [`OperationPrompts`](/api-reference/department/types#operationprompts) | No | Starter prompts keyed by operation |
| `profile` | [`ProfileSummary`](/api-reference/department/types#profilesummary) | Yes | Caller identity from JWT |
| `caller_permissions` | [`CallerPermissions`](/api-reference/department/types#callerpermissions) | Yes | Evaluated permissions for this caller |

---

# `POST` `/department/create`

Route: /api-reference/department/post-department-create

# `POST` `/department/create`

Create Department

Create departments using composable infra architecture.

## Request Body (`CreateDepartmentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `departments` | [`CreateDepartmentItem`](/api-reference/department/types#createdepartmentitem)[] | Yes | List of departments to create |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant create |
| `soft` | `boolean` | No | Stage the create dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`CreateDepartmentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`DepartmentResultItem`](/api-reference/department/types#departmentresultitem)[] | Yes | Per-item creation results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |
| `departments` | [`ListDepartmentApiDepartment`](/api-reference/department/types#listdepartmentapidepartment)[] | No | Hydrated rows for the successfully-created departments (mirrors /department/search shape) |

---

# `POST` `/department/csv`

Route: /api-reference/department/post-department-csv

# `POST` `/department/csv`

Parse Department Csv

Parse a CSV file and return mapped items for preview.

## Request Body

| Field | Type | Required | Description |
|---|---|---|---|
| `file` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `soft` | `boolean` | No | — |
| `accept` | `boolean` | No | — |

## Response (`ParseDepartmentCsvApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `upload_id` | `string` | Yes | — |
| `items` | [`CreateDepartmentItem`](/api-reference/department/types#createdepartmentitem)[] | Yes | — |
| `mapped_fields` | `string`[] | Yes | — |
| `row_count` | `integer` | Yes | — |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with `accept` to promote/reject the staged raw-CSV upload. NOTE: ack returns no items (the preview is only on the propose). |

---

# `POST` `/department/delete`

Route: /api-reference/department/post-department-delete

# `POST` `/department/delete`

Delete Department

Bulk delete departments — composable infra architecture.

## Request Body (`DeleteDepartmentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `department_ids` | `string`[] | No | UUIDs of departments to delete (required on first call when ``all`` is false) |
| `all` | `boolean` | No | When true, delete every department matching the filter fields below (minus ``excluded_ids``) |
| `excluded_ids` | `string`[] | No | UUIDs to skip even when matched by ``all``-mode filters |
| `search` | `string` | No | Full-text search query |
| `flag_search` | `string` | No | Search text for flag facet (no-op for row filtering) |
| `idempotency_key` | `string` | No | Operation key for ack — confirms or rejects a dormant delete |
| `soft` | `boolean` | No | Stage the delete dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (confirm) or reject dormant state. Only meaningful with idempotency_key |

## Response (`DeleteDepartmentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`DeleteDepartmentResult`](/api-reference/department/types#deletedepartmentresult)[] | Yes | Per-item deletion results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/department/draft`

Route: /api-reference/department/post-department-draft

# `POST` `/department/draft`

Patch Department Draft

Patch department draft — composable infra architecture.

## Request Body (`PatchDepartmentDraftApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `draft_id` | `string` | No | Existing draft UUID to update |
| `input_draft_id` | `string` | No | Existing draft UUID to update |
| `name` | `string` | No | Name value to resolve or create |
| `name_id` | `string` | No | UUID of the name resource |
| `description` | `string` | No | Description value to resolve or create |
| `description_id` | `string` | No | UUID of the description resource |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `active` | `boolean` | No | Denormalized department_active flag state; resolved to a flag_ids entry server-side |
| `settings` | `string`[] | No | Setting names to resolve |
| `setting_ids` | `string`[] | No | Setting UUIDs to assign |
| `pending_ids` | `string`[] | No | Resource IDs to keep pending where supported |
| `idempotency_key` | `string` | No | Operation key for ack or retry |
| `soft` | `boolean` | No | Stage the draft dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept or reject dormant state |

## Response (`PatchDepartmentDraftApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the draft save succeeded |
| `draft_id` | `string` | Yes | UUID of the saved draft |
| `idempotency_key` | `string` | No | Idempotency key for this draft operation |
| `message` | `string` | Yes | Result message |
| `form_state` | [`app__infra__department__types__DraftFormState`](/api-reference/department/types#app-infra-department-types-draftformstate) | No | Server-authoritative form state |

---

# `POST` `/department/drafts`

Route: /api-reference/department/post-department-drafts

# `POST` `/department/drafts`

Get Department Drafts

List department drafts owned by the current profile.

## Request Body (`GetDepartmentDraftsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE substring) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GetDepartmentDraftsApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entries` | [`GetDepartmentDraftResponse`](/api-reference/department/types#getdepartmentdraftresponse)[] | No | List of department draft entries |

---

# `POST` `/department/duplicate`

Route: /api-reference/department/post-department-duplicate

# `POST` `/department/duplicate`

Duplicate Department

Duplicate a department — composable infra architecture.

## Request Body (`DuplicateDepartmentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `department_id` | `string` | Yes | UUID of the department to duplicate |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant duplicate |
| `soft` | `boolean` | No | Stage the duplicate dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`DuplicateDepartmentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the duplication succeeded |
| `department_id` | `string` | Yes | UUID of the newly created department |
| `message` | `string` | Yes | Result message |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |
| `departments` | [`ListDepartmentApiDepartment`](/api-reference/department/types#listdepartmentapidepartment)[] | No | Hydrated row for the newly-created duplicate department (mirrors /department/search shape) |

---

# `POST` `/department/export`

Route: /api-reference/department/post-department-export

# `POST` `/department/export`

Export Departments

Export all departments as a clean, denormalized CSV.

## Request Body (`ExportDepartmentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `department_id` | `string` | No | UUID of the department to export |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior export instead of re-running |
| `soft` | `boolean` | No | Stage the export dormant (active=False); ack with accept activates it |
| `accept` | `boolean` | No | Ack: True promotes the staged export, False rejects. Only meaningful with idempotency_key |

## Response (`ExportDepartmentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource holding the export CSV |
| `file_name` | `string` | Yes | Suggested download file name |
| `row_count` | `integer` | Yes | Number of data rows in the export |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with `accept` to promote/reject the staged export. |

---

# `POST` `/department/file_download`

Route: /api-reference/department/post-department-file-download

# `POST` `/department/file_download`

Download File

Download a file by file resource ID.

## Request Body (`FileDownloadDepartmentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource to download |

## Response

```
{}
```

---

# `POST` `/department/generate`

Route: /api-reference/department/post-department-generate

# `POST` `/department/generate`

Generate Department

Trigger department generation. Returns immediately; progress via events.

## Request Body (`ArtifactGenerateRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `instructions` | `string`[] | No | — |
| `config` | [`GenerateConfig`](/api-reference/department/types#generateconfig) | No | — |
| `modalities` | `string`[] | No | — |
| `audios_id` | `string` | No | — |
| `conversation_id` | `string` | No | — |
| `trace_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `accept` | `boolean` | No | — |
| `wait_for_complete` | `boolean` | No | — |

## Response (`ArtifactGenerateResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `run_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `eval` | [`EvalSetup`](/api-reference/department/types#evalsetup) | No | — |
| `produced_media` | [`ProducedMedia`](/api-reference/department/types#producedmedia)[] | No | — |

---

# `POST` `/department/generations`

Route: /api-reference/department/post-department-generations

# `POST` `/department/generations`

Generations Department

List department generation groups — composable infra architecture.

## Request Body (`GenerationsDepartmentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GenerationsDepartmentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `items` | [`GenerationsDepartmentListItem`](/api-reference/department/types#generationsdepartmentlistitem)[] | No | Generation groups |
| `total_count` | `integer` | No | Total number of matching generations |

---

# `POST` `/department/get`

Route: /api-reference/department/post-department-get

# `POST` `/department/get`

Get Department

Get department information using the canonical shared department operation.

## Request Body (`GetDepartmentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Department UUID to retrieve |
| `department_id` | `string` | No | Legacy department UUID to retrieve |
| `draft_id` | `string` | No | UUID of the draft to load |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |
| `names` | [`app__infra__department__types__SectionFilter`](/api-reference/department/types#app-infra-department-types-sectionfilter) | No | Filter options for names section |
| `descriptions` | [`app__infra__department__types__SectionFilter`](/api-reference/department/types#app-infra-department-types-sectionfilter) | No | Filter options for descriptions section |
| `flags` | [`app__infra__department__types__SectionFilter`](/api-reference/department/types#app-infra-department-types-sectionfilter) | No | Filter options for flags section |
| `settings` | [`app__infra__department__types__SectionFilter`](/api-reference/department/types#app-infra-department-types-sectionfilter) | No | Filter options for settings section |

## Response (`GetDepartmentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the acting user |
| `department_exists` | `boolean` | No | Whether the department exists |
| `can_edit` | `boolean` | No | Whether the actor can edit this department |
| `disabled_reason` | `string` | No | Reason editing is disabled, if any |
| `group_id` | `string` | No | Group UUID for draft collaboration |
| `draft_name` | `string` | No | Immutable draft label from the active draft entry, when a ``draft_id`` was supplied. ``None`` for non-draft fetches. |
| `show_ai_generate` | `boolean` | No | Whether to show AI generate anywhere |
| `basic_show_ai_generate` | `boolean` | No | Whether to show AI generate for basic sections |
| `pending_ids` | `string`[] | No | Pending resource identifiers when available |
| `names` | [`DepartmentNameResource`](/api-reference/department/types#departmentnameresource)[] | No | Name resources |
| `descriptions` | [`DepartmentDescriptionResource`](/api-reference/department/types#departmentdescriptionresource)[] | No | Description resources |
| `flags` | [`DepartmentFlagResource`](/api-reference/department/types#departmentflagresource)[] | No | Flag resources (one per flags_resource row, value=true/false) |
| `settings` | [`DepartmentSettingResource`](/api-reference/department/types#departmentsettingresource)[] | No | Setting resources |

---

# `POST` `/department/group`

Route: /api-reference/department/post-department-group

# `POST` `/department/group`

Group Department

Resolve or create a department group with optional naming.

## Request Body (`GroupDepartmentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | No | Existing group UUID (omit to create or reuse via time window) |
| `snapshot_key` | `string` | No | Snapshot key for SETNX-race convergence on a single group across concurrent reads (e.g. parallel /context + /group + /search fan-out on page load). Echoed back in the response. |

## Response (`GroupDepartmentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Resolved or newly created group UUID |
| `name` | `string` | No | The group's current title (latest active group_names_entry, or 'New Chat' fallback for freshly minted groups) |
| `snapshot_key` | `string` | No | Snapshot key echoed back — the UUID concurrent fan-out reads converged on via SETNX. Mirrors the resolved group_id. |
| `runs` | [`GroupRun`](/api-reference/department/types#grouprun)[] | No | Conversation history — populated when resolving an existing group for fetch |
| `group_exists` | `boolean` | No | (detail) Whether the group exists in storage — populated when ``include_resources=True`` |
| `actor_name` | `string` | No | (detail) Display name of the current actor (caller profile) |
| `total_message_count` | `integer` | No | (detail) Total number of messages in the group |
| `models` | [`GroupResource`](/api-reference/department/types#groupresource)[] | No | (detail) Models used in the group |
| `agents` | [`GroupResource`](/api-reference/department/types#groupresource)[] | No | (detail) Agents used in the group |
| `profiles` | [`GroupResource`](/api-reference/department/types#groupresource)[] | No | (detail) Profiles that authored runs in this group |

---

# `POST` `/department/problem`

Route: /api-reference/department/post-department-problem

# `POST` `/department/problem`

Problem Department

Report a department problem — composable infra architecture.

## Request Body (`ProblemDepartmentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | `string` | Yes | Problem type: feature, bug, question, other |
| `message` | `string` | Yes | Problem description (max 1000 chars) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant problem |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`ProblemDepartmentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `problem_id` | `string` | Yes | UUID of the created problem |
| `success` | `boolean` | No | Whether the problem was created |
| `message` | `string` | No | Status message |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/department/refresh`

Route: /api-reference/department/post-department-refresh

# `POST` `/department/refresh`

Department Refresh

Refresh department materialized views and invalidate caches.

## Request Body (`RefreshDepartmentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `targets` | `string`[] | No | MV targets to refresh (omit for all). Options: department_drafts_mv |
| `idempotency_key` | `string` | No | Operation key for ack |
| `accept` | `boolean` | No | Accept or reject. Only meaningful with idempotency_key |
| `soft` | `boolean` | No | Stage the refresh as a pending (held) request — recorded but not enqueued; ack with accept releases/enqueues it |

## Response (`RefreshResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | — |
| `refreshed_views` | `string`[] | Yes | — |
| `invalidated_tags` | `string`[] | Yes | — |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/department/search`

Route: /api-reference/department/post-department-search

# `POST` `/department/search`

Search Department

Search departments — composable infra architecture.

## Request Body (`SearchDepartmentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | — |
| `page_size` | `integer` | No | — |
| `page_offset` | `integer` | No | — |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`ListDepartmentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the acting user |
| `departments` | [`ListDepartmentApiDepartment`](/api-reference/department/types#listdepartmentapidepartment)[] | No | List of department items |
| `flag_filter` | [`ListFilterSection`](/api-reference/department/types#listfiltersection) | No | Filter options for flags in list UI |
| `profile_filter` | [`ListFilterSection`](/api-reference/department/types#listfiltersection) | No | Filter options for profiles in list UI |
| `settings_filter` | [`ListFilterSection`](/api-reference/department/types#listfiltersection) | No | Filter options for settings in list UI |
| `logins_filter` | [`ListFilterSection`](/api-reference/department/types#listfiltersection) | No | Filter options for logins in list UI |
| `total_count` | `integer` | No | Total number of departments |
| `import_fields` | [`ImportField`](/api-reference/department/types#importfield)[] | No | CSV import column schema for the bulk-import dialog |

---

# `POST` `/department/text_download`

Route: /api-reference/department/post-department-text-download

# `POST` `/department/text_download`

Download Text

Download a text file by text resource ID.

## Request Body (`TextDownloadDepartmentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `text_id` | `string` | Yes | UUID of the texts_resource to download |

## Response

```
{}
```

---

# `POST` `/department/title`

Route: /api-reference/department/post-department-title

# `POST` `/department/title`

Title Department

Rename a department's group (writes group_names_entry).

## Request Body (`TitleDepartmentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Group to rename |
| `title` | `string` | Yes | New title (display name) for the group |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant rename |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`TitleDepartmentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | The group that was renamed |
| `group_name_id` | `string` | Yes | UUID of the new group_names_entry row |
| `title` | `string` | Yes | The title that was set |
| `idempotency_key` | `string` | No | Operation key echoed back |

---

# `POST` `/department/update`

Route: /api-reference/department/post-department-update

# `POST` `/department/update`

Update Department

Update departments using composable infra architecture.

## Request Body (`UpdateDepartmentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `departments` | [`UpdateDepartmentItem`](/api-reference/department/types#updatedepartmentitem)[] | No | List of departments to update (required on first call when ``all`` is false) |
| `all` | `boolean` | No | When true, apply ``patch`` to every department matching the filter fields below (minus ``excluded_ids``) |
| `excluded_ids` | `string`[] | No | UUIDs to skip even when matched by ``all``-mode filters |
| `patch` | [`UpdateDepartmentPatch`](/api-reference/department/types#updatedepartmentpatch) | No | Shared change set applied to every matched row when ``all=true`` (sparse — only set fields are updated; ``patch.id`` ignored) |
| `search` | `string` | No | Full-text search query |
| `flag_search` | `string` | No | Search text for flag facet (no-op for row filtering) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant update |
| `soft` | `boolean` | No | Stage the update dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`UpdateDepartmentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`DepartmentResultItem`](/api-reference/department/types#departmentresultitem)[] | Yes | Per-item update results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |
| `departments` | [`ListDepartmentApiDepartment`](/api-reference/department/types#listdepartmentapidepartment)[] | No | Hydrated rows for the successfully-updated departments (mirrors /department/search shape) |

---

# `POST` `/department/watch`

Route: /api-reference/department/post-department-watch

# `POST` `/department/watch`

Department Watch Once

One-shot snapshot of run state, snapshot-replayable via ``snapshot_key``.

## Request Body (`WatchApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Chat group whose events we watch |
| `run_id` | `string` | No | Specific run to watch (e.g. the ``run_id`` returned by a prior ``X_Generate`` call). If None, watches every active run in the group at call time. |
| `wait_for_complete` | `boolean` | No | If True, block until the watched run reaches a terminal (complete/failed) event or timeout fires. If False, return current state and exit immediately. |
| `timeout_seconds` | `integer` | No | Max wait time when ``wait_for_complete=True``. |
| `snapshot_key` | `string` | No | Read snapshot key — on the one-shot POST /watch, the audit wrapper records this watch's point-in-time view (latest run state at call time) keyed by it and replays the same view on any later call with the same key. Ignored by the SSE GET stream. |

## Response (`WatchApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `runs` | [`RunStatus`](/api-reference/department/types#runstatus)[] | Yes | — |
| `timed_out` | `boolean` | No | — |
| `waited_seconds` | `number` | No | — |

---

# Department Types

Route: /api-reference/department/types

# Department Types

## `CallerPermissions`

Evaluated permissions for the current caller on this artifact type.

| Field | Type | Required | Description |
|---|---|---|---|
| `can_create` | `boolean` | Yes | Whether the caller can create new artifacts |
| `can_draft` | `boolean` | Yes | Whether the caller can create/update drafts |
| `can_duplicate` | `boolean` | Yes | Whether the caller can duplicate artifacts |
| `has_access` | `boolean` | No | Whether the caller can view this entity |
| `can_edit` | `boolean` | No | Whether the caller can edit this entity |
| `can_delete` | `boolean` | No | Whether the caller can delete this entity |
| `disabled_reason` | `string` | No | Human-readable reason if editing is disabled |

---

## `ColumnInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Column name |
| `type` | `string` | Yes | Column data type |
| `nullable` | `boolean` | Yes | Whether the column is nullable |

---

## `CreateDepartmentItem`

Single department item for create — no department_id.

Required fields (name): provide ID or value.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Optional preset UUID for the new department artifact |
| `resource_id` | `string` | No | Optional preset UUID for the departments_resource snapshot |
| `name_id` | `string` | No | REQUIRED FOR CREATE (or pass ``name``). UUID of an existing name resource. |
| `name` | `string` | No | REQUIRED FOR CREATE (or pass ``name_id``). Display name text — creates a new name resource on the fly. |
| `description_id` | `string` | No | UUID of the description resource |
| `description` | `string` | No | Description value to resolve or create |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `active` | `boolean` | No | Denormalized department_active flag state; resolved to a flag_ids entry server-side |
| `settings_ids` | `string`[] | No | Setting UUIDs to assign |
| `department_ids` | `string`[] | No | Sub-department UUIDs to assign |

---

## `DeleteDepartmentResult`

Per-item result within a bulk delete response.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the deletion succeeded |
| `department_id` | `string` | No | UUID of the deleted department |
| `message` | `string` | Yes | Result message |

---

## `DepartmentDescriptionResource`

Description resource for department.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `description` | `string` | No | Description text |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `DepartmentFieldError`

Per-field error from value resolution.

| Field | Type | Required | Description |
|---|---|---|---|
| `field` | `string` | Yes | Name of the field that failed validation |
| `message` | `string` | Yes | Validation error message |

---

## `DepartmentFlagResource`

Flag option row — one per (name, type, value) entry in flags_resource.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Flag resource identifier |
| `name` | `string` | No | Flag display name |
| `type` | `string` | No | Flag type (e.g. 'department_active') |
| `value` | `boolean` | No | Underlying bool value of this option |
| `description` | `string` | No | Flag description text |
| `icon_id` | `string` | No | Icon identifier for the flag |
| `icon` | `string` | No | Resolved SVG markup for the icon (hydrated from icons_resource) |
| `generated` | `boolean` | No | Whether the flag was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `DepartmentNameResource`

Name resource for department.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `name` | `string` | No | Display name |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `DepartmentResultItem`

Per-item result within a bulk create/update response.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `department_id` | `string` | No | UUID of the created or updated department |
| `message` | `string` | Yes | Result message |
| `errors` | [`DepartmentFieldError`](#departmentfielderror)[] | No | Per-field validation errors |

---

## `DepartmentSettingResource`

Setting resource for department.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `name` | `string` | No | Setting display name |
| `description` | `string` | No | Setting description |
| `department_ids` | `string`[] | No | Associated department identifiers |
| `provider_key_ids` | `string`[] | No | Associated provider key identifiers |
| `auth_ids` | `string`[] | No | Associated auth identifiers |
| `system_ids` | `string`[] | No | Associated system identifiers |
| `active` | `boolean` | No | Whether this setting is active |
| `mcp` | `boolean` | No | Whether this setting used MCP |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `DocsApiResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `list` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `detail` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `new` | [`PageMetaItem`](#pagemetaitem) | Yes | — |

---

## `DocsResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Resource or entry name |
| `type` | `string` | Yes | Resource or entry type identifier |
| `description` | `string` | Yes | Human-readable description |
| `materialized_view` | [`MvInfo`](#mvinfo) | No | Materialized view metadata |
| `tables` | [`TableInfo`](#tableinfo)[] | Yes | Related database tables |
| `operations` | [`OperationInfo`](#operationinfo)[] | Yes | Available operations |

---

## `EvalSetup`

Run-level eval scaffold — first-class on the generate response.

Audit's ``**output`` spread carries this onto
``<artifact>.generate.completed``. Null when no rubric-bearing
agent participated.

| Field | Type | Required | Description |
|---|---|---|---|
| `test_id` | `string` | Yes | — |
| `invocations` | [`InvocationSlot`](#invocationslot)[] | Yes | — |

---

## `GenerateConfig`

Developer configuration — all optional with sensible defaults.

| Field | Type | Required | Description |
|---|---|---|---|
| `operations` | `string`[] | No | — |
| `dangerous` | `boolean` | No | — |
| `params` | `object` | No | — |
| `group_id` | `string` | No | — |

---

## `GenerationsDepartmentListItem`

Single generation group in the department generations response.

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | UUID of the generation group |
| `session_id` | `string` | No | UUID of the parent session |
| `group_name` | `string` | No | Name of the generation group |
| `created_at` | `string` | No | Timestamp of the generation |

---

## `GetDepartmentDraftResponse`

Resolved department draft entry with selected and pending links.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | UUID of the draft |
| `created_at` | `string` | Yes | Creation timestamp |
| `generated` | `boolean` | Yes | Whether this was AI-generated |
| `mcp` | `boolean` | Yes | Whether MCP tooling was used |
| `active` | `boolean` | Yes | Whether this draft is active |
| `session_id` | `string` | Yes | Associated session UUID |
| `name` | `string` | No | Immutable draft label set at create time |
| `description_ids` | `string`[] | Yes | Associated description UUIDs |
| `flag_ids` | `string`[] | Yes | Associated flag UUIDs |
| `name_ids` | `string`[] | Yes | Associated name UUIDs |
| `profile_ids` | `string`[] | Yes | Associated profile UUIDs |
| `setting_ids` | `string`[] | Yes | Associated setting UUIDs |
| `pending_description_ids` | `string`[] | No | Inactive pending description UUIDs |
| `pending_flag_ids` | `string`[] | No | Inactive pending flag UUIDs |
| `pending_name_ids` | `string`[] | No | Inactive pending name UUIDs |
| `pending_setting_ids` | `string`[] | No | Inactive pending setting UUIDs |

---

## `GroupCall`

Tool call referenced by a message.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `tool_name` | `string` | No | — |
| `template_name` | `string` | No | — |
| `tool` | `object` | No | — |
| `ledger_status` | `string` | No | — |
| `ledger_operation` | `string` | No | — |
| `ledger_artifact` | `string` | No | — |
| `ledger_artifact_id` | `string` | No | — |

---

## `GroupMessage`

Message within a run.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `role` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `text_ids` | `string`[] | No | — |
| `audio_ids` | `string`[] | No | — |
| `image_ids` | `string`[] | No | — |
| `video_ids` | `string`[] | No | — |
| `file_ids` | `string`[] | No | — |
| `call_ids` | `string`[] | No | — |
| `calls` | [`GroupCall`](#groupcall)[] | No | — |
| `reasoning` | `boolean` | No | True when this row is a chain-of-thought trace persisted alongside the assistant answer (rendered as a collapsed accordion). |
| `in_context` | `boolean` | No | Whether this message is included in the LLM context for the next generation. Mirrors the dedup pass that builds chat history (see in_context_reason). |
| `in_context_reason` | `string` | No | Why this message is in/out of LLM context. 'kept' = included; 'deduped_read' = older read-only call to a tool that has a fresher result later in the group; future values may include 'trimmed_top_n'. |

---

## `GroupResource`

Lightweight `\{id, name\}` for cross-referencing run-level ids
(``model_id`` / ``agent_id`` / ``profile_id``) against human-readable
names on the analytics panel. Names come from the canonical
``get_models`` / ``get_agents`` / ``get_profiles`` black boxes.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `name` | `string` | No | — |

---

## `GroupRun`

Run within a group, with its messages.

Carries token / cost / model / agent / profile attribution so the
analytics view can render per-run cost + actor info without a
parallel detail shape. ``profile_id`` is the authoring profile
(human user), ``agent_id`` is the LLM-side actor, ``model_id`` is
the model used by that agent. All optional — runs predating these
columns or with unresolved attributions surface ``None``.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `input_tokens` | `integer` | No | — |
| `output_tokens` | `integer` | No | — |
| `cached_input_tokens` | `integer` | No | — |
| `cost` | `number` | No | — |
| `model_id` | `string` | No | — |
| `agent_id` | `string` | No | — |
| `profile_id` | `string` | No | — |
| `previous_context_start_index` | `integer` | No | Index in ``messages`` where the current run's own messages begin; earlier rows are previous-context replay. ``None`` when the run has no previous context attached. |
| `messages` | [`GroupMessage`](#groupmessage)[] | No | — |

---

## `ImportField`

Field descriptor for CSV import column mapping.

| Field | Type | Required | Description |
|---|---|---|---|
| `key` | `string` | Yes | — |
| `label` | `string` | Yes | — |
| `required` | `boolean` | No | — |
| `multi` | `boolean` | No | — |
| `type` | `string` | No | — |
| `example` | `string` | No | — |
| `description` | `string` | No | — |

---

## `InvocationSlot`

One agent's slot in a multi-agent generation pool.

Populated by ``setup_generation_test`` when an agent carries a
rubric. The client uses these IDs to drive the eval workflow:
review the candidate's output, optionally fire a grader against
its ``invocation_id``, and promote/reject by call_id via the
existing ``idempotency_key + accept`` pattern.

| Field | Type | Required | Description |
|---|---|---|---|
| `invocation_id` | `string` | Yes | — |
| `agent_id` | `string` | Yes | — |
| `rubric_id` | `string` | No | — |

---

## `ListDepartmentApiDepartment`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Department artifact UUID (canonical id; mirrors department_id) |
| `department_id` | `string` | No | Unique department identifier |
| `name` | `string` | No | Department display name |
| `description` | `string` | No | Department description text |
| `staff_count` | `integer` | No | Number of staff in the department |
| `profile_ids` | `string`[] | No | Profile artifact UUIDs assigned to this department |
| `setting_ids` | `string`[] | No | Setting artifact UUIDs scoped to this department |
| `login_ids` | `string`[] | No | Login resource UUIDs reachable via this department's settings |
| `is_inactive` | `boolean` | No | Whether the department is inactive |
| `can_edit` | `boolean` | No | Whether the actor can edit this department |
| `can_duplicate` | `boolean` | No | Whether the actor can duplicate this department |
| `can_delete` | `boolean` | No | Whether the actor can delete this department |
| `updated_at` | `string` | No | Timestamp of last update |
| `pending_status` | `string` | No | Soft-call ledger status (pending/accepted/rejected) for the latest pending op on this row |
| `pending_operation` | `string` | No | Operation name (create/update/delete/duplicate/draft) of the latest pending soft-call entry |
| `pending_call_id` | `string` | No | Originating tool call id for the latest pending soft-call entry |

---

## `ListFilterOption`

Standardized option for list endpoint filter sections.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier for this filter option |
| `name` | `string` | No | Display name |
| `count` | `integer` | No | Number of matching records |
| `hex_code` | `string` | No | Hex color code for display |
| `value` | `string` | No | Internal value |
| `type` | `string` | No | Option type discriminator |

---

## `ListFilterSection`

Filter section with options and echoed request state.

| Field | Type | Required | Description |
|---|---|---|---|
| `options` | [`ListFilterOption`](#listfilteroption)[] | No | Available filter options |
| `selected_ids` | `string`[] | No | Currently selected filter option IDs |
| `search` | `string` | No | Active search text for filtering |

---

## `MvInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Materialized view name |
| `definition` | `string` | Yes | SQL definition of the view |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the view |

---

## `OperationInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Operation name |
| `description` | `string` | Yes | Human-readable description of the operation |
| `params` | [`ParamInfo`](#paraminfo)[] | Yes | List of operation parameters |
| `returns` | `object` | No | Return type schema |

---

## `OperationPrompts`

Starter prompts keyed by operation name.

Each key is an operation (e.g. "create", "search", "draft", "export")
and the value is a list of starter prompts for that operation.
The client picks from the operations the caller has permission for
and rotates through them.

| Field | Type | Required | Description |
|---|---|---|---|
| `prompts` | `object` | No | Map of operation name to starter prompts |

---

## `PageMetaItem`

| Field | Type | Required | Description |
|---|---|---|---|
| `title` | `string` | Yes | — |
| `description` | `string` | Yes | — |

---

## `ParamInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Parameter name |
| `type` | `string` | Yes | Parameter data type |
| `required` | `boolean` | Yes | Whether the parameter is required |
| `default` | `any` | No | Default value if not required |

---

## `ProducedMedia`

One asset produced by a generation run.

``resource_id`` is the canonical id the per-artifact download tools
accept (e.g. ``Scenario_Image_Download(image_id=resource_id)`` for
``modality="image"``). It maps to ``images_resource.id`` /
``videos_resource.id`` / ``audios_resource.id`` depending on the
modality.

| Field | Type | Required | Description |
|---|---|---|---|
| `modality` | `"image"` \| `"video"` \| `"audio"` | Yes | — |
| `resource_id` | `string` | Yes | — |
| `upload_id` | `string` | Yes | — |
| `mime_type` | `string` | No | — |
| `file_size` | `integer` | No | — |

---

## `ProfileSummary`

Caller identity derived from JWT — who you are on this page.

Superset of the old six-field version: now carries everything the client
needs so that ``/\{artifact\}/context`` fully replaces ``/profiles/context``
and the extra ``getLayoutContextData`` round-trip can be dropped.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Display name of the authenticated user |
| `role` | `string` | Yes | Role name (e.g. 'Super Administrator') |
| `role_level` | `integer` | Yes | Role hierarchy level (0 = highest privilege) |
| `department_ids` | `string`[] | Yes | Departments the user belongs to |
| `artifact_access` | `string`[] | Yes | Artifact types this role can access (sidebar visibility) |
| `role_permissions` | `any`[][] | Yes | Full (artifact, operation) permission tuples for granular page gating |
| `is_active` | `boolean` | Yes | Whether the user's profile is active |
| `id` | `string` | Yes | Profile UUID (SocketProvider, ProfileProvider) |
| `theme` | [`ThemeBundle`](#themebundle) | No | Resolved theme: hex primitives + derived oklch tokens + score thresholds |
| `session_id` | `string` | No | Current session UUID |
| `is_emulation` | `boolean` | No | Whether user is in emulation mode (ProfileProvider) |
| `role_resources` | [`QGetProfileContextV4RoleResource`](#qgetprofilecontextv4roleresource)[] | No | All role resources for emulation display (ProfileProvider) |
| `scoped_roles` | `string`[] | No | Roles the user can emulate (ProfileProvider) |
| `active` | `boolean` | No | Alias for is_active (ProfileProvider uses this name) |

---

## `QGetProfileContextV4RoleResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `role` | `string` | No | — |
| `name` | `string` | No | — |
| `description` | `string` | No | — |
| `icon_value` | `string` | No | — |
| `color_hex` | `string` | No | — |

---

## `RunStatus`

Outcome of one watched run.

| Field | Type | Required | Description |
|---|---|---|---|
| `run_id` | `string` | Yes | — |
| `status` | `"pending"` \| `"completed"` \| `"failed"` | Yes | — |
| `modality` | `string` | No | Modality of generated output (image, video, text…) |
| `resource_ids` | `string`[] | No | Resource UUIDs produced by this run (e.g. images_resource ids) |
| `error` | `string` | No | — |

---

## `TableInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Table name |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the table |

---

## `ThemeBundle`

Full theme payload for a page bootstrap.

Riding along on every ``/\{artifact\}/context`` response via
``ProfileSummary.theme``. Layers:
  - ``primitives`` / ``dark_primitives`` — hex inputs the settings
    editor reads/writes (light + dark palettes).
  - ``tokens`` / ``dark_tokens`` — oklch tokens the client paints with.
    ``ThemeStyle`` emits two ``<style>`` blocks: one scoped to
    ``:root:not(.dark)`` (light) and one to ``:root.dark`` (dark).
  - ``thresholds`` — numeric score thresholds for analytics components.
Empty-in → empty-out per token: missing values fall through to the
matching ``globals.css`` default.

| Field | Type | Required | Description |
|---|---|---|---|
| `primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (light palette, for the theme editor) |
| `tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for light mode (SSR CSS-var injection) |
| `dark_primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (dark palette, for the theme editor) |
| `dark_tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for dark mode (SSR CSS-var injection) |
| `thresholds` | [`Thresholds`](#thresholds) | No | Score thresholds resolved from the setting |

---

## `ThemePrimitives`

40 optional fields. The 17 essentials drive the rest; the other 23
are overrides for fine-tuning when derivation isn't what you want.

Empty primitive → empty token → client falls back to globals.css.

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `primary` | `string` | No | — |
| `accent` | `string` | No | — |
| `card` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `ring` | `string` | No | — |
| `border` | `string` | No | — |
| `destructive` | `string` | No | — |
| `success` | `string` | No | — |
| `warning` | `string` | No | — |
| `info` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `input` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `ThemeTokens`

40 fully-resolved CSS variable values (snake_case 1:1 with vars).

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `accent` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `border` | `string` | No | — |
| `input` | `string` | No | — |
| `ring` | `string` | No | — |
| `success` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `Thresholds`

Numeric score thresholds resolved from the active setting.

Server pre-buckets dashboard metrics into ``success | warning | danger |
neutral`` already, so most components don't need these values. Surface
them for chart reference lines, tooltips, and any client-side bucketing.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `integer` | Yes | Score >= this counts as success |
| `warning` | `integer` | Yes | Score >= this counts as warning |
| `danger` | `integer` | Yes | Score < success threshold but >= this counts as danger; below is neutral/no-data |

---

## `UpdateDepartmentItem`

Single department item for update — department_id required, all fields optional.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | UUID of the department to update |
| `name_id` | `string` | No | UUID of the name resource |
| `name` | `string` | No | Name value to resolve or create |
| `description_id` | `string` | No | UUID of the description resource |
| `description` | `string` | No | Description value to resolve or create |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `active` | `boolean` | No | Denormalized department_active flag state; resolved to a flag_ids entry server-side |
| `settings_ids` | `string`[] | No | Setting UUIDs to assign |
| `department_ids` | `string`[] | No | Sub-department UUIDs to assign |

---

## `UpdateDepartmentPatch`

Shared patch for bulk-update-all-matching mode.

Mirrors every field of ``UpdateDepartmentItem`` but with ``id``
relaxed to optional — the bulk impl stamps the resolved id onto a
clone of the patch per matched row, so any client-supplied id is
ignored. Sparse semantics: only fields the client sets are written.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Ignored — bulk impl stamps the resolved department id per matched row |
| `name_id` | `string` | No | UUID of the name resource |
| `name` | `string` | No | Name value to resolve or create |
| `description_id` | `string` | No | UUID of the description resource |
| `description` | `string` | No | Description value to resolve or create |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `active` | `boolean` | No | Denormalized department_active flag state; resolved to a flag_ids entry server-side |
| `settings_ids` | `string`[] | No | Setting UUIDs to assign |
| `department_ids` | `string`[] | No | Sub-department UUIDs to assign |

---

## `app__infra__department__types__DraftFormState`

Server-authoritative form state returned after draft save.

| Field | Type | Required | Description |
|---|---|---|---|
| `name_id` | `string` | No | Resolved name resource UUID |
| `name` | `string` | No | Echoed name value |
| `description_id` | `string` | No | Resolved description resource UUID |
| `description` | `string` | No | Echoed description value |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs |
| `active` | `boolean` | No | Echoed department_active flag state |
| `setting_ids` | `string`[] | No | Assigned setting UUIDs |
| `pending_ids` | `string`[] | No | Pending resource identifiers |

---

## `app__infra__department__types__SectionFilter`

Per-section filter options for GET requests.

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Filter options by search text |
| `limit` | `integer` | No | Max options to return |
| `selected` | `boolean` | No | Only return selected items |
| `suggested` | `boolean` | No | Only return suggested items |
| `include` | `boolean` | No | Include this section in response (default true) |
| `parameter_ids` | `string`[] | No | Reserved for compatibility with shared filter parsing |

---

---

# `GET` `/document/watch`

Route: /api-reference/document/get-document-watch

# `GET` `/document/watch`

Document Watch

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `group_id` | query | No | — |
| `run_id` | query | No | Optional run filter. If provided, only events whose envelope run_id matches are streamed. Omit to receive every document event in the group (the FE default). |

## Response

```
{}
```

---

# `POST` `/document/call_download`

Route: /api-reference/document/post-document-call-download

# `POST` `/document/call_download`

Download Call

Download a call file by call resource ID.

## Request Body (`CallDownloadDocumentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `call_id` | `string` | Yes | UUID of the calls_resource to download |

## Response

```
{}
```

---

# `POST` `/document/context`

Route: /api-reference/document/post-document-context

# `POST` `/document/context`

Get Document Context

Get page context for the document artifact.

Returns docs + profile identity + evaluated permissions in a single call.
Superset of /docs — clients can migrate from /docs to /context incrementally.

## Request Body (`DocsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entity_id` | `string` | No | — |
| `snapshot_key` | `string` | No | — |
| `schema` | `boolean` | No | If true, include MCP/tooling schema metadata (artifact, entries, resources, permission_docs, api_operations). Defaults to false for lean page-bootstrap responses. |

## Response (`ComposedContextResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Artifact name |
| `type` | `string` | Yes | Artifact type identifier |
| `description` | `string` | Yes | Human-readable description |
| `artifact` | [`DocsResponse`](/api-reference/document/types#docsresponse) | No | Artifact tool documentation (None unless schema=true) |
| `entries` | [`DocsResponse`](/api-reference/document/types#docsresponse)[] | No | Entry documentation list (None unless schema=true) |
| `resources` | [`DocsResponse`](/api-reference/document/types#docsresponse)[] | No | Resource documentation list (None unless schema=true) |
| `permission_docs` | [`OperationInfo`](/api-reference/document/types#operationinfo)[] | No | Permission function signatures for MCP/dev tooling (None unless schema=true) |
| `api_operations` | [`OperationInfo`](/api-reference/document/types#operationinfo)[] | No | API operation documentation (None unless schema=true) |
| `page_metadata` | [`DocsApiResponse`](/api-reference/document/types#docsapiresponse) | No | Page-level metadata |
| `prompts` | [`OperationPrompts`](/api-reference/document/types#operationprompts) | No | Starter prompts keyed by operation |
| `profile` | [`ProfileSummary`](/api-reference/document/types#profilesummary) | Yes | Caller identity from JWT |
| `caller_permissions` | [`CallerPermissions`](/api-reference/document/types#callerpermissions) | Yes | Evaluated permissions for this caller |

---

# `POST` `/document/create`

Route: /api-reference/document/post-document-create

# `POST` `/document/create`

Create Document

Create documents using composable infra architecture.

## Request Body (`CreateDocumentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `documents` | [`CreateDocumentItem`](/api-reference/document/types#createdocumentitem)[] | Yes | List of documents to create |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant create |
| `soft` | `boolean` | No | Stage the create dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`CreateDocumentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`DocumentResultItem`](/api-reference/document/types#documentresultitem)[] | Yes | List of operation results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/document/csv`

Route: /api-reference/document/post-document-csv

# `POST` `/document/csv`

Parse Document Csv

Parse a CSV file and return mapped items for preview.

## Request Body

| Field | Type | Required | Description |
|---|---|---|---|
| `file` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `soft` | `boolean` | No | — |
| `accept` | `boolean` | No | — |

## Response (`ParseDocumentCsvApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `upload_id` | `string` | Yes | — |
| `items` | [`CreateDocumentItem`](/api-reference/document/types#createdocumentitem)[] | Yes | — |
| `mapped_fields` | `string`[] | Yes | — |
| `row_count` | `integer` | Yes | — |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with `accept` to promote/reject the staged raw-CSV upload. NOTE: ack returns no items (the preview is only on the propose). |

---

# `POST` `/document/delete`

Route: /api-reference/document/post-document-delete

# `POST` `/document/delete`

Delete Document

Bulk delete documents — composable infra architecture.

## Request Body (`DeleteDocumentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `document_ids` | `string`[] | No | Document UUIDs to delete (required on first call when ``all`` is false) |
| `all` | `boolean` | No | When true, delete every document matching the filter fields below (minus ``excluded_ids``) |
| `excluded_ids` | `string`[] | No | UUIDs to skip even when matched by ``all``-mode filters |
| `search` | `string` | No | Full-text search query |
| `scenario_ids` | `string`[] | No | Filter by scenario UUIDs |
| `field_ids` | `string`[] | No | Filter by field UUIDs |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `scenario_search` | `string` | No | Search text for scenario facet (no-op for row filtering) |
| `field_search` | `string` | No | Search text for field facet (no-op for row filtering) |
| `department_search` | `string` | No | Search text for department facet (no-op for row filtering) |
| `flag_search` | `string` | No | Search text for flag facet (no-op for row filtering) |
| `idempotency_key` | `string` | No | Operation key for ack — confirms or rejects a dormant delete |
| `soft` | `boolean` | No | Stage the delete dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (confirm deletion) or reject (restore). Only meaningful with idempotency_key |

## Response (`DeleteDocumentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`DeleteDocumentResult`](/api-reference/document/types#deletedocumentresult)[] | Yes | List of operation results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/document/draft`

Route: /api-reference/document/post-document-draft

# `POST` `/document/draft`

Patch Document Draft

Patch document draft — composable infra architecture.

## Request Body (`PatchDocumentDraftApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `draft_id` | `string` | No | Existing draft UUID to patch |
| `input_draft_id` | `string` | No | Legacy alias for existing draft UUID to patch |
| `name` | `string` | No | Name value to create a resource |
| `name_id` | `string` | No | Existing name resource UUID |
| `description` | `string` | No | Description value to create a resource |
| `description_id` | `string` | No | Existing description resource UUID |
| `files` | [`DraftFileValue`](/api-reference/document/types#draftfilevalue)[] | No | File values to create resources |
| `file_ids` | `string`[] | No | Existing file resource UUIDs |
| `texts` | [`DraftTextValue`](/api-reference/document/types#drafttextvalue)[] | No | Text values to create resources |
| `text_ids` | `string`[] | No | Existing text resource UUIDs |
| `images` | [`app__infra__document__types__DraftImageValue`](/api-reference/document/types#app-infra-document-types-draftimagevalue)[] | No | Image values to create resources |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `active` | `boolean` | No | Denormalized document_active flag state; resolved to a flag_ids entry server-side |
| `department_ids` | `string`[] | No | Department UUIDs |
| `image_ids` | `string`[] | No | Image UUIDs |
| `parameter_field_ids` | `string`[] | No | Parameter field UUIDs |
| `parameter_ids` | `string`[] | No | Parameter UUIDs |
| `pending_ids` | `string`[] | No | Resource IDs to keep as pending where supported by the tool layer |
| `idempotency_key` | `string` | No | Operation key for ack or retry |
| `soft` | `boolean` | No | Stage the draft dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`PatchDocumentDraftApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `draft_id` | `string` | Yes | Draft UUID |
| `idempotency_key` | `string` | Yes | Idempotency key for this draft operation |
| `message` | `string` | Yes | Human-readable result message |
| `form_state` | [`app__infra__document__types__DraftFormState`](/api-reference/document/types#app-infra-document-types-draftformstate) | No | Server-authoritative form state |

---

# `POST` `/document/drafts`

Route: /api-reference/document/post-document-drafts

# `POST` `/document/drafts`

Get Document Drafts

List document drafts owned by the current profile.

## Request Body (`GetDocumentDraftsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE substring) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GetDocumentDraftsApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entries` | [`GetDocumentDraftResponse`](/api-reference/document/types#getdocumentdraftresponse)[] | No | List of document draft entries |

---

# `POST` `/document/duplicate`

Route: /api-reference/document/post-document-duplicate

# `POST` `/document/duplicate`

Duplicate Document

Duplicate a document — composable infra architecture.

## Request Body (`DuplicateDocumentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `document_id` | `string` | Yes | Document UUID to duplicate |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant duplicate |
| `soft` | `boolean` | No | Stage the duplicate dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`DuplicateDocumentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `document_id` | `string` | Yes | Newly created document UUID |
| `message` | `string` | Yes | Human-readable result message |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/document/export`

Route: /api-reference/document/post-document-export

# `POST` `/document/export`

Export Documents

Export all documents as a clean, denormalized CSV.

## Request Body (`ExportDocumentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `document_id` | `string` | No | Document UUID to export |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior export instead of re-running |

## Response (`ExportDocumentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `content` | `string` | Yes | Exported file content |
| `file_name` | `string` | Yes | Suggested file name for download |
| `mime_type` | `string` | Yes | MIME type of the exported content |
| `row_count` | `integer` | Yes | Number of rows in the export |

---

# `POST` `/document/file_download`

Route: /api-reference/document/post-document-file-download

# `POST` `/document/file_download`

Download File

Download a file by file resource ID.

## Request Body (`FileDownloadDocumentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource to download |

## Response

```
{}
```

---

# `POST` `/document/file_preview`

Route: /api-reference/document/post-document-file-preview

# `POST` `/document/file_preview`

Preview File

Return a PNG preview of the first page of a PDF upload.

## Request Body (`FilePreviewDocumentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource to preview |

## Response

```
{}
```

---

# `POST` `/document/file_upload`

Route: /api-reference/document/post-document-file-upload

# `POST` `/document/file_upload`

Upload File

Upload a file for later use in documents (soft/accept dormant flow).

## Request Body

| Field | Type | Required | Description |
|---|---|---|---|
| `file` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `soft` | `boolean` | No | — |
| `accept` | `boolean` | No | — |

## Response (`FileUploadDocumentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the created files_resource |
| `idempotency_key` | `string` | No | Server-minted soft-call key (the audit call_id). On a soft propose, echo this back with `accept` to promote/reject the staged upload. |

---

# `POST` `/document/generate`

Route: /api-reference/document/post-document-generate

# `POST` `/document/generate`

Generate Document

Trigger document generation. Returns immediately; progress via events.

## Request Body (`ArtifactGenerateRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `instructions` | `string`[] | No | — |
| `config` | [`GenerateConfig`](/api-reference/document/types#generateconfig) | No | — |
| `modalities` | `string`[] | No | — |
| `audios_id` | `string` | No | — |
| `conversation_id` | `string` | No | — |
| `trace_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `accept` | `boolean` | No | — |
| `wait_for_complete` | `boolean` | No | — |

## Response (`ArtifactGenerateResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `run_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `eval` | [`EvalSetup`](/api-reference/document/types#evalsetup) | No | — |
| `produced_media` | [`ProducedMedia`](/api-reference/document/types#producedmedia)[] | No | — |

---

# `POST` `/document/generations`

Route: /api-reference/document/post-document-generations

# `POST` `/document/generations`

Generations Document

List document generation groups — composable infra architecture.

## Request Body (`GenerationsDocumentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GenerationsDocumentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `items` | [`GenerationsDocumentListItem`](/api-reference/document/types#generationsdocumentlistitem)[] | No | Generation groups |
| `total_count` | `integer` | No | Total number of matching generations |

---

# `POST` `/document/get`

Route: /api-reference/document/post-document-get

# `POST` `/document/get`

Get Document

Get document information using the canonical shared document operation.

## Request Body (`GetDocumentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Document UUID to retrieve |
| `document_id` | `string` | No | Legacy alias for the document UUID |
| `draft_id` | `string` | No | Draft UUID to load from |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |
| `names` | [`app__infra__document__types__SectionFilter`](/api-reference/document/types#app-infra-document-types-sectionfilter) | No | Filter options for names section |
| `descriptions` | [`app__infra__document__types__SectionFilter`](/api-reference/document/types#app-infra-document-types-sectionfilter) | No | Filter options for descriptions section |
| `flags` | [`app__infra__document__types__SectionFilter`](/api-reference/document/types#app-infra-document-types-sectionfilter) | No | Filter options for flags section |
| `departments` | [`app__infra__document__types__SectionFilter`](/api-reference/document/types#app-infra-document-types-sectionfilter) | No | Filter options for departments section |
| `parameter_fields` | [`app__infra__document__types__SectionFilter`](/api-reference/document/types#app-infra-document-types-sectionfilter) | No | Filter options for parameter fields section |
| `parameters` | [`app__infra__document__types__SectionFilter`](/api-reference/document/types#app-infra-document-types-sectionfilter) | No | Filter options for parameters section |
| `files` | [`app__infra__document__types__SectionFilter`](/api-reference/document/types#app-infra-document-types-sectionfilter) | No | Filter options for files section |
| `images` | [`app__infra__document__types__SectionFilter`](/api-reference/document/types#app-infra-document-types-sectionfilter) | No | Filter options for images section |
| `texts` | [`app__infra__document__types__SectionFilter`](/api-reference/document/types#app-infra-document-types-sectionfilter) | No | Filter options for texts section |
| `fields` | [`app__infra__document__types__SectionFilter`](/api-reference/document/types#app-infra-document-types-sectionfilter) | No | Legacy alias for parameter_fields |
| `uploads` | [`app__infra__document__types__SectionFilter`](/api-reference/document/types#app-infra-document-types-sectionfilter) | No | Legacy alias for files |

## Response (`GetDocumentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current user |
| `document_exists` | `boolean` | No | Whether the document exists |
| `can_edit` | `boolean` | No | Whether the current user can edit |
| `disabled_reason` | `string` | No | Reason editing is disabled |
| `group_id` | `string` | No | Associated group UUID |
| `draft_name` | `string` | No | Immutable draft label from the active draft entry, when a ``draft_id`` was supplied. ``None`` for non-draft fetches. |
| `show_ai_generate` | `boolean` | No | Whether AI generation is available |
| `basic_show_ai_generate` | `boolean` | No | Whether to show AI generate for basic step |
| `content_show_ai_generate` | `boolean` | No | Whether to show AI generate for content step |
| `pending_ids` | `string`[] | No | Pending resource IDs from the draft, when available |
| `names` | [`DocumentNameResource`](/api-reference/document/types#documentnameresource)[] | No | Name resources |
| `descriptions` | [`DocumentDescriptionResource`](/api-reference/document/types#documentdescriptionresource)[] | No | Description resources |
| `flags` | [`DocumentFlagResource`](/api-reference/document/types#documentflagresource)[] | No | Flag resources (one per flags_resource row, value=true/false) |
| `departments` | [`DocumentDepartmentResource`](/api-reference/document/types#documentdepartmentresource)[] | No | Department resources |
| `parameter_fields` | [`DocumentParameterFieldResource`](/api-reference/document/types#documentparameterfieldresource)[] | No | Parameter field resources |
| `parameters` | [`DocumentParameterResource`](/api-reference/document/types#documentparameterresource)[] | No | Parameter catalog resources |
| `files` | [`DocumentFileResource`](/api-reference/document/types#documentfileresource)[] | No | File resources |
| `images` | [`DocumentImageResource`](/api-reference/document/types#documentimageresource)[] | No | Image resources |
| `texts` | [`DocumentTextResource`](/api-reference/document/types#documenttextresource)[] | No | Text resources |

---

# `POST` `/document/group`

Route: /api-reference/document/post-document-group

# `POST` `/document/group`

Group Document

Resolve or create a document group with optional naming.

## Request Body (`GroupDocumentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | No | Existing group UUID (omit to create or reuse via time window) |
| `snapshot_key` | `string` | No | Snapshot key for SETNX-race convergence on a single group across concurrent reads (e.g. parallel /context + /group + /search fan-out on page load). Echoed back in the response. |

## Response (`GroupDocumentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Resolved or newly created group UUID |
| `name` | `string` | No | The group's current title (latest active group_names_entry, or 'New Chat' fallback for freshly minted groups) |
| `snapshot_key` | `string` | No | Snapshot key echoed back — the UUID concurrent fan-out reads converged on via SETNX. Mirrors the resolved group_id. |
| `runs` | [`GroupRun`](/api-reference/document/types#grouprun)[] | No | Conversation history — populated when resolving an existing group for fetch |
| `group_exists` | `boolean` | No | (detail) Whether the group exists in storage — populated when ``include_resources=True`` |
| `actor_name` | `string` | No | (detail) Display name of the current actor (caller profile) |
| `total_message_count` | `integer` | No | (detail) Total number of messages in the group |
| `models` | [`GroupResource`](/api-reference/document/types#groupresource)[] | No | (detail) Models used in the group |
| `agents` | [`GroupResource`](/api-reference/document/types#groupresource)[] | No | (detail) Agents used in the group |
| `profiles` | [`GroupResource`](/api-reference/document/types#groupresource)[] | No | (detail) Profiles that authored runs in this group |

---

# `POST` `/document/image_download`

Route: /api-reference/document/post-document-image-download

# `POST` `/document/image_download`

Download Image

Download an image file by image resource ID.

## Request Body (`ImageDownloadDocumentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `image_id` | `string` | Yes | UUID of the images_resource to download |

## Response

```
{}
```

---

# `POST` `/document/image_upload`

Route: /api-reference/document/post-document-image-upload

# `POST` `/document/image_upload`

Upload Image

Upload an image for later use in documents (soft/accept dormant flow).

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `name` | query | No | — |
| `description` | query | No | — |

## Request Body

| Field | Type | Required | Description |
|---|---|---|---|
| `file` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `soft` | `boolean` | No | — |
| `accept` | `boolean` | No | — |

## Response (`ImageUploadDocumentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `image_id` | `string` | Yes | UUID of the created images_resource |
| `upload_id` | `string` | Yes | UUID of the underlying uploads_entry |
| `idempotency_key` | `string` | No | Server-minted soft-call key (the audit call_id). On a soft propose, echo this back with `accept` to promote/reject the staged upload. |

---

# `POST` `/document/problem`

Route: /api-reference/document/post-document-problem

# `POST` `/document/problem`

Problem Document

Report a document problem — composable infra architecture.

## Request Body (`ProblemDocumentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | `string` | Yes | Problem type: feature, bug, question, other |
| `message` | `string` | Yes | Problem description (max 1000 chars) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant problem |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`ProblemDocumentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `problem_id` | `string` | Yes | UUID of the created problem |
| `success` | `boolean` | No | Whether the problem was created |
| `message` | `string` | No | Status message |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/document/refresh`

Route: /api-reference/document/post-document-refresh

# `POST` `/document/refresh`

Document Refresh

Refresh document materialized views and invalidate caches.

## Request Body (`RefreshDocumentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `targets` | `string`[] | No | MV targets to refresh (omit for all). Options: document_drafts_mv, runs_mv, messages_mv, calls_mv, groups_mv, group_names_mv |
| `idempotency_key` | `string` | No | Operation key for ack |
| `accept` | `boolean` | No | Accept or reject. Only meaningful with idempotency_key |
| `soft` | `boolean` | No | Stage the refresh as a pending (held) request — recorded but not enqueued; ack with accept releases/enqueues it |

## Response (`RefreshResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | — |
| `refreshed_views` | `string`[] | Yes | — |
| `invalidated_tags` | `string`[] | Yes | — |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/document/search`

Route: /api-reference/document/post-document-search

# `POST` `/document/search`

Search Document

Search documents — composable infra architecture.

## Request Body (`SearchDocumentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | — |
| `scenario_ids` | `string`[] | No | — |
| `field_ids` | `string`[] | No | — |
| `filter_department_ids` | `string`[] | No | — |
| `scenario_search` | `string` | No | — |
| `field_search` | `string` | No | — |
| `department_search` | `string` | No | — |
| `page_size` | `integer` | No | — |
| `page_offset` | `integer` | No | — |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`ListDocumentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current user |
| `documents` | [`ListDocumentApiDocument`](/api-reference/document/types#listdocumentapidocument)[] | No | List of documents |
| `scenario_filter` | [`ListFilterSection`](/api-reference/document/types#listfiltersection) | No | Filter options for scenarios in list UI |
| `field_filter` | [`ListFilterSection`](/api-reference/document/types#listfiltersection) | No | Filter options for fields in list UI |
| `department_filter` | [`ListFilterSection`](/api-reference/document/types#listfiltersection) | No | Filter options for departments in list UI |
| `flag_filter` | [`ListFilterSection`](/api-reference/document/types#listfiltersection) | No | Filter options for flags in list UI |
| `total_count` | `integer` | No | Total number of matching records |
| `import_fields` | [`ImportField`](/api-reference/document/types#importfield)[] | No | CSV import column schema for the bulk-import dialog |

---

# `POST` `/document/text_download`

Route: /api-reference/document/post-document-text-download

# `POST` `/document/text_download`

Download Text

Download a text file by text resource ID.

## Request Body (`TextDownloadDocumentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `text_id` | `string` | Yes | UUID of the texts_resource to download |

## Response

```
{}
```

---

# `POST` `/document/text_upload`

Route: /api-reference/document/post-document-text-upload

# `POST` `/document/text_upload`

Upload Text

Upload a text file for later use in documents (soft/accept dormant flow).

## Request Body

| Field | Type | Required | Description |
|---|---|---|---|
| `file` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `soft` | `boolean` | No | — |
| `accept` | `boolean` | No | — |

## Response (`TextUploadDocumentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `text_id` | `string` | Yes | UUID of the created texts_resource |
| `upload_id` | `string` | Yes | UUID of the uploads_entry (file on disk) |
| `idempotency_key` | `string` | No | Server-minted soft-call key (the audit call_id). On a soft propose, echo this back with `accept` to promote/reject the staged upload. |

---

# `POST` `/document/title`

Route: /api-reference/document/post-document-title

# `POST` `/document/title`

Title Document

Rename a document's group (writes group_names_entry).

## Request Body (`TitleDocumentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Group to rename |
| `title` | `string` | Yes | New title (display name) for the group |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant rename |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`TitleDocumentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | The group that was renamed |
| `group_name_id` | `string` | Yes | UUID of the new group_names_entry row |
| `title` | `string` | Yes | The title that was set |
| `idempotency_key` | `string` | No | Operation key echoed back |

---

# `POST` `/document/update`

Route: /api-reference/document/post-document-update

# `POST` `/document/update`

Update Document

Update documents using composable infra architecture.

## Request Body (`UpdateDocumentApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `documents` | [`UpdateDocumentItem`](/api-reference/document/types#updatedocumentitem)[] | No | List of documents to update (required on first call when ``all`` is false) |
| `all` | `boolean` | No | When true, apply ``patch`` to every document matching the filter fields below (minus ``excluded_ids``) |
| `excluded_ids` | `string`[] | No | UUIDs to skip even when matched by ``all``-mode filters |
| `patch` | [`UpdateDocumentPatch`](/api-reference/document/types#updatedocumentpatch) | No | Shared change set applied to every matched row when ``all=true`` (sparse — only set fields are updated; ``patch.id`` ignored) |
| `search` | `string` | No | Full-text search query |
| `scenario_ids` | `string`[] | No | Filter by scenario UUIDs |
| `field_ids` | `string`[] | No | Filter by field UUIDs |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `scenario_search` | `string` | No | Search text for scenario facet (no-op for row filtering) |
| `field_search` | `string` | No | Search text for field facet (no-op for row filtering) |
| `department_search` | `string` | No | Search text for department facet (no-op for row filtering) |
| `flag_search` | `string` | No | Search text for flag facet (no-op for row filtering) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant update |
| `soft` | `boolean` | No | Stage the update dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`UpdateDocumentApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`DocumentResultItem`](/api-reference/document/types#documentresultitem)[] | Yes | List of operation results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/document/watch`

Route: /api-reference/document/post-document-watch

# `POST` `/document/watch`

Document Watch Once

One-shot snapshot of run state, snapshot-replayable via ``snapshot_key``.

## Request Body (`WatchApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Chat group whose events we watch |
| `run_id` | `string` | No | Specific run to watch (e.g. the ``run_id`` returned by a prior ``X_Generate`` call). If None, watches every active run in the group at call time. |
| `wait_for_complete` | `boolean` | No | If True, block until the watched run reaches a terminal (complete/failed) event or timeout fires. If False, return current state and exit immediately. |
| `timeout_seconds` | `integer` | No | Max wait time when ``wait_for_complete=True``. |
| `snapshot_key` | `string` | No | Read snapshot key — on the one-shot POST /watch, the audit wrapper records this watch's point-in-time view (latest run state at call time) keyed by it and replays the same view on any later call with the same key. Ignored by the SSE GET stream. |

## Response (`WatchApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `runs` | [`RunStatus`](/api-reference/document/types#runstatus)[] | Yes | — |
| `timed_out` | `boolean` | No | — |
| `waited_seconds` | `number` | No | — |

---

# Document Types

Route: /api-reference/document/types

# Document Types

## `CallerPermissions`

Evaluated permissions for the current caller on this artifact type.

| Field | Type | Required | Description |
|---|---|---|---|
| `can_create` | `boolean` | Yes | Whether the caller can create new artifacts |
| `can_draft` | `boolean` | Yes | Whether the caller can create/update drafts |
| `can_duplicate` | `boolean` | Yes | Whether the caller can duplicate artifacts |
| `has_access` | `boolean` | No | Whether the caller can view this entity |
| `can_edit` | `boolean` | No | Whether the caller can edit this entity |
| `can_delete` | `boolean` | No | Whether the caller can delete this entity |
| `disabled_reason` | `string` | No | Human-readable reason if editing is disabled |

---

## `ColumnInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Column name |
| `type` | `string` | Yes | Column data type |
| `nullable` | `boolean` | Yes | Whether the column is nullable |

---

## `CreateDocumentItem`

Single document item for create — no document_id.

Required fields (name): provide ID or value.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Optional pre-assigned UUID |
| `resource_id` | `string` | No | Optional preset UUID for the resource snapshot |
| `name_id` | `string` | No | Name resource UUID |
| `name` | `string` | No | Name value for resolution |
| `description_id` | `string` | No | Description resource UUID |
| `description` | `string` | No | Description value for resolution |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `active` | `boolean` | No | Denormalized document_active flag state; resolved to a flag_ids entry server-side |
| `department_ids` | `string`[] | No | Department UUIDs |
| `departments` | `string`[] | No | Department names for resolution |
| `parameter_field_ids` | `string`[] | No | Parameter field UUIDs |
| `upload_ids` | `string`[] | No | File upload UUIDs |
| `image_ids` | `string`[] | No | Image UUIDs |
| `text_ids` | `string`[] | No | Text resource UUIDs |
| `file_id` | `string` | No | Files resource UUID for document file |
| `text_id` | `string` | No | Texts resource UUID for document text |

---

## `DeleteDocumentResult`

Per-item result within a bulk delete response.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `document_id` | `string` | No | Document UUID |
| `message` | `string` | Yes | Human-readable result message |

---

## `DocsApiResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `list` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `detail` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `new` | [`PageMetaItem`](#pagemetaitem) | Yes | — |

---

## `DocsResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Resource or entry name |
| `type` | `string` | Yes | Resource or entry type identifier |
| `description` | `string` | Yes | Human-readable description |
| `materialized_view` | [`MvInfo`](#mvinfo) | No | Materialized view metadata |
| `tables` | [`TableInfo`](#tableinfo)[] | Yes | Related database tables |
| `operations` | [`OperationInfo`](#operationinfo)[] | Yes | Available operations |

---

## `DocumentDepartmentResource`

Department resource for document.

| Field | Type | Required | Description |
|---|---|---|---|
| `department_id` | `string` | No | Department UUID |
| `name` | `string` | No | Department name |
| `description` | `string` | No | Department description |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `DocumentDescriptionResource`

Description resource for document.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `description` | `string` | No | Description text |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `DocumentFieldError`

Per-field error from value resolution.

| Field | Type | Required | Description |
|---|---|---|---|
| `field` | `string` | Yes | Field name that has the error |
| `message` | `string` | Yes | Human-readable error message |

---

## `DocumentFileResource`

File resource for document.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `files_id` | `string` | No | File resource UUID |
| `file_path` | `string` | No | Stored file path |
| `mime_type` | `string` | No | File MIME type |
| `size` | `integer` | No | File size in bytes |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `DocumentFlagResource`

Flag option row — one per (name, type, value) entry in flags_resource.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Flag resource identifier |
| `name` | `string` | No | Flag display name |
| `type` | `string` | No | Flag type (e.g. 'document_active') |
| `value` | `boolean` | No | Underlying bool value of this option |
| `description` | `string` | No | Flag description text |
| `icon_id` | `string` | No | Icon identifier for the flag |
| `icon` | `string` | No | Resolved SVG markup for the icon |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `DocumentImageResource`

Image resource for document.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `image_id` | `string` | No | Image resource UUID |
| `name` | `string` | No | Image name |
| `description` | `string` | No | Image description |
| `file_path` | `string` | No | Stored file path |
| `mime_type` | `string` | No | File MIME type |
| `size` | `integer` | No | File size in bytes |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `DocumentNameResource`

Name resource for document.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `name` | `string` | No | Display name |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `DocumentParameterFieldResource`

Parameter field resource for document.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `field_id` | `string` | No | Associated field UUID |
| `parameter_id` | `string` | No | Associated parameter UUID |
| `name` | `string` | No | Field name |
| `description` | `string` | No | Field description |
| `conditional_parameter_id` | `string` | No | Conditional parameter UUID for grouping |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `DocumentParameterResource`

Parameter catalog item exposed to the client.

| Field | Type | Required | Description |
|---|---|---|---|
| `parameter_id` | `string` | No | Parameter UUID |
| `name` | `string` | No | Parameter name |
| `description` | `string` | No | Parameter description |
| `value` | `string` | No | Parameter value |
| `department_ids` | `string`[] | No | Department UUIDs |
| `persona_parameter` | `boolean` | No | Whether this is a persona parameter |
| `document_parameter` | `boolean` | No | Whether this is a document parameter |
| `scenario_parameter` | `boolean` | No | Whether this is a scenario parameter |
| `video_parameter` | `boolean` | No | Whether this is a video parameter |
| `field_ids` | `string`[] | No | Associated field UUIDs |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `DocumentResultItem`

Per-item result within a bulk create/update response.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `document_id` | `string` | No | Document UUID |
| `message` | `string` | Yes | Human-readable result message |
| `errors` | [`DocumentFieldError`](#documentfielderror)[] | No | List of per-field errors |

---

## `DocumentTextResource`

Text resource for document.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `texts_id` | `string` | No | Text resource UUID |
| `file_path` | `string` | No | Stored file path |
| `mime_type` | `string` | No | File MIME type |
| `content` | `string` | No | Optional text content when available |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `DraftFileValue`

Value for creating a file via the draft endpoint.

Client provides the upload_id from a finalized TUS upload.
Server creates the full chain: files_resource → files_entry → file_uploads_entry.

| Field | Type | Required | Description |
|---|---|---|---|
| `upload_id` | `string` | Yes | Upload UUID from a finalized TUS upload |

---

## `DraftTextValue`

Value for creating a text via the draft endpoint.

Client provides text content.
Server creates the full chain: uploads_entry → texts_resource → texts_entry → text_uploads_entry.

| Field | Type | Required | Description |
|---|---|---|---|
| `content` | `string` | Yes | Text content to create |

---

## `EvalSetup`

Run-level eval scaffold — first-class on the generate response.

Audit's ``**output`` spread carries this onto
``<artifact>.generate.completed``. Null when no rubric-bearing
agent participated.

| Field | Type | Required | Description |
|---|---|---|---|
| `test_id` | `string` | Yes | — |
| `invocations` | [`InvocationSlot`](#invocationslot)[] | Yes | — |

---

## `GenerateConfig`

Developer configuration — all optional with sensible defaults.

| Field | Type | Required | Description |
|---|---|---|---|
| `operations` | `string`[] | No | — |
| `dangerous` | `boolean` | No | — |
| `params` | `object` | No | — |
| `group_id` | `string` | No | — |

---

## `GenerationsDocumentListItem`

Single generation group in the document generations response.

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | UUID of the generation group |
| `session_id` | `string` | No | UUID of the parent session |
| `group_name` | `string` | No | Name of the generation group |
| `created_at` | `string` | No | Timestamp of the generation |

---

## `GetDocumentDraftResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | UUID of the draft |
| `created_at` | `string` | Yes | Creation timestamp |
| `generated` | `boolean` | Yes | Whether this was AI-generated |
| `mcp` | `boolean` | Yes | Whether MCP tooling was used |
| `active` | `boolean` | Yes | Whether this draft is active |
| `session_id` | `string` | Yes | Associated session UUID |
| `name` | `string` | No | Immutable draft label set at create time |
| `department_ids` | `string`[] | Yes | Associated department UUIDs |
| `description_ids` | `string`[] | Yes | Associated description UUIDs |
| `file_ids` | `string`[] | Yes | Associated file UUIDs |
| `flag_ids` | `string`[] | Yes | Associated flag UUIDs |
| `image_ids` | `string`[] | Yes | Associated image UUIDs |
| `name_ids` | `string`[] | Yes | Associated name UUIDs |
| `parameter_field_ids` | `string`[] | Yes | Associated parameter field UUIDs |
| `parameter_ids` | `string`[] | Yes | Associated parameter UUIDs |
| `profile_ids` | `string`[] | Yes | Associated profile UUIDs |
| `text_ids` | `string`[] | Yes | Associated text UUIDs |
| `pending_department_ids` | `string`[] | No | Pending department UUIDs |
| `pending_description_ids` | `string`[] | No | Pending description UUIDs |
| `pending_file_ids` | `string`[] | No | Pending file UUIDs |
| `pending_flag_ids` | `string`[] | No | Pending flag UUIDs |
| `pending_image_ids` | `string`[] | No | Pending image UUIDs |
| `pending_name_ids` | `string`[] | No | Pending name UUIDs |
| `pending_parameter_field_ids` | `string`[] | No | Pending parameter field UUIDs |
| `pending_parameter_ids` | `string`[] | No | Pending parameter UUIDs |
| `pending_text_ids` | `string`[] | No | Pending text UUIDs |

---

## `GroupCall`

Tool call referenced by a message.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `tool_name` | `string` | No | — |
| `template_name` | `string` | No | — |
| `tool` | `object` | No | — |
| `ledger_status` | `string` | No | — |
| `ledger_operation` | `string` | No | — |
| `ledger_artifact` | `string` | No | — |
| `ledger_artifact_id` | `string` | No | — |

---

## `GroupMessage`

Message within a run.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `role` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `text_ids` | `string`[] | No | — |
| `audio_ids` | `string`[] | No | — |
| `image_ids` | `string`[] | No | — |
| `video_ids` | `string`[] | No | — |
| `file_ids` | `string`[] | No | — |
| `call_ids` | `string`[] | No | — |
| `calls` | [`GroupCall`](#groupcall)[] | No | — |
| `reasoning` | `boolean` | No | True when this row is a chain-of-thought trace persisted alongside the assistant answer (rendered as a collapsed accordion). |
| `in_context` | `boolean` | No | Whether this message is included in the LLM context for the next generation. Mirrors the dedup pass that builds chat history (see in_context_reason). |
| `in_context_reason` | `string` | No | Why this message is in/out of LLM context. 'kept' = included; 'deduped_read' = older read-only call to a tool that has a fresher result later in the group; future values may include 'trimmed_top_n'. |

---

## `GroupResource`

Lightweight `\{id, name\}` for cross-referencing run-level ids
(``model_id`` / ``agent_id`` / ``profile_id``) against human-readable
names on the analytics panel. Names come from the canonical
``get_models`` / ``get_agents`` / ``get_profiles`` black boxes.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `name` | `string` | No | — |

---

## `GroupRun`

Run within a group, with its messages.

Carries token / cost / model / agent / profile attribution so the
analytics view can render per-run cost + actor info without a
parallel detail shape. ``profile_id`` is the authoring profile
(human user), ``agent_id`` is the LLM-side actor, ``model_id`` is
the model used by that agent. All optional — runs predating these
columns or with unresolved attributions surface ``None``.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `input_tokens` | `integer` | No | — |
| `output_tokens` | `integer` | No | — |
| `cached_input_tokens` | `integer` | No | — |
| `cost` | `number` | No | — |
| `model_id` | `string` | No | — |
| `agent_id` | `string` | No | — |
| `profile_id` | `string` | No | — |
| `previous_context_start_index` | `integer` | No | Index in ``messages`` where the current run's own messages begin; earlier rows are previous-context replay. ``None`` when the run has no previous context attached. |
| `messages` | [`GroupMessage`](#groupmessage)[] | No | — |

---

## `ImportField`

Field descriptor for CSV import column mapping.

| Field | Type | Required | Description |
|---|---|---|---|
| `key` | `string` | Yes | — |
| `label` | `string` | Yes | — |
| `required` | `boolean` | No | — |
| `multi` | `boolean` | No | — |
| `type` | `string` | No | — |
| `example` | `string` | No | — |
| `description` | `string` | No | — |

---

## `InvocationSlot`

One agent's slot in a multi-agent generation pool.

Populated by ``setup_generation_test`` when an agent carries a
rubric. The client uses these IDs to drive the eval workflow:
review the candidate's output, optionally fire a grader against
its ``invocation_id``, and promote/reject by call_id via the
existing ``idempotency_key + accept`` pattern.

| Field | Type | Required | Description |
|---|---|---|---|
| `invocation_id` | `string` | Yes | — |
| `agent_id` | `string` | Yes | — |
| `rubric_id` | `string` | No | — |

---

## `ListDocumentApiDocument`

Document type for list endpoint with computed permissions.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Document artifact UUID (canonical id; mirrors document_id) |
| `document_id` | `string` | No | Document UUID |
| `name` | `string` | No | Document name |
| `description` | `string` | No | Document description |
| `department_ids` | `string`[] | No | Associated department IDs |
| `scenario_ids` | `string`[] | No | Associated scenario UUIDs |
| `field_ids` | `string`[] | No | Associated field UUIDs |
| `flag_ids` | `string`[] | No | Currently selected flag option UUIDs |
| `is_inactive` | `boolean` | No | Whether the document is inactive (derived from document_active flag) |
| `is_template` | `boolean` | No | Whether the document is a template (derived from document_template flag) |
| `pending_status` | `string` | No | Latest soft_calls_mv status: 'pending' / 'accepted' / 'rejected' |
| `pending_operation` | `string` | No | Operation type ('create'|'update'|'delete'|'duplicate') of the pending op |
| `pending_call_id` | `string` | No | call_id (idempotency key for ack) of the pending op |
| `extension` | `string` | No | File extension derived from the primary file (e.g. 'pdf', 'docx', 'txt') |
| `num_scenarios` | `integer` | No | Total number of scenarios |
| `active_scenario_count` | `integer` | No | Number of active scenarios |
| `file_id` | `string` | No | Associated file resource UUID |
| `can_edit` | `boolean` | No | Whether the current user can edit |
| `can_duplicate` | `boolean` | No | Whether the current user can duplicate |
| `can_delete` | `boolean` | No | Whether the current user can delete |
| `updated_at` | `string` | No | Last updated timestamp |

---

## `ListFilterOption`

Standardized option for list endpoint filter sections.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier for this filter option |
| `name` | `string` | No | Display name |
| `count` | `integer` | No | Number of matching records |
| `hex_code` | `string` | No | Hex color code for display |
| `value` | `string` | No | Internal value |
| `type` | `string` | No | Option type discriminator |

---

## `ListFilterSection`

Filter section with options and echoed request state.

| Field | Type | Required | Description |
|---|---|---|---|
| `options` | [`ListFilterOption`](#listfilteroption)[] | No | Available filter options |
| `selected_ids` | `string`[] | No | Currently selected filter option IDs |
| `search` | `string` | No | Active search text for filtering |

---

## `MvInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Materialized view name |
| `definition` | `string` | Yes | SQL definition of the view |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the view |

---

## `OperationInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Operation name |
| `description` | `string` | Yes | Human-readable description of the operation |
| `params` | [`ParamInfo`](#paraminfo)[] | Yes | List of operation parameters |
| `returns` | `object` | No | Return type schema |

---

## `OperationPrompts`

Starter prompts keyed by operation name.

Each key is an operation (e.g. "create", "search", "draft", "export")
and the value is a list of starter prompts for that operation.
The client picks from the operations the caller has permission for
and rotates through them.

| Field | Type | Required | Description |
|---|---|---|---|
| `prompts` | `object` | No | Map of operation name to starter prompts |

---

## `PageMetaItem`

| Field | Type | Required | Description |
|---|---|---|---|
| `title` | `string` | Yes | — |
| `description` | `string` | Yes | — |

---

## `ParamInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Parameter name |
| `type` | `string` | Yes | Parameter data type |
| `required` | `boolean` | Yes | Whether the parameter is required |
| `default` | `any` | No | Default value if not required |

---

## `ProducedMedia`

One asset produced by a generation run.

``resource_id`` is the canonical id the per-artifact download tools
accept (e.g. ``Scenario_Image_Download(image_id=resource_id)`` for
``modality="image"``). It maps to ``images_resource.id`` /
``videos_resource.id`` / ``audios_resource.id`` depending on the
modality.

| Field | Type | Required | Description |
|---|---|---|---|
| `modality` | `"image"` \| `"video"` \| `"audio"` | Yes | — |
| `resource_id` | `string` | Yes | — |
| `upload_id` | `string` | Yes | — |
| `mime_type` | `string` | No | — |
| `file_size` | `integer` | No | — |

---

## `ProfileSummary`

Caller identity derived from JWT — who you are on this page.

Superset of the old six-field version: now carries everything the client
needs so that ``/\{artifact\}/context`` fully replaces ``/profiles/context``
and the extra ``getLayoutContextData`` round-trip can be dropped.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Display name of the authenticated user |
| `role` | `string` | Yes | Role name (e.g. 'Super Administrator') |
| `role_level` | `integer` | Yes | Role hierarchy level (0 = highest privilege) |
| `department_ids` | `string`[] | Yes | Departments the user belongs to |
| `artifact_access` | `string`[] | Yes | Artifact types this role can access (sidebar visibility) |
| `role_permissions` | `any`[][] | Yes | Full (artifact, operation) permission tuples for granular page gating |
| `is_active` | `boolean` | Yes | Whether the user's profile is active |
| `id` | `string` | Yes | Profile UUID (SocketProvider, ProfileProvider) |
| `theme` | [`ThemeBundle`](#themebundle) | No | Resolved theme: hex primitives + derived oklch tokens + score thresholds |
| `session_id` | `string` | No | Current session UUID |
| `is_emulation` | `boolean` | No | Whether user is in emulation mode (ProfileProvider) |
| `role_resources` | [`QGetProfileContextV4RoleResource`](#qgetprofilecontextv4roleresource)[] | No | All role resources for emulation display (ProfileProvider) |
| `scoped_roles` | `string`[] | No | Roles the user can emulate (ProfileProvider) |
| `active` | `boolean` | No | Alias for is_active (ProfileProvider uses this name) |

---

## `QGetProfileContextV4RoleResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `role` | `string` | No | — |
| `name` | `string` | No | — |
| `description` | `string` | No | — |
| `icon_value` | `string` | No | — |
| `color_hex` | `string` | No | — |

---

## `RunStatus`

Outcome of one watched run.

| Field | Type | Required | Description |
|---|---|---|---|
| `run_id` | `string` | Yes | — |
| `status` | `"pending"` \| `"completed"` \| `"failed"` | Yes | — |
| `modality` | `string` | No | Modality of generated output (image, video, text…) |
| `resource_ids` | `string`[] | No | Resource UUIDs produced by this run (e.g. images_resource ids) |
| `error` | `string` | No | — |

---

## `TableInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Table name |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the table |

---

## `ThemeBundle`

Full theme payload for a page bootstrap.

Riding along on every ``/\{artifact\}/context`` response via
``ProfileSummary.theme``. Layers:
  - ``primitives`` / ``dark_primitives`` — hex inputs the settings
    editor reads/writes (light + dark palettes).
  - ``tokens`` / ``dark_tokens`` — oklch tokens the client paints with.
    ``ThemeStyle`` emits two ``<style>`` blocks: one scoped to
    ``:root:not(.dark)`` (light) and one to ``:root.dark`` (dark).
  - ``thresholds`` — numeric score thresholds for analytics components.
Empty-in → empty-out per token: missing values fall through to the
matching ``globals.css`` default.

| Field | Type | Required | Description |
|---|---|---|---|
| `primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (light palette, for the theme editor) |
| `tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for light mode (SSR CSS-var injection) |
| `dark_primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (dark palette, for the theme editor) |
| `dark_tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for dark mode (SSR CSS-var injection) |
| `thresholds` | [`Thresholds`](#thresholds) | No | Score thresholds resolved from the setting |

---

## `ThemePrimitives`

40 optional fields. The 17 essentials drive the rest; the other 23
are overrides for fine-tuning when derivation isn't what you want.

Empty primitive → empty token → client falls back to globals.css.

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `primary` | `string` | No | — |
| `accent` | `string` | No | — |
| `card` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `ring` | `string` | No | — |
| `border` | `string` | No | — |
| `destructive` | `string` | No | — |
| `success` | `string` | No | — |
| `warning` | `string` | No | — |
| `info` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `input` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `ThemeTokens`

40 fully-resolved CSS variable values (snake_case 1:1 with vars).

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `accent` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `border` | `string` | No | — |
| `input` | `string` | No | — |
| `ring` | `string` | No | — |
| `success` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `Thresholds`

Numeric score thresholds resolved from the active setting.

Server pre-buckets dashboard metrics into ``success | warning | danger |
neutral`` already, so most components don't need these values. Surface
them for chart reference lines, tooltips, and any client-side bucketing.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `integer` | Yes | Score >= this counts as success |
| `warning` | `integer` | Yes | Score >= this counts as warning |
| `danger` | `integer` | Yes | Score < success threshold but >= this counts as danger; below is neutral/no-data |

---

## `UpdateDocumentItem`

Single document item for update — document_id required, all fields optional.

Only provided fields are updated (partial update).

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | Document UUID to update |
| `name_id` | `string` | No | Name resource UUID |
| `name` | `string` | No | Name value for resolution |
| `description_id` | `string` | No | Description resource UUID |
| `description` | `string` | No | Description value for resolution |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `active` | `boolean` | No | Denormalized document_active flag state; resolved to a flag_ids entry server-side |
| `department_ids` | `string`[] | No | Department UUIDs |
| `departments` | `string`[] | No | Department names for resolution |
| `parameter_field_ids` | `string`[] | No | Parameter field UUIDs |
| `upload_ids` | `string`[] | No | File upload UUIDs |
| `image_ids` | `string`[] | No | Image UUIDs |
| `text_ids` | `string`[] | No | Text resource UUIDs |

---

## `UpdateDocumentPatch`

Shared patch for bulk-update-all-matching mode.

Inherits every field from ``UpdateDocumentItem`` and just relaxes
``id`` to optional — the bulk impl stamps the resolved id onto a
clone of the patch per matched row, so any client-supplied id is
ignored. Sparse semantics: only fields the client sets are written.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Ignored — bulk impl stamps the resolved document id per matched row |
| `name_id` | `string` | No | Name resource UUID |
| `name` | `string` | No | Name value for resolution |
| `description_id` | `string` | No | Description resource UUID |
| `description` | `string` | No | Description value for resolution |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `active` | `boolean` | No | Denormalized document_active flag state; resolved to a flag_ids entry server-side |
| `department_ids` | `string`[] | No | Department UUIDs |
| `departments` | `string`[] | No | Department names for resolution |
| `parameter_field_ids` | `string`[] | No | Parameter field UUIDs |
| `upload_ids` | `string`[] | No | File upload UUIDs |
| `image_ids` | `string`[] | No | Image UUIDs |
| `text_ids` | `string`[] | No | Text resource UUIDs |

---

## `app__infra__document__types__DraftFormState`

Server-authoritative form state returned after draft save.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | No | Echoed unresolved name value |
| `name_id` | `string` | No | Selected name resource UUID |
| `description` | `string` | No | Echoed unresolved description value |
| `description_id` | `string` | No | Selected description resource UUID |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs |
| `active` | `boolean` | No | Echoed document_active flag state |
| `department_ids` | `string`[] | No | Selected department UUIDs |
| `file_ids` | `string`[] | No | Selected file resource UUIDs |
| `image_ids` | `string`[] | No | Selected image UUIDs |
| `text_ids` | `string`[] | No | Selected text resource UUIDs |
| `parameter_field_ids` | `string`[] | No | Selected parameter field UUIDs |
| `parameter_ids` | `string`[] | No | Selected parameter UUIDs |
| `pending_ids` | `string`[] | No | Pending resource UUIDs where supported |

---

## `app__infra__document__types__DraftImageValue`

Value for creating an image via the draft endpoint.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Image name |
| `description` | `string` | Yes | Image description text |
| `upload_id` | `string` | No | Associated upload UUID |

---

## `app__infra__document__types__SectionFilter`

Per-section filter options for GET requests.

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Filter options by search text |
| `limit` | `integer` | No | Max options to return |
| `selected` | `boolean` | No | Only return selected items |
| `suggested` | `boolean` | No | Only return suggested items |
| `include` | `boolean` | No | Include this section in response (default true) |
| `parameter_ids` | `string`[] | No | Parameter group IDs for parameter field hydration |

---

---

# `GET` `/eval/watch`

Route: /api-reference/eval/get-eval-watch

# `GET` `/eval/watch`

Eval Watch

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `group_id` | query | No | — |
| `run_id` | query | No | Optional run filter. If provided, only events whose envelope run_id matches are streamed. Omit to receive every eval event in the group (the FE default). |

## Response

```
{}
```

---

# `POST` `/eval/call_download`

Route: /api-reference/eval/post-eval-call-download

# `POST` `/eval/call_download`

Download Call

Download a call file by call resource ID.

## Request Body (`CallDownloadEvalApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `call_id` | `string` | Yes | UUID of the calls_resource to download |

## Response

```
{}
```

---

# `POST` `/eval/context`

Route: /api-reference/eval/post-eval-context

# `POST` `/eval/context`

Get Eval Context

Get page context for the eval artifact.

Returns docs + profile identity + evaluated permissions in a single call.
Superset of /docs — clients can migrate from /docs to /context incrementally.

## Request Body (`DocsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entity_id` | `string` | No | — |
| `snapshot_key` | `string` | No | — |
| `schema` | `boolean` | No | If true, include MCP/tooling schema metadata (artifact, entries, resources, permission_docs, api_operations). Defaults to false for lean page-bootstrap responses. |

## Response (`ComposedContextResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Artifact name |
| `type` | `string` | Yes | Artifact type identifier |
| `description` | `string` | Yes | Human-readable description |
| `artifact` | [`DocsResponse`](/api-reference/eval/types#docsresponse) | No | Artifact tool documentation (None unless schema=true) |
| `entries` | [`DocsResponse`](/api-reference/eval/types#docsresponse)[] | No | Entry documentation list (None unless schema=true) |
| `resources` | [`DocsResponse`](/api-reference/eval/types#docsresponse)[] | No | Resource documentation list (None unless schema=true) |
| `permission_docs` | [`OperationInfo`](/api-reference/eval/types#operationinfo)[] | No | Permission function signatures for MCP/dev tooling (None unless schema=true) |
| `api_operations` | [`OperationInfo`](/api-reference/eval/types#operationinfo)[] | No | API operation documentation (None unless schema=true) |
| `page_metadata` | [`DocsApiResponse`](/api-reference/eval/types#docsapiresponse) | No | Page-level metadata |
| `prompts` | [`OperationPrompts`](/api-reference/eval/types#operationprompts) | No | Starter prompts keyed by operation |
| `profile` | [`ProfileSummary`](/api-reference/eval/types#profilesummary) | Yes | Caller identity from JWT |
| `caller_permissions` | [`CallerPermissions`](/api-reference/eval/types#callerpermissions) | Yes | Evaluated permissions for this caller |

---

# `POST` `/eval/create`

Route: /api-reference/eval/post-eval-create

# `POST` `/eval/create`

Create Eval

Create evals using composable infra architecture.

## Request Body (`CreateEvalApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `evals` | [`CreateEvalItem`](/api-reference/eval/types#createevalitem)[] | Yes | List of evals to create |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant create |
| `soft` | `boolean` | No | Stage the create dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`CreateEvalApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`EvalResultItem`](/api-reference/eval/types#evalresultitem)[] | Yes | List of operation results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |
| `evals` | [`ListEvalApiEval`](/api-reference/eval/types#listevalapieval)[] | No | Hydrated list rows for the newly-created evals — same shape as ``/eval/search`` returns. Used by the client's ghost rail to materialize the new row from the audit ``.completed`` payload without a router refresh. ``None`` for soft-pending creates (dormant artifact, hydration runs on ack-accept). |

---

# `POST` `/eval/csv`

Route: /api-reference/eval/post-eval-csv

# `POST` `/eval/csv`

Parse Eval Csv

Parse a CSV file and return mapped items for preview.

## Request Body

| Field | Type | Required | Description |
|---|---|---|---|
| `file` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `soft` | `boolean` | No | — |
| `accept` | `boolean` | No | — |

## Response (`ParseEvalCsvApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `upload_id` | `string` | Yes | — |
| `items` | [`CreateEvalItem`](/api-reference/eval/types#createevalitem)[] | Yes | — |
| `mapped_fields` | `string`[] | Yes | — |
| `row_count` | `integer` | Yes | — |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with `accept` to promote/reject the staged raw-CSV upload. NOTE: ack returns no items (the preview is only on the propose). |

---

# `POST` `/eval/delete`

Route: /api-reference/eval/post-eval-delete

# `POST` `/eval/delete`

Delete Eval

Bulk delete evals — composable infra architecture.

## Request Body (`DeleteEvalApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `eval_ids` | `string`[] | No | List of eval UUIDs to delete (required on first call when ``all`` is false) |
| `all` | `boolean` | No | When true, delete every eval matching the filter fields below (minus ``excluded_ids``) |
| `excluded_ids` | `string`[] | No | UUIDs to skip even when matched by ``all``-mode filters |
| `search` | `string` | No | Full-text search query |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `department_search` | `string` | No | Search text for department facet (no-op for row filtering) |
| `flag_search` | `string` | No | Search text for flag facet (no-op for row filtering) |
| `idempotency_key` | `string` | No | Operation key for ack — confirms or rejects a dormant delete |
| `soft` | `boolean` | No | Stage the delete dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (confirm) or reject dormant state. Only meaningful with idempotency_key |

## Response (`DeleteEvalApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`DeleteEvalResult`](/api-reference/eval/types#deleteevalresult)[] | Yes | List of operation results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/eval/draft`

Route: /api-reference/eval/post-eval-draft

# `POST` `/eval/draft`

Patch Eval Draft

Patch eval draft — composable infra architecture.

## Request Body (`PatchEvalDraftApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `draft_id` | `string` | No | Existing draft UUID to patch |
| `input_draft_id` | `string` | No | Existing draft UUID to patch |
| `name` | `string` | No | Name value to create a resource |
| `name_id` | `string` | No | Existing name resource UUID |
| `description` | `string` | No | Description value to create a resource |
| `description_id` | `string` | No | Existing description resource UUID |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `active` | `boolean` | No | Denormalized eval_active flag state; resolved to a flag_ids entry server-side |
| `departments` | `string`[] | No | Department names to resolve |
| `department_ids` | `string`[] | No | Department UUIDs |
| `model_ids` | `string`[] | No | Model UUIDs |
| `model_flag_ids` | `string`[] | No | Model flag UUIDs (canonical junction-row ids) |
| `model_flags` | `object`[] | No | Inline-create shape for model_flags junction rows: list of \{model_id, flag_id\} (id=null entries). Resolver upserts the junction row and merges the id into model_flag_ids. |
| `model_flag_values` | [`EvalModelFlagValue`](/api-reference/eval/types#evalmodelflagvalue)[] | No | Denormalized per-(model, type) selections. For each entry the server resolves (type, value) -> flag_id via search_flags, then upserts a model_flags_resource row for (model_id, flag_id) and merges its id into model_flag_ids. |
| `model_position_ids` | `string`[] | No | Model position UUIDs |
| `model_rubric_ids` | `string`[] | No | Model rubric UUIDs |
| `pending_ids` | `string`[] | No | Resource IDs to keep inactive on the draft |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant draft |
| `soft` | `boolean` | No | Stage the draft dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept or reject dormant state. Only meaningful with idempotency_key |

## Response (`PatchEvalDraftApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `draft_id` | `string` | Yes | Draft UUID |
| `idempotency_key` | `string` | No | Operation key echoed back for client correlation |
| `message` | `string` | Yes | Human-readable result message |
| `form_state` | [`app__infra__eval__types__DraftFormState`](/api-reference/eval/types#app-infra-eval-types-draftformstate) | No | Server-authoritative form state |

---

# `POST` `/eval/drafts`

Route: /api-reference/eval/post-eval-drafts

# `POST` `/eval/drafts`

Get Eval Drafts

List eval drafts owned by the current profile.

## Request Body (`GetEvalDraftsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE substring) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GetEvalDraftsApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entries` | [`GetEvalDraftResponse`](/api-reference/eval/types#getevaldraftresponse)[] | No | List of eval draft entries |

---

# `POST` `/eval/duplicate`

Route: /api-reference/eval/post-eval-duplicate

# `POST` `/eval/duplicate`

Duplicate Eval

Duplicate an eval — composable infra architecture.

## Request Body (`DuplicateEvalApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `eval_id` | `string` | Yes | Eval UUID to duplicate |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant duplicate |
| `soft` | `boolean` | No | Stage the duplicate dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`DuplicateEvalApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `eval_id` | `string` | Yes | Newly created eval UUID |
| `message` | `string` | Yes | Human-readable result message |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |
| `evals` | [`ListEvalApiEval`](/api-reference/eval/types#listevalapieval)[] | No | Hydrated list rows for the duplicated eval — single-element list, kept as a list for shape consistency with create/update. ``None`` for soft-pending duplicates. |

---

# `POST` `/eval/export`

Route: /api-reference/eval/post-eval-export

# `POST` `/eval/export`

Export Evals

Export all evals as a clean, denormalized CSV.

## Request Body (`ExportEvalApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `eval_id` | `string` | No | — |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior export instead of re-running |
| `soft` | `boolean` | No | Stage the export dormant (active=False); ack with accept activates it |
| `accept` | `boolean` | No | Ack: True promotes the staged export, False rejects. Only meaningful with idempotency_key |

## Response (`ExportEvalApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource holding the export CSV |
| `file_name` | `string` | Yes | Suggested download file name |
| `row_count` | `integer` | Yes | Number of data rows in the export |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with `accept` to promote/reject the staged export. |

---

# `POST` `/eval/file_download`

Route: /api-reference/eval/post-eval-file-download

# `POST` `/eval/file_download`

Download File

Download a file by file resource ID.

## Request Body (`FileDownloadEvalApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource to download |

## Response

```
{}
```

---

# `POST` `/eval/generate`

Route: /api-reference/eval/post-eval-generate

# `POST` `/eval/generate`

Generate Eval

Trigger eval generation. Returns immediately; progress via events.

## Request Body (`ArtifactGenerateRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `instructions` | `string`[] | No | — |
| `config` | [`GenerateConfig`](/api-reference/eval/types#generateconfig) | No | — |
| `modalities` | `string`[] | No | — |
| `audios_id` | `string` | No | — |
| `conversation_id` | `string` | No | — |
| `trace_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `accept` | `boolean` | No | — |
| `wait_for_complete` | `boolean` | No | — |

## Response (`ArtifactGenerateResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `run_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `eval` | [`EvalSetup`](/api-reference/eval/types#evalsetup) | No | — |
| `produced_media` | [`ProducedMedia`](/api-reference/eval/types#producedmedia)[] | No | — |

---

# `POST` `/eval/generations`

Route: /api-reference/eval/post-eval-generations

# `POST` `/eval/generations`

Generations Eval

List eval generation groups — composable infra architecture.

## Request Body (`GenerationsEvalApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GenerationsEvalApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `items` | [`GenerationsEvalListItem`](/api-reference/eval/types#generationsevallistitem)[] | No | Generation groups |
| `total_count` | `integer` | No | Total number of matching generations |

---

# `POST` `/eval/get`

Route: /api-reference/eval/post-eval-get

# `POST` `/eval/get`

Get Eval

Get eval information using the canonical shared eval operation.

## Request Body (`GetEvalApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Eval UUID to retrieve |
| `eval_id` | `string` | No | Legacy eval UUID to retrieve |
| `draft_id` | `string` | No | Draft UUID to load from |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |
| `names` | [`app__infra__eval__types__SectionFilter`](/api-reference/eval/types#app-infra-eval-types-sectionfilter) | No | Filter options for names section |
| `descriptions` | [`app__infra__eval__types__SectionFilter`](/api-reference/eval/types#app-infra-eval-types-sectionfilter) | No | Filter options for descriptions section |
| `flags` | [`app__infra__eval__types__SectionFilter`](/api-reference/eval/types#app-infra-eval-types-sectionfilter) | No | Filter options for flags section |
| `departments` | [`app__infra__eval__types__SectionFilter`](/api-reference/eval/types#app-infra-eval-types-sectionfilter) | No | Filter options for departments section |
| `models` | [`app__infra__eval__types__SectionFilter`](/api-reference/eval/types#app-infra-eval-types-sectionfilter) | No | Filter options for models section |
| `model_flags` | [`app__infra__eval__types__SectionFilter`](/api-reference/eval/types#app-infra-eval-types-sectionfilter) | No | Filter options for model flags section |
| `model_rubrics` | [`app__infra__eval__types__SectionFilter`](/api-reference/eval/types#app-infra-eval-types-sectionfilter) | No | Filter options for model rubrics section |
| `model_positions` | [`app__infra__eval__types__SectionFilter`](/api-reference/eval/types#app-infra-eval-types-sectionfilter) | No | Filter options for model positions section |

## Response (`GetEvalApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current user |
| `eval_exists` | `boolean` | No | Whether the eval exists |
| `can_edit` | `boolean` | No | Whether the current user can edit |
| `disabled_reason` | `string` | No | Reason editing is disabled |
| `group_id` | `string` | No | Associated group UUID |
| `draft_name` | `string` | No | Immutable draft label from the active draft entry, when a ``draft_id`` was supplied. ``None`` for non-draft fetches. |
| `basic_show_ai_generate` | `boolean` | No | Whether to show AI generate for the basic step |
| `model_show_ai_generate` | `boolean` | No | Whether to show AI generate for the model step |
| `show_ai_generate` | `boolean` | No | Whether any AI generate action should be shown |
| `pending_ids` | `string`[] | No | Pending resource identifiers when available |
| `names` | [`EvalNameResource`](/api-reference/eval/types#evalnameresource)[] | No | Name resources |
| `descriptions` | [`EvalDescriptionResource`](/api-reference/eval/types#evaldescriptionresource)[] | No | Description resources |
| `flags` | [`EvalFlagResource`](/api-reference/eval/types#evalflagresource)[] | No | Flag resources (one per flags_resource row, value=true/false) |
| `departments` | [`EvalDepartmentResource`](/api-reference/eval/types#evaldepartmentresource)[] | No | Department resources |
| `models` | [`EvalModelResource`](/api-reference/eval/types#evalmodelresource)[] | No | Model resources |
| `model_flags` | [`EvalModelFlagResource`](/api-reference/eval/types#evalmodelflagresource)[] | No | Model flag resources (linked junction rows) |
| `model_flag_options` | [`EvalModelFlagOptionResource`](/api-reference/eval/types#evalmodelflagoptionresource)[] | No | Cross-product (model x flag-type x value) options for the ModelFlags picker. |
| `model_rubrics` | [`EvalModelRubricResource`](/api-reference/eval/types#evalmodelrubricresource)[] | No | Model rubric resources |
| `model_positions` | [`EvalModelPositionResource`](/api-reference/eval/types#evalmodelpositionresource)[] | No | Model position resources |
| `rubrics` | [`EvalRubricResource`](/api-reference/eval/types#evalrubricresource)[] | No | Top-level rubric catalog for the ModelRubrics picker |

---

# `POST` `/eval/group`

Route: /api-reference/eval/post-eval-group

# `POST` `/eval/group`

Group Eval

Resolve or create an eval group with optional naming.

## Request Body (`GroupEvalApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | No | Existing group UUID (omit to create or reuse via time window) |
| `snapshot_key` | `string` | No | Snapshot key for SETNX-race convergence on a single group across concurrent reads (e.g. parallel /context + /group + /search fan-out on page load). Echoed back in the response. |

## Response (`GroupEvalApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Resolved or newly created group UUID |
| `name` | `string` | No | The group's current title (latest active group_names_entry, or 'New Chat' fallback for freshly minted groups) |
| `snapshot_key` | `string` | No | Snapshot key echoed back — the UUID concurrent fan-out reads converged on via SETNX. Mirrors the resolved group_id. |
| `runs` | [`GroupRun`](/api-reference/eval/types#grouprun)[] | No | Conversation history — populated when resolving an existing group for fetch |
| `group_exists` | `boolean` | No | (detail) Whether the group exists in storage — populated when ``include_resources=True`` |
| `actor_name` | `string` | No | (detail) Display name of the current actor (caller profile) |
| `total_message_count` | `integer` | No | (detail) Total number of messages in the group |
| `models` | [`GroupResource`](/api-reference/eval/types#groupresource)[] | No | (detail) Models used in the group |
| `agents` | [`GroupResource`](/api-reference/eval/types#groupresource)[] | No | (detail) Agents used in the group |
| `profiles` | [`GroupResource`](/api-reference/eval/types#groupresource)[] | No | (detail) Profiles that authored runs in this group |

---

# `POST` `/eval/problem`

Route: /api-reference/eval/post-eval-problem

# `POST` `/eval/problem`

Problem Eval

Report an eval problem — composable infra architecture.

## Request Body (`ProblemEvalApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | `string` | Yes | Problem type: feature, bug, question, other |
| `message` | `string` | Yes | Problem description (max 1000 chars) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant problem |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`ProblemEvalApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `problem_id` | `string` | Yes | UUID of the created problem |
| `success` | `boolean` | No | Whether the problem was created |
| `message` | `string` | No | Status message |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/eval/refresh`

Route: /api-reference/eval/post-eval-refresh

# `POST` `/eval/refresh`

Eval Refresh

Refresh eval materialized views and invalidate caches.

## Request Body (`RefreshEvalApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `targets` | `string`[] | No | MV targets to refresh (omit for all). Options: eval_drafts_mv |
| `idempotency_key` | `string` | No | Operation key for ack |
| `accept` | `boolean` | No | Accept or reject. Only meaningful with idempotency_key |
| `soft` | `boolean` | No | Stage the refresh as a pending (held) request — recorded but not enqueued; ack with accept releases/enqueues it |

## Response (`RefreshResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | — |
| `refreshed_views` | `string`[] | Yes | — |
| `invalidated_tags` | `string`[] | Yes | — |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/eval/search`

Route: /api-reference/eval/post-eval-search

# `POST` `/eval/search`

Search Eval

Search evals — composable infra architecture.

## Request Body (`SearchEvalApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | — |
| `filter_department_ids` | `string`[] | No | — |
| `department_search` | `string` | No | — |
| `page_size` | `integer` | No | — |
| `page_offset` | `integer` | No | — |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`ListEvalApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current user |
| `evals` | [`ListEvalApiEval`](/api-reference/eval/types#listevalapieval)[] | No | List of evals |
| `department_filter` | [`ListFilterSection`](/api-reference/eval/types#listfiltersection) | No | Filter options for departments in list UI |
| `flag_filter` | [`ListFilterSection`](/api-reference/eval/types#listfiltersection) | No | Filter options for flags in list UI |
| `model_filter` | [`ListFilterSection`](/api-reference/eval/types#listfiltersection) | No | Filter options for models in list UI |
| `rubric_filter` | [`ListFilterSection`](/api-reference/eval/types#listfiltersection) | No | Filter options for rubrics in list UI |
| `total_count` | `integer` | No | Total number of matching records |
| `user_role` | `string` | No | Role of the current user |
| `import_fields` | [`ImportField`](/api-reference/eval/types#importfield)[] | No | CSV import column schema for the bulk-import dialog |

---

# `POST` `/eval/text_download`

Route: /api-reference/eval/post-eval-text-download

# `POST` `/eval/text_download`

Download Text

Download a text file by text resource ID.

## Request Body (`TextDownloadEvalApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `text_id` | `string` | Yes | UUID of the texts_resource to download |

## Response

```
{}
```

---

# `POST` `/eval/title`

Route: /api-reference/eval/post-eval-title

# `POST` `/eval/title`

Title Eval

Rename a eval's group (writes group_names_entry).

## Request Body (`TitleEvalApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Group to rename |
| `title` | `string` | Yes | New title (display name) for the group |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant rename |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`TitleEvalApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | The group that was renamed |
| `group_name_id` | `string` | Yes | UUID of the new group_names_entry row |
| `title` | `string` | Yes | The title that was set |
| `idempotency_key` | `string` | No | Operation key echoed back |

---

# `POST` `/eval/update`

Route: /api-reference/eval/post-eval-update

# `POST` `/eval/update`

Update Eval

Update evals using composable infra architecture.

## Request Body (`UpdateEvalApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `evals` | [`UpdateEvalItem`](/api-reference/eval/types#updateevalitem)[] | No | List of evals to update (required on first call when ``all`` is false) |
| `all` | `boolean` | No | When true, apply ``patch`` to every eval matching the filter fields below (minus ``excluded_ids``) |
| `excluded_ids` | `string`[] | No | UUIDs to skip even when matched by ``all``-mode filters |
| `patch` | [`UpdateEvalPatch`](/api-reference/eval/types#updateevalpatch) | No | Shared change set applied to every matched row when ``all=true`` (sparse — only set fields are updated; ``patch.id`` ignored) |
| `search` | `string` | No | Full-text search query |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `department_search` | `string` | No | Search text for department facet (no-op for row filtering) |
| `flag_search` | `string` | No | Search text for flag facet (no-op for row filtering) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant update |
| `soft` | `boolean` | No | Stage the update dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`UpdateEvalApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`EvalResultItem`](/api-reference/eval/types#evalresultitem)[] | Yes | List of operation results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |
| `evals` | [`ListEvalApiEval`](/api-reference/eval/types#listevalapieval)[] | No | Hydrated list rows for the updated evals — same shape as ``/eval/search`` returns. Used by the client's ghost rail to materialize the changed row from the audit ``.completed`` payload without a router refresh. ``None`` for soft-pending updates. |

---

# `POST` `/eval/watch`

Route: /api-reference/eval/post-eval-watch

# `POST` `/eval/watch`

Eval Watch Once

One-shot snapshot of run state, snapshot-replayable via ``snapshot_key``.

## Request Body (`WatchApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Chat group whose events we watch |
| `run_id` | `string` | No | Specific run to watch (e.g. the ``run_id`` returned by a prior ``X_Generate`` call). If None, watches every active run in the group at call time. |
| `wait_for_complete` | `boolean` | No | If True, block until the watched run reaches a terminal (complete/failed) event or timeout fires. If False, return current state and exit immediately. |
| `timeout_seconds` | `integer` | No | Max wait time when ``wait_for_complete=True``. |
| `snapshot_key` | `string` | No | Read snapshot key — on the one-shot POST /watch, the audit wrapper records this watch's point-in-time view (latest run state at call time) keyed by it and replays the same view on any later call with the same key. Ignored by the SSE GET stream. |

## Response (`WatchApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `runs` | [`RunStatus`](/api-reference/eval/types#runstatus)[] | Yes | — |
| `timed_out` | `boolean` | No | — |
| `waited_seconds` | `number` | No | — |

---

# Eval Types

Route: /api-reference/eval/types

# Eval Types

## `CallerPermissions`

Evaluated permissions for the current caller on this artifact type.

| Field | Type | Required | Description |
|---|---|---|---|
| `can_create` | `boolean` | Yes | Whether the caller can create new artifacts |
| `can_draft` | `boolean` | Yes | Whether the caller can create/update drafts |
| `can_duplicate` | `boolean` | Yes | Whether the caller can duplicate artifacts |
| `has_access` | `boolean` | No | Whether the caller can view this entity |
| `can_edit` | `boolean` | No | Whether the caller can edit this entity |
| `can_delete` | `boolean` | No | Whether the caller can delete this entity |
| `disabled_reason` | `string` | No | Human-readable reason if editing is disabled |

---

## `ColumnInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Column name |
| `type` | `string` | Yes | Column data type |
| `nullable` | `boolean` | Yes | Whether the column is nullable |

---

## `CreateEvalItem`

Single eval item for create — no eval_id.

Required fields (name): provide ID or value.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Optional pre-assigned UUID |
| `resource_id` | `string` | No | Optional preset UUID for the resource snapshot |
| `name_id` | `string` | No | REQUIRED FOR CREATE (or pass `name`): UUID of an existing name resource |
| `name` | `string` | No | REQUIRED FOR CREATE (or pass `name_id`): display name text — creates a new name resource if `name_id` is not provided |
| `description_id` | `string` | No | Description resource UUID |
| `description` | `string` | No | Description value for resolution |
| `flag_ids` | `string`[] | No | Flag option UUIDs |
| `department_ids` | `string`[] | No | Department UUIDs |
| `departments` | `string`[] | No | Department names for resolution |
| `model_ids` | `string`[] | No | Model UUIDs |
| `model_flag_ids` | `string`[] | No | Model flag UUIDs |
| `model_rubric_ids` | `string`[] | No | Model rubric UUIDs |
| `model_position_ids` | `string`[] | No | Model position UUIDs |
| `active` | `boolean` | No | Denormalized eval_active flag state; resolved to a flag_ids entry server-side |

---

## `DeleteEvalResult`

Per-item result within a bulk delete response.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `eval_id` | `string` | No | Eval UUID (None only for soft-skipped rows) |
| `message` | `string` | Yes | Human-readable result message |

---

## `DocsApiResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `list` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `detail` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `new` | [`PageMetaItem`](#pagemetaitem) | Yes | — |

---

## `DocsResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Resource or entry name |
| `type` | `string` | Yes | Resource or entry type identifier |
| `description` | `string` | Yes | Human-readable description |
| `materialized_view` | [`MvInfo`](#mvinfo) | No | Materialized view metadata |
| `tables` | [`TableInfo`](#tableinfo)[] | Yes | Related database tables |
| `operations` | [`OperationInfo`](#operationinfo)[] | Yes | Available operations |

---

## `EvalDepartmentResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `department_id` | `string` | No | Department identifier |
| `name` | `string` | No | Display name |
| `description` | `string` | No | Description text |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `EvalDescriptionResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `description` | `string` | No | Description text |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `EvalFieldError`

Per-field error from value resolution.

| Field | Type | Required | Description |
|---|---|---|---|
| `field` | `string` | Yes | Field name that has the error |
| `message` | `string` | Yes | Human-readable error message |

---

## `EvalFlagResource`

Flag option row — one per (name, type, value) entry in flags_resource.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Flag resource identifier |
| `name` | `string` | No | Flag display name |
| `type` | `string` | No | Flag type (e.g. 'eval_active') |
| `value` | `boolean` | No | Underlying bool value of this option |
| `description` | `string` | No | Flag description text |
| `icon_id` | `string` | No | Icon identifier for the flag |
| `icon` | `string` | No | Resolved SVG markup (hydrated from icons_resource) |
| `generated` | `boolean` | No | Whether the flag was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `EvalModelFlagOptionResource`

Cross-product option row: one per (model_id, flag_type, value) tuple.
The ModelFlags picker groups these by (model_id, type) and renders a
Switch per group; toggling picks the row whose `value` matches the new
state and sends its flag_id (or denormalized \{model_id,type,value\}) up
through the draft endpoint.

| Field | Type | Required | Description |
|---|---|---|---|
| `model_id` | `string` | No | Model identifier |
| `flag_id` | `string` | No | Flag resource identifier (flags_resource row) |
| `type` | `string` | No | Flag type, e.g. 'model_active' |
| `value` | `boolean` | No | Underlying flag value for this option |
| `name` | `string` | No | Display name from the flags_resource row |
| `description` | `string` | No | Description text from the flags_resource row |
| `icon` | `string` | No | Icon SVG markup hydrated from icons_resource |

---

## `EvalModelFlagResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Model-flag resource identifier |
| `model_id` | `string` | No | Associated model identifier |
| `flag_id` | `string` | No | Associated flag identifier |
| `type` | `string` | No | Flag type (e.g. 'model_active') of the linked flags_resource row |
| `value` | `boolean` | No | Underlying bool value of the linked flags_resource row |
| `name` | `string` | No | Display name |
| `description` | `string` | No | Description text |
| `icon` | `string` | No | Icon identifier |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `EvalModelFlagValue`

Denormalized per-(model, type) selection. Clients send these to update
model-flag selections without needing the underlying flag_id; the server
resolves (type, value) -> flag_id and upserts the model_flags_resource
junction row.

| Field | Type | Required | Description |
|---|---|---|---|
| `model_id` | `string` | Yes | Target model identifier |
| `type` | `string` | Yes | Flag type, e.g. 'model_active' |
| `value` | `boolean` | Yes | Desired flag value |

---

## `EvalModelPositionResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Model-position resource identifier |
| `model_id` | `string` | No | Associated model identifier |
| `value` | `integer` \| `number` | No | Associated position value |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `EvalModelResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Model resource identifier |
| `name` | `string` | No | Display name |
| `description` | `string` | No | Description text |
| `modality_ids` | `string`[] | No | Associated modality identifiers |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `EvalModelRubricResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Model-rubric resource identifier |
| `model_id` | `string` | No | Associated model identifier |
| `rubric_id` | `string` | No | Associated rubric identifier |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `EvalNameResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `name` | `string` | No | Display name |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `EvalResultItem`

Per-item result within a bulk create/update response.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `eval_id` | `string` | No | Eval UUID |
| `message` | `string` | Yes | Human-readable result message |
| `errors` | [`EvalFieldError`](#evalfielderror)[] | No | List of per-field errors |

---

## `EvalRubricResource`

Top-level rubric catalog entry. The ModelRubrics picker renders
one of these per option (alongside a "no rubric" clear state).

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Rubric resource UUID |
| `name` | `string` | No | Rubric display name |
| `description` | `string` | No | Rubric description |

---

## `EvalSetup`

Run-level eval scaffold — first-class on the generate response.

Audit's ``**output`` spread carries this onto
``<artifact>.generate.completed``. Null when no rubric-bearing
agent participated.

| Field | Type | Required | Description |
|---|---|---|---|
| `test_id` | `string` | Yes | — |
| `invocations` | [`InvocationSlot`](#invocationslot)[] | Yes | — |

---

## `GenerateConfig`

Developer configuration — all optional with sensible defaults.

| Field | Type | Required | Description |
|---|---|---|---|
| `operations` | `string`[] | No | — |
| `dangerous` | `boolean` | No | — |
| `params` | `object` | No | — |
| `group_id` | `string` | No | — |

---

## `GenerationsEvalListItem`

Single generation group in the eval generations response.

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | UUID of the generation group |
| `session_id` | `string` | No | UUID of the parent session |
| `group_name` | `string` | No | Name of the generation group |
| `created_at` | `string` | No | Timestamp of the generation |

---

## `GetEvalDraftResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | UUID of the draft |
| `created_at` | `string` | Yes | Creation timestamp |
| `generated` | `boolean` | Yes | Whether this was AI-generated |
| `mcp` | `boolean` | Yes | Whether MCP tooling was used |
| `active` | `boolean` | Yes | Whether this draft is active |
| `session_id` | `string` | Yes | Associated session UUID |
| `name` | `string` | No | Immutable draft label set at create time |
| `department_ids` | `string`[] | Yes | Associated department UUIDs |
| `description_ids` | `string`[] | Yes | Associated description UUIDs |
| `flag_ids` | `string`[] | Yes | Associated flag UUIDs |
| `model_ids` | `string`[] | Yes | Associated model UUIDs |
| `name_ids` | `string`[] | Yes | Associated name UUIDs |
| `profile_ids` | `string`[] | Yes | Associated profile UUIDs |
| `rubric_ids` | `string`[] | Yes | Associated rubric UUIDs |
| `model_flag_ids` | `string`[] | No | Associated model flag UUIDs |
| `model_position_ids` | `string`[] | No | Associated model position UUIDs |
| `model_rubric_ids` | `string`[] | No | Associated model rubric UUIDs |
| `pending_department_ids` | `string`[] | No | Associated department UUIDs stored as inactive pending links |
| `pending_description_ids` | `string`[] | No | Associated description UUIDs stored as inactive pending links |
| `pending_flag_ids` | `string`[] | No | Associated flag UUIDs stored as inactive pending links |
| `pending_model_ids` | `string`[] | No | Associated model UUIDs stored as inactive pending links |
| `pending_name_ids` | `string`[] | No | Associated name UUIDs stored as inactive pending links |
| `pending_rubric_ids` | `string`[] | No | Associated rubric UUIDs stored as inactive pending links |
| `pending_model_flag_ids` | `string`[] | No | Pending model flag UUIDs |
| `pending_model_position_ids` | `string`[] | No | Pending model position UUIDs |
| `pending_model_rubric_ids` | `string`[] | No | Pending model rubric UUIDs |

---

## `GroupCall`

Tool call referenced by a message.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `tool_name` | `string` | No | — |
| `template_name` | `string` | No | — |
| `tool` | `object` | No | — |
| `ledger_status` | `string` | No | — |
| `ledger_operation` | `string` | No | — |
| `ledger_artifact` | `string` | No | — |
| `ledger_artifact_id` | `string` | No | — |

---

## `GroupMessage`

Message within a run.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `role` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `text_ids` | `string`[] | No | — |
| `audio_ids` | `string`[] | No | — |
| `image_ids` | `string`[] | No | — |
| `video_ids` | `string`[] | No | — |
| `file_ids` | `string`[] | No | — |
| `call_ids` | `string`[] | No | — |
| `calls` | [`GroupCall`](#groupcall)[] | No | — |
| `reasoning` | `boolean` | No | True when this row is a chain-of-thought trace persisted alongside the assistant answer (rendered as a collapsed accordion). |
| `in_context` | `boolean` | No | Whether this message is included in the LLM context for the next generation. Mirrors the dedup pass that builds chat history (see in_context_reason). |
| `in_context_reason` | `string` | No | Why this message is in/out of LLM context. 'kept' = included; 'deduped_read' = older read-only call to a tool that has a fresher result later in the group; future values may include 'trimmed_top_n'. |

---

## `GroupResource`

Lightweight `\{id, name\}` for cross-referencing run-level ids
(``model_id`` / ``agent_id`` / ``profile_id``) against human-readable
names on the analytics panel. Names come from the canonical
``get_models`` / ``get_agents`` / ``get_profiles`` black boxes.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `name` | `string` | No | — |

---

## `GroupRun`

Run within a group, with its messages.

Carries token / cost / model / agent / profile attribution so the
analytics view can render per-run cost + actor info without a
parallel detail shape. ``profile_id`` is the authoring profile
(human user), ``agent_id`` is the LLM-side actor, ``model_id`` is
the model used by that agent. All optional — runs predating these
columns or with unresolved attributions surface ``None``.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `input_tokens` | `integer` | No | — |
| `output_tokens` | `integer` | No | — |
| `cached_input_tokens` | `integer` | No | — |
| `cost` | `number` | No | — |
| `model_id` | `string` | No | — |
| `agent_id` | `string` | No | — |
| `profile_id` | `string` | No | — |
| `previous_context_start_index` | `integer` | No | Index in ``messages`` where the current run's own messages begin; earlier rows are previous-context replay. ``None`` when the run has no previous context attached. |
| `messages` | [`GroupMessage`](#groupmessage)[] | No | — |

---

## `ImportField`

Field descriptor for CSV import column mapping.

| Field | Type | Required | Description |
|---|---|---|---|
| `key` | `string` | Yes | — |
| `label` | `string` | Yes | — |
| `required` | `boolean` | No | — |
| `multi` | `boolean` | No | — |
| `type` | `string` | No | — |
| `example` | `string` | No | — |
| `description` | `string` | No | — |

---

## `InvocationSlot`

One agent's slot in a multi-agent generation pool.

Populated by ``setup_generation_test`` when an agent carries a
rubric. The client uses these IDs to drive the eval workflow:
review the candidate's output, optionally fire a grader against
its ``invocation_id``, and promote/reject by call_id via the
existing ``idempotency_key + accept`` pattern.

| Field | Type | Required | Description |
|---|---|---|---|
| `invocation_id` | `string` | Yes | — |
| `agent_id` | `string` | Yes | — |
| `rubric_id` | `string` | No | — |

---

## `ListEvalApiEval`

Eval type for list endpoint with computed permissions.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Eval artifact UUID (canonical id; mirrors eval_id) |
| `eval_id` | `string` | No | Eval UUID |
| `name` | `string` | No | Eval name |
| `description` | `string` | No | Eval description |
| `department_ids` | `string`[] | No | Associated department IDs |
| `model_ids` | `string`[] | No | Model resource UUIDs assigned to this eval |
| `rubric_ids` | `string`[] | No | Rubric artifact UUIDs assigned to this eval (via model_rubrics_resource) |
| `is_inactive` | `boolean` | No | Whether the eval is inactive |
| `is_dynamic` | `boolean` | No | Whether the eval uses dynamic mode |
| `use_groups` | `boolean` | No | Whether the eval uses groups |
| `pending_status` | `string` | No | Latest soft_calls_mv status: 'pending' / 'accepted' / 'rejected' |
| `pending_operation` | `string` | No | Operation type ('create'|'update'|'delete'|'duplicate') of the pending op |
| `pending_call_id` | `string` | No | call_id (idempotency key for ack) of the pending op |
| `num_runs` | `integer` | No | Number of eval runs |
| `num_groups` | `integer` | No | Number of eval groups |
| `can_edit` | `boolean` | No | Whether the current user can edit |
| `can_duplicate` | `boolean` | No | Whether the current user can duplicate |
| `can_delete` | `boolean` | No | Whether the current user can delete |
| `updated_at` | `string` | No | Last updated timestamp |

---

## `ListFilterOption`

Standardized option for list endpoint filter sections.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier for this filter option |
| `name` | `string` | No | Display name |
| `count` | `integer` | No | Number of matching records |
| `hex_code` | `string` | No | Hex color code for display |
| `value` | `string` | No | Internal value |
| `type` | `string` | No | Option type discriminator |

---

## `ListFilterSection`

Filter section with options and echoed request state.

| Field | Type | Required | Description |
|---|---|---|---|
| `options` | [`ListFilterOption`](#listfilteroption)[] | No | Available filter options |
| `selected_ids` | `string`[] | No | Currently selected filter option IDs |
| `search` | `string` | No | Active search text for filtering |

---

## `MvInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Materialized view name |
| `definition` | `string` | Yes | SQL definition of the view |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the view |

---

## `OperationInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Operation name |
| `description` | `string` | Yes | Human-readable description of the operation |
| `params` | [`ParamInfo`](#paraminfo)[] | Yes | List of operation parameters |
| `returns` | `object` | No | Return type schema |

---

## `OperationPrompts`

Starter prompts keyed by operation name.

Each key is an operation (e.g. "create", "search", "draft", "export")
and the value is a list of starter prompts for that operation.
The client picks from the operations the caller has permission for
and rotates through them.

| Field | Type | Required | Description |
|---|---|---|---|
| `prompts` | `object` | No | Map of operation name to starter prompts |

---

## `PageMetaItem`

| Field | Type | Required | Description |
|---|---|---|---|
| `title` | `string` | Yes | — |
| `description` | `string` | Yes | — |

---

## `ParamInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Parameter name |
| `type` | `string` | Yes | Parameter data type |
| `required` | `boolean` | Yes | Whether the parameter is required |
| `default` | `any` | No | Default value if not required |

---

## `ProducedMedia`

One asset produced by a generation run.

``resource_id`` is the canonical id the per-artifact download tools
accept (e.g. ``Scenario_Image_Download(image_id=resource_id)`` for
``modality="image"``). It maps to ``images_resource.id`` /
``videos_resource.id`` / ``audios_resource.id`` depending on the
modality.

| Field | Type | Required | Description |
|---|---|---|---|
| `modality` | `"image"` \| `"video"` \| `"audio"` | Yes | — |
| `resource_id` | `string` | Yes | — |
| `upload_id` | `string` | Yes | — |
| `mime_type` | `string` | No | — |
| `file_size` | `integer` | No | — |

---

## `ProfileSummary`

Caller identity derived from JWT — who you are on this page.

Superset of the old six-field version: now carries everything the client
needs so that ``/\{artifact\}/context`` fully replaces ``/profiles/context``
and the extra ``getLayoutContextData`` round-trip can be dropped.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Display name of the authenticated user |
| `role` | `string` | Yes | Role name (e.g. 'Super Administrator') |
| `role_level` | `integer` | Yes | Role hierarchy level (0 = highest privilege) |
| `department_ids` | `string`[] | Yes | Departments the user belongs to |
| `artifact_access` | `string`[] | Yes | Artifact types this role can access (sidebar visibility) |
| `role_permissions` | `any`[][] | Yes | Full (artifact, operation) permission tuples for granular page gating |
| `is_active` | `boolean` | Yes | Whether the user's profile is active |
| `id` | `string` | Yes | Profile UUID (SocketProvider, ProfileProvider) |
| `theme` | [`ThemeBundle`](#themebundle) | No | Resolved theme: hex primitives + derived oklch tokens + score thresholds |
| `session_id` | `string` | No | Current session UUID |
| `is_emulation` | `boolean` | No | Whether user is in emulation mode (ProfileProvider) |
| `role_resources` | [`QGetProfileContextV4RoleResource`](#qgetprofilecontextv4roleresource)[] | No | All role resources for emulation display (ProfileProvider) |
| `scoped_roles` | `string`[] | No | Roles the user can emulate (ProfileProvider) |
| `active` | `boolean` | No | Alias for is_active (ProfileProvider uses this name) |

---

## `QGetProfileContextV4RoleResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `role` | `string` | No | — |
| `name` | `string` | No | — |
| `description` | `string` | No | — |
| `icon_value` | `string` | No | — |
| `color_hex` | `string` | No | — |

---

## `RunStatus`

Outcome of one watched run.

| Field | Type | Required | Description |
|---|---|---|---|
| `run_id` | `string` | Yes | — |
| `status` | `"pending"` \| `"completed"` \| `"failed"` | Yes | — |
| `modality` | `string` | No | Modality of generated output (image, video, text…) |
| `resource_ids` | `string`[] | No | Resource UUIDs produced by this run (e.g. images_resource ids) |
| `error` | `string` | No | — |

---

## `TableInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Table name |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the table |

---

## `ThemeBundle`

Full theme payload for a page bootstrap.

Riding along on every ``/\{artifact\}/context`` response via
``ProfileSummary.theme``. Layers:
  - ``primitives`` / ``dark_primitives`` — hex inputs the settings
    editor reads/writes (light + dark palettes).
  - ``tokens`` / ``dark_tokens`` — oklch tokens the client paints with.
    ``ThemeStyle`` emits two ``<style>`` blocks: one scoped to
    ``:root:not(.dark)`` (light) and one to ``:root.dark`` (dark).
  - ``thresholds`` — numeric score thresholds for analytics components.
Empty-in → empty-out per token: missing values fall through to the
matching ``globals.css`` default.

| Field | Type | Required | Description |
|---|---|---|---|
| `primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (light palette, for the theme editor) |
| `tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for light mode (SSR CSS-var injection) |
| `dark_primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (dark palette, for the theme editor) |
| `dark_tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for dark mode (SSR CSS-var injection) |
| `thresholds` | [`Thresholds`](#thresholds) | No | Score thresholds resolved from the setting |

---

## `ThemePrimitives`

40 optional fields. The 17 essentials drive the rest; the other 23
are overrides for fine-tuning when derivation isn't what you want.

Empty primitive → empty token → client falls back to globals.css.

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `primary` | `string` | No | — |
| `accent` | `string` | No | — |
| `card` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `ring` | `string` | No | — |
| `border` | `string` | No | — |
| `destructive` | `string` | No | — |
| `success` | `string` | No | — |
| `warning` | `string` | No | — |
| `info` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `input` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `ThemeTokens`

40 fully-resolved CSS variable values (snake_case 1:1 with vars).

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `accent` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `border` | `string` | No | — |
| `input` | `string` | No | — |
| `ring` | `string` | No | — |
| `success` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `Thresholds`

Numeric score thresholds resolved from the active setting.

Server pre-buckets dashboard metrics into ``success | warning | danger |
neutral`` already, so most components don't need these values. Surface
them for chart reference lines, tooltips, and any client-side bucketing.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `integer` | Yes | Score >= this counts as success |
| `warning` | `integer` | Yes | Score >= this counts as warning |
| `danger` | `integer` | Yes | Score < success threshold but >= this counts as danger; below is neutral/no-data |

---

## `UpdateEvalItem`

Single eval item for update — eval_id required, all fields optional.

Only provided fields are updated (partial update).

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | Eval UUID to update |
| `name_id` | `string` | No | Name resource UUID |
| `name` | `string` | No | Name value for resolution |
| `description_id` | `string` | No | Description resource UUID |
| `description` | `string` | No | Description value for resolution |
| `flag_ids` | `string`[] | No | Flag option UUIDs |
| `department_ids` | `string`[] | No | Department UUIDs |
| `departments` | `string`[] | No | Department names for resolution |
| `model_ids` | `string`[] | No | Model UUIDs |
| `model_flag_ids` | `string`[] | No | Model flag UUIDs |
| `model_rubric_ids` | `string`[] | No | Model rubric UUIDs |
| `model_position_ids` | `string`[] | No | Model position UUIDs |
| `active` | `boolean` | No | Denormalized eval_active flag state; resolved to a flag_ids entry server-side |

---

## `UpdateEvalPatch`

Shared patch for bulk-update-all-matching mode.

Inherits every field from ``UpdateEvalItem`` and just relaxes
``id`` to optional — the bulk impl stamps the resolved id onto a
clone of the patch per matched row, so any client-supplied id is
ignored. Sparse semantics: only fields the client sets are written.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Ignored — bulk impl stamps the resolved eval id per matched row |
| `name_id` | `string` | No | Name resource UUID |
| `name` | `string` | No | Name value for resolution |
| `description_id` | `string` | No | Description resource UUID |
| `description` | `string` | No | Description value for resolution |
| `flag_ids` | `string`[] | No | Flag option UUIDs |
| `department_ids` | `string`[] | No | Department UUIDs |
| `departments` | `string`[] | No | Department names for resolution |
| `model_ids` | `string`[] | No | Model UUIDs |
| `model_flag_ids` | `string`[] | No | Model flag UUIDs |
| `model_rubric_ids` | `string`[] | No | Model rubric UUIDs |
| `model_position_ids` | `string`[] | No | Model position UUIDs |
| `active` | `boolean` | No | Denormalized eval_active flag state; resolved to a flag_ids entry server-side |

---

## `app__infra__eval__types__DraftFormState`

Server-authoritative form state returned after draft save.

| Field | Type | Required | Description |
|---|---|---|---|
| `name_id` | `string` | No | Selected name resource UUID |
| `name` | `string` | No | Echoed selected name value |
| `description_id` | `string` | No | Selected description resource UUID |
| `description` | `string` | No | Echoed selected description value |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs |
| `active` | `boolean` | No | Echoed eval_active flag state |
| `department_ids` | `string`[] | No | Selected department UUIDs |
| `model_ids` | `string`[] | No | Selected model UUIDs |
| `model_flag_ids` | `string`[] | No | Selected model flag UUIDs |
| `model_flag_values` | [`EvalModelFlagValue`](#evalmodelflagvalue)[] | No | Denormalized (model_id, type, value) echo derived from model_flag_ids |
| `model_position_ids` | `string`[] | No | Selected model position UUIDs |
| `model_rubric_ids` | `string`[] | No | Selected model rubric UUIDs |
| `pending_ids` | `string`[] | No | Pending resource identifiers |

---

## `app__infra__eval__types__SectionFilter`

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Filter options by search text |
| `limit` | `integer` | No | Max options to return |
| `selected` | `boolean` | No | Only return selected items |
| `suggested` | `boolean` | No | Only return suggested items |
| `include` | `boolean` | No | Include this section in response (default true) |
| `parameter_ids` | `string`[] | No | Reserved for compatibility with shared filter parsing |

---

---

# `GET` `/field/watch`

Route: /api-reference/field/get-field-watch

# `GET` `/field/watch`

Field Watch

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `group_id` | query | No | — |
| `run_id` | query | No | Optional run filter. If provided, only events whose envelope run_id matches are streamed. Omit to receive every field event in the group (the FE default). |

## Response

```
{}
```

---

# `POST` `/field/call_download`

Route: /api-reference/field/post-field-call-download

# `POST` `/field/call_download`

Download Call

Download a call file by call resource ID.

## Request Body (`CallDownloadFieldApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `call_id` | `string` | Yes | UUID of the calls_resource to download |

## Response

```
{}
```

---

# `POST` `/field/context`

Route: /api-reference/field/post-field-context

# `POST` `/field/context`

Get Field Context

Get page context for the field artifact.

Returns docs + profile identity + evaluated permissions in a single call.
Superset of /docs — clients can migrate from /docs to /context incrementally.

## Request Body (`DocsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entity_id` | `string` | No | — |
| `snapshot_key` | `string` | No | — |
| `schema` | `boolean` | No | If true, include MCP/tooling schema metadata (artifact, entries, resources, permission_docs, api_operations). Defaults to false for lean page-bootstrap responses. |

## Response (`ComposedContextResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Artifact name |
| `type` | `string` | Yes | Artifact type identifier |
| `description` | `string` | Yes | Human-readable description |
| `artifact` | [`DocsResponse`](/api-reference/field/types#docsresponse) | No | Artifact tool documentation (None unless schema=true) |
| `entries` | [`DocsResponse`](/api-reference/field/types#docsresponse)[] | No | Entry documentation list (None unless schema=true) |
| `resources` | [`DocsResponse`](/api-reference/field/types#docsresponse)[] | No | Resource documentation list (None unless schema=true) |
| `permission_docs` | [`OperationInfo`](/api-reference/field/types#operationinfo)[] | No | Permission function signatures for MCP/dev tooling (None unless schema=true) |
| `api_operations` | [`OperationInfo`](/api-reference/field/types#operationinfo)[] | No | API operation documentation (None unless schema=true) |
| `page_metadata` | [`DocsApiResponse`](/api-reference/field/types#docsapiresponse) | No | Page-level metadata |
| `prompts` | [`OperationPrompts`](/api-reference/field/types#operationprompts) | No | Starter prompts keyed by operation |
| `profile` | [`ProfileSummary`](/api-reference/field/types#profilesummary) | Yes | Caller identity from JWT |
| `caller_permissions` | [`CallerPermissions`](/api-reference/field/types#callerpermissions) | Yes | Evaluated permissions for this caller |

---

# `POST` `/field/create`

Route: /api-reference/field/post-field-create

# `POST` `/field/create`

Create Field

Create fields using composable infra architecture.

## Request Body (`CreateFieldApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `fields` | [`CreateFieldItem`](/api-reference/field/types#createfielditem)[] | Yes | List of fields to create |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant create |
| `soft` | `boolean` | No | Stage the create dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`CreateFieldApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`FieldResultItem`](/api-reference/field/types#fieldresultitem)[] | Yes | Per-item creation results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/field/csv`

Route: /api-reference/field/post-field-csv

# `POST` `/field/csv`

Parse Field Csv

Parse a CSV file and return mapped items for preview.

## Request Body

| Field | Type | Required | Description |
|---|---|---|---|
| `file` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `soft` | `boolean` | No | — |
| `accept` | `boolean` | No | — |

## Response (`ParseFieldCsvApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `upload_id` | `string` | Yes | — |
| `items` | [`CreateFieldItem`](/api-reference/field/types#createfielditem)[] | Yes | — |
| `mapped_fields` | `string`[] | Yes | — |
| `row_count` | `integer` | Yes | — |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with `accept` to promote/reject the staged raw-CSV upload. NOTE: ack returns no items (the preview is only on the propose). |

---

# `POST` `/field/delete`

Route: /api-reference/field/post-field-delete

# `POST` `/field/delete`

Delete Field

Bulk delete fields — composable infra architecture.

## Request Body (`DeleteFieldApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `field_ids` | `string`[] | No | UUIDs of fields to delete (required on first call when ``all`` is false) |
| `all` | `boolean` | No | When true, delete every field matching the filter fields below (minus ``excluded_ids``) |
| `excluded_ids` | `string`[] | No | UUIDs to skip even when matched by ``all``-mode filters |
| `search` | `string` | No | Full-text search query |
| `parameter_ids` | `string`[] | No | Filter by parameter UUIDs |
| `persona_ids` | `string`[] | No | Filter by persona UUIDs |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `parameter_search` | `string` | No | Search text for parameter facet (no-op for row filtering) |
| `persona_search` | `string` | No | Search text for persona facet (no-op for row filtering) |
| `department_search` | `string` | No | Search text for department facet (no-op for row filtering) |
| `flag_search` | `string` | No | Search text for flag facet (no-op for row filtering) |
| `idempotency_key` | `string` | No | Operation key for ack — confirms or rejects a dormant delete |
| `soft` | `boolean` | No | Stage the delete dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (confirm deletion) or reject (restore). Only meaningful with idempotency_key |

## Response (`DeleteFieldApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`DeleteFieldResult`](/api-reference/field/types#deletefieldresult)[] | Yes | Per-item deletion results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/field/draft`

Route: /api-reference/field/post-field-draft

# `POST` `/field/draft`

Patch Field Draft

Patch field draft — composable infra architecture.

## Request Body (`PatchFieldDraftApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `draft_id` | `string` | No | Existing draft UUID to update |
| `input_draft_id` | `string` | No | Existing draft UUID to update |
| `name` | `string` | No | Name value to resolve or create |
| `name_id` | `string` | No | UUID of the name resource |
| `description` | `string` | No | Description value to resolve or create |
| `description_id` | `string` | No | UUID of the description resource |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `active` | `boolean` | No | Denormalized field_active flag state; resolved to a flag_ids entry server-side |
| `department_ids` | `string`[] | No | Department UUIDs to assign |
| `departments` | `string`[] | No | Department names to resolve |
| `conditional_parameter_ids` | `string`[] | No | Conditional parameter UUIDs |
| `conditional_parameters` | `string`[] | No | Conditional parameter names to resolve |
| `pending_ids` | `string`[] | No | Resource IDs to keep pending where supported |
| `idempotency_key` | `string` | No | Operation key for ack or retry |
| `soft` | `boolean` | No | Stage the draft dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept or reject dormant state |

## Response (`PatchFieldDraftApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the draft save succeeded |
| `draft_id` | `string` | Yes | UUID of the saved draft |
| `idempotency_key` | `string` | Yes | Idempotency key for this draft operation |
| `message` | `string` | Yes | Result message |
| `form_state` | [`app__infra__field__types__DraftFormState`](/api-reference/field/types#app-infra-field-types-draftformstate) | No | Server-authoritative form state |

---

# `POST` `/field/drafts`

Route: /api-reference/field/post-field-drafts

# `POST` `/field/drafts`

Get Field Drafts

List field drafts owned by the current profile.

## Request Body (`GetFieldDraftsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE substring) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GetFieldDraftsApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entries` | [`GetFieldDraftResponse`](/api-reference/field/types#getfielddraftresponse)[] | No | List of field draft entries |

---

# `POST` `/field/duplicate`

Route: /api-reference/field/post-field-duplicate

# `POST` `/field/duplicate`

Duplicate Field

Duplicate a field — composable infra architecture.

## Request Body (`DuplicateFieldApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `field_id` | `string` | Yes | UUID of the field to duplicate |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant duplicate |
| `soft` | `boolean` | No | Stage the duplicate dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`DuplicateFieldApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the duplication succeeded |
| `field_id` | `string` | Yes | UUID of the newly created field |
| `message` | `string` | Yes | Result message |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/field/export`

Route: /api-reference/field/post-field-export

# `POST` `/field/export`

Export Fields

Export all fields as a clean, denormalized CSV.

## Request Body (`ExportFieldApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `field_id` | `string` | No | UUID of the field to export |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior export instead of re-running |
| `soft` | `boolean` | No | Stage the export dormant (active=False); ack with accept activates it |
| `accept` | `boolean` | No | Ack: True promotes the staged export, False rejects. Only meaningful with idempotency_key |

## Response (`ExportFieldApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource holding the export CSV |
| `file_name` | `string` | Yes | Suggested download file name |
| `row_count` | `integer` | Yes | Number of data rows in the export |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with `accept` to promote/reject the staged export. |

---

# `POST` `/field/file_download`

Route: /api-reference/field/post-field-file-download

# `POST` `/field/file_download`

Download File

Download a file by file resource ID.

## Request Body (`FileDownloadFieldApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource to download |

## Response

```
{}
```

---

# `POST` `/field/generate`

Route: /api-reference/field/post-field-generate

# `POST` `/field/generate`

Generate Field

Trigger field generation. Returns immediately; progress via events.

## Request Body (`ArtifactGenerateRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `instructions` | `string`[] | No | — |
| `config` | [`GenerateConfig`](/api-reference/field/types#generateconfig) | No | — |
| `modalities` | `string`[] | No | — |
| `audios_id` | `string` | No | — |
| `conversation_id` | `string` | No | — |
| `trace_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `accept` | `boolean` | No | — |
| `wait_for_complete` | `boolean` | No | — |

## Response (`ArtifactGenerateResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `run_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `eval` | [`EvalSetup`](/api-reference/field/types#evalsetup) | No | — |
| `produced_media` | [`ProducedMedia`](/api-reference/field/types#producedmedia)[] | No | — |

---

# `POST` `/field/generations`

Route: /api-reference/field/post-field-generations

# `POST` `/field/generations`

Generations Field

List field generation groups — composable infra architecture.

## Request Body (`GenerationsFieldApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GenerationsFieldApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `items` | [`GenerationsFieldListItem`](/api-reference/field/types#generationsfieldlistitem)[] | No | Generation groups |
| `total_count` | `integer` | No | Total number of matching generations |

---

# `POST` `/field/get`

Route: /api-reference/field/post-field-get

# `POST` `/field/get`

Get Field

Get field information using the canonical shared field operation.

## Request Body (`GetFieldApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Field UUID to retrieve |
| `field_id` | `string` | No | UUID of the field to retrieve |
| `draft_id` | `string` | No | UUID of the draft to load |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |
| `names` | [`app__infra__field__types__SectionFilter`](/api-reference/field/types#app-infra-field-types-sectionfilter) | No | Filter options for names section |
| `descriptions` | [`app__infra__field__types__SectionFilter`](/api-reference/field/types#app-infra-field-types-sectionfilter) | No | Filter options for descriptions section |
| `flags` | [`app__infra__field__types__SectionFilter`](/api-reference/field/types#app-infra-field-types-sectionfilter) | No | Filter options for flags section |
| `departments` | [`app__infra__field__types__SectionFilter`](/api-reference/field/types#app-infra-field-types-sectionfilter) | No | Filter options for departments section |
| `conditional_parameters` | [`app__infra__field__types__SectionFilter`](/api-reference/field/types#app-infra-field-types-sectionfilter) | No | Filter options for conditional parameters section |
| `descriptions_search` | `string` | No | Search query for description resources |
| `conditional_parameter_search` | `string` | No | Search query for conditional parameters |
| `conditional_parameter_show_selected` | `boolean` | No | Whether to show only selected parameters |

## Response (`GetFieldApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the acting user |
| `field_exists` | `boolean` | No | Whether the field exists |
| `can_edit` | `boolean` | No | Whether the actor can edit this field |
| `disabled_reason` | `string` | No | Reason editing is disabled, if any |
| `group_id` | `string` | No | Group UUID for draft collaboration |
| `draft_name` | `string` | No | Immutable draft label from the active draft entry, when a ``draft_id`` was supplied. ``None`` for non-draft fetches. |
| `show_ai_generate` | `boolean` | No | Whether to show AI generate button anywhere |
| `basic_show_ai_generate` | `boolean` | No | Whether to show AI generate button |
| `pending_ids` | `string`[] | No | Pending resource identifiers when available |
| `names` | [`FieldNameResource`](/api-reference/field/types#fieldnameresource)[] | No | Name resources |
| `descriptions` | [`FieldDescriptionResource`](/api-reference/field/types#fielddescriptionresource)[] | No | Description resources |
| `flags` | [`FieldFlagResource`](/api-reference/field/types#fieldflagresource)[] | No | Flag resources (one per flags_resource row, value=true/false) |
| `departments` | [`FieldDepartmentResource`](/api-reference/field/types#fielddepartmentresource)[] | No | Department resources |
| `conditional_parameters` | [`FieldConditionalParameterResource`](/api-reference/field/types#fieldconditionalparameterresource)[] | No | Conditional parameter resources |

---

# `POST` `/field/group`

Route: /api-reference/field/post-field-group

# `POST` `/field/group`

Group Field

Resolve or create a field group with optional naming.

## Request Body (`GroupFieldApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | No | Existing group UUID (omit to create or reuse via time window) |
| `snapshot_key` | `string` | No | Snapshot key for SETNX-race convergence on a single group across concurrent reads (e.g. parallel /context + /group + /search fan-out on page load). Echoed back in the response. |

## Response (`GroupFieldApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Resolved or newly created group UUID |
| `name` | `string` | No | The group's current title (latest active group_names_entry, or 'New Chat' fallback for freshly minted groups) |
| `snapshot_key` | `string` | No | Snapshot key echoed back — the UUID concurrent fan-out reads converged on via SETNX. Mirrors the resolved group_id. |
| `runs` | [`GroupRun`](/api-reference/field/types#grouprun)[] | No | Conversation history — populated when resolving an existing group for fetch |
| `group_exists` | `boolean` | No | (detail) Whether the group exists in storage — populated when ``include_resources=True`` |
| `actor_name` | `string` | No | (detail) Display name of the current actor (caller profile) |
| `total_message_count` | `integer` | No | (detail) Total number of messages in the group |
| `models` | [`GroupResource`](/api-reference/field/types#groupresource)[] | No | (detail) Models used in the group |
| `agents` | [`GroupResource`](/api-reference/field/types#groupresource)[] | No | (detail) Agents used in the group |
| `profiles` | [`GroupResource`](/api-reference/field/types#groupresource)[] | No | (detail) Profiles that authored runs in this group |

---

# `POST` `/field/problem`

Route: /api-reference/field/post-field-problem

# `POST` `/field/problem`

Problem Field

Report a field problem — composable infra architecture.

## Request Body (`ProblemFieldApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | `string` | Yes | Problem type: feature, bug, question, other |
| `message` | `string` | Yes | Problem description (max 1000 chars) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant problem |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`ProblemFieldApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `problem_id` | `string` | Yes | UUID of the created problem |
| `success` | `boolean` | No | Whether the problem was created |
| `message` | `string` | No | Status message |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/field/refresh`

Route: /api-reference/field/post-field-refresh

# `POST` `/field/refresh`

Field Refresh

Refresh field materialized views and invalidate caches.

## Request Body (`RefreshFieldApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `targets` | `string`[] | No | MV targets to refresh (omit for all). Options: field_drafts_mv |
| `idempotency_key` | `string` | No | Operation key for ack |
| `accept` | `boolean` | No | Accept or reject. Only meaningful with idempotency_key |
| `soft` | `boolean` | No | Stage the refresh as a pending (held) request — recorded but not enqueued; ack with accept releases/enqueues it |

## Response (`RefreshResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | — |
| `refreshed_views` | `string`[] | Yes | — |
| `invalidated_tags` | `string`[] | Yes | — |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/field/search`

Route: /api-reference/field/post-field-search

# `POST` `/field/search`

Search Field

Search fields — composable infra architecture.

## Request Body (`SearchFieldApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | — |
| `parameter_ids` | `string`[] | No | — |
| `persona_ids` | `string`[] | No | — |
| `filter_department_ids` | `string`[] | No | — |
| `parameter_search` | `string` | No | — |
| `persona_search` | `string` | No | — |
| `department_search` | `string` | No | — |
| `page_size` | `integer` | No | — |
| `page_offset` | `integer` | No | — |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`ListFieldApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the acting user |
| `fields` | [`ListFieldApiField`](/api-reference/field/types#listfieldapifield)[] | No | List of field items |
| `parameter_filter` | [`ListFilterSection`](/api-reference/field/types#listfiltersection) | No | Filter options for parameters |
| `persona_filter` | [`ListFilterSection`](/api-reference/field/types#listfiltersection) | No | Filter options for personas |
| `department_filter` | [`ListFilterSection`](/api-reference/field/types#listfiltersection) | No | Filter options for departments |
| `flag_filter` | [`ListFilterSection`](/api-reference/field/types#listfiltersection) | No | Filter options for flags in list UI |
| `total_count` | `integer` | No | Total number of fields |
| `import_fields` | [`ImportField`](/api-reference/field/types#importfield)[] | No | CSV import column schema for the bulk-import dialog |

---

# `POST` `/field/text_download`

Route: /api-reference/field/post-field-text-download

# `POST` `/field/text_download`

Download Text

Download a text file by text resource ID.

## Request Body (`TextDownloadFieldApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `text_id` | `string` | Yes | UUID of the texts_resource to download |

## Response

```
{}
```

---

# `POST` `/field/title`

Route: /api-reference/field/post-field-title

# `POST` `/field/title`

Title Field

Rename a field's group (writes group_names_entry).

## Request Body (`TitleFieldApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Group to rename |
| `title` | `string` | Yes | New title (display name) for the group |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant rename |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`TitleFieldApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | The group that was renamed |
| `group_name_id` | `string` | Yes | UUID of the new group_names_entry row |
| `title` | `string` | Yes | The title that was set |
| `idempotency_key` | `string` | No | Operation key echoed back |

---

# `POST` `/field/update`

Route: /api-reference/field/post-field-update

# `POST` `/field/update`

Update Field

Update fields using composable infra architecture.

## Request Body (`UpdateFieldApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `fields` | [`UpdateFieldItem`](/api-reference/field/types#updatefielditem)[] | No | List of fields to update (required on first call when ``all`` is false) |
| `all` | `boolean` | No | When true, apply ``patch`` to every field matching the filter fields below (minus ``excluded_ids``) |
| `excluded_ids` | `string`[] | No | UUIDs to skip even when matched by ``all``-mode filters |
| `patch` | [`UpdateFieldPatch`](/api-reference/field/types#updatefieldpatch) | No | Shared change set applied to every matched row when ``all=true`` (sparse — only set fields are updated; ``patch.id`` ignored) |
| `search` | `string` | No | Full-text search query |
| `parameter_ids` | `string`[] | No | Filter by parameter UUIDs |
| `persona_ids` | `string`[] | No | Filter by persona UUIDs |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `parameter_search` | `string` | No | Search text for parameter facet (no-op for row filtering) |
| `persona_search` | `string` | No | Search text for persona facet (no-op for row filtering) |
| `department_search` | `string` | No | Search text for department facet (no-op for row filtering) |
| `flag_search` | `string` | No | Search text for flag facet (no-op for row filtering) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant update |
| `soft` | `boolean` | No | Stage the update dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`UpdateFieldApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`FieldResultItem`](/api-reference/field/types#fieldresultitem)[] | Yes | Per-item update results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/field/watch`

Route: /api-reference/field/post-field-watch

# `POST` `/field/watch`

Field Watch Once

One-shot snapshot of run state, snapshot-replayable via ``snapshot_key``.

## Request Body (`WatchApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Chat group whose events we watch |
| `run_id` | `string` | No | Specific run to watch (e.g. the ``run_id`` returned by a prior ``X_Generate`` call). If None, watches every active run in the group at call time. |
| `wait_for_complete` | `boolean` | No | If True, block until the watched run reaches a terminal (complete/failed) event or timeout fires. If False, return current state and exit immediately. |
| `timeout_seconds` | `integer` | No | Max wait time when ``wait_for_complete=True``. |
| `snapshot_key` | `string` | No | Read snapshot key — on the one-shot POST /watch, the audit wrapper records this watch's point-in-time view (latest run state at call time) keyed by it and replays the same view on any later call with the same key. Ignored by the SSE GET stream. |

## Response (`WatchApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `runs` | [`RunStatus`](/api-reference/field/types#runstatus)[] | Yes | — |
| `timed_out` | `boolean` | No | — |
| `waited_seconds` | `number` | No | — |

---

# Field Types

Route: /api-reference/field/types

# Field Types

## `CallerPermissions`

Evaluated permissions for the current caller on this artifact type.

| Field | Type | Required | Description |
|---|---|---|---|
| `can_create` | `boolean` | Yes | Whether the caller can create new artifacts |
| `can_draft` | `boolean` | Yes | Whether the caller can create/update drafts |
| `can_duplicate` | `boolean` | Yes | Whether the caller can duplicate artifacts |
| `has_access` | `boolean` | No | Whether the caller can view this entity |
| `can_edit` | `boolean` | No | Whether the caller can edit this entity |
| `can_delete` | `boolean` | No | Whether the caller can delete this entity |
| `disabled_reason` | `string` | No | Human-readable reason if editing is disabled |

---

## `ColumnInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Column name |
| `type` | `string` | Yes | Column data type |
| `nullable` | `boolean` | Yes | Whether the column is nullable |

---

## `CreateFieldItem`

Single field item for create — no field_id.

Required fields (name): provide ID or value.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Optional preset UUID for the new field |
| `resource_id` | `string` | No | Optional preset UUID for the resource snapshot |
| `name_id` | `string` | No | UUID of the name resource |
| `name` | `string` | No | Name value to resolve or create |
| `description_id` | `string` | No | UUID of the description resource |
| `description` | `string` | No | Description value to resolve or create |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `active` | `boolean` | No | Denormalized field_active flag state; resolved to a flag_ids entry server-side |
| `department_ids` | `string`[] | No | Department UUIDs to assign |
| `departments` | `string`[] | No | Department names to resolve |
| `conditional_parameter_ids` | `string`[] | No | Conditional parameter UUIDs |
| `field_ids` | `string`[] | No | Related field UUIDs |

---

## `DeleteFieldResult`

Per-item result within a bulk delete response.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the deletion succeeded |
| `field_id` | `string` | No | UUID of the deleted field |
| `message` | `string` | Yes | Result message |

---

## `DocsApiResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `list` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `detail` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `new` | [`PageMetaItem`](#pagemetaitem) | Yes | — |

---

## `DocsResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Resource or entry name |
| `type` | `string` | Yes | Resource or entry type identifier |
| `description` | `string` | Yes | Human-readable description |
| `materialized_view` | [`MvInfo`](#mvinfo) | No | Materialized view metadata |
| `tables` | [`TableInfo`](#tableinfo)[] | Yes | Related database tables |
| `operations` | [`OperationInfo`](#operationinfo)[] | Yes | Available operations |

---

## `EvalSetup`

Run-level eval scaffold — first-class on the generate response.

Audit's ``**output`` spread carries this onto
``<artifact>.generate.completed``. Null when no rubric-bearing
agent participated.

| Field | Type | Required | Description |
|---|---|---|---|
| `test_id` | `string` | Yes | — |
| `invocations` | [`InvocationSlot`](#invocationslot)[] | Yes | — |

---

## `FieldConditionalParameterResource`

Conditional parameter resource for field.

| Field | Type | Required | Description |
|---|---|---|---|
| `parameter_id` | `string` | No | Parameter identifier |
| `name` | `string` | No | Parameter display name |
| `description` | `string` | No | Parameter description |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `FieldDepartmentResource`

Department resource for field.

| Field | Type | Required | Description |
|---|---|---|---|
| `department_id` | `string` | No | Department identifier |
| `name` | `string` | No | Department name |
| `description` | `string` | No | Department description |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `FieldDescriptionResource`

Description resource for field.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `description` | `string` | No | Description text |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `FieldFieldError`

Per-field error from value resolution.

| Field | Type | Required | Description |
|---|---|---|---|
| `field` | `string` | Yes | Name of the field that failed validation |
| `message` | `string` | Yes | Validation error message |

---

## `FieldFlagResource`

Flag option row — one per (name, type, value) entry in flags_resource.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Flag resource identifier |
| `name` | `string` | No | Flag display name |
| `type` | `string` | No | Flag type (e.g. 'field_active') |
| `value` | `boolean` | No | Underlying bool value of this option |
| `description` | `string` | No | Flag description text |
| `icon_id` | `string` | No | Icon identifier for the flag |
| `icon` | `string` | No | Resolved SVG markup for the icon (hydrated from icons_resource) |
| `generated` | `boolean` | No | Whether the flag was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `FieldNameResource`

Name resource for field.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `name` | `string` | No | Display name |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `FieldResultItem`

Per-item result within a bulk create/update response.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `field_id` | `string` | No | UUID of the created or updated field |
| `message` | `string` | Yes | Result message |
| `errors` | [`FieldFieldError`](#fieldfielderror)[] | No | Per-field validation errors |

---

## `GenerateConfig`

Developer configuration — all optional with sensible defaults.

| Field | Type | Required | Description |
|---|---|---|---|
| `operations` | `string`[] | No | — |
| `dangerous` | `boolean` | No | — |
| `params` | `object` | No | — |
| `group_id` | `string` | No | — |

---

## `GenerationsFieldListItem`

Single generation group in the field generations response.

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | UUID of the generation group |
| `session_id` | `string` | No | UUID of the parent session |
| `group_name` | `string` | No | Name of the generation group |
| `created_at` | `string` | No | Timestamp of the generation |

---

## `GetFieldDraftResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | UUID of the draft |
| `created_at` | `string` | Yes | Creation timestamp |
| `generated` | `boolean` | Yes | Whether this was AI-generated |
| `mcp` | `boolean` | Yes | Whether MCP tooling was used |
| `active` | `boolean` | Yes | Whether this draft is active |
| `session_id` | `string` | Yes | Associated session UUID |
| `name` | `string` | No | Immutable draft label set at create time |
| `conditional_parameter_ids` | `string`[] | Yes | Associated conditional parameter UUIDs |
| `department_ids` | `string`[] | Yes | Associated department UUIDs |
| `description_ids` | `string`[] | Yes | Associated description UUIDs |
| `flag_ids` | `string`[] | Yes | Associated flag UUIDs |
| `name_ids` | `string`[] | Yes | Associated name UUIDs |
| `profile_ids` | `string`[] | Yes | Associated profile UUIDs |
| `pending_conditional_parameter_ids` | `string`[] | No | Pending conditional parameter UUIDs |
| `pending_department_ids` | `string`[] | No | Pending department UUIDs |
| `pending_description_ids` | `string`[] | No | Pending description UUIDs |
| `pending_flag_ids` | `string`[] | No | Pending flag UUIDs |
| `pending_name_ids` | `string`[] | No | Pending name UUIDs |

---

## `GroupCall`

Tool call referenced by a message.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `tool_name` | `string` | No | — |
| `template_name` | `string` | No | — |
| `tool` | `object` | No | — |
| `ledger_status` | `string` | No | — |
| `ledger_operation` | `string` | No | — |
| `ledger_artifact` | `string` | No | — |
| `ledger_artifact_id` | `string` | No | — |

---

## `GroupMessage`

Message within a run.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `role` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `text_ids` | `string`[] | No | — |
| `audio_ids` | `string`[] | No | — |
| `image_ids` | `string`[] | No | — |
| `video_ids` | `string`[] | No | — |
| `file_ids` | `string`[] | No | — |
| `call_ids` | `string`[] | No | — |
| `calls` | [`GroupCall`](#groupcall)[] | No | — |
| `reasoning` | `boolean` | No | True when this row is a chain-of-thought trace persisted alongside the assistant answer (rendered as a collapsed accordion). |
| `in_context` | `boolean` | No | Whether this message is included in the LLM context for the next generation. Mirrors the dedup pass that builds chat history (see in_context_reason). |
| `in_context_reason` | `string` | No | Why this message is in/out of LLM context. 'kept' = included; 'deduped_read' = older read-only call to a tool that has a fresher result later in the group; future values may include 'trimmed_top_n'. |

---

## `GroupResource`

Lightweight `\{id, name\}` for cross-referencing run-level ids
(``model_id`` / ``agent_id`` / ``profile_id``) against human-readable
names on the analytics panel. Names come from the canonical
``get_models`` / ``get_agents`` / ``get_profiles`` black boxes.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `name` | `string` | No | — |

---

## `GroupRun`

Run within a group, with its messages.

Carries token / cost / model / agent / profile attribution so the
analytics view can render per-run cost + actor info without a
parallel detail shape. ``profile_id`` is the authoring profile
(human user), ``agent_id`` is the LLM-side actor, ``model_id`` is
the model used by that agent. All optional — runs predating these
columns or with unresolved attributions surface ``None``.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `input_tokens` | `integer` | No | — |
| `output_tokens` | `integer` | No | — |
| `cached_input_tokens` | `integer` | No | — |
| `cost` | `number` | No | — |
| `model_id` | `string` | No | — |
| `agent_id` | `string` | No | — |
| `profile_id` | `string` | No | — |
| `previous_context_start_index` | `integer` | No | Index in ``messages`` where the current run's own messages begin; earlier rows are previous-context replay. ``None`` when the run has no previous context attached. |
| `messages` | [`GroupMessage`](#groupmessage)[] | No | — |

---

## `ImportField`

Field descriptor for CSV import column mapping.

| Field | Type | Required | Description |
|---|---|---|---|
| `key` | `string` | Yes | — |
| `label` | `string` | Yes | — |
| `required` | `boolean` | No | — |
| `multi` | `boolean` | No | — |
| `type` | `string` | No | — |
| `example` | `string` | No | — |
| `description` | `string` | No | — |

---

## `InvocationSlot`

One agent's slot in a multi-agent generation pool.

Populated by ``setup_generation_test`` when an agent carries a
rubric. The client uses these IDs to drive the eval workflow:
review the candidate's output, optionally fire a grader against
its ``invocation_id``, and promote/reject by call_id via the
existing ``idempotency_key + accept`` pattern.

| Field | Type | Required | Description |
|---|---|---|---|
| `invocation_id` | `string` | Yes | — |
| `agent_id` | `string` | Yes | — |
| `rubric_id` | `string` | No | — |

---

## `ListFieldApiField`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Field artifact UUID (canonical id; mirrors field_id) |
| `field_id` | `string` | No | Unique field identifier |
| `name` | `string` | No | Field display name |
| `description` | `string` | No | Field description text |
| `department_ids` | `string`[] | No | Associated department IDs |
| `conditional_parameter_ids` | `string`[] | No | Associated conditional parameter UUIDs |
| `persona_ids` | `string`[] | No | Associated persona UUIDs |
| `is_inactive` | `boolean` | No | Whether the field is inactive |
| `pending_status` | `string` | No | Latest soft_calls_mv status: 'pending' / 'accepted' / 'rejected' |
| `pending_operation` | `string` | No | Operation type ('create'|'update'|'delete'|'duplicate') of the pending op |
| `pending_call_id` | `string` | No | call_id (idempotency key for ack) of the pending op |
| `can_edit` | `boolean` | No | Whether the actor can edit this field |
| `can_duplicate` | `boolean` | No | Whether the actor can duplicate this field |
| `can_delete` | `boolean` | No | Whether the actor can delete this field |
| `updated_at` | `string` | No | Timestamp of last update |

---

## `ListFilterOption`

Standardized option for list endpoint filter sections.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier for this filter option |
| `name` | `string` | No | Display name |
| `count` | `integer` | No | Number of matching records |
| `hex_code` | `string` | No | Hex color code for display |
| `value` | `string` | No | Internal value |
| `type` | `string` | No | Option type discriminator |

---

## `ListFilterSection`

Filter section with options and echoed request state.

| Field | Type | Required | Description |
|---|---|---|---|
| `options` | [`ListFilterOption`](#listfilteroption)[] | No | Available filter options |
| `selected_ids` | `string`[] | No | Currently selected filter option IDs |
| `search` | `string` | No | Active search text for filtering |

---

## `MvInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Materialized view name |
| `definition` | `string` | Yes | SQL definition of the view |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the view |

---

## `OperationInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Operation name |
| `description` | `string` | Yes | Human-readable description of the operation |
| `params` | [`ParamInfo`](#paraminfo)[] | Yes | List of operation parameters |
| `returns` | `object` | No | Return type schema |

---

## `OperationPrompts`

Starter prompts keyed by operation name.

Each key is an operation (e.g. "create", "search", "draft", "export")
and the value is a list of starter prompts for that operation.
The client picks from the operations the caller has permission for
and rotates through them.

| Field | Type | Required | Description |
|---|---|---|---|
| `prompts` | `object` | No | Map of operation name to starter prompts |

---

## `PageMetaItem`

| Field | Type | Required | Description |
|---|---|---|---|
| `title` | `string` | Yes | — |
| `description` | `string` | Yes | — |

---

## `ParamInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Parameter name |
| `type` | `string` | Yes | Parameter data type |
| `required` | `boolean` | Yes | Whether the parameter is required |
| `default` | `any` | No | Default value if not required |

---

## `ProducedMedia`

One asset produced by a generation run.

``resource_id`` is the canonical id the per-artifact download tools
accept (e.g. ``Scenario_Image_Download(image_id=resource_id)`` for
``modality="image"``). It maps to ``images_resource.id`` /
``videos_resource.id`` / ``audios_resource.id`` depending on the
modality.

| Field | Type | Required | Description |
|---|---|---|---|
| `modality` | `"image"` \| `"video"` \| `"audio"` | Yes | — |
| `resource_id` | `string` | Yes | — |
| `upload_id` | `string` | Yes | — |
| `mime_type` | `string` | No | — |
| `file_size` | `integer` | No | — |

---

## `ProfileSummary`

Caller identity derived from JWT — who you are on this page.

Superset of the old six-field version: now carries everything the client
needs so that ``/\{artifact\}/context`` fully replaces ``/profiles/context``
and the extra ``getLayoutContextData`` round-trip can be dropped.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Display name of the authenticated user |
| `role` | `string` | Yes | Role name (e.g. 'Super Administrator') |
| `role_level` | `integer` | Yes | Role hierarchy level (0 = highest privilege) |
| `department_ids` | `string`[] | Yes | Departments the user belongs to |
| `artifact_access` | `string`[] | Yes | Artifact types this role can access (sidebar visibility) |
| `role_permissions` | `any`[][] | Yes | Full (artifact, operation) permission tuples for granular page gating |
| `is_active` | `boolean` | Yes | Whether the user's profile is active |
| `id` | `string` | Yes | Profile UUID (SocketProvider, ProfileProvider) |
| `theme` | [`ThemeBundle`](#themebundle) | No | Resolved theme: hex primitives + derived oklch tokens + score thresholds |
| `session_id` | `string` | No | Current session UUID |
| `is_emulation` | `boolean` | No | Whether user is in emulation mode (ProfileProvider) |
| `role_resources` | [`QGetProfileContextV4RoleResource`](#qgetprofilecontextv4roleresource)[] | No | All role resources for emulation display (ProfileProvider) |
| `scoped_roles` | `string`[] | No | Roles the user can emulate (ProfileProvider) |
| `active` | `boolean` | No | Alias for is_active (ProfileProvider uses this name) |

---

## `QGetProfileContextV4RoleResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `role` | `string` | No | — |
| `name` | `string` | No | — |
| `description` | `string` | No | — |
| `icon_value` | `string` | No | — |
| `color_hex` | `string` | No | — |

---

## `RunStatus`

Outcome of one watched run.

| Field | Type | Required | Description |
|---|---|---|---|
| `run_id` | `string` | Yes | — |
| `status` | `"pending"` \| `"completed"` \| `"failed"` | Yes | — |
| `modality` | `string` | No | Modality of generated output (image, video, text…) |
| `resource_ids` | `string`[] | No | Resource UUIDs produced by this run (e.g. images_resource ids) |
| `error` | `string` | No | — |

---

## `TableInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Table name |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the table |

---

## `ThemeBundle`

Full theme payload for a page bootstrap.

Riding along on every ``/\{artifact\}/context`` response via
``ProfileSummary.theme``. Layers:
  - ``primitives`` / ``dark_primitives`` — hex inputs the settings
    editor reads/writes (light + dark palettes).
  - ``tokens`` / ``dark_tokens`` — oklch tokens the client paints with.
    ``ThemeStyle`` emits two ``<style>`` blocks: one scoped to
    ``:root:not(.dark)`` (light) and one to ``:root.dark`` (dark).
  - ``thresholds`` — numeric score thresholds for analytics components.
Empty-in → empty-out per token: missing values fall through to the
matching ``globals.css`` default.

| Field | Type | Required | Description |
|---|---|---|---|
| `primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (light palette, for the theme editor) |
| `tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for light mode (SSR CSS-var injection) |
| `dark_primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (dark palette, for the theme editor) |
| `dark_tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for dark mode (SSR CSS-var injection) |
| `thresholds` | [`Thresholds`](#thresholds) | No | Score thresholds resolved from the setting |

---

## `ThemePrimitives`

40 optional fields. The 17 essentials drive the rest; the other 23
are overrides for fine-tuning when derivation isn't what you want.

Empty primitive → empty token → client falls back to globals.css.

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `primary` | `string` | No | — |
| `accent` | `string` | No | — |
| `card` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `ring` | `string` | No | — |
| `border` | `string` | No | — |
| `destructive` | `string` | No | — |
| `success` | `string` | No | — |
| `warning` | `string` | No | — |
| `info` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `input` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `ThemeTokens`

40 fully-resolved CSS variable values (snake_case 1:1 with vars).

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `accent` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `border` | `string` | No | — |
| `input` | `string` | No | — |
| `ring` | `string` | No | — |
| `success` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `Thresholds`

Numeric score thresholds resolved from the active setting.

Server pre-buckets dashboard metrics into ``success | warning | danger |
neutral`` already, so most components don't need these values. Surface
them for chart reference lines, tooltips, and any client-side bucketing.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `integer` | Yes | Score >= this counts as success |
| `warning` | `integer` | Yes | Score >= this counts as warning |
| `danger` | `integer` | Yes | Score < success threshold but >= this counts as danger; below is neutral/no-data |

---

## `UpdateFieldItem`

Single field item for update — field_id required, all fields optional.

Only provided fields are updated (partial update).

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | UUID of the field to update |
| `name_id` | `string` | No | UUID of the name resource |
| `name` | `string` | No | Name value to resolve or create |
| `description_id` | `string` | No | UUID of the description resource |
| `description` | `string` | No | Description value to resolve or create |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `active` | `boolean` | No | Denormalized field_active flag state; resolved to a flag_ids entry server-side |
| `department_ids` | `string`[] | No | Department UUIDs to assign |
| `departments` | `string`[] | No | Department names to resolve |
| `conditional_parameter_ids` | `string`[] | No | Conditional parameter UUIDs |
| `field_ids` | `string`[] | No | Related field UUIDs |

---

## `UpdateFieldPatch`

Shared patch for bulk-update-all-matching mode.

Inherits every field from ``UpdateFieldItem`` and just relaxes
``id`` to optional — the bulk impl stamps the resolved id onto a
clone of the patch per matched row, so any client-supplied id is
ignored. Sparse semantics: only fields the client sets are written.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Ignored — bulk impl stamps the resolved field id per matched row |
| `name_id` | `string` | No | UUID of the name resource |
| `name` | `string` | No | Name value to resolve or create |
| `description_id` | `string` | No | UUID of the description resource |
| `description` | `string` | No | Description value to resolve or create |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `active` | `boolean` | No | Denormalized field_active flag state; resolved to a flag_ids entry server-side |
| `department_ids` | `string`[] | No | Department UUIDs to assign |
| `departments` | `string`[] | No | Department names to resolve |
| `conditional_parameter_ids` | `string`[] | No | Conditional parameter UUIDs |
| `field_ids` | `string`[] | No | Related field UUIDs |

---

## `app__infra__field__types__DraftFormState`

Server-authoritative form state returned after draft save.

| Field | Type | Required | Description |
|---|---|---|---|
| `name_id` | `string` | No | Resolved name resource UUID |
| `name` | `string` | No | Echoed name value |
| `description_id` | `string` | No | Resolved description resource UUID |
| `description` | `string` | No | Echoed description value |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs |
| `active` | `boolean` | No | Echoed field_active flag state |
| `department_ids` | `string`[] | No | Assigned department UUIDs |
| `conditional_parameter_ids` | `string`[] | No | Assigned conditional parameter UUIDs |
| `pending_ids` | `string`[] | No | Pending resource identifiers |

---

## `app__infra__field__types__SectionFilter`

Per-section filter options for GET requests.

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Filter options by search text |
| `limit` | `integer` | No | Max options to return |
| `selected` | `boolean` | No | Only return selected items |
| `suggested` | `boolean` | No | Only return suggested items |
| `include` | `boolean` | No | Include this section in response (default true) |
| `parameter_ids` | `string`[] | No | Parameter group IDs to filter by where relevant |

---

---

# `GET` `/jwks`

Route: /api-reference/jwks

# `GET` `/jwks`

Jwks Endpoint

JWKS endpoint for public key exposure.

## Response

```
{}
```

---

# `GET` `/login`

Route: /api-reference/login

# `GET` `/login`

Login

Redirect to Keycloak login page.

## Response

```
{}
```

---

# `GET` `/logout`

Route: /api-reference/logout

# `GET` `/logout`

Logout

OIDC end_session_endpoint — proxy logout to Keycloak.

The client sends a Glow-signed id_token_hint. We look up the
corresponding KC-signed id_token (stored during login) and pass
that to Keycloak so it can do a silent logout without confirmation.

Also writes a ``logouts_entry`` row when the caller includes a
valid bearer token, so the session resolver mints a fresh session
on the next request. FE flows that fetch ``/logout`` with the
access token attached get this immediately; raw browser
navigations (no header) fall through to the 10-min idle gap.

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `post_logout_redirect_uri` | query | No | — |
| `client_id` | query | No | — |
| `id_token_hint` | query | No | — |

## Response

```
{}
```

---

# `GET` `/me`

Route: /api-reference/me

# `GET` `/me`

Me

Return current authenticated user info.

## Response

```
{}
```

---

# `GET` `/model/watch`

Route: /api-reference/model/get-model-watch

# `GET` `/model/watch`

Model Watch

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `group_id` | query | No | — |
| `run_id` | query | No | Optional run filter. If provided, only events whose envelope run_id matches are streamed. Omit to receive every model event in the group (the FE default). |

## Response

```
{}
```

---

# `POST` `/model/call_download`

Route: /api-reference/model/post-model-call-download

# `POST` `/model/call_download`

Download Call

Download a call file by call resource ID.

## Request Body (`CallDownloadModelApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `call_id` | `string` | Yes | UUID of the calls_resource to download |

## Response

```
{}
```

---

# `POST` `/model/context`

Route: /api-reference/model/post-model-context

# `POST` `/model/context`

Get Model Context

Get page context for the model artifact.

Returns docs + profile identity + evaluated permissions in a single call.
Superset of /docs — clients can migrate from /docs to /context incrementally.

## Request Body (`DocsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entity_id` | `string` | No | — |
| `snapshot_key` | `string` | No | — |
| `schema` | `boolean` | No | If true, include MCP/tooling schema metadata (artifact, entries, resources, permission_docs, api_operations). Defaults to false for lean page-bootstrap responses. |

## Response (`ComposedContextResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Artifact name |
| `type` | `string` | Yes | Artifact type identifier |
| `description` | `string` | Yes | Human-readable description |
| `artifact` | [`DocsResponse`](/api-reference/model/types#docsresponse) | No | Artifact tool documentation (None unless schema=true) |
| `entries` | [`DocsResponse`](/api-reference/model/types#docsresponse)[] | No | Entry documentation list (None unless schema=true) |
| `resources` | [`DocsResponse`](/api-reference/model/types#docsresponse)[] | No | Resource documentation list (None unless schema=true) |
| `permission_docs` | [`OperationInfo`](/api-reference/model/types#operationinfo)[] | No | Permission function signatures for MCP/dev tooling (None unless schema=true) |
| `api_operations` | [`OperationInfo`](/api-reference/model/types#operationinfo)[] | No | API operation documentation (None unless schema=true) |
| `page_metadata` | [`DocsApiResponse`](/api-reference/model/types#docsapiresponse) | No | Page-level metadata |
| `prompts` | [`OperationPrompts`](/api-reference/model/types#operationprompts) | No | Starter prompts keyed by operation |
| `profile` | [`ProfileSummary`](/api-reference/model/types#profilesummary) | Yes | Caller identity from JWT |
| `caller_permissions` | [`CallerPermissions`](/api-reference/model/types#callerpermissions) | Yes | Evaluated permissions for this caller |

---

# `POST` `/model/create`

Route: /api-reference/model/post-model-create

# `POST` `/model/create`

Create Model

Create models using composable infra architecture.

## Request Body (`CreateModelApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `models` | [`CreateModelItem`](/api-reference/model/types#createmodelitem)[] | No | List of models to create (required on first call) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant create |
| `soft` | `boolean` | No | Stage the create dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`CreateModelApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`ModelResultItem`](/api-reference/model/types#modelresultitem)[] | Yes | List of operation results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |
| `models` | [`ListModelApiModel`](/api-reference/model/types#listmodelapimodel)[] | No | Hydrated rows for the successfully-created models (mirrors /model/search shape) |

---

# `POST` `/model/csv`

Route: /api-reference/model/post-model-csv

# `POST` `/model/csv`

Parse Model Csv

Parse a CSV file and return mapped items for preview.

## Request Body

| Field | Type | Required | Description |
|---|---|---|---|
| `file` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `soft` | `boolean` | No | — |
| `accept` | `boolean` | No | — |

## Response (`ParseModelCsvApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `upload_id` | `string` | Yes | — |
| `items` | [`CreateModelItem`](/api-reference/model/types#createmodelitem)[] | Yes | — |
| `mapped_fields` | `string`[] | Yes | — |
| `row_count` | `integer` | Yes | — |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with `accept` to promote/reject the staged raw-CSV upload. NOTE: ack returns no items (the preview is only on the propose). |

---

# `POST` `/model/delete`

Route: /api-reference/model/post-model-delete

# `POST` `/model/delete`

Delete Model

Bulk delete models — composable infra architecture.

## Request Body (`DeleteModelApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `model_ids` | `string`[] | No | List of model IDs to delete (required on first call when ``all`` is false) |
| `all` | `boolean` | No | When true, delete every model matching the filter fields below (minus ``excluded_ids``) |
| `excluded_ids` | `string`[] | No | UUIDs to skip even when matched by ``all``-mode filters |
| `search` | `string` | No | Full-text search query |
| `filter_provider_ids` | `string`[] | No | Filter by provider UUIDs |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `filter_agent_ids` | `string`[] | No | Filter by agent UUIDs |
| `provider_search` | `string` | No | Search text for provider facet (no-op for row filtering) |
| `department_search` | `string` | No | Search text for department facet (no-op for row filtering) |
| `agent_search` | `string` | No | Search text for agent facet (no-op for row filtering) |
| `flag_search` | `string` | No | Search text for flag facet (no-op for row filtering) |
| `idempotency_key` | `string` | No | Operation key for ack — confirms or rejects a dormant delete |
| `soft` | `boolean` | No | Stage the delete dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (confirm) or reject dormant state. Only meaningful with idempotency_key |

## Response (`DeleteModelApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`DeleteModelResult`](/api-reference/model/types#deletemodelresult)[] | Yes | List of deletion results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/model/draft`

Route: /api-reference/model/post-model-draft

# `POST` `/model/draft`

Patch Model Draft

Patch model draft — composable infra architecture.

## Request Body (`PatchModelDraftApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `draft_id` | `string` | No | Existing draft ID to update |
| `input_draft_id` | `string` | No | Existing draft ID to update |
| `idempotency_key` | `string` | No | Operation key for accept/reject style ack |
| `soft` | `boolean` | No | Stage the draft dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept or reject when idempotency_key is supplied |
| `name` | `string` | No | Display name value |
| `name_id` | `string` | No | Name resource identifier |
| `description` | `string` | No | Description text value |
| `description_id` | `string` | No | Description resource identifier |
| `value` | `string` | No | Direct model value |
| `value_id` | `string` | No | Value resource identifier |
| `provider` | `string` | No | Provider name to match |
| `provider_id` | `string` | No | Provider identifier |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `active` | `boolean` | No | Denormalized model_active flag state |
| `modalities_enabled` | `boolean` | No | Denormalized model_modalities_enabled flag state |
| `temperature_enabled` | `boolean` | No | Denormalized model_temperature_enabled flag state |
| `pricing_enabled` | `boolean` | No | Denormalized model_pricing_enabled flag state |
| `voices_enabled` | `boolean` | No | Denormalized model_voices_enabled flag state |
| `reasoning_levels_enabled` | `boolean` | No | Denormalized model_reasoning_levels_enabled flag state |
| `qualities_enabled` | `boolean` | No | Denormalized model_qualities_enabled flag state |
| `departments` | `string`[] | No | Department names to match |
| `department_ids` | `string`[] | No | Department identifiers |
| `modalities` | `string`[] | No | Modality labels to match |
| `modality_ids` | `string`[] | No | Modality identifiers |
| `pricing` | [`PricingDraftValue`](/api-reference/model/types#pricingdraftvalue)[] | No | Inline-create pricing entries. Entries without id are created; resulting IDs merge into pricing_ids. |
| `pricing_ids` | `string`[] | No | Pricing tier identifiers |
| `qualities` | `string`[] | No | Quality labels to match |
| `quality_ids` | `string`[] | No | Quality level identifiers |
| `reasoning_levels` | `string`[] | No | Reasoning level labels to match |
| `reasoning_level_ids` | `string`[] | No | Reasoning level identifiers |
| `temperature_levels` | `string`[] | No | Temperature level labels to match |
| `temperature_level_ids` | `string`[] | No | Temperature level identifiers |
| `voices` | `string`[] | No | Voice labels to create or match |
| `voice_ids` | `string`[] | No | Voice identifiers |
| `pending_ids` | `string`[] | No | Pending resource identifiers |

## Response (`PatchModelDraftApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the draft save succeeded |
| `draft_id` | `string` | Yes | Draft unique identifier |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |
| `message` | `string` | Yes | Result message |
| `form_state` | [`app__infra__model__types__DraftFormState`](/api-reference/model/types#app-infra-model-types-draftformstate) | No | Server-authoritative form state |

---

# `POST` `/model/drafts`

Route: /api-reference/model/post-model-drafts

# `POST` `/model/drafts`

Get Model Drafts

List model drafts owned by the current profile.

## Request Body (`GetModelDraftsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE substring) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GetModelDraftsApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entries` | [`GetModelDraftResponse`](/api-reference/model/types#getmodeldraftresponse)[] | No | List of model draft entries |

---

# `POST` `/model/duplicate`

Route: /api-reference/model/post-model-duplicate

# `POST` `/model/duplicate`

Duplicate Model

Duplicate a model — composable infra architecture.

## Request Body (`DuplicateModelApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `model_id` | `string` | Yes | Model identifier to duplicate |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant duplicate |
| `soft` | `boolean` | No | Stage the duplicate dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`DuplicateModelApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the duplication succeeded |
| `model_id` | `string` | Yes | New duplicated model identifier |
| `message` | `string` | Yes | Result message |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |
| `models` | [`ListModelApiModel`](/api-reference/model/types#listmodelapimodel)[] | No | Hydrated row for the newly-created duplicate model (mirrors /model/search shape) |

---

# `POST` `/model/export`

Route: /api-reference/model/post-model-export

# `POST` `/model/export`

Export Models

Export all models as a clean, denormalized CSV.

## Request Body (`ExportModelApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `model_id` | `string` | No | Model identifier to export |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior export instead of re-running |
| `soft` | `boolean` | No | Stage the export dormant (active=False); ack with accept activates it |
| `accept` | `boolean` | No | Ack: True promotes the staged export, False rejects. Only meaningful with idempotency_key |

## Response (`ExportModelApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource holding the export CSV |
| `file_name` | `string` | Yes | Suggested download file name |
| `row_count` | `integer` | Yes | Number of data rows in the export |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with `accept` to promote/reject the staged export. |

---

# `POST` `/model/file_download`

Route: /api-reference/model/post-model-file-download

# `POST` `/model/file_download`

Download File

Download a file by file resource ID.

## Request Body (`FileDownloadModelApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource to download |

## Response

```
{}
```

---

# `POST` `/model/generate`

Route: /api-reference/model/post-model-generate

# `POST` `/model/generate`

Generate Model

Trigger model generation. Returns immediately; progress via events.

## Request Body (`ArtifactGenerateRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `instructions` | `string`[] | No | — |
| `config` | [`GenerateConfig`](/api-reference/model/types#generateconfig) | No | — |
| `modalities` | `string`[] | No | — |
| `audios_id` | `string` | No | — |
| `conversation_id` | `string` | No | — |
| `trace_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `accept` | `boolean` | No | — |
| `wait_for_complete` | `boolean` | No | — |

## Response (`ArtifactGenerateResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `run_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `eval` | [`EvalSetup`](/api-reference/model/types#evalsetup) | No | — |
| `produced_media` | [`ProducedMedia`](/api-reference/model/types#producedmedia)[] | No | — |

---

# `POST` `/model/generations`

Route: /api-reference/model/post-model-generations

# `POST` `/model/generations`

Generations Model

List model generation groups — composable infra architecture.

## Request Body (`GenerationsModelApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GenerationsModelApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `items` | [`GenerationsModelListItem`](/api-reference/model/types#generationsmodellistitem)[] | No | Generation groups |
| `total_count` | `integer` | No | Total number of matching generations |

---

# `POST` `/model/get`

Route: /api-reference/model/post-model-get

# `POST` `/model/get`

Get Model

Get model information using the canonical shared model operation.

## Request Body (`GetModelApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Model unique identifier |
| `model_id` | `string` | No | Legacy alias for model unique identifier |
| `draft_id` | `string` | No | Draft unique identifier |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |
| `names` | [`app__infra__model__types__SectionFilter`](/api-reference/model/types#app-infra-model-types-sectionfilter) | No | Filter options for names |
| `descriptions` | [`app__infra__model__types__SectionFilter`](/api-reference/model/types#app-infra-model-types-sectionfilter) | No | Filter options for descriptions |
| `values` | [`app__infra__model__types__SectionFilter`](/api-reference/model/types#app-infra-model-types-sectionfilter) | No | Filter options for values |
| `providers` | [`app__infra__model__types__SectionFilter`](/api-reference/model/types#app-infra-model-types-sectionfilter) | No | Filter options for providers |
| `flags` | [`app__infra__model__types__SectionFilter`](/api-reference/model/types#app-infra-model-types-sectionfilter) | No | Filter options for flags |
| `departments` | [`app__infra__model__types__SectionFilter`](/api-reference/model/types#app-infra-model-types-sectionfilter) | No | Filter options for departments |
| `modalities` | [`app__infra__model__types__SectionFilter`](/api-reference/model/types#app-infra-model-types-sectionfilter) | No | Filter options for modalities |
| `temperature_levels` | [`app__infra__model__types__SectionFilter`](/api-reference/model/types#app-infra-model-types-sectionfilter) | No | Filter options for temperature levels |
| `pricing` | [`app__infra__model__types__SectionFilter`](/api-reference/model/types#app-infra-model-types-sectionfilter) | No | Filter options for pricing |
| `reasoning_levels` | [`app__infra__model__types__SectionFilter`](/api-reference/model/types#app-infra-model-types-sectionfilter) | No | Filter options for reasoning levels |
| `qualities` | [`app__infra__model__types__SectionFilter`](/api-reference/model/types#app-infra-model-types-sectionfilter) | No | Filter options for qualities |
| `voices` | [`app__infra__model__types__SectionFilter`](/api-reference/model/types#app-infra-model-types-sectionfilter) | No | Filter options for voices |

## Response (`GetModelApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `model_exists` | `boolean` | No | Whether the model exists |
| `can_edit` | `boolean` | No | Whether the current user can edit |
| `disabled_reason` | `string` | No | Reason editing is disabled |
| `group_id` | `string` | No | Group identifier for the model |
| `draft_name` | `string` | No | Immutable draft label from the active draft entry, when a ``draft_id`` was supplied. ``None`` for non-draft fetches. |
| `model_id` | `string` | No | Model identifier |
| `show_ai_generate` | `boolean` | No | Whether any step should show AI generate |
| `basic_show_ai_generate` | `boolean` | No | Show AI generate for basic step |
| `provider_show_ai_generate` | `boolean` | No | Show AI generate for provider step |
| `features_show_ai_generate` | `boolean` | No | Show AI generate for features step |
| `pending_ids` | `string`[] | No | Pending resource identifiers when available |
| `names` | [`ModelNameResource`](/api-reference/model/types#modelnameresource)[] | No | Name resources |
| `descriptions` | [`ModelDescriptionResource`](/api-reference/model/types#modeldescriptionresource)[] | No | Description resources |
| `values` | [`ModelValueResource`](/api-reference/model/types#modelvalueresource)[] | No | Value resources |
| `providers` | [`ModelProviderResource`](/api-reference/model/types#modelproviderresource)[] | No | Provider resources |
| `flags` | [`ModelFlagResource`](/api-reference/model/types#modelflagresource)[] | No | Flag configs |
| `departments` | [`ModelDepartmentResource`](/api-reference/model/types#modeldepartmentresource)[] | No | Department resources |
| `modalities` | [`ModelModalityResource`](/api-reference/model/types#modelmodalityresource)[] | No | Modality resources |
| `temperature_levels` | [`ModelTemperatureLevelResource`](/api-reference/model/types#modeltemperaturelevelresource)[] | No | Temperature level resources |
| `pricing` | [`ModelPricingResource`](/api-reference/model/types#modelpricingresource)[] | No | Pricing resources |
| `reasoning_levels` | [`ModelReasoningLevelResource`](/api-reference/model/types#modelreasoninglevelresource)[] | No | Reasoning level resources |
| `qualities` | [`ModelQualityResource`](/api-reference/model/types#modelqualityresource)[] | No | Quality resources |
| `voices` | [`ModelVoiceResource`](/api-reference/model/types#modelvoiceresource)[] | No | Voice resources |

---

# `POST` `/model/group`

Route: /api-reference/model/post-model-group

# `POST` `/model/group`

Group Model

Resolve or create a model group with optional naming.

## Request Body (`GroupModelApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | No | Existing group UUID (omit to create or reuse via time window) |
| `snapshot_key` | `string` | No | Snapshot key for SETNX-race convergence on a single group across concurrent reads (e.g. parallel /context + /group + /search fan-out on page load). Echoed back in the response. |

## Response (`GroupModelApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Resolved or newly created group UUID |
| `name` | `string` | No | The group's current title (latest active group_names_entry, or 'New Chat' fallback for freshly minted groups) |
| `snapshot_key` | `string` | No | Snapshot key echoed back — the UUID concurrent fan-out reads converged on via SETNX. Mirrors the resolved group_id. |
| `runs` | [`GroupRun`](/api-reference/model/types#grouprun)[] | No | Conversation history — populated when resolving an existing group for fetch |
| `group_exists` | `boolean` | No | (detail) Whether the group exists in storage — populated when ``include_resources=True`` |
| `actor_name` | `string` | No | (detail) Display name of the current actor (caller profile) |
| `total_message_count` | `integer` | No | (detail) Total number of messages in the group |
| `models` | [`GroupResource`](/api-reference/model/types#groupresource)[] | No | (detail) Models used in the group |
| `agents` | [`GroupResource`](/api-reference/model/types#groupresource)[] | No | (detail) Agents used in the group |
| `profiles` | [`GroupResource`](/api-reference/model/types#groupresource)[] | No | (detail) Profiles that authored runs in this group |

---

# `POST` `/model/problem`

Route: /api-reference/model/post-model-problem

# `POST` `/model/problem`

Problem Model

Report a model problem — composable infra architecture.

## Request Body (`ProblemModelApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | `string` | Yes | Problem type: feature, bug, question, other |
| `message` | `string` | Yes | Problem description (max 1000 chars) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant problem |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`ProblemModelApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `problem_id` | `string` | Yes | UUID of the created problem |
| `success` | `boolean` | No | Whether the problem was created |
| `message` | `string` | No | Status message |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/model/refresh`

Route: /api-reference/model/post-model-refresh

# `POST` `/model/refresh`

Model Refresh

Refresh model materialized views and invalidate caches.

## Request Body (`RefreshModelApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `targets` | `string`[] | No | MV targets to refresh (omit for all). Options: model_drafts_mv |
| `idempotency_key` | `string` | No | Operation key for ack |
| `accept` | `boolean` | No | Accept or reject. Only meaningful with idempotency_key |
| `soft` | `boolean` | No | Stage the refresh as a pending (held) request — recorded but not enqueued; ack with accept releases/enqueues it |

## Response (`RefreshResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | — |
| `refreshed_views` | `string`[] | Yes | — |
| `invalidated_tags` | `string`[] | Yes | — |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/model/search`

Route: /api-reference/model/post-model-search

# `POST` `/model/search`

Search Model

Search models — composable infra architecture.

## Request Body (`SearchModelApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | — |
| `filter_provider_ids` | `string`[] | No | — |
| `filter_department_ids` | `string`[] | No | — |
| `filter_agent_ids` | `string`[] | No | — |
| `provider_search` | `string` | No | — |
| `department_search` | `string` | No | — |
| `agent_search` | `string` | No | — |
| `page_size` | `integer` | No | — |
| `page_offset` | `integer` | No | — |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`ListModelApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `models` | [`ListModelApiModel`](/api-reference/model/types#listmodelapimodel)[] | No | List of model entries |
| `provider_filter` | [`ListFilterSection`](/api-reference/model/types#listfiltersection) | No | Provider filter options |
| `department_filter` | [`ListFilterSection`](/api-reference/model/types#listfiltersection) | No | Department filter options |
| `agent_filter` | [`ListFilterSection`](/api-reference/model/types#listfiltersection) | No | Agent filter options |
| `flag_filter` | [`ListFilterSection`](/api-reference/model/types#listfiltersection) | No | Filter options for flags in list UI |
| `total_count` | `integer` | No | Total number of models |
| `import_fields` | [`ImportField`](/api-reference/model/types#importfield)[] | No | CSV import column schema for the bulk-import dialog |

---

# `POST` `/model/text_download`

Route: /api-reference/model/post-model-text-download

# `POST` `/model/text_download`

Download Text

Download a text file by text resource ID.

## Request Body (`TextDownloadModelApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `text_id` | `string` | Yes | UUID of the texts_resource to download |

## Response

```
{}
```

---

# `POST` `/model/title`

Route: /api-reference/model/post-model-title

# `POST` `/model/title`

Title Model

Rename a model's group (writes group_names_entry).

## Request Body (`TitleModelApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Group to rename |
| `title` | `string` | Yes | New title (display name) for the group |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant rename |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`TitleModelApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | The group that was renamed |
| `group_name_id` | `string` | Yes | UUID of the new group_names_entry row |
| `title` | `string` | Yes | The title that was set |
| `idempotency_key` | `string` | No | Operation key echoed back |

---

# `POST` `/model/update`

Route: /api-reference/model/post-model-update

# `POST` `/model/update`

Update Model

Update models using composable infra architecture.

## Request Body (`UpdateModelApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `models` | [`UpdateModelItem`](/api-reference/model/types#updatemodelitem)[] | No | List of models to update (required on first call when ``all`` is false) |
| `all` | `boolean` | No | When true, apply ``patch`` to every model matching the filter fields below (minus ``excluded_ids``) |
| `excluded_ids` | `string`[] | No | UUIDs to skip even when matched by ``all``-mode filters |
| `patch` | [`UpdateModelPatch`](/api-reference/model/types#updatemodelpatch) | No | Shared change set applied to every matched row when ``all=true`` (sparse — only set fields are updated; ``patch.id`` ignored) |
| `search` | `string` | No | Full-text search query |
| `filter_provider_ids` | `string`[] | No | Filter by provider UUIDs |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `filter_agent_ids` | `string`[] | No | Filter by agent UUIDs |
| `provider_search` | `string` | No | Search text for provider facet (no-op for row filtering) |
| `department_search` | `string` | No | Search text for department facet (no-op for row filtering) |
| `agent_search` | `string` | No | Search text for agent facet (no-op for row filtering) |
| `flag_search` | `string` | No | Search text for flag facet (no-op for row filtering) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant update |
| `soft` | `boolean` | No | Stage the update dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`UpdateModelApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`ModelResultItem`](/api-reference/model/types#modelresultitem)[] | Yes | List of operation results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |
| `models` | [`ListModelApiModel`](/api-reference/model/types#listmodelapimodel)[] | No | Hydrated rows for the successfully-updated models (mirrors /model/search shape) |

---

# `POST` `/model/watch`

Route: /api-reference/model/post-model-watch

# `POST` `/model/watch`

Model Watch Once

One-shot snapshot of run state, snapshot-replayable via ``snapshot_key``.

## Request Body (`WatchApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Chat group whose events we watch |
| `run_id` | `string` | No | Specific run to watch (e.g. the ``run_id`` returned by a prior ``X_Generate`` call). If None, watches every active run in the group at call time. |
| `wait_for_complete` | `boolean` | No | If True, block until the watched run reaches a terminal (complete/failed) event or timeout fires. If False, return current state and exit immediately. |
| `timeout_seconds` | `integer` | No | Max wait time when ``wait_for_complete=True``. |
| `snapshot_key` | `string` | No | Read snapshot key — on the one-shot POST /watch, the audit wrapper records this watch's point-in-time view (latest run state at call time) keyed by it and replays the same view on any later call with the same key. Ignored by the SSE GET stream. |

## Response (`WatchApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `runs` | [`RunStatus`](/api-reference/model/types#runstatus)[] | Yes | — |
| `timed_out` | `boolean` | No | — |
| `waited_seconds` | `number` | No | — |

---

# Model Types

Route: /api-reference/model/types

# Model Types

## `CallerPermissions`

Evaluated permissions for the current caller on this artifact type.

| Field | Type | Required | Description |
|---|---|---|---|
| `can_create` | `boolean` | Yes | Whether the caller can create new artifacts |
| `can_draft` | `boolean` | Yes | Whether the caller can create/update drafts |
| `can_duplicate` | `boolean` | Yes | Whether the caller can duplicate artifacts |
| `has_access` | `boolean` | No | Whether the caller can view this entity |
| `can_edit` | `boolean` | No | Whether the caller can edit this entity |
| `can_delete` | `boolean` | No | Whether the caller can delete this entity |
| `disabled_reason` | `string` | No | Human-readable reason if editing is disabled |

---

## `ColumnInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Column name |
| `type` | `string` | Yes | Column data type |
| `nullable` | `boolean` | Yes | Whether the column is nullable |

---

## `CreateModelItem`

Single model item for create — no model_id.

Required pair (name): provide ID or value. Strongly recommended:
pair ``value`` and ``provider_id`` so the resulting model is
actually callable.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Optional pre-assigned identifier |
| `resource_id` | `string` | No | Optional preset UUID for the resource snapshot |
| `name_id` | `string` | No | REQUIRED FOR CREATE (or pass ``name``). UUID of an existing name resource. |
| `name` | `string` | No | REQUIRED FOR CREATE (or pass ``name_id``). Display name text — creates a new name resource on the fly. |
| `value_id` | `string` | No | UUID of an existing value resource (the API model identifier). |
| `value` | `string` | No | Direct model value/identifier (e.g. the actual API model name like 'gpt-4o'). Strongly recommended on create alongside ``provider_id`` so the model is callable. |
| `provider_id` | `string` | No | UUID of an existing provider resource. Strongly recommended on create alongside ``value`` so the model is callable. |
| `description_id` | `string` | No | UUID of an existing description resource |
| `description` | `string` | No | Description text value (creates a new description resource if description_id not provided) |
| `department_ids` | `string`[] | No | Department identifiers |
| `departments` | `string`[] | No | Department names to match |
| `flag_ids` | `string`[] | No | Flag option identifiers |
| `modality_ids` | `string`[] | No | Modality identifiers |
| `pricing_ids` | `string`[] | No | Pricing tier identifiers |
| `quality_ids` | `string`[] | No | Quality level identifiers |
| `reasoning_level_ids` | `string`[] | No | Reasoning level identifiers |
| `temperature_level_ids` | `string`[] | No | Temperature level identifiers |
| `voice_ids` | `string`[] | No | Voice identifiers |
| `model_ids` | `string`[] | No | Related model identifiers |

---

## `DeleteModelResult`

Per-item result within a bulk delete response.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the deletion succeeded |
| `model_id` | `string` | No | Deleted model identifier (None for soft-skipped not-found rows under all-matching mode) |
| `message` | `string` | Yes | Result message |

---

## `DocsApiResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `list` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `detail` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `new` | [`PageMetaItem`](#pagemetaitem) | Yes | — |

---

## `DocsResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Resource or entry name |
| `type` | `string` | Yes | Resource or entry type identifier |
| `description` | `string` | Yes | Human-readable description |
| `materialized_view` | [`MvInfo`](#mvinfo) | No | Materialized view metadata |
| `tables` | [`TableInfo`](#tableinfo)[] | Yes | Related database tables |
| `operations` | [`OperationInfo`](#operationinfo)[] | Yes | Available operations |

---

## `EvalSetup`

Run-level eval scaffold — first-class on the generate response.

Audit's ``**output`` spread carries this onto
``<artifact>.generate.completed``. Null when no rubric-bearing
agent participated.

| Field | Type | Required | Description |
|---|---|---|---|
| `test_id` | `string` | Yes | — |
| `invocations` | [`InvocationSlot`](#invocationslot)[] | Yes | — |

---

## `GenerateConfig`

Developer configuration — all optional with sensible defaults.

| Field | Type | Required | Description |
|---|---|---|---|
| `operations` | `string`[] | No | — |
| `dangerous` | `boolean` | No | — |
| `params` | `object` | No | — |
| `group_id` | `string` | No | — |

---

## `GenerationsModelListItem`

Single generation group in the model generations response.

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | UUID of the generation group |
| `session_id` | `string` | No | UUID of the parent session |
| `group_name` | `string` | No | Name of the generation group |
| `created_at` | `string` | No | Timestamp of the generation |

---

## `GetModelDraftResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | UUID of the draft |
| `created_at` | `string` | Yes | Creation timestamp |
| `generated` | `boolean` | Yes | Whether this was AI-generated |
| `mcp` | `boolean` | Yes | Whether MCP tooling was used |
| `active` | `boolean` | Yes | Whether this draft is active |
| `session_id` | `string` | Yes | Associated session UUID |
| `name` | `string` | No | Immutable draft label set at create time |
| `department_ids` | `string`[] | Yes | Associated department UUIDs |
| `description_ids` | `string`[] | Yes | Associated description UUIDs |
| `flag_ids` | `string`[] | Yes | Associated flag UUIDs |
| `modality_ids` | `string`[] | Yes | Associated modality UUIDs |
| `name_ids` | `string`[] | Yes | Associated name UUIDs |
| `pricing_ids` | `string`[] | Yes | Associated pricing UUIDs |
| `profile_ids` | `string`[] | Yes | Associated profile UUIDs |
| `provider_ids` | `string`[] | Yes | Associated provider UUIDs |
| `quality_ids` | `string`[] | Yes | Associated quality UUIDs |
| `reasoning_level_ids` | `string`[] | Yes | Associated reasoning level UUIDs |
| `temperature_level_ids` | `string`[] | Yes | Associated temperature level UUIDs |
| `value_id` | `string` | No | Associated value UUID |
| `voice_ids` | `string`[] | Yes | Associated voice UUIDs |
| `pending_department_ids` | `string`[] | No | Pending department UUIDs |
| `pending_description_ids` | `string`[] | No | Pending description UUIDs |
| `pending_flag_ids` | `string`[] | No | Pending flag UUIDs |
| `pending_modality_ids` | `string`[] | No | Pending modality UUIDs |
| `pending_name_ids` | `string`[] | No | Pending name UUIDs |
| `pending_pricing_ids` | `string`[] | No | Pending pricing UUIDs |
| `pending_provider_ids` | `string`[] | No | Pending provider UUIDs |
| `pending_quality_ids` | `string`[] | No | Pending quality UUIDs |
| `pending_reasoning_level_ids` | `string`[] | No | Pending reasoning level UUIDs |
| `pending_temperature_level_ids` | `string`[] | No | Pending temperature level UUIDs |
| `pending_value_ids` | `string`[] | No | Pending value UUIDs |
| `pending_voice_ids` | `string`[] | No | Pending voice UUIDs |

---

## `GroupCall`

Tool call referenced by a message.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `tool_name` | `string` | No | — |
| `template_name` | `string` | No | — |
| `tool` | `object` | No | — |
| `ledger_status` | `string` | No | — |
| `ledger_operation` | `string` | No | — |
| `ledger_artifact` | `string` | No | — |
| `ledger_artifact_id` | `string` | No | — |

---

## `GroupMessage`

Message within a run.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `role` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `text_ids` | `string`[] | No | — |
| `audio_ids` | `string`[] | No | — |
| `image_ids` | `string`[] | No | — |
| `video_ids` | `string`[] | No | — |
| `file_ids` | `string`[] | No | — |
| `call_ids` | `string`[] | No | — |
| `calls` | [`GroupCall`](#groupcall)[] | No | — |
| `reasoning` | `boolean` | No | True when this row is a chain-of-thought trace persisted alongside the assistant answer (rendered as a collapsed accordion). |
| `in_context` | `boolean` | No | Whether this message is included in the LLM context for the next generation. Mirrors the dedup pass that builds chat history (see in_context_reason). |
| `in_context_reason` | `string` | No | Why this message is in/out of LLM context. 'kept' = included; 'deduped_read' = older read-only call to a tool that has a fresher result later in the group; future values may include 'trimmed_top_n'. |

---

## `GroupResource`

Lightweight `\{id, name\}` for cross-referencing run-level ids
(``model_id`` / ``agent_id`` / ``profile_id``) against human-readable
names on the analytics panel. Names come from the canonical
``get_models`` / ``get_agents`` / ``get_profiles`` black boxes.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `name` | `string` | No | — |

---

## `GroupRun`

Run within a group, with its messages.

Carries token / cost / model / agent / profile attribution so the
analytics view can render per-run cost + actor info without a
parallel detail shape. ``profile_id`` is the authoring profile
(human user), ``agent_id`` is the LLM-side actor, ``model_id`` is
the model used by that agent. All optional — runs predating these
columns or with unresolved attributions surface ``None``.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `input_tokens` | `integer` | No | — |
| `output_tokens` | `integer` | No | — |
| `cached_input_tokens` | `integer` | No | — |
| `cost` | `number` | No | — |
| `model_id` | `string` | No | — |
| `agent_id` | `string` | No | — |
| `profile_id` | `string` | No | — |
| `previous_context_start_index` | `integer` | No | Index in ``messages`` where the current run's own messages begin; earlier rows are previous-context replay. ``None`` when the run has no previous context attached. |
| `messages` | [`GroupMessage`](#groupmessage)[] | No | — |

---

## `ImportField`

Field descriptor for CSV import column mapping.

| Field | Type | Required | Description |
|---|---|---|---|
| `key` | `string` | Yes | — |
| `label` | `string` | Yes | — |
| `required` | `boolean` | No | — |
| `multi` | `boolean` | No | — |
| `type` | `string` | No | — |
| `example` | `string` | No | — |
| `description` | `string` | No | — |

---

## `InvocationSlot`

One agent's slot in a multi-agent generation pool.

Populated by ``setup_generation_test`` when an agent carries a
rubric. The client uses these IDs to drive the eval workflow:
review the candidate's output, optionally fire a grader against
its ``invocation_id``, and promote/reject by call_id via the
existing ``idempotency_key + accept`` pattern.

| Field | Type | Required | Description |
|---|---|---|---|
| `invocation_id` | `string` | Yes | — |
| `agent_id` | `string` | Yes | — |
| `rubric_id` | `string` | No | — |

---

## `ListFilterOption`

Standardized option for list endpoint filter sections.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier for this filter option |
| `name` | `string` | No | Display name |
| `count` | `integer` | No | Number of matching records |
| `hex_code` | `string` | No | Hex color code for display |
| `value` | `string` | No | Internal value |
| `type` | `string` | No | Option type discriminator |

---

## `ListFilterSection`

Filter section with options and echoed request state.

| Field | Type | Required | Description |
|---|---|---|---|
| `options` | [`ListFilterOption`](#listfilteroption)[] | No | Available filter options |
| `selected_ids` | `string`[] | No | Currently selected filter option IDs |
| `search` | `string` | No | Active search text for filtering |

---

## `ListModelApiModel`

Model type for list endpoint with computed permissions.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Model artifact UUID (canonical id; mirrors model_id) |
| `model_id` | `string` | No | Model unique identifier |
| `name` | `string` | No | Display name of the model |
| `description` | `string` | No | Model description text |
| `provider_id` | `string` | No | Associated provider identifier |
| `provider_name` | `string` | No | Associated provider display name |
| `base_url` | `string` | No | Base URL for the model API |
| `department_ids` | `string`[] | No | Associated department identifiers |
| `is_inactive` | `boolean` | No | Whether the model is inactive |
| `active` | `boolean` | No | Whether the model is currently active |
| `image_model` | `boolean` | No | Whether this is an image model |
| `pending_status` | `string` | No | Latest soft_calls_mv status: 'pending' / 'accepted' / 'rejected' |
| `pending_operation` | `string` | No | Operation type ('create'|'update'|'delete'|'duplicate') of the pending op |
| `pending_call_id` | `string` | No | call_id (idempotency key for ack) of the pending op |
| `can_edit` | `boolean` | No | Whether the current user can edit |
| `can_duplicate` | `boolean` | No | Whether the current user can duplicate |
| `can_delete` | `boolean` | No | Whether the current user can delete |
| `updated_at` | `string` | No | Timestamp of last update |

---

## `ModelDepartmentResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `department_id` | `string` | No | Department identifier |
| `name` | `string` | No | Department name |
| `description` | `string` | No | Department description |
| `generated` | `boolean` | No | Whether the department was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `ModelDescriptionResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Description resource identifier |
| `description` | `string` | No | Model description |
| `generated` | `boolean` | No | Whether the description was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `ModelFieldError`

Per-field error from value resolution.

| Field | Type | Required | Description |
|---|---|---|---|
| `field` | `string` | Yes | Field name that caused the error |
| `message` | `string` | Yes | Error message describing the issue |

---

## `ModelFlagResource`

Flag option row — one per (name, type, value) entry in flags_resource.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Flag resource identifier |
| `name` | `string` | No | Flag display name |
| `type` | `string` | No | Flag type (e.g. 'model_active') |
| `value` | `boolean` | No | Underlying bool value of this option |
| `description` | `string` | No | Flag description text |
| `icon_id` | `string` | No | Icon identifier for the flag |
| `icon` | `string` | No | Resolved SVG markup (hydrated from icons_resource) |
| `generated` | `boolean` | No | Whether the flag was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `ModelModalityResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Modality resource identifier |
| `modality` | `string` | No | Modality name |
| `is_input` | `boolean` | No | Whether this is an input modality |
| `generated` | `boolean` | No | Whether the modality was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `ModelNameResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Name resource identifier |
| `name` | `string` | No | Model display name |
| `generated` | `boolean` | No | Whether the name was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `ModelPricingResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Pricing resource identifier |
| `pricing_type` | `string` | No | Pricing type |
| `price` | `number` | No | Pricing amount |
| `unit_name` | `string` | No | Pricing unit name |
| `unit_category` | `string` | No | Pricing unit category |
| `unit_value` | `number` | No | Pricing unit value |
| `generated` | `boolean` | No | Whether the pricing resource was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `ModelProviderResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Provider resource identifier |
| `name` | `string` | No | Provider display name |
| `description` | `string` | No | Provider description |
| `value` | `string` | No | Provider value |
| `base_url` | `string` | No | Provider endpoint |
| `generated` | `boolean` | No | Whether the provider was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `ModelQualityResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Quality resource identifier |
| `quality` | `string` | No | Quality label |
| `generated` | `boolean` | No | Whether the quality was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `ModelReasoningLevelResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Reasoning level resource identifier |
| `reasoning_level` | `string` | No | Reasoning level label |
| `generated` | `boolean` | No | Whether the reasoning level was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `ModelResultItem`

Per-item result within a bulk create/update response.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `model_id` | `string` | No | Model unique identifier |
| `message` | `string` | Yes | Result message |
| `errors` | [`ModelFieldError`](#modelfielderror)[] | No | List of field-level errors |

---

## `ModelTemperatureLevelResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Temperature level resource identifier |
| `temperature` | `string` | No | Temperature level label |
| `generated` | `boolean` | No | Whether the temperature level was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `ModelValueResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Value resource identifier |
| `value` | `string` | No | Model value |
| `value_type` | `string` | No | Stored value type |
| `generated` | `boolean` | No | Whether the value was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `ModelVoiceResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Voice resource identifier |
| `voice` | `string` | No | Voice label |
| `generated` | `boolean` | No | Whether the voice was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `MvInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Materialized view name |
| `definition` | `string` | Yes | SQL definition of the view |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the view |

---

## `OperationInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Operation name |
| `description` | `string` | Yes | Human-readable description of the operation |
| `params` | [`ParamInfo`](#paraminfo)[] | Yes | List of operation parameters |
| `returns` | `object` | No | Return type schema |

---

## `OperationPrompts`

Starter prompts keyed by operation name.

Each key is an operation (e.g. "create", "search", "draft", "export")
and the value is a list of starter prompts for that operation.
The client picks from the operations the caller has permission for
and rotates through them.

| Field | Type | Required | Description |
|---|---|---|---|
| `prompts` | `object` | No | Map of operation name to starter prompts |

---

## `PageMetaItem`

| Field | Type | Required | Description |
|---|---|---|---|
| `title` | `string` | Yes | — |
| `description` | `string` | Yes | — |

---

## `ParamInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Parameter name |
| `type` | `string` | Yes | Parameter data type |
| `required` | `boolean` | Yes | Whether the parameter is required |
| `default` | `any` | No | Default value if not required |

---

## `PricingDraftValue`

Value-object for inline-creating a pricing_resource row from the model editor.

Entries without `id` are created server-side; resulting IDs merge into
pricing_ids. Mirrors the standard_groups pattern so the model draft can
accept either existing pricing rows or new authored ones in the same
request.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Existing pricing UUID, if any |
| `pricing_type` | `string` | Yes | Pricing role (e.g. 'input_tokens', 'output_tokens') |
| `price` | `number` | Yes | Price amount |
| `unit_name` | `string` | Yes | Display label for the rate unit (e.g. '1M tokens') |
| `unit_category` | `string` | Yes | Unit category (e.g. 'tokens', 'requests', 'minutes') |
| `unit_value` | `integer` | Yes | Numeric multiplier for the unit (e.g. 1000000 for 1M) |

---

## `ProducedMedia`

One asset produced by a generation run.

``resource_id`` is the canonical id the per-artifact download tools
accept (e.g. ``Scenario_Image_Download(image_id=resource_id)`` for
``modality="image"``). It maps to ``images_resource.id`` /
``videos_resource.id`` / ``audios_resource.id`` depending on the
modality.

| Field | Type | Required | Description |
|---|---|---|---|
| `modality` | `"image"` \| `"video"` \| `"audio"` | Yes | — |
| `resource_id` | `string` | Yes | — |
| `upload_id` | `string` | Yes | — |
| `mime_type` | `string` | No | — |
| `file_size` | `integer` | No | — |

---

## `ProfileSummary`

Caller identity derived from JWT — who you are on this page.

Superset of the old six-field version: now carries everything the client
needs so that ``/\{artifact\}/context`` fully replaces ``/profiles/context``
and the extra ``getLayoutContextData`` round-trip can be dropped.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Display name of the authenticated user |
| `role` | `string` | Yes | Role name (e.g. 'Super Administrator') |
| `role_level` | `integer` | Yes | Role hierarchy level (0 = highest privilege) |
| `department_ids` | `string`[] | Yes | Departments the user belongs to |
| `artifact_access` | `string`[] | Yes | Artifact types this role can access (sidebar visibility) |
| `role_permissions` | `any`[][] | Yes | Full (artifact, operation) permission tuples for granular page gating |
| `is_active` | `boolean` | Yes | Whether the user's profile is active |
| `id` | `string` | Yes | Profile UUID (SocketProvider, ProfileProvider) |
| `theme` | [`ThemeBundle`](#themebundle) | No | Resolved theme: hex primitives + derived oklch tokens + score thresholds |
| `session_id` | `string` | No | Current session UUID |
| `is_emulation` | `boolean` | No | Whether user is in emulation mode (ProfileProvider) |
| `role_resources` | [`QGetProfileContextV4RoleResource`](#qgetprofilecontextv4roleresource)[] | No | All role resources for emulation display (ProfileProvider) |
| `scoped_roles` | `string`[] | No | Roles the user can emulate (ProfileProvider) |
| `active` | `boolean` | No | Alias for is_active (ProfileProvider uses this name) |

---

## `QGetProfileContextV4RoleResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `role` | `string` | No | — |
| `name` | `string` | No | — |
| `description` | `string` | No | — |
| `icon_value` | `string` | No | — |
| `color_hex` | `string` | No | — |

---

## `RunStatus`

Outcome of one watched run.

| Field | Type | Required | Description |
|---|---|---|---|
| `run_id` | `string` | Yes | — |
| `status` | `"pending"` \| `"completed"` \| `"failed"` | Yes | — |
| `modality` | `string` | No | Modality of generated output (image, video, text…) |
| `resource_ids` | `string`[] | No | Resource UUIDs produced by this run (e.g. images_resource ids) |
| `error` | `string` | No | — |

---

## `TableInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Table name |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the table |

---

## `ThemeBundle`

Full theme payload for a page bootstrap.

Riding along on every ``/\{artifact\}/context`` response via
``ProfileSummary.theme``. Layers:
  - ``primitives`` / ``dark_primitives`` — hex inputs the settings
    editor reads/writes (light + dark palettes).
  - ``tokens`` / ``dark_tokens`` — oklch tokens the client paints with.
    ``ThemeStyle`` emits two ``<style>`` blocks: one scoped to
    ``:root:not(.dark)`` (light) and one to ``:root.dark`` (dark).
  - ``thresholds`` — numeric score thresholds for analytics components.
Empty-in → empty-out per token: missing values fall through to the
matching ``globals.css`` default.

| Field | Type | Required | Description |
|---|---|---|---|
| `primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (light palette, for the theme editor) |
| `tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for light mode (SSR CSS-var injection) |
| `dark_primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (dark palette, for the theme editor) |
| `dark_tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for dark mode (SSR CSS-var injection) |
| `thresholds` | [`Thresholds`](#thresholds) | No | Score thresholds resolved from the setting |

---

## `ThemePrimitives`

40 optional fields. The 17 essentials drive the rest; the other 23
are overrides for fine-tuning when derivation isn't what you want.

Empty primitive → empty token → client falls back to globals.css.

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `primary` | `string` | No | — |
| `accent` | `string` | No | — |
| `card` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `ring` | `string` | No | — |
| `border` | `string` | No | — |
| `destructive` | `string` | No | — |
| `success` | `string` | No | — |
| `warning` | `string` | No | — |
| `info` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `input` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `ThemeTokens`

40 fully-resolved CSS variable values (snake_case 1:1 with vars).

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `accent` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `border` | `string` | No | — |
| `input` | `string` | No | — |
| `ring` | `string` | No | — |
| `success` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `Thresholds`

Numeric score thresholds resolved from the active setting.

Server pre-buckets dashboard metrics into ``success | warning | danger |
neutral`` already, so most components don't need these values. Surface
them for chart reference lines, tooltips, and any client-side bucketing.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `integer` | Yes | Score >= this counts as success |
| `warning` | `integer` | Yes | Score >= this counts as warning |
| `danger` | `integer` | Yes | Score < success threshold but >= this counts as danger; below is neutral/no-data |

---

## `UpdateModelItem`

Single model item for update — model_id required, all fields optional.

Only provided fields are updated (partial update).

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | Target model identifier to update |
| `name_id` | `string` | No | Name resource identifier |
| `name` | `string` | No | Display name value |
| `description_id` | `string` | No | Description resource identifier |
| `description` | `string` | No | Description text value |
| `department_ids` | `string`[] | No | Department identifiers |
| `departments` | `string`[] | No | Department names to match |
| `flag_ids` | `string`[] | No | Flag option identifiers |
| `modality_ids` | `string`[] | No | Modality identifiers |
| `pricing_ids` | `string`[] | No | Pricing tier identifiers |
| `provider_id` | `string` | No | Provider identifier |
| `quality_ids` | `string`[] | No | Quality level identifiers |
| `reasoning_level_ids` | `string`[] | No | Reasoning level identifiers |
| `temperature_level_ids` | `string`[] | No | Temperature level identifiers |
| `value_id` | `string` | No | Value resource identifier |
| `voice_ids` | `string`[] | No | Voice identifiers |
| `model_ids` | `string`[] | No | Related model identifiers |

---

## `UpdateModelPatch`

Shared patch for bulk-update-all-matching mode.

Inherits every field from ``UpdateModelItem`` and just relaxes
``id`` to optional — the bulk impl stamps the resolved id onto a
clone of the patch per matched row, so any client-supplied id is
ignored. Sparse semantics: only fields the client sets are written.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Ignored — bulk impl stamps the resolved model id per matched row |
| `name_id` | `string` | No | Name resource identifier |
| `name` | `string` | No | Display name value |
| `description_id` | `string` | No | Description resource identifier |
| `description` | `string` | No | Description text value |
| `department_ids` | `string`[] | No | Department identifiers |
| `departments` | `string`[] | No | Department names to match |
| `flag_ids` | `string`[] | No | Flag option identifiers |
| `modality_ids` | `string`[] | No | Modality identifiers |
| `pricing_ids` | `string`[] | No | Pricing tier identifiers |
| `provider_id` | `string` | No | Provider identifier |
| `quality_ids` | `string`[] | No | Quality level identifiers |
| `reasoning_level_ids` | `string`[] | No | Reasoning level identifiers |
| `temperature_level_ids` | `string`[] | No | Temperature level identifiers |
| `value_id` | `string` | No | Value resource identifier |
| `voice_ids` | `string`[] | No | Voice identifiers |
| `model_ids` | `string`[] | No | Related model identifiers |

---

## `app__infra__model__types__DraftFormState`

| Field | Type | Required | Description |
|---|---|---|---|
| `name_id` | `string` | No | Resolved name resource identifier |
| `name` | `string` | No | Resolved name value |
| `description_id` | `string` | No | Resolved description resource identifier |
| `description` | `string` | No | Resolved description value |
| `value_id` | `string` | No | Resolved value resource identifier |
| `value` | `string` | No | Resolved model value |
| `provider_id` | `string` | No | Resolved provider identifier |
| `provider` | `string` | No | Resolved provider name |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs |
| `active` | `boolean` | No | Echoed model_active flag state |
| `modalities_enabled` | `boolean` | No | Echoed model_modalities_enabled flag state |
| `temperature_enabled` | `boolean` | No | Echoed model_temperature_enabled flag state |
| `pricing_enabled` | `boolean` | No | Echoed model_pricing_enabled flag state |
| `voices_enabled` | `boolean` | No | Echoed model_voices_enabled flag state |
| `reasoning_levels_enabled` | `boolean` | No | Echoed model_reasoning_levels_enabled flag state |
| `qualities_enabled` | `boolean` | No | Echoed model_qualities_enabled flag state |
| `department_ids` | `string`[] | No | Department identifiers |
| `modality_ids` | `string`[] | No | Modality identifiers |
| `pricing_ids` | `string`[] | No | Pricing tier identifiers |
| `pricing` | [`PricingDraftValue`](#pricingdraftvalue)[] | No | Resolved inline-created pricing entries (all ids filled in). |
| `quality_ids` | `string`[] | No | Quality level identifiers |
| `reasoning_level_ids` | `string`[] | No | Reasoning level identifiers |
| `temperature_level_ids` | `string`[] | No | Temperature level identifiers |
| `voice_ids` | `string`[] | No | Voice identifiers |
| `pending_ids` | `string`[] | No | Pending resource identifiers |

---

## `app__infra__model__types__SectionFilter`

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Filter options by search text |
| `limit` | `integer` | No | Max options to return |
| `selected` | `boolean` | No | Only return selected items |
| `suggested` | `boolean` | No | Only return suggested items |
| `include` | `boolean` | No | Include this section in response (default true) |

---

---

# `GET` `/oidc-callback`

Route: /api-reference/oidc-callback

# `GET` `/oidc-callback`

Oidc Callback

Handle Keycloak's redirect back after user authentication.

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `code` | query | No | — |
| `state` | query | No | — |
| `error` | query | No | — |
| `error_description` | query | No | — |

## Response

```
{}
```

---

# API Reference

Route: /api-reference

# API Reference

Every Glow HTTP endpoint, auto-generated from the platform's OpenAPI
spec — so these pages track the deployed API version (see
[`api-versions.json`](https://github.com/glow-academic/docs/blob/main/api-versions.json)).

Each resource (Agent, Attempt, Persona, Scenario, and the rest) has its
own section in the sidebar on the left; expand one to see its endpoints,
request and response shapes, and types. Or press <kbd>⌘ K</kbd> to
search straight to an endpoint.

Every endpoint authenticates with a bearer token — see
[Authentication](/authentication).

---

# `GET` `/parameter/watch`

Route: /api-reference/parameter/get-parameter-watch

# `GET` `/parameter/watch`

Parameter Watch

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `group_id` | query | No | — |
| `run_id` | query | No | Optional run filter. If provided, only events whose envelope run_id matches are streamed. Omit to receive every parameter event in the group (the FE default). |

## Response

```
{}
```

---

# `POST` `/parameter/call_download`

Route: /api-reference/parameter/post-parameter-call-download

# `POST` `/parameter/call_download`

Download Call

Download a call file by call resource ID.

## Request Body (`CallDownloadParameterApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `call_id` | `string` | Yes | UUID of the calls_resource to download |

## Response

```
{}
```

---

# `POST` `/parameter/context`

Route: /api-reference/parameter/post-parameter-context

# `POST` `/parameter/context`

Get Parameter Context

Get page context for the parameter artifact.

Returns docs + profile identity + evaluated permissions in a single call.
Superset of /docs — clients can migrate from /docs to /context incrementally.

## Request Body (`DocsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entity_id` | `string` | No | — |
| `snapshot_key` | `string` | No | — |
| `schema` | `boolean` | No | If true, include MCP/tooling schema metadata (artifact, entries, resources, permission_docs, api_operations). Defaults to false for lean page-bootstrap responses. |

## Response (`ComposedContextResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Artifact name |
| `type` | `string` | Yes | Artifact type identifier |
| `description` | `string` | Yes | Human-readable description |
| `artifact` | [`DocsResponse`](/api-reference/parameter/types#docsresponse) | No | Artifact tool documentation (None unless schema=true) |
| `entries` | [`DocsResponse`](/api-reference/parameter/types#docsresponse)[] | No | Entry documentation list (None unless schema=true) |
| `resources` | [`DocsResponse`](/api-reference/parameter/types#docsresponse)[] | No | Resource documentation list (None unless schema=true) |
| `permission_docs` | [`OperationInfo`](/api-reference/parameter/types#operationinfo)[] | No | Permission function signatures for MCP/dev tooling (None unless schema=true) |
| `api_operations` | [`OperationInfo`](/api-reference/parameter/types#operationinfo)[] | No | API operation documentation (None unless schema=true) |
| `page_metadata` | [`DocsApiResponse`](/api-reference/parameter/types#docsapiresponse) | No | Page-level metadata |
| `prompts` | [`OperationPrompts`](/api-reference/parameter/types#operationprompts) | No | Starter prompts keyed by operation |
| `profile` | [`ProfileSummary`](/api-reference/parameter/types#profilesummary) | Yes | Caller identity from JWT |
| `caller_permissions` | [`CallerPermissions`](/api-reference/parameter/types#callerpermissions) | Yes | Evaluated permissions for this caller |

---

# `POST` `/parameter/create`

Route: /api-reference/parameter/post-parameter-create

# `POST` `/parameter/create`

Create Parameter

Create parameters using composable infra architecture.

## Request Body (`CreateParameterApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `parameters` | [`CreateParameterItem`](/api-reference/parameter/types#createparameteritem)[] | Yes | List of parameters to create |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant create |
| `soft` | `boolean` | No | Stage the create dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`CreateParameterApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`ParameterResultItem`](/api-reference/parameter/types#parameterresultitem)[] | Yes | List of operation results |
| `parameters` | [`ListParameterApiParameter`](/api-reference/parameter/types#listparameterapiparameter)[] | No | Hydrated list rows for the just-created parameters — same shape as ``/parameter/search`` returns. Lets the client materialize the new rows directly from the response (or audit ``.completed`` payload) without a follow-up search burst. Omitted on the soft-pending (ack-shaped) paths — dormant rows aren't fully active until accepted. |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/parameter/csv`

Route: /api-reference/parameter/post-parameter-csv

# `POST` `/parameter/csv`

Parse Parameter Csv

Parse a CSV file and return mapped items for preview.

## Request Body

| Field | Type | Required | Description |
|---|---|---|---|
| `file` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `soft` | `boolean` | No | — |
| `accept` | `boolean` | No | — |

## Response (`ParseParameterCsvApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `upload_id` | `string` | Yes | — |
| `items` | [`CreateParameterItem`](/api-reference/parameter/types#createparameteritem)[] | Yes | — |
| `mapped_fields` | `string`[] | Yes | — |
| `row_count` | `integer` | Yes | — |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with `accept` to promote/reject the staged raw-CSV upload. NOTE: ack returns no items (the preview is only on the propose). |

---

# `POST` `/parameter/delete`

Route: /api-reference/parameter/post-parameter-delete

# `POST` `/parameter/delete`

Delete Parameter

Bulk delete parameters — composable infra architecture.

## Request Body (`DeleteParameterApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `parameter_ids` | `string`[] | No | UUIDs of parameters to delete (required on first call when ``all`` is false) |
| `all` | `boolean` | No | When true, delete every parameter matching the filter fields below (minus ``excluded_ids``) |
| `excluded_ids` | `string`[] | No | UUIDs to skip even when matched by ``all``-mode filters |
| `search` | `string` | No | Full-text search query |
| `scenario_ids` | `string`[] | No | Filter by scenario UUIDs |
| `field_ids` | `string`[] | No | Filter by field UUIDs |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `scenario_search` | `string` | No | Search text for scenario facet (no-op for row filtering) |
| `field_search` | `string` | No | Search text for field facet (no-op for row filtering) |
| `department_search` | `string` | No | Search text for department facet (no-op for row filtering) |
| `flag_search` | `string` | No | Search text for flag facet (no-op for row filtering) |
| `idempotency_key` | `string` | No | Operation key for ack — confirms or rejects a dormant delete |
| `soft` | `boolean` | No | Stage the delete dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (confirm deletion) or reject (restore). Only meaningful with idempotency_key |

## Response (`DeleteParameterApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`DeleteParameterResult`](/api-reference/parameter/types#deleteparameterresult)[] | Yes | List of deletion results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/parameter/draft`

Route: /api-reference/parameter/post-parameter-draft

# `POST` `/parameter/draft`

Patch Parameter Draft

Patch parameter draft — composable infra architecture.

## Request Body (`PatchParameterDraftApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `draft_id` | `string` | No | Existing draft ID to update |
| `input_draft_id` | `string` | No | Legacy alias for existing draft ID to update |
| `name` | `string` | No | Display name value |
| `name_id` | `string` | No | Name resource identifier |
| `description` | `string` | No | Description text value |
| `description_id` | `string` | No | Description resource identifier |
| `flag_ids` | `string`[] | No | Flag option identifiers |
| `department_ids` | `string`[] | No | Department identifiers |
| `field_ids` | `string`[] | No | Field identifiers |
| `departments` | `string`[] | No | Department names to resolve |
| `parameter_fields` | `string`[] | No | Parameter field names to resolve |
| `pending_ids` | `string`[] | No | Resource IDs to keep pending where supported |
| `idempotency_key` | `string` | No | Operation key for ack or retry |
| `soft` | `boolean` | No | Stage the draft dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept or reject dormant state |

## Response (`PatchParameterDraftApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the draft save succeeded |
| `draft_id` | `string` | Yes | Draft unique identifier |
| `idempotency_key` | `string` | Yes | Idempotency key for this draft operation |
| `message` | `string` | Yes | Result message |
| `form_state` | [`app__infra__parameter__types__DraftFormState`](/api-reference/parameter/types#app-infra-parameter-types-draftformstate) | No | Server-authoritative form state |

---

# `POST` `/parameter/drafts`

Route: /api-reference/parameter/post-parameter-drafts

# `POST` `/parameter/drafts`

Get Parameter Drafts

List parameter drafts owned by the current profile.

## Request Body (`GetParameterDraftsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE substring) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GetParameterDraftsApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entries` | [`GetParameterDraftResponse`](/api-reference/parameter/types#getparameterdraftresponse)[] | No | List of parameter draft entries |

---

# `POST` `/parameter/duplicate`

Route: /api-reference/parameter/post-parameter-duplicate

# `POST` `/parameter/duplicate`

Duplicate Parameter

Duplicate a parameter — composable infra architecture.

## Request Body (`DuplicateParameterApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `parameter_id` | `string` | Yes | Parameter identifier to duplicate |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant duplicate |
| `soft` | `boolean` | No | Stage the duplicate dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`DuplicateParameterApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the duplication succeeded |
| `parameter_id` | `string` | Yes | New duplicated parameter identifier |
| `message` | `string` | Yes | Result message |
| `parameters` | [`ListParameterApiParameter`](/api-reference/parameter/types#listparameterapiparameter)[] | No | Hydrated list row for the just-duplicated parameter — single-element list for shape consistency with create / update. Same shape as ``/parameter/search`` returns. Omitted on the soft-pending (ack-shaped) path. |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/parameter/export`

Route: /api-reference/parameter/post-parameter-export

# `POST` `/parameter/export`

Export Parameters

Export all parameters as a clean, denormalized CSV.

## Request Body (`ExportParameterApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `parameter_id` | `string` | No | Parameter identifier to export |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior export instead of re-running |
| `soft` | `boolean` | No | Stage the export dormant (active=False); ack with accept activates it |
| `accept` | `boolean` | No | Ack: True promotes the staged export, False rejects. Only meaningful with idempotency_key |

## Response (`ExportParameterApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource holding the export CSV |
| `file_name` | `string` | Yes | Suggested download file name |
| `row_count` | `integer` | Yes | Number of data rows in the export |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with `accept` to promote/reject the staged export. |

---

# `POST` `/parameter/file_download`

Route: /api-reference/parameter/post-parameter-file-download

# `POST` `/parameter/file_download`

Download File

Download a file by file resource ID.

## Request Body (`FileDownloadParameterApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource to download |

## Response

```
{}
```

---

# `POST` `/parameter/generate`

Route: /api-reference/parameter/post-parameter-generate

# `POST` `/parameter/generate`

Generate Parameter

Trigger parameter generation. Returns immediately; progress via events.

## Request Body (`ArtifactGenerateRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `instructions` | `string`[] | No | — |
| `config` | [`GenerateConfig`](/api-reference/parameter/types#generateconfig) | No | — |
| `modalities` | `string`[] | No | — |
| `audios_id` | `string` | No | — |
| `conversation_id` | `string` | No | — |
| `trace_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `accept` | `boolean` | No | — |
| `wait_for_complete` | `boolean` | No | — |

## Response (`ArtifactGenerateResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `run_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `eval` | [`EvalSetup`](/api-reference/parameter/types#evalsetup) | No | — |
| `produced_media` | [`ProducedMedia`](/api-reference/parameter/types#producedmedia)[] | No | — |

---

# `POST` `/parameter/generations`

Route: /api-reference/parameter/post-parameter-generations

# `POST` `/parameter/generations`

Generations Parameter

List parameter generation groups — composable infra architecture.

## Request Body (`GenerationsParameterApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GenerationsParameterApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `items` | [`GenerationsParameterListItem`](/api-reference/parameter/types#generationsparameterlistitem)[] | No | Generation groups |
| `total_count` | `integer` | No | Total number of matching generations |

---

# `POST` `/parameter/get`

Route: /api-reference/parameter/post-parameter-get

# `POST` `/parameter/get`

Get Parameter

Get parameter information using the canonical shared parameter operation.

## Request Body (`GetParameterApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Parameter unique identifier |
| `parameter_id` | `string` | No | Legacy alias for parameter unique identifier |
| `draft_id` | `string` | No | Draft unique identifier |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |
| `names` | [`app__infra__parameter__types__SectionFilter`](/api-reference/parameter/types#app-infra-parameter-types-sectionfilter) | No | Filter options for names section |
| `descriptions` | [`app__infra__parameter__types__SectionFilter`](/api-reference/parameter/types#app-infra-parameter-types-sectionfilter) | No | Filter options for descriptions section |
| `flags` | [`app__infra__parameter__types__SectionFilter`](/api-reference/parameter/types#app-infra-parameter-types-sectionfilter) | No | Filter options for flags section |
| `departments` | [`app__infra__parameter__types__SectionFilter`](/api-reference/parameter/types#app-infra-parameter-types-sectionfilter) | No | Filter options for departments section |
| `parameter_fields` | [`app__infra__parameter__types__SectionFilter`](/api-reference/parameter/types#app-infra-parameter-types-sectionfilter) | No | Filter options for parameter fields section |
| `fields` | [`app__infra__parameter__types__SectionFilter`](/api-reference/parameter/types#app-infra-parameter-types-sectionfilter) | No | Legacy alias for parameter_fields |

## Response (`GetParameterApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `parameter_exists` | `boolean` | No | Whether the parameter exists |
| `can_edit` | `boolean` | No | Whether the current user can edit |
| `disabled_reason` | `string` | No | Reason editing is disabled |
| `group_id` | `string` | No | Group identifier for the parameter |
| `draft_name` | `string` | No | Immutable draft label from the active draft entry, when a ``draft_id`` was supplied. ``None`` for non-draft fetches. |
| `show_ai_generate` | `boolean` | No | Show AI generate if any resource supports it |
| `basic_show_ai_generate` | `boolean` | No | Show AI generate for basic step |
| `fields_step_show_ai_generate` | `boolean` | No | Show AI generate for fields step |
| `pending_ids` | `string`[] | No | Pending resource identifiers when available |
| `names` | [`ParameterNameResource`](/api-reference/parameter/types#parameternameresource)[] | No | Name resources |
| `descriptions` | [`ParameterDescriptionResource`](/api-reference/parameter/types#parameterdescriptionresource)[] | No | Description resources |
| `flags` | [`ParameterFlagResource`](/api-reference/parameter/types#parameterflagresource)[] | No | Flag configs |
| `departments` | [`ParameterDepartmentResource`](/api-reference/parameter/types#parameterdepartmentresource)[] | No | Department resources |
| `parameter_fields` | [`ParameterFieldResource`](/api-reference/parameter/types#parameterfieldresource)[] | No | Parameter field resources |

---

# `POST` `/parameter/group`

Route: /api-reference/parameter/post-parameter-group

# `POST` `/parameter/group`

Group Parameter

Resolve or create a parameter group with optional naming.

## Request Body (`GroupParameterApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | No | Existing group UUID (omit to create or reuse via time window) |
| `snapshot_key` | `string` | No | Snapshot key for SETNX-race convergence on a single group across concurrent reads (e.g. parallel /context + /group + /search fan-out on page load). Echoed back in the response. |

## Response (`GroupParameterApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Resolved or newly created group UUID |
| `name` | `string` | No | The group's current title (latest active group_names_entry, or 'New Chat' fallback for freshly minted groups) |
| `snapshot_key` | `string` | No | Snapshot key echoed back — the UUID concurrent fan-out reads converged on via SETNX. Mirrors the resolved group_id. |
| `runs` | [`GroupRun`](/api-reference/parameter/types#grouprun)[] | No | Conversation history — populated when resolving an existing group for fetch |
| `group_exists` | `boolean` | No | (detail) Whether the group exists in storage — populated when ``include_resources=True`` |
| `actor_name` | `string` | No | (detail) Display name of the current actor (caller profile) |
| `total_message_count` | `integer` | No | (detail) Total number of messages in the group |
| `models` | [`GroupResource`](/api-reference/parameter/types#groupresource)[] | No | (detail) Models used in the group |
| `agents` | [`GroupResource`](/api-reference/parameter/types#groupresource)[] | No | (detail) Agents used in the group |
| `profiles` | [`GroupResource`](/api-reference/parameter/types#groupresource)[] | No | (detail) Profiles that authored runs in this group |

---

# `POST` `/parameter/problem`

Route: /api-reference/parameter/post-parameter-problem

# `POST` `/parameter/problem`

Problem Parameter

Report a parameter problem — composable infra architecture.

## Request Body (`ProblemParameterApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | `string` | Yes | Problem type: feature, bug, question, other |
| `message` | `string` | Yes | Problem description (max 1000 chars) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant problem |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`ProblemParameterApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `problem_id` | `string` | Yes | UUID of the created problem |
| `success` | `boolean` | No | Whether the problem was created |
| `message` | `string` | No | Status message |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/parameter/refresh`

Route: /api-reference/parameter/post-parameter-refresh

# `POST` `/parameter/refresh`

Parameter Refresh

Refresh parameter materialized views and invalidate caches.

## Request Body (`RefreshParameterApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `targets` | `string`[] | No | MV targets to refresh (omit for all). Options: parameter_drafts_mv, runs_mv, messages_mv, calls_mv, groups_mv, group_names_mv |
| `idempotency_key` | `string` | No | Operation key for ack |
| `accept` | `boolean` | No | Accept or reject. Only meaningful with idempotency_key |
| `soft` | `boolean` | No | Stage the refresh as a pending (held) request — recorded but not enqueued; ack with accept releases/enqueues it |

## Response (`RefreshResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | — |
| `refreshed_views` | `string`[] | Yes | — |
| `invalidated_tags` | `string`[] | Yes | — |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/parameter/search`

Route: /api-reference/parameter/post-parameter-search

# `POST` `/parameter/search`

Search Parameter

Search parameters — composable infra architecture.

## Request Body (`SearchParameterApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | — |
| `scenario_ids` | `string`[] | No | — |
| `field_ids` | `string`[] | No | — |
| `filter_department_ids` | `string`[] | No | — |
| `scenario_search` | `string` | No | — |
| `field_search` | `string` | No | — |
| `department_search` | `string` | No | — |
| `page_size` | `integer` | No | — |
| `page_offset` | `integer` | No | — |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`ListParameterApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `parameters` | [`ListParameterApiParameter`](/api-reference/parameter/types#listparameterapiparameter)[] | No | List of parameter entries |
| `scenario_filter` | [`ListFilterSection`](/api-reference/parameter/types#listfiltersection) | No | Scenario filter options |
| `field_filter` | [`ListFilterSection`](/api-reference/parameter/types#listfiltersection) | No | Field filter options |
| `department_filter` | [`ListFilterSection`](/api-reference/parameter/types#listfiltersection) | No | Department filter options |
| `flag_filter` | [`ListFilterSection`](/api-reference/parameter/types#listfiltersection) | No | Filter options for flags in list UI |
| `total_count` | `integer` | No | Total number of parameters |
| `import_fields` | [`ImportField`](/api-reference/parameter/types#importfield)[] | No | CSV import column schema for the bulk-import dialog |

---

# `POST` `/parameter/text_download`

Route: /api-reference/parameter/post-parameter-text-download

# `POST` `/parameter/text_download`

Download Text

Download a text file by text resource ID.

## Request Body (`TextDownloadParameterApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `text_id` | `string` | Yes | UUID of the texts_resource to download |

## Response

```
{}
```

---

# `POST` `/parameter/title`

Route: /api-reference/parameter/post-parameter-title

# `POST` `/parameter/title`

Title Parameter

Rename a parameter's group (writes group_names_entry).

## Request Body (`TitleParameterApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Group to rename |
| `title` | `string` | Yes | New title (display name) for the group |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant rename |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`TitleParameterApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | The group that was renamed |
| `group_name_id` | `string` | Yes | UUID of the new group_names_entry row |
| `title` | `string` | Yes | The title that was set |
| `idempotency_key` | `string` | No | Operation key echoed back |

---

# `POST` `/parameter/update`

Route: /api-reference/parameter/post-parameter-update

# `POST` `/parameter/update`

Update Parameter

Update parameters using composable infra architecture.

## Request Body (`UpdateParameterApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `parameters` | [`UpdateParameterItem`](/api-reference/parameter/types#updateparameteritem)[] | No | List of parameters to update (required on first call when ``all`` is false) |
| `all` | `boolean` | No | When true, apply ``patch`` to every parameter matching the filter fields below (minus ``excluded_ids``) |
| `excluded_ids` | `string`[] | No | UUIDs to skip even when matched by ``all``-mode filters |
| `patch` | [`UpdateParameterPatch`](/api-reference/parameter/types#updateparameterpatch) | No | Shared change set applied to every matched row when ``all=true`` (sparse — only set fields are updated; ``patch.id`` ignored) |
| `search` | `string` | No | Full-text search query |
| `scenario_ids` | `string`[] | No | Filter by scenario UUIDs |
| `field_ids` | `string`[] | No | Filter by field UUIDs |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `scenario_search` | `string` | No | Search text for scenario facet (no-op for row filtering) |
| `field_search` | `string` | No | Search text for field facet (no-op for row filtering) |
| `department_search` | `string` | No | Search text for department facet (no-op for row filtering) |
| `flag_search` | `string` | No | Search text for flag facet (no-op for row filtering) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant update |
| `soft` | `boolean` | No | Stage the update dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`UpdateParameterApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`ParameterResultItem`](/api-reference/parameter/types#parameterresultitem)[] | Yes | List of operation results |
| `parameters` | [`ListParameterApiParameter`](/api-reference/parameter/types#listparameterapiparameter)[] | No | Hydrated list rows for the just-updated parameters — same shape as ``/parameter/search`` returns. Lets the client patch in updated rows directly from the response without a follow-up search. Omitted on the soft-pending (ack-shaped) paths. |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/parameter/watch`

Route: /api-reference/parameter/post-parameter-watch

# `POST` `/parameter/watch`

Parameter Watch Once

One-shot snapshot of run state, snapshot-replayable via ``snapshot_key``.

## Request Body (`WatchApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Chat group whose events we watch |
| `run_id` | `string` | No | Specific run to watch (e.g. the ``run_id`` returned by a prior ``X_Generate`` call). If None, watches every active run in the group at call time. |
| `wait_for_complete` | `boolean` | No | If True, block until the watched run reaches a terminal (complete/failed) event or timeout fires. If False, return current state and exit immediately. |
| `timeout_seconds` | `integer` | No | Max wait time when ``wait_for_complete=True``. |
| `snapshot_key` | `string` | No | Read snapshot key — on the one-shot POST /watch, the audit wrapper records this watch's point-in-time view (latest run state at call time) keyed by it and replays the same view on any later call with the same key. Ignored by the SSE GET stream. |

## Response (`WatchApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `runs` | [`RunStatus`](/api-reference/parameter/types#runstatus)[] | Yes | — |
| `timed_out` | `boolean` | No | — |
| `waited_seconds` | `number` | No | — |

---

# Parameter Types

Route: /api-reference/parameter/types

# Parameter Types

## `CallerPermissions`

Evaluated permissions for the current caller on this artifact type.

| Field | Type | Required | Description |
|---|---|---|---|
| `can_create` | `boolean` | Yes | Whether the caller can create new artifacts |
| `can_draft` | `boolean` | Yes | Whether the caller can create/update drafts |
| `can_duplicate` | `boolean` | Yes | Whether the caller can duplicate artifacts |
| `has_access` | `boolean` | No | Whether the caller can view this entity |
| `can_edit` | `boolean` | No | Whether the caller can edit this entity |
| `can_delete` | `boolean` | No | Whether the caller can delete this entity |
| `disabled_reason` | `string` | No | Human-readable reason if editing is disabled |

---

## `ColumnInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Column name |
| `type` | `string` | Yes | Column data type |
| `nullable` | `boolean` | Yes | Whether the column is nullable |

---

## `CreateParameterItem`

Single parameter item for create — no parameter_id.

Required fields (name): provide ID or value.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Optional pre-assigned identifier |
| `resource_id` | `string` | No | Optional preset UUID for the resource snapshot |
| `name_id` | `string` | No | UUID of an existing name resource |
| `name` | `string` | No | REQUIRED FOR CREATE (or pass `name_id`) — display name text (creates new resource if name_id not provided) |
| `description_id` | `string` | No | UUID of an existing description resource |
| `description` | `string` | No | Description text value (creates new resource if description_id not provided) |
| `department_ids` | `string`[] | No | Department identifiers |
| `departments` | `string`[] | No | Department names to match |
| `flag_ids` | `string`[] | No | Flag option identifiers |
| `field_ids` | `string`[] | No | Field identifiers |
| `persona_parameter` | `boolean` | No | Show on persona edit page |
| `document_parameter` | `boolean` | No | Show on document edit page |
| `scenario_parameter` | `boolean` | No | Show on scenario edit page |
| `video_parameter` | `boolean` | No | Show on video edit page |

---

## `DeleteParameterResult`

Per-item result within a bulk delete response.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the deletion succeeded |
| `parameter_id` | `string` | No | Deleted parameter identifier (None for soft-skipped not-found rows) |
| `message` | `string` | Yes | Result message |

---

## `DocsApiResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `list` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `detail` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `new` | [`PageMetaItem`](#pagemetaitem) | Yes | — |

---

## `DocsResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Resource or entry name |
| `type` | `string` | Yes | Resource or entry type identifier |
| `description` | `string` | Yes | Human-readable description |
| `materialized_view` | [`MvInfo`](#mvinfo) | No | Materialized view metadata |
| `tables` | [`TableInfo`](#tableinfo)[] | Yes | Related database tables |
| `operations` | [`OperationInfo`](#operationinfo)[] | Yes | Available operations |

---

## `EvalSetup`

Run-level eval scaffold — first-class on the generate response.

Audit's ``**output`` spread carries this onto
``<artifact>.generate.completed``. Null when no rubric-bearing
agent participated.

| Field | Type | Required | Description |
|---|---|---|---|
| `test_id` | `string` | Yes | — |
| `invocations` | [`InvocationSlot`](#invocationslot)[] | Yes | — |

---

## `GenerateConfig`

Developer configuration — all optional with sensible defaults.

| Field | Type | Required | Description |
|---|---|---|---|
| `operations` | `string`[] | No | — |
| `dangerous` | `boolean` | No | — |
| `params` | `object` | No | — |
| `group_id` | `string` | No | — |

---

## `GenerationsParameterListItem`

Single generation group in the parameter generations response.

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | UUID of the generation group |
| `session_id` | `string` | No | UUID of the parent session |
| `group_name` | `string` | No | Name of the generation group |
| `created_at` | `string` | No | Timestamp of the generation |

---

## `GetParameterDraftResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | UUID of the draft |
| `created_at` | `string` | Yes | Creation timestamp |
| `generated` | `boolean` | Yes | Whether this was AI-generated |
| `mcp` | `boolean` | Yes | Whether MCP tooling was used |
| `active` | `boolean` | Yes | Whether this draft is active |
| `session_id` | `string` | Yes | Associated session UUID |
| `name` | `string` | No | Immutable draft label set at create time |
| `department_ids` | `string`[] | Yes | Associated department UUIDs |
| `description_ids` | `string`[] | Yes | Associated description UUIDs |
| `field_ids` | `string`[] | Yes | Associated field UUIDs |
| `flag_ids` | `string`[] | Yes | Associated flag UUIDs |
| `name_ids` | `string`[] | Yes | Associated name UUIDs |
| `profile_ids` | `string`[] | Yes | Associated profile UUIDs |
| `pending_department_ids` | `string`[] | No | Pending department UUIDs |
| `pending_description_ids` | `string`[] | No | Pending description UUIDs |
| `pending_field_ids` | `string`[] | No | Pending field UUIDs |
| `pending_flag_ids` | `string`[] | No | Pending flag UUIDs |
| `pending_name_ids` | `string`[] | No | Pending name UUIDs |

---

## `GroupCall`

Tool call referenced by a message.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `tool_name` | `string` | No | — |
| `template_name` | `string` | No | — |
| `tool` | `object` | No | — |
| `ledger_status` | `string` | No | — |
| `ledger_operation` | `string` | No | — |
| `ledger_artifact` | `string` | No | — |
| `ledger_artifact_id` | `string` | No | — |

---

## `GroupMessage`

Message within a run.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `role` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `text_ids` | `string`[] | No | — |
| `audio_ids` | `string`[] | No | — |
| `image_ids` | `string`[] | No | — |
| `video_ids` | `string`[] | No | — |
| `file_ids` | `string`[] | No | — |
| `call_ids` | `string`[] | No | — |
| `calls` | [`GroupCall`](#groupcall)[] | No | — |
| `reasoning` | `boolean` | No | True when this row is a chain-of-thought trace persisted alongside the assistant answer (rendered as a collapsed accordion). |
| `in_context` | `boolean` | No | Whether this message is included in the LLM context for the next generation. Mirrors the dedup pass that builds chat history (see in_context_reason). |
| `in_context_reason` | `string` | No | Why this message is in/out of LLM context. 'kept' = included; 'deduped_read' = older read-only call to a tool that has a fresher result later in the group; future values may include 'trimmed_top_n'. |

---

## `GroupResource`

Lightweight `\{id, name\}` for cross-referencing run-level ids
(``model_id`` / ``agent_id`` / ``profile_id``) against human-readable
names on the analytics panel. Names come from the canonical
``get_models`` / ``get_agents`` / ``get_profiles`` black boxes.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `name` | `string` | No | — |

---

## `GroupRun`

Run within a group, with its messages.

Carries token / cost / model / agent / profile attribution so the
analytics view can render per-run cost + actor info without a
parallel detail shape. ``profile_id`` is the authoring profile
(human user), ``agent_id`` is the LLM-side actor, ``model_id`` is
the model used by that agent. All optional — runs predating these
columns or with unresolved attributions surface ``None``.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `input_tokens` | `integer` | No | — |
| `output_tokens` | `integer` | No | — |
| `cached_input_tokens` | `integer` | No | — |
| `cost` | `number` | No | — |
| `model_id` | `string` | No | — |
| `agent_id` | `string` | No | — |
| `profile_id` | `string` | No | — |
| `previous_context_start_index` | `integer` | No | Index in ``messages`` where the current run's own messages begin; earlier rows are previous-context replay. ``None`` when the run has no previous context attached. |
| `messages` | [`GroupMessage`](#groupmessage)[] | No | — |

---

## `ImportField`

Field descriptor for CSV import column mapping.

| Field | Type | Required | Description |
|---|---|---|---|
| `key` | `string` | Yes | — |
| `label` | `string` | Yes | — |
| `required` | `boolean` | No | — |
| `multi` | `boolean` | No | — |
| `type` | `string` | No | — |
| `example` | `string` | No | — |
| `description` | `string` | No | — |

---

## `InvocationSlot`

One agent's slot in a multi-agent generation pool.

Populated by ``setup_generation_test`` when an agent carries a
rubric. The client uses these IDs to drive the eval workflow:
review the candidate's output, optionally fire a grader against
its ``invocation_id``, and promote/reject by call_id via the
existing ``idempotency_key + accept`` pattern.

| Field | Type | Required | Description |
|---|---|---|---|
| `invocation_id` | `string` | Yes | — |
| `agent_id` | `string` | Yes | — |
| `rubric_id` | `string` | No | — |

---

## `ListFilterOption`

Standardized option for list endpoint filter sections.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier for this filter option |
| `name` | `string` | No | Display name |
| `count` | `integer` | No | Number of matching records |
| `hex_code` | `string` | No | Hex color code for display |
| `value` | `string` | No | Internal value |
| `type` | `string` | No | Option type discriminator |

---

## `ListFilterSection`

Filter section with options and echoed request state.

| Field | Type | Required | Description |
|---|---|---|---|
| `options` | [`ListFilterOption`](#listfilteroption)[] | No | Available filter options |
| `selected_ids` | `string`[] | No | Currently selected filter option IDs |
| `search` | `string` | No | Active search text for filtering |

---

## `ListParameterApiParameter`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Parameter artifact UUID (canonical id; mirrors parameter_id) |
| `parameter_id` | `string` | No | Parameter unique identifier |
| `name` | `string` | No | Display name of the parameter |
| `description` | `string` | No | Parameter description text |
| `active` | `boolean` | No | Whether this parameter is currently active |
| `is_inactive` | `boolean` | No | Whether the parameter is inactive |
| `department_ids` | `string`[] | No | Associated department identifiers |
| `scenario_ids` | `string`[] | No | Associated scenario identifiers |
| `document_ids` | `string`[] | No | Associated document identifiers |
| `num_items` | `integer` | No | Number of items in this parameter |
| `sample_items` | `string`[] | No | Sample items for preview |
| `can_edit` | `boolean` | No | Whether the current user can edit |
| `can_duplicate` | `boolean` | No | Whether the current user can duplicate |
| `can_delete` | `boolean` | No | Whether the current user can delete |
| `updated_at` | `string` | No | Timestamp of last update |
| `pending_status` | `string` | No | Pending soft_calls_entry status (e.g. 'pending') |
| `pending_operation` | `string` | No | Pending operation (create/update/delete/duplicate) |
| `pending_call_id` | `string` | No | Originating tool call id for ack |

---

## `MvInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Materialized view name |
| `definition` | `string` | Yes | SQL definition of the view |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the view |

---

## `OperationInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Operation name |
| `description` | `string` | Yes | Human-readable description of the operation |
| `params` | [`ParamInfo`](#paraminfo)[] | Yes | List of operation parameters |
| `returns` | `object` | No | Return type schema |

---

## `OperationPrompts`

Starter prompts keyed by operation name.

Each key is an operation (e.g. "create", "search", "draft", "export")
and the value is a list of starter prompts for that operation.
The client picks from the operations the caller has permission for
and rotates through them.

| Field | Type | Required | Description |
|---|---|---|---|
| `prompts` | `object` | No | Map of operation name to starter prompts |

---

## `PageMetaItem`

| Field | Type | Required | Description |
|---|---|---|---|
| `title` | `string` | Yes | — |
| `description` | `string` | Yes | — |

---

## `ParamInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Parameter name |
| `type` | `string` | Yes | Parameter data type |
| `required` | `boolean` | Yes | Whether the parameter is required |
| `default` | `any` | No | Default value if not required |

---

## `ParameterDepartmentResource`

Department resource for parameter.

| Field | Type | Required | Description |
|---|---|---|---|
| `department_id` | `string` | No | Department identifier |
| `name` | `string` | No | Department name |
| `description` | `string` | No | Department description |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `ParameterDescriptionResource`

Description resource for parameter.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `description` | `string` | No | Description text |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `ParameterFieldError`

Per-field error from value resolution.

| Field | Type | Required | Description |
|---|---|---|---|
| `field` | `string` | Yes | Field name that caused the error |
| `message` | `string` | Yes | Error message describing the issue |

---

## `ParameterFieldResource`

Parameter field resource for parameter.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `field_id` | `string` | No | Associated field identifier |
| `parameter_id` | `string` | No | Parent parameter identifier |
| `name` | `string` | No | Field display name |
| `description` | `string` | No | Field description |
| `conditional_parameter_id` | `string` | No | Conditional parameter identifier |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `ParameterFlagResource`

Flag option row — one per (name, type, value) flags_resource entry.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Flag resource identifier |
| `name` | `string` | No | Flag display name |
| `type` | `string` | No | Flag type |
| `value` | `boolean` | No | Underlying bool value of this option |
| `description` | `string` | No | Flag description |
| `icon_id` | `string` | No | Icon identifier for the flag |
| `icon` | `string` | No | Resolved SVG markup for the icon (hydrated from icons_resource) |
| `generated` | `boolean` | No | Whether this flag was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `ParameterNameResource`

Name resource for parameter.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `name` | `string` | No | Display name |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `ParameterResultItem`

Per-item result within a bulk create/update response.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `parameter_id` | `string` | No | Parameter unique identifier |
| `message` | `string` | Yes | Result message |
| `errors` | [`ParameterFieldError`](#parameterfielderror)[] | No | List of field-level errors |

---

## `ProducedMedia`

One asset produced by a generation run.

``resource_id`` is the canonical id the per-artifact download tools
accept (e.g. ``Scenario_Image_Download(image_id=resource_id)`` for
``modality="image"``). It maps to ``images_resource.id`` /
``videos_resource.id`` / ``audios_resource.id`` depending on the
modality.

| Field | Type | Required | Description |
|---|---|---|---|
| `modality` | `"image"` \| `"video"` \| `"audio"` | Yes | — |
| `resource_id` | `string` | Yes | — |
| `upload_id` | `string` | Yes | — |
| `mime_type` | `string` | No | — |
| `file_size` | `integer` | No | — |

---

## `ProfileSummary`

Caller identity derived from JWT — who you are on this page.

Superset of the old six-field version: now carries everything the client
needs so that ``/\{artifact\}/context`` fully replaces ``/profiles/context``
and the extra ``getLayoutContextData`` round-trip can be dropped.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Display name of the authenticated user |
| `role` | `string` | Yes | Role name (e.g. 'Super Administrator') |
| `role_level` | `integer` | Yes | Role hierarchy level (0 = highest privilege) |
| `department_ids` | `string`[] | Yes | Departments the user belongs to |
| `artifact_access` | `string`[] | Yes | Artifact types this role can access (sidebar visibility) |
| `role_permissions` | `any`[][] | Yes | Full (artifact, operation) permission tuples for granular page gating |
| `is_active` | `boolean` | Yes | Whether the user's profile is active |
| `id` | `string` | Yes | Profile UUID (SocketProvider, ProfileProvider) |
| `theme` | [`ThemeBundle`](#themebundle) | No | Resolved theme: hex primitives + derived oklch tokens + score thresholds |
| `session_id` | `string` | No | Current session UUID |
| `is_emulation` | `boolean` | No | Whether user is in emulation mode (ProfileProvider) |
| `role_resources` | [`QGetProfileContextV4RoleResource`](#qgetprofilecontextv4roleresource)[] | No | All role resources for emulation display (ProfileProvider) |
| `scoped_roles` | `string`[] | No | Roles the user can emulate (ProfileProvider) |
| `active` | `boolean` | No | Alias for is_active (ProfileProvider uses this name) |

---

## `QGetProfileContextV4RoleResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `role` | `string` | No | — |
| `name` | `string` | No | — |
| `description` | `string` | No | — |
| `icon_value` | `string` | No | — |
| `color_hex` | `string` | No | — |

---

## `RunStatus`

Outcome of one watched run.

| Field | Type | Required | Description |
|---|---|---|---|
| `run_id` | `string` | Yes | — |
| `status` | `"pending"` \| `"completed"` \| `"failed"` | Yes | — |
| `modality` | `string` | No | Modality of generated output (image, video, text…) |
| `resource_ids` | `string`[] | No | Resource UUIDs produced by this run (e.g. images_resource ids) |
| `error` | `string` | No | — |

---

## `TableInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Table name |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the table |

---

## `ThemeBundle`

Full theme payload for a page bootstrap.

Riding along on every ``/\{artifact\}/context`` response via
``ProfileSummary.theme``. Layers:
  - ``primitives`` / ``dark_primitives`` — hex inputs the settings
    editor reads/writes (light + dark palettes).
  - ``tokens`` / ``dark_tokens`` — oklch tokens the client paints with.
    ``ThemeStyle`` emits two ``<style>`` blocks: one scoped to
    ``:root:not(.dark)`` (light) and one to ``:root.dark`` (dark).
  - ``thresholds`` — numeric score thresholds for analytics components.
Empty-in → empty-out per token: missing values fall through to the
matching ``globals.css`` default.

| Field | Type | Required | Description |
|---|---|---|---|
| `primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (light palette, for the theme editor) |
| `tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for light mode (SSR CSS-var injection) |
| `dark_primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (dark palette, for the theme editor) |
| `dark_tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for dark mode (SSR CSS-var injection) |
| `thresholds` | [`Thresholds`](#thresholds) | No | Score thresholds resolved from the setting |

---

## `ThemePrimitives`

40 optional fields. The 17 essentials drive the rest; the other 23
are overrides for fine-tuning when derivation isn't what you want.

Empty primitive → empty token → client falls back to globals.css.

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `primary` | `string` | No | — |
| `accent` | `string` | No | — |
| `card` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `ring` | `string` | No | — |
| `border` | `string` | No | — |
| `destructive` | `string` | No | — |
| `success` | `string` | No | — |
| `warning` | `string` | No | — |
| `info` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `input` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `ThemeTokens`

40 fully-resolved CSS variable values (snake_case 1:1 with vars).

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `accent` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `border` | `string` | No | — |
| `input` | `string` | No | — |
| `ring` | `string` | No | — |
| `success` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `Thresholds`

Numeric score thresholds resolved from the active setting.

Server pre-buckets dashboard metrics into ``success | warning | danger |
neutral`` already, so most components don't need these values. Surface
them for chart reference lines, tooltips, and any client-side bucketing.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `integer` | Yes | Score >= this counts as success |
| `warning` | `integer` | Yes | Score >= this counts as warning |
| `danger` | `integer` | Yes | Score < success threshold but >= this counts as danger; below is neutral/no-data |

---

## `UpdateParameterItem`

Single parameter item for update — parameter_id required, all fields optional.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | Target parameter identifier to update |
| `name_id` | `string` | No | Name resource identifier |
| `name` | `string` | No | Display name value |
| `description_id` | `string` | No | Description resource identifier |
| `description` | `string` | No | Description text value |
| `department_ids` | `string`[] | No | Department identifiers |
| `departments` | `string`[] | No | Department names to match |
| `flag_ids` | `string`[] | No | Flag option identifiers |
| `field_ids` | `string`[] | No | Field identifiers |

---

## `UpdateParameterPatch`

Shared patch for bulk-update-all-matching mode.

Inherits every field from ``UpdateParameterItem`` and just relaxes
``id`` to optional — the bulk impl stamps the resolved id onto a
clone of the patch per matched row, so any client-supplied id is
ignored. Sparse semantics: only fields the client sets are written.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Ignored — bulk impl stamps the resolved parameter id per matched row |
| `name_id` | `string` | No | Name resource identifier |
| `name` | `string` | No | Display name value |
| `description_id` | `string` | No | Description resource identifier |
| `description` | `string` | No | Description text value |
| `department_ids` | `string`[] | No | Department identifiers |
| `departments` | `string`[] | No | Department names to match |
| `flag_ids` | `string`[] | No | Flag option identifiers |
| `field_ids` | `string`[] | No | Field identifiers |

---

## `app__infra__parameter__types__DraftFormState`

Server-authoritative form state returned after draft save.

| Field | Type | Required | Description |
|---|---|---|---|
| `name_id` | `string` | No | Resolved name resource identifier |
| `name` | `string` | No | Echoed name value |
| `description_id` | `string` | No | Resolved description resource identifier |
| `description` | `string` | No | Echoed description value |
| `flag_ids` | `string`[] | Yes | Flag option identifiers |
| `department_ids` | `string`[] | Yes | Department identifiers |
| `field_ids` | `string`[] | Yes | Field identifiers |
| `pending_ids` | `string`[] | No | Pending resource identifiers |

---

## `app__infra__parameter__types__SectionFilter`

Per-section filter options for GET requests.

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Filter options by search text |
| `limit` | `integer` | No | Max options to return |
| `selected` | `boolean` | No | Only return selected items |
| `suggested` | `boolean` | No | Only return suggested items |
| `include` | `boolean` | No | Include this section in response (default true) |
| `parameter_ids` | `string`[] | No | Parameter group IDs to filter by (parameter_fields section only) |

---

---

# `GET` `/persona/watch`

Route: /api-reference/persona/get-persona-watch

# `GET` `/persona/watch`

Persona Watch

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `group_id` | query | No | — |
| `run_id` | query | No | Optional run filter. If provided, only events whose envelope run_id matches are streamed. Omit to receive every persona event in the group (the FE default). |

## Response

```
{}
```

---

# `POST` `/persona/call_download`

Route: /api-reference/persona/post-persona-call-download

# `POST` `/persona/call_download`

Download Call

Download a call file by call resource ID.

## Request Body (`CallDownloadPersonaApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `call_id` | `string` | Yes | UUID of the calls_resource to download |

## Response

```
{}
```

---

# `POST` `/persona/context`

Route: /api-reference/persona/post-persona-context

# `POST` `/persona/context`

Get Persona Context

Get page context for the persona artifact.

Returns docs + profile identity + evaluated permissions in a single call.
Superset of /docs — clients can migrate from /docs to /context incrementally.

## Request Body (`DocsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entity_id` | `string` | No | — |
| `snapshot_key` | `string` | No | — |
| `schema` | `boolean` | No | If true, include MCP/tooling schema metadata (artifact, entries, resources, permission_docs, api_operations). Defaults to false for lean page-bootstrap responses. |

## Response (`ComposedContextResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Artifact name |
| `type` | `string` | Yes | Artifact type identifier |
| `description` | `string` | Yes | Human-readable description |
| `artifact` | [`DocsResponse`](/api-reference/persona/types#docsresponse) | No | Artifact tool documentation (None unless schema=true) |
| `entries` | [`DocsResponse`](/api-reference/persona/types#docsresponse)[] | No | Entry documentation list (None unless schema=true) |
| `resources` | [`DocsResponse`](/api-reference/persona/types#docsresponse)[] | No | Resource documentation list (None unless schema=true) |
| `permission_docs` | [`OperationInfo`](/api-reference/persona/types#operationinfo)[] | No | Permission function signatures for MCP/dev tooling (None unless schema=true) |
| `api_operations` | [`OperationInfo`](/api-reference/persona/types#operationinfo)[] | No | API operation documentation (None unless schema=true) |
| `page_metadata` | [`DocsApiResponse`](/api-reference/persona/types#docsapiresponse) | No | Page-level metadata |
| `prompts` | [`OperationPrompts`](/api-reference/persona/types#operationprompts) | No | Starter prompts keyed by operation |
| `profile` | [`ProfileSummary`](/api-reference/persona/types#profilesummary) | Yes | Caller identity from JWT |
| `caller_permissions` | [`CallerPermissions`](/api-reference/persona/types#callerpermissions) | Yes | Evaluated permissions for this caller |

---

# `POST` `/persona/create`

Route: /api-reference/persona/post-persona-create

# `POST` `/persona/create`

Create Persona

Create personas using composable infra architecture.

## Request Body (`CreatePersonaApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `personas` | [`CreatePersonaItem`](/api-reference/persona/types#createpersonaitem)[] | No | List of persona items to create (required on first call) |
| `idempotency_key` | `string` | No | Idempotency key — safe-retry replay on the first call; ack of a dormant create when sent with accept |
| `soft` | `boolean` | No | Stage the create dormant (active=False) — propose; the response echoes a server key to ack with (\{idempotency_key, accept\}) |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`CreatePersonaApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`PersonaResultItem`](/api-reference/persona/types#personaresultitem)[] | Yes | Per-persona creation results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |
| `personas` | [`ListPersonaApiPersona`](/api-reference/persona/types#listpersonaapipersona)[] | No | Hydrated rows for the successfully-created personas (mirrors /persona/search shape) |

---

# `POST` `/persona/csv`

Route: /api-reference/persona/post-persona-csv

# `POST` `/persona/csv`

Parse Persona Csv

Parse a CSV file and return mapped items for preview (soft/accept on the raw upload).

## Request Body

| Field | Type | Required | Description |
|---|---|---|---|
| `file` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `soft` | `boolean` | No | — |
| `accept` | `boolean` | No | — |

## Response (`ParsePersonaCsvApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `upload_id` | `string` | Yes | UUID of the uploaded CSV file |
| `items` | [`CreatePersonaItem`](/api-reference/persona/types#createpersonaitem)[] | Yes | Parsed persona items for preview |
| `mapped_fields` | `string`[] | Yes | Column keys that were auto-mapped |
| `row_count` | `integer` | Yes | Number of data rows parsed |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with `accept` to promote/reject the staged raw-CSV upload. NOTE: ack returns no items (the preview is only on the propose). |

---

# `POST` `/persona/delete`

Route: /api-reference/persona/post-persona-delete

# `POST` `/persona/delete`

Delete Persona

Bulk delete personas — composable infra architecture.

## Request Body (`DeletePersonaApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `ids` | `string`[] | No | List of persona UUIDs to delete (required on first call when ``all`` is false) |
| `all` | `boolean` | No | When true, delete every persona matching the filter fields below (minus ``excluded_ids``) |
| `excluded_ids` | `string`[] | No | UUIDs to skip even when matched by ``all``-mode filters |
| `search` | `string` | No | Full-text search query |
| `scenario_ids` | `string`[] | No | Filter by scenario UUIDs |
| `field_ids` | `string`[] | No | Filter by field UUIDs |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `scenario_search` | `string` | No | Search text for scenario facet (no-op for row filtering) |
| `field_search` | `string` | No | Search text for field facet (no-op for row filtering) |
| `department_search` | `string` | No | Search text for department facet (no-op for row filtering) |
| `color_search` | `string` | No | Search text for color facet (no-op for row filtering) |
| `icon_search` | `string` | No | Search text for icon facet (no-op for row filtering) |
| `voice_search` | `string` | No | Search text for voice facet (no-op for row filtering) |
| `instruction_search` | `string` | No | Search text for instruction facet (no-op for row filtering) |
| `idempotency_key` | `string` | No | Operation key for ack — confirms or rejects a dormant delete |
| `soft` | `boolean` | No | Stage the delete dormant — propose; the ack (\{idempotency_key, accept\}) confirms/rejects it |
| `accept` | `boolean` | No | Accept (confirm deletion) or reject (restore). Only meaningful with idempotency_key |

## Response (`DeletePersonaApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`DeletePersonaResult`](/api-reference/persona/types#deletepersonaresult)[] | Yes | Per-persona deletion results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/persona/draft`

Route: /api-reference/persona/post-persona-draft

# `POST` `/persona/draft`

Patch Persona Draft

Patch persona draft — composable infra architecture.

## Request Body (`PatchPersonaDraftApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `draft_id` | `string` | No | Existing draft UUID to patch (omit to create a new draft) |
| `name` | `string` | No | Display name text (creates new name resource) |
| `name_id` | `string` | No | UUID of an existing name resource to select |
| `description` | `string` | No | Description text (creates new description resource) |
| `description_id` | `string` | No | UUID of an existing description resource to select |
| `color` | `string` | No | Hex color code (creates new resource if color_id not provided) |
| `color_id` | `string` | No | UUID of a color resource to select |
| `icon` | `string` | No | Resolved SVG markup for the icon (hydrated from icons_resource) |
| `icon_id` | `string` | No | UUID of an icon resource to select |
| `instructions` | `string` | No | Instruction template text (creates new instruction resource) |
| `instructions_id` | `string` | No | UUID of an existing instruction resource to select |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `active` | `boolean` | No | Denormalized persona_active flag state; resolved to a flag_ids entry server-side |
| `examples` | `string`[] | No | Example texts (creates new example resources) |
| `example_ids` | `string`[] | No | Existing example resource UUIDs to select |
| `department_ids` | `string`[] | No | Department UUIDs to associate |
| `departments` | `string`[] | No | Department names (resolved to UUIDs server-side) |
| `parameter_field_ids` | `string`[] | No | Parameter field UUIDs to associate |
| `parameter_fields` | `string`[] | No | Parameter field names (resolved to UUIDs server-side) |
| `voice_ids` | `string`[] | No | Voice resource UUIDs to associate |
| `voices` | `string`[] | No | Voice values (resolved to UUIDs server-side) |
| `pending_ids` | `string`[] | No | Resource IDs to keep as pending (active=false on connection) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant draft |
| `soft` | `boolean` | No | Stage the draft dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`PatchPersonaDraftApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the draft operation succeeded |
| `draft_id` | `string` | Yes | UUID of the created or updated draft |
| `idempotency_key` | `string` | Yes | Idempotency key for this draft operation (same as draft entry ID) |
| `message` | `string` | Yes | Human-readable result message |
| `form_state` | [`app__infra__persona__types__DraftFormState`](/api-reference/persona/types#app-infra-persona-types-draftformstate) | Yes | Complete form state after patch — client should replace local state |

---

# `POST` `/persona/drafts`

Route: /api-reference/persona/post-persona-drafts

# `POST` `/persona/drafts`

Get Persona Drafts

List persona drafts owned by the current profile.

## Request Body (`GetPersonaDraftsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE substring) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GetPersonaDraftsApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entries` | [`GetPersonaDraftResponse`](/api-reference/persona/types#getpersonadraftresponse)[] | No | List of persona drafts |

---

# `POST` `/persona/duplicate`

Route: /api-reference/persona/post-persona-duplicate

# `POST` `/persona/duplicate`

Duplicate Persona

Duplicate a persona — composable infra architecture.

## Request Body (`DuplicatePersonaApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | UUID of the persona to duplicate (required on first call) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant duplicate |
| `soft` | `boolean` | No | Stage the duplicate dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`DuplicatePersonaApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the duplication succeeded |
| `id` | `string` | Yes | UUID of the newly created duplicate persona |
| `message` | `string` | Yes | Human-readable result message |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |
| `personas` | [`ListPersonaApiPersona`](/api-reference/persona/types#listpersonaapipersona)[] | No | Hydrated row for the newly-created duplicate persona (single-element list) |

---

# `POST` `/persona/export`

Route: /api-reference/persona/post-persona-export

# `POST` `/persona/export`

Export Personas

Export all personas as a clean, denormalized CSV.

## Request Body (`ExportPersonaApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `persona_id` | `string` | No | UUID of a specific persona to export (omit for bulk export) |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior export instead of re-running |
| `soft` | `boolean` | No | Stage the export dormant (active=False); ack with accept activates it |
| `accept` | `boolean` | No | Ack: True promotes the staged export, False rejects. Only meaningful with idempotency_key |
| `search` | `string` | No | Filter personas by search text |
| `scenario_ids` | `string`[] | No | Filter to personas used in these scenarios |
| `field_ids` | `string`[] | No | Filter to personas with these fields |
| `filter_department_ids` | `string`[] | No | Filter to personas in these departments |

## Response (`ExportPersonaApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource holding the export CSV |
| `file_name` | `string` | Yes | Suggested download file name |
| `row_count` | `integer` | Yes | Number of data rows in the export |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with `accept` to promote/reject the staged export. |

---

# `POST` `/persona/file_download`

Route: /api-reference/persona/post-persona-file-download

# `POST` `/persona/file_download`

Download File

Download a file by file resource ID.

## Request Body (`FileDownloadPersonaApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource to download |

## Response

```
{}
```

---

# `POST` `/persona/generate`

Route: /api-reference/persona/post-persona-generate

# `POST` `/persona/generate`

Generate Persona

Trigger persona generation. Returns immediately; progress via events.

## Request Body (`ArtifactGenerateRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `instructions` | `string`[] | No | — |
| `config` | [`GenerateConfig`](/api-reference/persona/types#generateconfig) | No | — |
| `modalities` | `string`[] | No | — |
| `audios_id` | `string` | No | — |
| `conversation_id` | `string` | No | — |
| `trace_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `accept` | `boolean` | No | — |
| `wait_for_complete` | `boolean` | No | — |

## Response (`ArtifactGenerateResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `run_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `eval` | [`EvalSetup`](/api-reference/persona/types#evalsetup) | No | — |
| `produced_media` | [`ProducedMedia`](/api-reference/persona/types#producedmedia)[] | No | — |

---

# `POST` `/persona/generations`

Route: /api-reference/persona/post-persona-generations

# `POST` `/persona/generations`

Generations Persona

List persona generation groups — composable infra architecture.

## Request Body (`GenerationsPersonaApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |
| `search` | `string` | No | Name search (ILIKE) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |

## Response (`GenerationsPersonaApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `items` | [`GenerationsPersonaListItem`](/api-reference/persona/types#generationspersonalistitem)[] | No | Generation groups |
| `total_count` | `integer` | No | Total number of matching generations |

---

# `POST` `/persona/get`

Route: /api-reference/persona/post-persona-get

# `POST` `/persona/get`

Get Persona

Get persona information using the canonical shared persona operation.

## Request Body (`GetPersonaApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | UUID of the persona to retrieve |
| `draft_id` | `string` | No | UUID of the draft to load instead of published state |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |
| `names` | [`app__infra__persona__types__SectionFilter`](/api-reference/persona/types#app-infra-persona-types-sectionfilter) | No | Filter options for names section |
| `descriptions` | [`app__infra__persona__types__SectionFilter`](/api-reference/persona/types#app-infra-persona-types-sectionfilter) | No | Filter options for descriptions section |
| `colors` | [`app__infra__persona__types__SectionFilter`](/api-reference/persona/types#app-infra-persona-types-sectionfilter) | No | Filter options for colors section |
| `icons` | [`app__infra__persona__types__SectionFilter`](/api-reference/persona/types#app-infra-persona-types-sectionfilter) | No | Filter options for icons section |
| `instructions` | [`app__infra__persona__types__SectionFilter`](/api-reference/persona/types#app-infra-persona-types-sectionfilter) | No | Filter options for instructions section |
| `departments` | [`app__infra__persona__types__SectionFilter`](/api-reference/persona/types#app-infra-persona-types-sectionfilter) | No | Filter options for departments section |
| `examples` | [`app__infra__persona__types__SectionFilter`](/api-reference/persona/types#app-infra-persona-types-sectionfilter) | No | Filter options for examples section |
| `parameter_fields` | [`app__infra__persona__types__SectionFilter`](/api-reference/persona/types#app-infra-persona-types-sectionfilter) | No | Filter options for parameter fields section |
| `voices` | [`app__infra__persona__types__SectionFilter`](/api-reference/persona/types#app-infra-persona-types-sectionfilter) | No | Filter options for voices section |

## Response (`GetPersonaApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the authenticated user |
| `persona_exists` | `boolean` | No | Whether the requested persona exists |
| `can_edit` | `boolean` | No | Whether the current user has edit permission |
| `disabled_reason` | `string` | No | Human-readable reason if editing is disabled |
| `group_id` | `string` | No | Generation group UUID for AI operations |
| `draft_name` | `string` | No | Immutable draft label from the active draft entry, when a ``draft_id`` was supplied. ``None`` for non-draft fetches. The FE uses this to show the draft name in the SaveToolbar trigger. |
| `show_ai_generate` | `boolean` | No | Whether AI generation is available |
| `names` | [`PersonaNameResource`](/api-reference/persona/types#personanameresource)[] | No | Name resources with selected/suggested flags |
| `descriptions` | [`PersonaDescriptionResource`](/api-reference/persona/types#personadescriptionresource)[] | No | Description resources with selected/suggested flags |
| `colors` | [`PersonaColorResource`](/api-reference/persona/types#personacolorresource)[] | No | Color resources with selected/suggested flags |
| `icons` | [`PersonaIconResource`](/api-reference/persona/types#personaiconresource)[] | No | Icon resources with selected/suggested flags |
| `instructions` | [`PersonaInstructionResource`](/api-reference/persona/types#personainstructionresource)[] | No | Instruction resources with selected/suggested flags |
| `flags` | [`PersonaFlagResource`](/api-reference/persona/types#personaflagresource)[] | No | Flag resources (one per flags_resource row, value=true/false) |
| `departments` | [`PersonaDepartmentResource`](/api-reference/persona/types#personadepartmentresource)[] | No | Department resources with selected/suggested flags |
| `parameter_fields` | [`PersonaParameterFieldResource`](/api-reference/persona/types#personaparameterfieldresource)[] | No | Parameter field resources with selected/suggested flags |
| `examples` | [`PersonaExampleResource`](/api-reference/persona/types#personaexampleresource)[] | No | Example resources with selected/suggested flags |
| `parameters` | `any`[] | No | Parameter resources |
| `voices` | [`PersonaVoiceResource`](/api-reference/persona/types#personavoiceresource)[] | No | Voice resources with selected/suggested flags |
| `fields` | [`GetFieldResponse`](/api-reference/persona/types#getfieldresponse)[] | No | All available field definitions (computed, never saved) |
| `resolved_parameter_ids` | `string`[] | No | Parameter IDs derived from saved parameter_fields |

---

# `POST` `/persona/group`

Route: /api-reference/persona/post-persona-group

# `POST` `/persona/group`

Group Persona

Resolve or create a persona group with optional naming.

## Request Body (`GroupPersonaApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | No | Existing group UUID (omit to create or reuse via time window) |
| `snapshot_key` | `string` | No | Snapshot key for SETNX-race convergence on a single group across concurrent reads (e.g. parallel /context + /group + /search fan-out on page load). Echoed back in the response. |

## Response (`GroupPersonaApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Resolved or newly created group UUID |
| `name` | `string` | No | The group's current title (latest active group_names_entry, or 'New Chat' fallback for freshly minted groups) |
| `snapshot_key` | `string` | No | Snapshot key echoed back — the UUID concurrent fan-out reads converged on via SETNX. Mirrors the resolved group_id. |
| `runs` | [`GroupRun`](/api-reference/persona/types#grouprun)[] | No | Conversation history — populated when resolving an existing group for fetch |
| `group_exists` | `boolean` | No | (detail) Whether the group exists in storage — populated when ``include_resources=True`` |
| `actor_name` | `string` | No | (detail) Display name of the current actor (caller profile) |
| `total_message_count` | `integer` | No | (detail) Total number of messages in the group |
| `models` | [`GroupResource`](/api-reference/persona/types#groupresource)[] | No | (detail) Models used in the group |
| `agents` | [`GroupResource`](/api-reference/persona/types#groupresource)[] | No | (detail) Agents used in the group |
| `profiles` | [`GroupResource`](/api-reference/persona/types#groupresource)[] | No | (detail) Profiles that authored runs in this group |

---

# `POST` `/persona/problem`

Route: /api-reference/persona/post-persona-problem

# `POST` `/persona/problem`

Problem Persona

Report a persona problem — composable infra architecture.

## Request Body (`ProblemPersonaApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | `string` | No | Problem type: feature, bug, question, other (required on first call) |
| `message` | `string` | No | Problem description, max 1000 chars (required on first call) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant problem |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`ProblemPersonaApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `problem_id` | `string` | Yes | UUID of the created problem |
| `success` | `boolean` | No | Whether the problem was created |
| `message` | `string` | No | Status message |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/persona/refresh`

Route: /api-reference/persona/post-persona-refresh

# `POST` `/persona/refresh`

Persona Refresh

Refresh persona materialized views and invalidate caches.

## Request Body (`RefreshPersonaApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `targets` | `string`[] | No | MV targets to refresh (omit for all). Options: personas_mv, persona_drafts_mv |
| `idempotency_key` | `string` | No | Operation key for ack |
| `accept` | `boolean` | No | Accept or reject. Only meaningful with idempotency_key |
| `soft` | `boolean` | No | Stage the refresh as a pending (held) request — recorded but not enqueued; ack with accept releases/enqueues it |

## Response (`RefreshResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | — |
| `refreshed_views` | `string`[] | Yes | — |
| `invalidated_tags` | `string`[] | Yes | — |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/persona/search`

Route: /api-reference/persona/post-persona-search

# `POST` `/persona/search`

Search Persona

Search personas — composable infra architecture.

## Request Body (`SearchPersonaApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |
| `search` | `string` | No | Full-text search query for personas |
| `scenario_ids` | `string`[] | No | Filter by scenario UUIDs |
| `field_ids` | `string`[] | No | Filter by field UUIDs |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `scenario_search` | `string` | No | Search text for scenario facet |
| `field_search` | `string` | No | Search text for field facet |
| `department_search` | `string` | No | Search text for department facet |
| `color_search` | `string` | No | Search text for color facet |
| `icon_search` | `string` | No | Search text for icon facet |
| `voice_search` | `string` | No | Search text for voice facet |
| `instruction_search` | `string` | No | Search text for instruction facet |
| `page_size` | `integer` | No | Number of results per page |
| `page_offset` | `integer` | No | Pagination offset |

## Response (`ListPersonaApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the authenticated user |
| `personas` | [`ListPersonaApiPersona`](/api-reference/persona/types#listpersonaapipersona)[] | No | List of personas with computed permissions |
| `scenario_filter` | [`ListFilterSection`](/api-reference/persona/types#listfiltersection) | No | Scenario filter options for the list UI |
| `field_filter` | [`ListFilterSection`](/api-reference/persona/types#listfiltersection) | No | Field filter options for the list UI |
| `department_filter` | [`ListFilterSection`](/api-reference/persona/types#listfiltersection) | No | Department filter options for the list UI |
| `color_filter` | [`ListFilterSection`](/api-reference/persona/types#listfiltersection) | No | Color filter options for bulk edit |
| `icon_filter` | [`ListFilterSection`](/api-reference/persona/types#listfiltersection) | No | Icon filter options for bulk edit |
| `voice_filter` | [`ListFilterSection`](/api-reference/persona/types#listfiltersection) | No | Voice filter options for bulk edit |
| `instruction_filter` | [`ListFilterSection`](/api-reference/persona/types#listfiltersection) | No | Instruction filter options for bulk edit |
| `flag_filter` | [`ListFilterSection`](/api-reference/persona/types#listfiltersection) | No | Flag filter options for bulk edit |
| `total_count` | `integer` | No | Total number of personas matching filters |
| `import_fields` | [`ImportField`](/api-reference/persona/types#importfield)[] | No | CSV import column schema for the bulk-import dialog |

---

# `POST` `/persona/text_download`

Route: /api-reference/persona/post-persona-text-download

# `POST` `/persona/text_download`

Download Text

Download a text file by text resource ID.

## Request Body (`TextDownloadPersonaApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `text_id` | `string` | Yes | UUID of the texts_resource to download |

## Response

```
{}
```

---

# `POST` `/persona/title`

Route: /api-reference/persona/post-persona-title

# `POST` `/persona/title`

Title Persona

Rename a persona's group (writes group_names_entry).

## Request Body (`TitlePersonaApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Group to rename |
| `title` | `string` | Yes | New title (display name) for the group |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant rename |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`TitlePersonaApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | The group that was renamed |
| `group_name_id` | `string` | Yes | UUID of the new group_names_entry row |
| `title` | `string` | Yes | The title that was set |
| `idempotency_key` | `string` | No | Operation key echoed back |

---

# `POST` `/persona/update`

Route: /api-reference/persona/post-persona-update

# `POST` `/persona/update`

Update Persona

Update personas using composable infra architecture.

## Request Body (`UpdatePersonaApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `personas` | [`UpdatePersonaItem`](/api-reference/persona/types#updatepersonaitem)[] | No | List of persona items to update (required on first call when ``all`` is false) |
| `all` | `boolean` | No | When true, apply ``patch`` to every persona matching the filter fields below (minus ``excluded_ids``) |
| `excluded_ids` | `string`[] | No | UUIDs to skip even when matched by ``all``-mode filters |
| `patch` | [`UpdatePersonaPatch`](/api-reference/persona/types#updatepersonapatch) | No | Shared change set applied to every matched row when ``all=true`` (sparse — only set fields are updated; ``patch.id`` ignored) |
| `search` | `string` | No | Full-text search query |
| `scenario_ids` | `string`[] | No | Filter by scenario UUIDs |
| `field_ids` | `string`[] | No | Filter by field UUIDs |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `scenario_search` | `string` | No | Search text for scenario facet (no-op for row filtering) |
| `field_search` | `string` | No | Search text for field facet (no-op for row filtering) |
| `department_search` | `string` | No | Search text for department facet (no-op for row filtering) |
| `color_search` | `string` | No | Search text for color facet (no-op for row filtering) |
| `icon_search` | `string` | No | Search text for icon facet (no-op for row filtering) |
| `voice_search` | `string` | No | Search text for voice facet (no-op for row filtering) |
| `instruction_search` | `string` | No | Search text for instruction facet (no-op for row filtering) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant update |
| `soft` | `boolean` | No | Stage the update dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`UpdatePersonaApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`PersonaResultItem`](/api-reference/persona/types#personaresultitem)[] | Yes | Per-persona update results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |
| `personas` | [`ListPersonaApiPersona`](/api-reference/persona/types#listpersonaapipersona)[] | No | Hydrated rows for the successfully-updated personas (mirrors /persona/search shape) |

---

# `POST` `/persona/watch`

Route: /api-reference/persona/post-persona-watch

# `POST` `/persona/watch`

Persona Watch Once

One-shot snapshot of run state, snapshot-replayable via ``snapshot_key``.

## Request Body (`WatchApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Chat group whose events we watch |
| `run_id` | `string` | No | Specific run to watch (e.g. the ``run_id`` returned by a prior ``X_Generate`` call). If None, watches every active run in the group at call time. |
| `wait_for_complete` | `boolean` | No | If True, block until the watched run reaches a terminal (complete/failed) event or timeout fires. If False, return current state and exit immediately. |
| `timeout_seconds` | `integer` | No | Max wait time when ``wait_for_complete=True``. |
| `snapshot_key` | `string` | No | Read snapshot key — on the one-shot POST /watch, the audit wrapper records this watch's point-in-time view (latest run state at call time) keyed by it and replays the same view on any later call with the same key. Ignored by the SSE GET stream. |

## Response (`WatchApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `runs` | [`RunStatus`](/api-reference/persona/types#runstatus)[] | Yes | — |
| `timed_out` | `boolean` | No | — |
| `waited_seconds` | `number` | No | — |

---

# Persona Types

Route: /api-reference/persona/types

# Persona Types

## `CallerPermissions`

Evaluated permissions for the current caller on this artifact type.

| Field | Type | Required | Description |
|---|---|---|---|
| `can_create` | `boolean` | Yes | Whether the caller can create new artifacts |
| `can_draft` | `boolean` | Yes | Whether the caller can create/update drafts |
| `can_duplicate` | `boolean` | Yes | Whether the caller can duplicate artifacts |
| `has_access` | `boolean` | No | Whether the caller can view this entity |
| `can_edit` | `boolean` | No | Whether the caller can edit this entity |
| `can_delete` | `boolean` | No | Whether the caller can delete this entity |
| `disabled_reason` | `string` | No | Human-readable reason if editing is disabled |

---

## `ColumnInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Column name |
| `type` | `string` | Yes | Column data type |
| `nullable` | `boolean` | Yes | Whether the column is nullable |

---

## `CreatePersonaItem`

Single persona item for create — no persona_id.

Required fields (name, color, icon, instructions): provide ID or value.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Client-provided UUID for the new persona |
| `resource_id` | `string` | No | Optional preset UUID for the resource snapshot |
| `name_id` | `string` | No | UUID of an existing name resource |
| `name` | `string` | No | Display name text (creates new resource if name_id not provided) |
| `color_id` | `string` | No | UUID of an existing color resource |
| `color` | `string` | No | Hex color code, e.g. '#FF5733' (creates new resource if color_id not provided) |
| `icon_id` | `string` | No | UUID of an existing icon resource |
| `icon` | `string` | No | Icon identifier value (creates new resource if icon_id not provided) |
| `instructions_id` | `string` | No | UUID of an existing instruction resource |
| `instructions` | `string` | No | System instruction template (creates new resource if instructions_id not provided) |
| `description_id` | `string` | No | UUID of an existing description resource |
| `description` | `string` | No | Persona description text (creates new resource if description_id not provided) |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `active` | `boolean` | No | Denormalized persona_active flag state; resolved to a flag_ids entry server-side |
| `department_ids` | `string`[] | No | Department UUIDs to associate with this persona |
| `departments` | `string`[] | No | Department names (resolved to UUIDs server-side) |
| `parameter_field_ids` | `string`[] | No | Parameter field UUIDs to associate |
| `parameter_fields` | `string`[] | No | Parameter field names (resolved to UUIDs server-side) |
| `example_ids` | `string`[] | No | Existing example resource UUIDs to associate |
| `examples` | `string`[] | No | Example texts (creates new example resources) |
| `voice_ids` | `string`[] | No | Voice resource UUIDs to associate |
| `voices` | `string`[] | No | Voice values (resolved to UUIDs server-side) |

---

## `DeletePersonaResult`

Per-item result within a bulk delete response.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the deletion succeeded |
| `id` | `string` | Yes | UUID of the deleted persona |
| `message` | `string` | Yes | Human-readable result message |

---

## `DocsApiResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `list` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `detail` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `new` | [`PageMetaItem`](#pagemetaitem) | Yes | — |

---

## `DocsResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Resource or entry name |
| `type` | `string` | Yes | Resource or entry type identifier |
| `description` | `string` | Yes | Human-readable description |
| `materialized_view` | [`MvInfo`](#mvinfo) | No | Materialized view metadata |
| `tables` | [`TableInfo`](#tableinfo)[] | Yes | Related database tables |
| `operations` | [`OperationInfo`](#operationinfo)[] | Yes | Available operations |

---

## `EvalSetup`

Run-level eval scaffold — first-class on the generate response.

Audit's ``**output`` spread carries this onto
``<artifact>.generate.completed``. Null when no rubric-bearing
agent participated.

| Field | Type | Required | Description |
|---|---|---|---|
| `test_id` | `string` | Yes | — |
| `invocations` | [`InvocationSlot`](#invocationslot)[] | Yes | — |

---

## `GenerateConfig`

Developer configuration — all optional with sensible defaults.

| Field | Type | Required | Description |
|---|---|---|---|
| `operations` | `string`[] | No | — |
| `dangerous` | `boolean` | No | — |
| `params` | `object` | No | — |
| `group_id` | `string` | No | — |

---

## `GenerationsPersonaListItem`

Single generation group in the persona generations response.

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | UUID of the generation group |
| `session_id` | `string` | No | UUID of the parent session |
| `group_name` | `string` | No | Name of the generation group |
| `created_at` | `string` | No | Timestamp of the generation |

---

## `GetFieldResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | UUID of the field |
| `name` | `string` | Yes | Field name |
| `description` | `string` | Yes | Field description |
| `value` | `string` | Yes | Field value |
| `department_ids` | `string`[] | Yes | Associated department UUIDs |
| `conditional_parameter_ids` | `string`[] | Yes | Associated conditional parameter UUIDs |
| `created_at` | `string` | Yes | Creation timestamp |
| `active` | `boolean` | Yes | Whether the field is active |
| `generated` | `boolean` | Yes | Whether the field was AI-generated |
| `mcp` | `boolean` | Yes | Whether the field is from MCP |

---

## `GetPersonaDraftResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | UUID of the draft |
| `created_at` | `string` | Yes | Creation timestamp |
| `generated` | `boolean` | Yes | Whether this was AI-generated |
| `mcp` | `boolean` | Yes | Whether MCP tooling was used |
| `active` | `boolean` | Yes | Whether this draft is active |
| `session_id` | `string` | Yes | Associated session UUID |
| `name` | `string` | No | Immutable draft label set at create time |
| `color_ids` | `string`[] | Yes | Associated color UUIDs |
| `department_ids` | `string`[] | Yes | Associated department UUIDs |
| `description_ids` | `string`[] | Yes | Associated description UUIDs |
| `example_ids` | `string`[] | Yes | Associated example UUIDs |
| `flag_ids` | `string`[] | Yes | Associated flag UUIDs |
| `icon_ids` | `string`[] | Yes | Associated icon UUIDs |
| `instruction_ids` | `string`[] | Yes | Associated instruction UUIDs |
| `name_ids` | `string`[] | Yes | Associated name UUIDs |
| `parameter_field_ids` | `string`[] | Yes | Associated parameter field UUIDs |
| `profile_ids` | `string`[] | Yes | Associated profile UUIDs |
| `voice_ids` | `string`[] | Yes | Associated voice UUIDs |
| `pending_color_ids` | `string`[] | No | Pending color UUIDs |
| `pending_department_ids` | `string`[] | No | Pending department UUIDs |
| `pending_description_ids` | `string`[] | No | Pending description UUIDs |
| `pending_example_ids` | `string`[] | No | Pending example UUIDs |
| `pending_flag_ids` | `string`[] | No | Pending flag UUIDs |
| `pending_icon_ids` | `string`[] | No | Pending icon UUIDs |
| `pending_instruction_ids` | `string`[] | No | Pending instruction UUIDs |
| `pending_name_ids` | `string`[] | No | Pending name UUIDs |
| `pending_parameter_field_ids` | `string`[] | No | Pending parameter field UUIDs |
| `pending_voice_ids` | `string`[] | No | Pending voice UUIDs |

---

## `GroupCall`

Tool call referenced by a message.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `tool_name` | `string` | No | — |
| `template_name` | `string` | No | — |
| `tool` | `object` | No | — |
| `ledger_status` | `string` | No | — |
| `ledger_operation` | `string` | No | — |
| `ledger_artifact` | `string` | No | — |
| `ledger_artifact_id` | `string` | No | — |

---

## `GroupMessage`

Message within a run.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `role` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `text_ids` | `string`[] | No | — |
| `audio_ids` | `string`[] | No | — |
| `image_ids` | `string`[] | No | — |
| `video_ids` | `string`[] | No | — |
| `file_ids` | `string`[] | No | — |
| `call_ids` | `string`[] | No | — |
| `calls` | [`GroupCall`](#groupcall)[] | No | — |
| `reasoning` | `boolean` | No | True when this row is a chain-of-thought trace persisted alongside the assistant answer (rendered as a collapsed accordion). |
| `in_context` | `boolean` | No | Whether this message is included in the LLM context for the next generation. Mirrors the dedup pass that builds chat history (see in_context_reason). |
| `in_context_reason` | `string` | No | Why this message is in/out of LLM context. 'kept' = included; 'deduped_read' = older read-only call to a tool that has a fresher result later in the group; future values may include 'trimmed_top_n'. |

---

## `GroupResource`

Lightweight `\{id, name\}` for cross-referencing run-level ids
(``model_id`` / ``agent_id`` / ``profile_id``) against human-readable
names on the analytics panel. Names come from the canonical
``get_models`` / ``get_agents`` / ``get_profiles`` black boxes.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `name` | `string` | No | — |

---

## `GroupRun`

Run within a group, with its messages.

Carries token / cost / model / agent / profile attribution so the
analytics view can render per-run cost + actor info without a
parallel detail shape. ``profile_id`` is the authoring profile
(human user), ``agent_id`` is the LLM-side actor, ``model_id`` is
the model used by that agent. All optional — runs predating these
columns or with unresolved attributions surface ``None``.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `input_tokens` | `integer` | No | — |
| `output_tokens` | `integer` | No | — |
| `cached_input_tokens` | `integer` | No | — |
| `cost` | `number` | No | — |
| `model_id` | `string` | No | — |
| `agent_id` | `string` | No | — |
| `profile_id` | `string` | No | — |
| `previous_context_start_index` | `integer` | No | Index in ``messages`` where the current run's own messages begin; earlier rows are previous-context replay. ``None`` when the run has no previous context attached. |
| `messages` | [`GroupMessage`](#groupmessage)[] | No | — |

---

## `ImportField`

Field descriptor for CSV import column mapping.

| Field | Type | Required | Description |
|---|---|---|---|
| `key` | `string` | Yes | — |
| `label` | `string` | Yes | — |
| `required` | `boolean` | No | — |
| `multi` | `boolean` | No | — |
| `type` | `string` | No | — |
| `example` | `string` | No | — |
| `description` | `string` | No | — |

---

## `InvocationSlot`

One agent's slot in a multi-agent generation pool.

Populated by ``setup_generation_test`` when an agent carries a
rubric. The client uses these IDs to drive the eval workflow:
review the candidate's output, optionally fire a grader against
its ``invocation_id``, and promote/reject by call_id via the
existing ``idempotency_key + accept`` pattern.

| Field | Type | Required | Description |
|---|---|---|---|
| `invocation_id` | `string` | Yes | — |
| `agent_id` | `string` | Yes | — |
| `rubric_id` | `string` | No | — |

---

## `ListFilterOption`

Standardized option for list endpoint filter sections.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier for this filter option |
| `name` | `string` | No | Display name |
| `count` | `integer` | No | Number of matching records |
| `hex_code` | `string` | No | Hex color code for display |
| `value` | `string` | No | Internal value |
| `type` | `string` | No | Option type discriminator |

---

## `ListFilterSection`

Filter section with options and echoed request state.

| Field | Type | Required | Description |
|---|---|---|---|
| `options` | [`ListFilterOption`](#listfilteroption)[] | No | Available filter options |
| `selected_ids` | `string`[] | No | Currently selected filter option IDs |
| `search` | `string` | No | Active search text for filtering |

---

## `ListPersonaApiPersona`

Persona type for list endpoint with computed permissions.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Persona artifact UUID (canonical id; mirrors persona_id) |
| `persona_id` | `string` | No | UUID of the persona |
| `name` | `string` | No | Display name |
| `description` | `string` | No | Persona description text |
| `color` | `string` | No | Hex color code |
| `icon` | `string` | No | Icon identifier |
| `department_ids` | `string`[] | No | Associated department UUIDs |
| `scenario_ids` | `string`[] | No | Scenarios using this persona |
| `field_ids` | `string`[] | No | Associated field UUIDs |
| `is_inactive` | `boolean` | No | Whether the persona is marked inactive |
| `pending_status` | `string` | No | Latest soft_calls_mv status: 'pending' / 'accepted' / 'rejected' |
| `pending_operation` | `string` | No | Operation type ('create'|'update'|'delete'|'duplicate') of the pending op |
| `pending_call_id` | `string` | No | call_id (idempotency key for ack) of the pending op |
| `generated` | `boolean` | No | Whether the persona was AI-generated |
| `mcp` | `boolean` | No | Whether this persona uses MCP tooling |
| `num_scenarios` | `integer` | No | Count of scenarios using this persona |
| `num_profiles` | `integer` | No | Count of profiles who have interacted with this persona |
| `can_edit` | `boolean` | No | Whether the current user can edit this persona |
| `can_duplicate` | `boolean` | No | Whether the current user can duplicate this persona |
| `can_delete` | `boolean` | No | Whether the current user can delete this persona |
| `updated_at` | `string` | No | Last modification timestamp |

---

## `MvInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Materialized view name |
| `definition` | `string` | Yes | SQL definition of the view |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the view |

---

## `OperationInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Operation name |
| `description` | `string` | Yes | Human-readable description of the operation |
| `params` | [`ParamInfo`](#paraminfo)[] | Yes | List of operation parameters |
| `returns` | `object` | No | Return type schema |

---

## `OperationPrompts`

Starter prompts keyed by operation name.

Each key is an operation (e.g. "create", "search", "draft", "export")
and the value is a list of starter prompts for that operation.
The client picks from the operations the caller has permission for
and rotates through them.

| Field | Type | Required | Description |
|---|---|---|---|
| `prompts` | `object` | No | Map of operation name to starter prompts |

---

## `PageMetaItem`

| Field | Type | Required | Description |
|---|---|---|---|
| `title` | `string` | Yes | — |
| `description` | `string` | Yes | — |

---

## `ParamInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Parameter name |
| `type` | `string` | Yes | Parameter data type |
| `required` | `boolean` | Yes | Whether the parameter is required |
| `default` | `any` | No | Default value if not required |

---

## `PersonaColorResource`

Color resource for persona.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | — |
| `name` | `string` | No | — |
| `description` | `string` | No | — |
| `hex_code` | `string` | No | — |
| `generated` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `selected` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `PersonaDepartmentResource`

Department resource for persona.

| Field | Type | Required | Description |
|---|---|---|---|
| `department_id` | `string` | No | — |
| `name` | `string` | No | — |
| `description` | `string` | No | — |
| `generated` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `selected` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `PersonaDescriptionResource`

Description resource for persona.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | — |
| `description` | `string` | No | — |
| `generated` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `selected` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `PersonaExampleResource`

Example resource for persona.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | — |
| `example` | `string` | No | — |
| `generated` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `selected` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `PersonaFieldError`

Per-field error from value resolution.

| Field | Type | Required | Description |
|---|---|---|---|
| `field` | `string` | Yes | Name of the field that failed validation |
| `message` | `string` | Yes | Human-readable validation error message |

---

## `PersonaFlagResource`

Flag option row — one per (name, type, value) entry in flags_resource.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Flag resource identifier |
| `name` | `string` | No | Flag display name |
| `type` | `string` | No | Flag type (e.g. 'persona_active') |
| `value` | `boolean` | No | Underlying bool value of this option |
| `description` | `string` | No | Flag description text |
| `icon_id` | `string` | No | Icon identifier for the flag |
| `icon` | `string` | No | Resolved SVG markup (hydrated from icons_resource) |
| `generated` | `boolean` | No | Whether the flag was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `PersonaIconResource`

Icon resource for persona.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | — |
| `name` | `string` | No | — |
| `description` | `string` | No | — |
| `value` | `string` | No | — |
| `generated` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `selected` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `PersonaInstructionResource`

Instruction resource for persona.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | — |
| `template` | `string` | No | — |
| `generated` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `selected` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `PersonaNameResource`

Name resource for persona.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | — |
| `name` | `string` | No | — |
| `generated` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `selected` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `PersonaParameterFieldResource`

Parameter field resource for persona.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | — |
| `field_id` | `string` | No | — |
| `parameter_id` | `string` | No | — |
| `name` | `string` | No | — |
| `description` | `string` | No | — |
| `conditional_parameter_id` | `string` | No | — |
| `generated` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `selected` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `PersonaResultItem`

Per-item result within a bulk create/update response.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded for this item |
| `id` | `string` | No | UUID of the affected persona |
| `message` | `string` | Yes | Human-readable result message |
| `errors` | [`PersonaFieldError`](#personafielderror)[] | No | Per-field validation errors, if any |

---

## `PersonaVoiceResource`

Voice resource for persona.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | — |
| `voice` | `string` | No | — |
| `generated` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `selected` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `ProducedMedia`

One asset produced by a generation run.

``resource_id`` is the canonical id the per-artifact download tools
accept (e.g. ``Scenario_Image_Download(image_id=resource_id)`` for
``modality="image"``). It maps to ``images_resource.id`` /
``videos_resource.id`` / ``audios_resource.id`` depending on the
modality.

| Field | Type | Required | Description |
|---|---|---|---|
| `modality` | `"image"` \| `"video"` \| `"audio"` | Yes | — |
| `resource_id` | `string` | Yes | — |
| `upload_id` | `string` | Yes | — |
| `mime_type` | `string` | No | — |
| `file_size` | `integer` | No | — |

---

## `ProfileSummary`

Caller identity derived from JWT — who you are on this page.

Superset of the old six-field version: now carries everything the client
needs so that ``/\{artifact\}/context`` fully replaces ``/profiles/context``
and the extra ``getLayoutContextData`` round-trip can be dropped.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Display name of the authenticated user |
| `role` | `string` | Yes | Role name (e.g. 'Super Administrator') |
| `role_level` | `integer` | Yes | Role hierarchy level (0 = highest privilege) |
| `department_ids` | `string`[] | Yes | Departments the user belongs to |
| `artifact_access` | `string`[] | Yes | Artifact types this role can access (sidebar visibility) |
| `role_permissions` | `any`[][] | Yes | Full (artifact, operation) permission tuples for granular page gating |
| `is_active` | `boolean` | Yes | Whether the user's profile is active |
| `id` | `string` | Yes | Profile UUID (SocketProvider, ProfileProvider) |
| `theme` | [`ThemeBundle`](#themebundle) | No | Resolved theme: hex primitives + derived oklch tokens + score thresholds |
| `session_id` | `string` | No | Current session UUID |
| `is_emulation` | `boolean` | No | Whether user is in emulation mode (ProfileProvider) |
| `role_resources` | [`QGetProfileContextV4RoleResource`](#qgetprofilecontextv4roleresource)[] | No | All role resources for emulation display (ProfileProvider) |
| `scoped_roles` | `string`[] | No | Roles the user can emulate (ProfileProvider) |
| `active` | `boolean` | No | Alias for is_active (ProfileProvider uses this name) |

---

## `QGetProfileContextV4RoleResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `role` | `string` | No | — |
| `name` | `string` | No | — |
| `description` | `string` | No | — |
| `icon_value` | `string` | No | — |
| `color_hex` | `string` | No | — |

---

## `RunStatus`

Outcome of one watched run.

| Field | Type | Required | Description |
|---|---|---|---|
| `run_id` | `string` | Yes | — |
| `status` | `"pending"` \| `"completed"` \| `"failed"` | Yes | — |
| `modality` | `string` | No | Modality of generated output (image, video, text…) |
| `resource_ids` | `string`[] | No | Resource UUIDs produced by this run (e.g. images_resource ids) |
| `error` | `string` | No | — |

---

## `TableInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Table name |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the table |

---

## `ThemeBundle`

Full theme payload for a page bootstrap.

Riding along on every ``/\{artifact\}/context`` response via
``ProfileSummary.theme``. Layers:
  - ``primitives`` / ``dark_primitives`` — hex inputs the settings
    editor reads/writes (light + dark palettes).
  - ``tokens`` / ``dark_tokens`` — oklch tokens the client paints with.
    ``ThemeStyle`` emits two ``<style>`` blocks: one scoped to
    ``:root:not(.dark)`` (light) and one to ``:root.dark`` (dark).
  - ``thresholds`` — numeric score thresholds for analytics components.
Empty-in → empty-out per token: missing values fall through to the
matching ``globals.css`` default.

| Field | Type | Required | Description |
|---|---|---|---|
| `primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (light palette, for the theme editor) |
| `tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for light mode (SSR CSS-var injection) |
| `dark_primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (dark palette, for the theme editor) |
| `dark_tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for dark mode (SSR CSS-var injection) |
| `thresholds` | [`Thresholds`](#thresholds) | No | Score thresholds resolved from the setting |

---

## `ThemePrimitives`

40 optional fields. The 17 essentials drive the rest; the other 23
are overrides for fine-tuning when derivation isn't what you want.

Empty primitive → empty token → client falls back to globals.css.

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `primary` | `string` | No | — |
| `accent` | `string` | No | — |
| `card` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `ring` | `string` | No | — |
| `border` | `string` | No | — |
| `destructive` | `string` | No | — |
| `success` | `string` | No | — |
| `warning` | `string` | No | — |
| `info` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `input` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `ThemeTokens`

40 fully-resolved CSS variable values (snake_case 1:1 with vars).

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `accent` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `border` | `string` | No | — |
| `input` | `string` | No | — |
| `ring` | `string` | No | — |
| `success` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `Thresholds`

Numeric score thresholds resolved from the active setting.

Server pre-buckets dashboard metrics into ``success | warning | danger |
neutral`` already, so most components don't need these values. Surface
them for chart reference lines, tooltips, and any client-side bucketing.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `integer` | Yes | Score >= this counts as success |
| `warning` | `integer` | Yes | Score >= this counts as warning |
| `danger` | `integer` | Yes | Score < success threshold but >= this counts as danger; below is neutral/no-data |

---

## `UpdatePersonaItem`

Single persona item for update — id required, all fields optional.

Only provided fields are updated (partial update).

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | UUID of the persona to update (required) |
| `name_id` | `string` | No | UUID of an existing name resource to select |
| `name` | `string` | No | Display name text (creates new resource if name_id not provided) |
| `color_id` | `string` | No | UUID of an existing color resource to select |
| `color` | `string` | No | Hex color code (creates new resource if color_id not provided) |
| `icon_id` | `string` | No | UUID of an existing icon resource to select |
| `icon` | `string` | No | Icon identifier value (creates new resource if icon_id not provided) |
| `instructions_id` | `string` | No | UUID of an existing instruction resource to select |
| `instructions` | `string` | No | System instruction template (creates new resource if instructions_id not provided) |
| `description_id` | `string` | No | UUID of an existing description resource to select |
| `description` | `string` | No | Persona description text (creates new resource if description_id not provided) |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `active` | `boolean` | No | Denormalized persona_active flag state; resolved to a flag_ids entry server-side |
| `department_ids` | `string`[] | No | Department UUIDs to associate (replaces existing) |
| `departments` | `string`[] | No | Department names (resolved to UUIDs server-side) |
| `parameter_field_ids` | `string`[] | No | Parameter field UUIDs to associate (replaces existing) |
| `parameter_fields` | `string`[] | No | Parameter field names (resolved to UUIDs server-side) |
| `example_ids` | `string`[] | No | Example resource UUIDs to associate (replaces existing) |
| `examples` | `string`[] | No | Example texts (creates new example resources) |
| `voice_ids` | `string`[] | No | Voice resource UUIDs to associate (replaces existing) |
| `voices` | `string`[] | No | Voice values (resolved to UUIDs server-side) |

---

## `UpdatePersonaPatch`

Shared patch for bulk-update-all-matching mode.

Inherits every field from ``UpdatePersonaItem`` and just relaxes
``id`` to optional — the bulk impl stamps the resolved id onto a
clone of the patch per matched row, so any client-supplied id is
ignored. Sparse semantics: only fields the client sets are written.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Ignored — bulk impl stamps the resolved persona id per matched row |
| `name_id` | `string` | No | UUID of an existing name resource to select |
| `name` | `string` | No | Display name text (creates new resource if name_id not provided) |
| `color_id` | `string` | No | UUID of an existing color resource to select |
| `color` | `string` | No | Hex color code (creates new resource if color_id not provided) |
| `icon_id` | `string` | No | UUID of an existing icon resource to select |
| `icon` | `string` | No | Icon identifier value (creates new resource if icon_id not provided) |
| `instructions_id` | `string` | No | UUID of an existing instruction resource to select |
| `instructions` | `string` | No | System instruction template (creates new resource if instructions_id not provided) |
| `description_id` | `string` | No | UUID of an existing description resource to select |
| `description` | `string` | No | Persona description text (creates new resource if description_id not provided) |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `active` | `boolean` | No | Denormalized persona_active flag state; resolved to a flag_ids entry server-side |
| `department_ids` | `string`[] | No | Department UUIDs to associate (replaces existing) |
| `departments` | `string`[] | No | Department names (resolved to UUIDs server-side) |
| `parameter_field_ids` | `string`[] | No | Parameter field UUIDs to associate (replaces existing) |
| `parameter_fields` | `string`[] | No | Parameter field names (resolved to UUIDs server-side) |
| `example_ids` | `string`[] | No | Example resource UUIDs to associate (replaces existing) |
| `examples` | `string`[] | No | Example texts (creates new example resources) |
| `voice_ids` | `string`[] | No | Voice resource UUIDs to associate (replaces existing) |
| `voices` | `string`[] | No | Voice values (resolved to UUIDs server-side) |

---

## `app__infra__persona__types__DraftFormState`

Full form state after draft patch — server is source of truth.

Client replaces its local form state with this after every successful patch.
Includes both resolved IDs and echoed values for AI model feedback.

| Field | Type | Required | Description |
|---|---|---|---|
| `name_id` | `string` | No | Currently selected name resource UUID |
| `name` | `string` | No | Name value that was saved |
| `description_id` | `string` | No | Currently selected description resource UUID |
| `description` | `string` | No | Description value that was saved |
| `instructions_id` | `string` | No | Currently selected instruction resource UUID |
| `instructions` | `string` | No | Instructions value that was saved |
| `color_id` | `string` | No | Currently selected color resource UUID |
| `color` | `string` | No | Color value that was saved (hex code) |
| `icon_id` | `string` | No | Currently selected icon resource UUID |
| `icon` | `string` | No | Icon value that was saved |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs |
| `active` | `boolean` | No | Echoed persona_active flag state |
| `department_ids` | `string`[] | No | Currently associated department UUIDs |
| `example_ids` | `string`[] | No | Currently associated example resource UUIDs |
| `parameter_field_ids` | `string`[] | No | Currently associated parameter field UUIDs |
| `voice_ids` | `string`[] | No | Currently associated voice resource UUIDs |

---

## `app__infra__persona__types__SectionFilter`

Per-section filter options for GET requests.

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Filter options by search text |
| `limit` | `integer` | No | Max options to return |
| `selected` | `boolean` | No | Only return selected items |
| `suggested` | `boolean` | No | Only return suggested items |
| `include` | `boolean` | No | Include this section in response (default true) |
| `parameter_ids` | `string`[] | No | Parameter group IDs to filter by (parameter_fields section only) |

---

---

# `GET` `/profile/watch`

Route: /api-reference/profile/get-profile-watch

# `GET` `/profile/watch`

Profile Watch

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `group_id` | query | No | — |
| `run_id` | query | No | Optional run filter. If provided, only events whose envelope run_id matches are streamed. Omit to receive every profile event in the group (the FE default). |

## Response

```
{}
```

---

# `POST` `/profile/call_download`

Route: /api-reference/profile/post-profile-call-download

# `POST` `/profile/call_download`

Download Call

Download a call file by call resource ID.

## Request Body (`CallDownloadProfileApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `call_id` | `string` | Yes | UUID of the calls_resource to download |

## Response

```
{}
```

---

# `POST` `/profile/context`

Route: /api-reference/profile/post-profile-context

# `POST` `/profile/context`

Get Profile Context

Get page context for the profile artifact.

Returns docs + profile identity + evaluated permissions in a single call.
Superset of /docs — clients can migrate from /docs to /context incrementally.

## Request Body (`DocsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entity_id` | `string` | No | — |
| `snapshot_key` | `string` | No | — |
| `schema` | `boolean` | No | If true, include MCP/tooling schema metadata (artifact, entries, resources, permission_docs, api_operations). Defaults to false for lean page-bootstrap responses. |

## Response (`ComposedContextResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Artifact name |
| `type` | `string` | Yes | Artifact type identifier |
| `description` | `string` | Yes | Human-readable description |
| `artifact` | [`DocsResponse`](/api-reference/profile/types#docsresponse) | No | Artifact tool documentation (None unless schema=true) |
| `entries` | [`DocsResponse`](/api-reference/profile/types#docsresponse)[] | No | Entry documentation list (None unless schema=true) |
| `resources` | [`DocsResponse`](/api-reference/profile/types#docsresponse)[] | No | Resource documentation list (None unless schema=true) |
| `permission_docs` | [`OperationInfo`](/api-reference/profile/types#operationinfo)[] | No | Permission function signatures for MCP/dev tooling (None unless schema=true) |
| `api_operations` | [`OperationInfo`](/api-reference/profile/types#operationinfo)[] | No | API operation documentation (None unless schema=true) |
| `page_metadata` | [`DocsApiResponse`](/api-reference/profile/types#docsapiresponse) | No | Page-level metadata |
| `prompts` | [`OperationPrompts`](/api-reference/profile/types#operationprompts) | No | Starter prompts keyed by operation |
| `profile` | [`ProfileSummary`](/api-reference/profile/types#profilesummary) | Yes | Caller identity from JWT |
| `caller_permissions` | [`CallerPermissions`](/api-reference/profile/types#callerpermissions) | Yes | Evaluated permissions for this caller |

---

# `POST` `/profile/create`

Route: /api-reference/profile/post-profile-create

# `POST` `/profile/create`

Create Profile

Create profiles using composable infra architecture.

## Request Body (`CreateProfileApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `profiles` | [`CreateProfileItem`](/api-reference/profile/types#createprofileitem)[] | Yes | List of profiles to create |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant create |
| `soft` | `boolean` | No | Stage the create dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`CreateProfileApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`ProfileResultItem`](/api-reference/profile/types#profileresultitem)[] | Yes | Per-item creation results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |
| `profiles` | [`ListProfilesApiProfile`](/api-reference/profile/types#listprofilesapiprofile)[] | No | Hydrated rows for the successfully-created profiles (mirrors /profile/search shape) |

---

# `POST` `/profile/csv`

Route: /api-reference/profile/post-profile-csv

# `POST` `/profile/csv`

Parse Profile Csv

Parse a CSV file and return mapped items for preview.

## Request Body

| Field | Type | Required | Description |
|---|---|---|---|
| `file` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `soft` | `boolean` | No | — |
| `accept` | `boolean` | No | — |

## Response (`ParseProfileCsvApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `upload_id` | `string` | Yes | — |
| `items` | [`CreateProfileItem`](/api-reference/profile/types#createprofileitem)[] | Yes | — |
| `mapped_fields` | `string`[] | Yes | — |
| `row_count` | `integer` | Yes | — |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with `accept` to promote/reject the staged raw-CSV upload. NOTE: ack returns no items (the preview is only on the propose). |

---

# `POST` `/profile/delete`

Route: /api-reference/profile/post-profile-delete

# `POST` `/profile/delete`

Delete Profile

Bulk delete profiles — composable infra architecture.

## Request Body (`DeleteProfileApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `profile_ids` | `string`[] | No | UUIDs of profiles to delete (required on first call when ``all`` is false) |
| `all` | `boolean` | No | When true, delete every profile matching the filter fields below (minus ``excluded_ids``) |
| `excluded_ids` | `string`[] | No | UUIDs to skip even when matched by ``all``-mode filters |
| `search` | `string` | No | Full-text search query |
| `cohort_ids` | `string`[] | No | Filter by cohort UUIDs |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `role_filter` | `string` | No | Filter by role name |
| `cohort_search` | `string` | No | Search text for cohort facet (no-op for row filtering) |
| `department_search` | `string` | No | Search text for department facet (no-op for row filtering) |
| `role_search` | `string` | No | Search text for role facet (no-op for row filtering) |
| `flag_search` | `string` | No | Search text for flag facet (no-op for row filtering) |
| `idempotency_key` | `string` | No | Operation key for ack — confirms or rejects a dormant delete |
| `soft` | `boolean` | No | Stage the delete dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (confirm) or reject dormant state. Only meaningful with idempotency_key |

## Response (`DeleteProfileApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`DeleteProfileResult`](/api-reference/profile/types#deleteprofileresult)[] | Yes | Per-item deletion results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/profile/draft`

Route: /api-reference/profile/post-profile-draft

# `POST` `/profile/draft`

Patch Profile Draft

Patch profile draft — composable infra architecture.

## Request Body (`PatchProfileDraftApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `draft_id` | `string` | No | Existing draft UUID to update |
| `input_draft_id` | `string` | No | Existing draft UUID to update |
| `name` | `string` | No | Name value to resolve or create |
| `name_id` | `string` | No | UUID of the name resource |
| `email` | `string` | No | Email value to resolve or create |
| `emails` | `string`[] | No | Email values to resolve or create |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical |
| `active` | `boolean` | No | Denormalized profile_active flag state; resolved to a flag_ids entry server-side |
| `department_ids` | `string`[] | No | Department UUIDs to assign |
| `departments` | `string`[] | No | Department names to resolve |
| `email_ids` | `string`[] | No | Email resource UUIDs |
| `role` | `string` | No | Role name to resolve (single-name shortcut; legacy) |
| `role_id` | `string` | No | Role resource UUID |
| `role_draft` | [`ProfileRoleDraftValue`](/api-reference/profile/types#profileroledraftvalue) | No | Inline-creatable role; id=null asks server to create with permissions/limits |
| `primary_department_id` | `string` | No | UUID of the department to designate as primary |
| `pending_ids` | `string`[] | No | Resources to keep dormant |
| `idempotency_key` | `string` | No | Idempotency key for draft writes |
| `soft` | `boolean` | No | Stage the draft dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Whether to accept the pending draft state |

## Response (`PatchProfileDraftApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the draft save succeeded |
| `draft_id` | `string` | Yes | UUID of the saved draft |
| `idempotency_key` | `string` | No | Idempotency key for draft writes |
| `message` | `string` | Yes | Result message |
| `form_state` | [`app__infra__profile__types__DraftFormState`](/api-reference/profile/types#app-infra-profile-types-draftformstate) | No | Server-authoritative form state |

---

# `POST` `/profile/drafts`

Route: /api-reference/profile/post-profile-drafts

# `POST` `/profile/drafts`

Get Profile Drafts

List profile drafts owned by the current profile.

## Request Body (`GetProfileDraftsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE substring) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GetProfileDraftsApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entries` | [`GetProfileDraftResponse`](/api-reference/profile/types#getprofiledraftresponse)[] | No | List of profile draft entries |

---

# `POST` `/profile/duplicate`

Route: /api-reference/profile/post-profile-duplicate

# `POST` `/profile/duplicate`

Duplicate Profile

Duplicate a profile — composable infra architecture.

## Request Body (`DuplicateProfileApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `target_profile_id` | `string` | Yes | UUID of the profile to duplicate |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant duplicate |
| `soft` | `boolean` | No | Stage the duplicate dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`DuplicateProfileApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the duplication succeeded |
| `profile_id` | `string` | Yes | UUID of the newly created profile |
| `message` | `string` | Yes | Result message |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |
| `profiles` | [`ListProfilesApiProfile`](/api-reference/profile/types#listprofilesapiprofile)[] | No | Hydrated row for the newly-created duplicate profile (mirrors /profile/search shape) |

---

# `POST` `/profile/emulate`

Route: /api-reference/profile/post-profile-emulate

# `POST` `/profile/emulate`

Emulate Profile

Create emulation grant. Next request will resolve to target profile.

## Request Body (`EmulateProfileApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `target_profile_id` | `string` | No | UUID of the profile to emulate (omit on the ack call) |
| `ttl_minutes` | `integer` | No | Emulation duration in minutes |
| `idempotency_key` | `string` | No | Idempotency / soft-call key. Echo the server-minted value with accept to promote/reject a staged emulation. |
| `soft` | `boolean` | No | Stage the emulation grant dormant (active=False) — it impersonates nothing until accepted |
| `accept` | `boolean` | No | Ack: True promotes the staged emulation, False rejects. Only meaningful with idempotency_key |

## Response (`EmulateProfileApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `allowed` | `boolean` | Yes | Whether emulation is allowed |
| `reason` | `string` | No | Reason if emulation is denied |
| `grant_id` | `string` | No | UUID of the emulation grant |
| `expires_at` | `string` | No | When the emulation grant expires |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with accept to promote/reject the staged emulation. |

---

# `POST` `/profile/export`

Route: /api-reference/profile/post-profile-export

# `POST` `/profile/export`

Export Profiles

Export all profiles as a clean, denormalized CSV.

## Request Body (`ExportProfileApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `profile_export_id` | `string` | No | UUID of the profile to export |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior export instead of re-running |

## Response (`ExportProfileApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `content` | `string` | Yes | Exported file content |
| `file_name` | `string` | Yes | Suggested file name for download |
| `mime_type` | `string` | Yes | MIME type of the exported content |
| `row_count` | `integer` | Yes | Number of rows in the export |

---

# `POST` `/profile/file_download`

Route: /api-reference/profile/post-profile-file-download

# `POST` `/profile/file_download`

Download File

Download a file by file resource ID.

## Request Body (`FileDownloadProfileApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource to download |

## Response

```
{}
```

---

# `POST` `/profile/generate`

Route: /api-reference/profile/post-profile-generate

# `POST` `/profile/generate`

Generate Profile

Trigger profile generation. Returns immediately; progress via events.

## Request Body (`ArtifactGenerateRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `instructions` | `string`[] | No | — |
| `config` | [`GenerateConfig`](/api-reference/profile/types#generateconfig) | No | — |
| `modalities` | `string`[] | No | — |
| `audios_id` | `string` | No | — |
| `conversation_id` | `string` | No | — |
| `trace_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `accept` | `boolean` | No | — |
| `wait_for_complete` | `boolean` | No | — |

## Response (`ArtifactGenerateResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `run_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `eval` | [`EvalSetup`](/api-reference/profile/types#evalsetup) | No | — |
| `produced_media` | [`ProducedMedia`](/api-reference/profile/types#producedmedia)[] | No | — |

---

# `POST` `/profile/generations`

Route: /api-reference/profile/post-profile-generations

# `POST` `/profile/generations`

Generations Profile

List profile generation groups — composable infra architecture.

## Request Body (`GenerationsProfileApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GenerationsProfileApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `items` | [`GenerationsProfileListItem`](/api-reference/profile/types#generationsprofilelistitem)[] | No | Generation groups |
| `total_count` | `integer` | No | Total number of matching generations |

---

# `POST` `/profile/get`

Route: /api-reference/profile/post-profile-get

# `POST` `/profile/get`

Get Profile

Get profile information using the canonical shared profile operation.

## Request Body (`GetProfileApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | UUID of the profile to retrieve |
| `target_profile_id` | `string` | No | Legacy alias for profile UUID |
| `draft_id` | `string` | No | UUID of the draft to load |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |
| `names` | [`app__infra__profile__types__SectionFilter`](/api-reference/profile/types#app-infra-profile-types-sectionfilter) | No | Filter options for names section |
| `emails` | [`app__infra__profile__types__SectionFilter`](/api-reference/profile/types#app-infra-profile-types-sectionfilter) | No | Filter options for emails section |
| `flags` | [`app__infra__profile__types__SectionFilter`](/api-reference/profile/types#app-infra-profile-types-sectionfilter) | No | Filter options for flags section |
| `departments` | [`app__infra__profile__types__SectionFilter`](/api-reference/profile/types#app-infra-profile-types-sectionfilter) | No | Filter options for departments section |
| `roles` | [`app__infra__profile__types__SectionFilter`](/api-reference/profile/types#app-infra-profile-types-sectionfilter) | No | Filter options for roles section |

## Response (`GetProfileApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the acting user |
| `profile_exists` | `boolean` | No | Whether the profile exists |
| `can_edit` | `boolean` | No | Whether the actor can edit this profile |
| `disabled_reason` | `string` | No | Reason editing is disabled, if any |
| `group_id` | `string` | No | Group UUID for draft collaboration |
| `draft_name` | `string` | No | Immutable draft label from the active draft entry, when a ``draft_id`` was supplied. ``None`` for non-draft fetches. |
| `profile_id` | `string` | No | UUID of the profile |
| `show_ai_generate` | `boolean` | No | Whether to show AI generate anywhere |
| `basic_show_ai_generate` | `boolean` | No | Whether to show AI generate on the basic step |
| `contact_show_ai_generate` | `boolean` | No | Whether to show AI generate on the contact step |
| `pending_ids` | `string`[] | No | Pending resource identifiers when available |
| `role_options` | `string`[] | No | Role names the actor can assign |
| `names` | [`ProfileNameResource`](/api-reference/profile/types#profilenameresource)[] | No | Name resources |
| `emails` | [`ProfileEmailResource`](/api-reference/profile/types#profileemailresource)[] | No | Email resources |
| `flags` | [`ProfileFlagResource`](/api-reference/profile/types#profileflagresource)[] | No | Flag resources (one per flags_resource row, value=true/false) |
| `departments` | [`ProfileDepartmentResource`](/api-reference/profile/types#profiledepartmentresource)[] | No | Department resources |
| `roles` | [`ProfileRoleResource`](/api-reference/profile/types#profileroleresource)[] | No | Role resources |
| `permissions` | [`ProfilePermissionResource`](/api-reference/profile/types#profilepermissionresource)[] | No | Permission catalog for the role editor |
| `request_limits` | [`ProfileRequestLimitResource`](/api-reference/profile/types#profilerequestlimitresource)[] | No | Request-limit catalog for the role editor |

---

# `POST` `/profile/group`

Route: /api-reference/profile/post-profile-group

# `POST` `/profile/group`

Group Profile

Resolve or create a profile group with optional naming.

## Request Body (`GroupProfileApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | No | Existing group UUID (omit to create or reuse via time window) |
| `snapshot_key` | `string` | No | Snapshot key for SETNX-race convergence on a single group across concurrent reads (e.g. parallel /context + /group + /search fan-out on page load). Echoed back in the response. |

## Response (`GroupProfileApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Resolved or newly created group UUID |
| `name` | `string` | No | The group's current title (latest active group_names_entry, or 'New Chat' fallback for freshly minted groups) |
| `snapshot_key` | `string` | No | Snapshot key echoed back — the UUID concurrent fan-out reads converged on via SETNX. Mirrors the resolved group_id. |
| `runs` | [`GroupRun`](/api-reference/profile/types#grouprun)[] | No | Conversation history — populated when resolving an existing group for fetch |
| `group_exists` | `boolean` | No | (detail) Whether the group exists in storage — populated when ``include_resources=True`` |
| `actor_name` | `string` | No | (detail) Display name of the current actor (caller profile) |
| `total_message_count` | `integer` | No | (detail) Total number of messages in the group |
| `models` | [`GroupResource`](/api-reference/profile/types#groupresource)[] | No | (detail) Models used in the group |
| `agents` | [`GroupResource`](/api-reference/profile/types#groupresource)[] | No | (detail) Agents used in the group |
| `profiles` | [`GroupResource`](/api-reference/profile/types#groupresource)[] | No | (detail) Profiles that authored runs in this group |

---

# `POST` `/profile/problem`

Route: /api-reference/profile/post-profile-problem

# `POST` `/profile/problem`

Problem Profile

Report a profile problem — composable infra architecture.

## Request Body (`ProblemProfileApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | `string` | Yes | Problem type: feature, bug, question, other |
| `message` | `string` | Yes | Problem description (max 1000 chars) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant problem |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`ProblemProfileApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `problem_id` | `string` | Yes | UUID of the created problem |
| `success` | `boolean` | No | Whether the problem was created |
| `message` | `string` | No | Status message |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/profile/refresh`

Route: /api-reference/profile/post-profile-refresh

# `POST` `/profile/refresh`

Profile Refresh

Refresh profile materialized views and invalidate caches.

## Request Body (`RefreshProfileApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `targets` | `string`[] | No | MV targets to refresh (omit for all). Options: profile_drafts_mv |
| `idempotency_key` | `string` | No | Operation key for ack |
| `accept` | `boolean` | No | Accept or reject. Only meaningful with idempotency_key |
| `soft` | `boolean` | No | Stage the refresh as a pending (held) request — recorded but not enqueued; ack with accept releases/enqueues it |

## Response (`RefreshResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | — |
| `refreshed_views` | `string`[] | Yes | — |
| `invalidated_tags` | `string`[] | Yes | — |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/profile/search`

Route: /api-reference/profile/post-profile-search

# `POST` `/profile/search`

Search Profile

Search profiles — composable infra architecture.

## Request Body (`SearchProfileApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | — |
| `cohort_ids` | `string`[] | No | — |
| `filter_department_ids` | `string`[] | No | — |
| `role_filter` | `string` | No | — |
| `cohort_search` | `string` | No | — |
| `department_search` | `string` | No | — |
| `role_search` | `string` | No | — |
| `page_size` | `integer` | No | — |
| `page_offset` | `integer` | No | — |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`ListProfilesApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the acting user |
| `profiles` | [`ListProfilesApiProfile`](/api-reference/profile/types#listprofilesapiprofile)[] | No | List of profile items |
| `department_filter` | [`ListFilterSection`](/api-reference/profile/types#listfiltersection) | No | Filter options for departments |
| `role_filter` | [`ListFilterSection`](/api-reference/profile/types#listfiltersection) | No | Filter options for roles |
| `flag_filter` | [`ListFilterSection`](/api-reference/profile/types#listfiltersection) | No | Filter options for flags in list UI |
| `permissions_filter` | [`ListFilterSection`](/api-reference/profile/types#listfiltersection) | No | Filter options for permissions in list UI |
| `total_count` | `integer` | No | Total number of profiles |

---

# `POST` `/profile/text_download`

Route: /api-reference/profile/post-profile-text-download

# `POST` `/profile/text_download`

Download Text

Download a text file by text resource ID.

## Request Body (`TextDownloadProfileApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `text_id` | `string` | Yes | UUID of the texts_resource to download |

## Response

```
{}
```

---

# `POST` `/profile/title`

Route: /api-reference/profile/post-profile-title

# `POST` `/profile/title`

Title Profile

Rename a profile's group (writes group_names_entry).

## Request Body (`TitleProfileApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Group to rename |
| `title` | `string` | Yes | New title (display name) for the group |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant rename |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`TitleProfileApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | The group that was renamed |
| `group_name_id` | `string` | Yes | UUID of the new group_names_entry row |
| `title` | `string` | Yes | The title that was set |
| `idempotency_key` | `string` | No | Operation key echoed back |

---

# `POST` `/profile/unemulate`

Route: /api-reference/profile/post-profile-unemulate

# `POST` `/profile/unemulate`

Unemulate Profile

Exit emulation for a specific target profile.

## Request Body (`UnemulateProfileApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `target_profile_id` | `string` | No | Profile ID to stop emulating (omit on the ack call) |
| `idempotency_key` | `string` | No | Idempotency / soft-call key. Echo the server-minted value with accept to perform/reject a proposed unemulation. |
| `soft` | `boolean` | No | Propose the unemulation without performing it — emulation continues until accepted (record-and-hold) |
| `accept` | `boolean` | No | Ack: True performs the proposed unemulation, False discards it. Only meaningful with idempotency_key |

## Response (`UnemulateProfileApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `ok` | `boolean` | Yes | Whether unemulation succeeded |
| `reason` | `string` | No | Reason if unemulation failed |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with accept to perform/reject the proposed unemulation. |

---

# `POST` `/profile/update`

Route: /api-reference/profile/post-profile-update

# `POST` `/profile/update`

Update Profile

Update profiles using composable infra architecture.

## Request Body (`UpdateProfileApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `profiles` | [`UpdateProfileItem`](/api-reference/profile/types#updateprofileitem)[] | No | List of profiles to update (required on first call when ``all`` is false) |
| `all` | `boolean` | No | When true, apply ``patch`` to every profile matching the filter fields below (minus ``excluded_ids``) |
| `excluded_ids` | `string`[] | No | UUIDs to skip even when matched by ``all``-mode filters |
| `patch` | [`UpdateProfilePatch`](/api-reference/profile/types#updateprofilepatch) | No | Shared change set applied to every matched row when ``all=true`` (sparse — only set fields are updated; ``patch.profile_id`` ignored) |
| `search` | `string` | No | Full-text search query |
| `cohort_ids` | `string`[] | No | Filter by cohort UUIDs |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `role_filter` | `string` | No | Filter by role name |
| `cohort_search` | `string` | No | Search text for cohort facet (no-op for row filtering) |
| `department_search` | `string` | No | Search text for department facet (no-op for row filtering) |
| `role_search` | `string` | No | Search text for role facet (no-op for row filtering) |
| `flag_search` | `string` | No | Search text for flag facet (no-op for row filtering) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant update |
| `soft` | `boolean` | No | Stage the update dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`UpdateProfileApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`ProfileResultItem`](/api-reference/profile/types#profileresultitem)[] | Yes | Per-item update results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |
| `profiles` | [`ListProfilesApiProfile`](/api-reference/profile/types#listprofilesapiprofile)[] | No | Hydrated rows for the successfully-updated profiles (mirrors /profile/search shape) |

---

# `POST` `/profile/watch`

Route: /api-reference/profile/post-profile-watch

# `POST` `/profile/watch`

Profile Watch Once

One-shot snapshot of run state, snapshot-replayable via ``snapshot_key``.

## Request Body (`WatchApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Chat group whose events we watch |
| `run_id` | `string` | No | Specific run to watch (e.g. the ``run_id`` returned by a prior ``X_Generate`` call). If None, watches every active run in the group at call time. |
| `wait_for_complete` | `boolean` | No | If True, block until the watched run reaches a terminal (complete/failed) event or timeout fires. If False, return current state and exit immediately. |
| `timeout_seconds` | `integer` | No | Max wait time when ``wait_for_complete=True``. |
| `snapshot_key` | `string` | No | Read snapshot key — on the one-shot POST /watch, the audit wrapper records this watch's point-in-time view (latest run state at call time) keyed by it and replays the same view on any later call with the same key. Ignored by the SSE GET stream. |

## Response (`WatchApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `runs` | [`RunStatus`](/api-reference/profile/types#runstatus)[] | Yes | — |
| `timed_out` | `boolean` | No | — |
| `waited_seconds` | `number` | No | — |

---

# Profile Types

Route: /api-reference/profile/types

# Profile Types

## `CallerPermissions`

Evaluated permissions for the current caller on this artifact type.

| Field | Type | Required | Description |
|---|---|---|---|
| `can_create` | `boolean` | Yes | Whether the caller can create new artifacts |
| `can_draft` | `boolean` | Yes | Whether the caller can create/update drafts |
| `can_duplicate` | `boolean` | Yes | Whether the caller can duplicate artifacts |
| `has_access` | `boolean` | No | Whether the caller can view this entity |
| `can_edit` | `boolean` | No | Whether the caller can edit this entity |
| `can_delete` | `boolean` | No | Whether the caller can delete this entity |
| `disabled_reason` | `string` | No | Human-readable reason if editing is disabled |

---

## `ColumnInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Column name |
| `type` | `string` | Yes | Column data type |
| `nullable` | `boolean` | Yes | Whether the column is nullable |

---

## `CreateProfileItem`

Single profile item for create — no profile_id.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Optional preset UUID for the new profile |
| `resource_id` | `string` | No | Optional preset UUID for the resource snapshot |
| `name_id` | `string` | No | REQUIRED FOR CREATE (or pass ``name``). UUID of an existing name resource. |
| `name` | `string` | No | REQUIRED FOR CREATE (or pass ``name_id``). Display name text — creates a new name resource on the fly. |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs |
| `active` | `boolean` | No | Denormalized profile_active flag state |
| `department_ids` | `string`[] | No | Department UUIDs to assign |
| `departments` | `string`[] | No | Department names to resolve |
| `email_ids` | `string`[] | No | Email resource UUIDs |
| `role_id` | `string` | No | Role resource UUID |
| `primary_department_id` | `string` | No | UUID of the department to designate as primary |

---

## `DeleteProfileResult`

Per-item result within a bulk delete response.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the deletion succeeded |
| `profile_id` | `string` | No | UUID of the deleted profile (None if soft-skipped under all-matching mode) |
| `message` | `string` | Yes | Result message |

---

## `DocsApiResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `list` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `detail` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `new` | [`PageMetaItem`](#pagemetaitem) | Yes | — |

---

## `DocsResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Resource or entry name |
| `type` | `string` | Yes | Resource or entry type identifier |
| `description` | `string` | Yes | Human-readable description |
| `materialized_view` | [`MvInfo`](#mvinfo) | No | Materialized view metadata |
| `tables` | [`TableInfo`](#tableinfo)[] | Yes | Related database tables |
| `operations` | [`OperationInfo`](#operationinfo)[] | Yes | Available operations |

---

## `EvalSetup`

Run-level eval scaffold — first-class on the generate response.

Audit's ``**output`` spread carries this onto
``<artifact>.generate.completed``. Null when no rubric-bearing
agent participated.

| Field | Type | Required | Description |
|---|---|---|---|
| `test_id` | `string` | Yes | — |
| `invocations` | [`InvocationSlot`](#invocationslot)[] | Yes | — |

---

## `GenerateConfig`

Developer configuration — all optional with sensible defaults.

| Field | Type | Required | Description |
|---|---|---|---|
| `operations` | `string`[] | No | — |
| `dangerous` | `boolean` | No | — |
| `params` | `object` | No | — |
| `group_id` | `string` | No | — |

---

## `GenerationsProfileListItem`

Single generation group in the profile generations response.

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | UUID of the generation group |
| `session_id` | `string` | No | UUID of the parent session |
| `group_name` | `string` | No | Name of the generation group |
| `created_at` | `string` | No | Timestamp of the generation |

---

## `GetProfileDraftResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | UUID of the draft |
| `created_at` | `string` | Yes | Creation timestamp |
| `generated` | `boolean` | Yes | Whether this was AI-generated |
| `mcp` | `boolean` | Yes | Whether MCP tooling was used |
| `active` | `boolean` | Yes | Whether this draft is active |
| `session_id` | `string` | Yes | Associated session UUID |
| `name` | `string` | No | Immutable draft label set at create time |
| `profile_ids` | `string`[] | Yes | Associated profile UUIDs |
| `department_ids` | `string`[] | Yes | Associated department UUIDs |
| `email_ids` | `string`[] | Yes | Associated email UUIDs |
| `flag_ids` | `string`[] | Yes | Associated flag UUIDs |
| `name_ids` | `string`[] | Yes | Associated name UUIDs |
| `role_ids` | `string`[] | Yes | Associated role UUIDs |
| `primary_department_ids` | `string`[] | No | Associated primary_departments_resource UUIDs |
| `pending_department_ids` | `string`[] | No | Pending department UUIDs |
| `pending_email_ids` | `string`[] | No | Pending email UUIDs |
| `pending_flag_ids` | `string`[] | No | Pending flag UUIDs |
| `pending_name_ids` | `string`[] | No | Pending name UUIDs |
| `pending_role_ids` | `string`[] | No | Pending role UUIDs |
| `pending_primary_department_ids` | `string`[] | No | Pending primary_departments UUIDs |

---

## `GroupCall`

Tool call referenced by a message.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `tool_name` | `string` | No | — |
| `template_name` | `string` | No | — |
| `tool` | `object` | No | — |
| `ledger_status` | `string` | No | — |
| `ledger_operation` | `string` | No | — |
| `ledger_artifact` | `string` | No | — |
| `ledger_artifact_id` | `string` | No | — |

---

## `GroupMessage`

Message within a run.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `role` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `text_ids` | `string`[] | No | — |
| `audio_ids` | `string`[] | No | — |
| `image_ids` | `string`[] | No | — |
| `video_ids` | `string`[] | No | — |
| `file_ids` | `string`[] | No | — |
| `call_ids` | `string`[] | No | — |
| `calls` | [`GroupCall`](#groupcall)[] | No | — |
| `reasoning` | `boolean` | No | True when this row is a chain-of-thought trace persisted alongside the assistant answer (rendered as a collapsed accordion). |
| `in_context` | `boolean` | No | Whether this message is included in the LLM context for the next generation. Mirrors the dedup pass that builds chat history (see in_context_reason). |
| `in_context_reason` | `string` | No | Why this message is in/out of LLM context. 'kept' = included; 'deduped_read' = older read-only call to a tool that has a fresher result later in the group; future values may include 'trimmed_top_n'. |

---

## `GroupResource`

Lightweight `\{id, name\}` for cross-referencing run-level ids
(``model_id`` / ``agent_id`` / ``profile_id``) against human-readable
names on the analytics panel. Names come from the canonical
``get_models`` / ``get_agents`` / ``get_profiles`` black boxes.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `name` | `string` | No | — |

---

## `GroupRun`

Run within a group, with its messages.

Carries token / cost / model / agent / profile attribution so the
analytics view can render per-run cost + actor info without a
parallel detail shape. ``profile_id`` is the authoring profile
(human user), ``agent_id`` is the LLM-side actor, ``model_id`` is
the model used by that agent. All optional — runs predating these
columns or with unresolved attributions surface ``None``.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `input_tokens` | `integer` | No | — |
| `output_tokens` | `integer` | No | — |
| `cached_input_tokens` | `integer` | No | — |
| `cost` | `number` | No | — |
| `model_id` | `string` | No | — |
| `agent_id` | `string` | No | — |
| `profile_id` | `string` | No | — |
| `previous_context_start_index` | `integer` | No | Index in ``messages`` where the current run's own messages begin; earlier rows are previous-context replay. ``None`` when the run has no previous context attached. |
| `messages` | [`GroupMessage`](#groupmessage)[] | No | — |

---

## `InvocationSlot`

One agent's slot in a multi-agent generation pool.

Populated by ``setup_generation_test`` when an agent carries a
rubric. The client uses these IDs to drive the eval workflow:
review the candidate's output, optionally fire a grader against
its ``invocation_id``, and promote/reject by call_id via the
existing ``idempotency_key + accept`` pattern.

| Field | Type | Required | Description |
|---|---|---|---|
| `invocation_id` | `string` | Yes | — |
| `agent_id` | `string` | Yes | — |
| `rubric_id` | `string` | No | — |

---

## `ListFilterOption`

Standardized option for list endpoint filter sections.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier for this filter option |
| `name` | `string` | No | Display name |
| `count` | `integer` | No | Number of matching records |
| `hex_code` | `string` | No | Hex color code for display |
| `value` | `string` | No | Internal value |
| `type` | `string` | No | Option type discriminator |

---

## `ListFilterSection`

Filter section with options and echoed request state.

| Field | Type | Required | Description |
|---|---|---|---|
| `options` | [`ListFilterOption`](#listfilteroption)[] | No | Available filter options |
| `selected_ids` | `string`[] | No | Currently selected filter option IDs |
| `search` | `string` | No | Active search text for filtering |

---

## `ListProfilesApiProfile`

Profile type for list endpoint with computed permissions.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Profile artifact UUID (canonical id; mirrors profile_id) |
| `profile_id` | `string` | No | Unique profile identifier |
| `emails` | `string`[] | No | All email addresses for the profile |
| `primary_email` | `string` | No | Primary email address |
| `name` | `string` | No | Profile display name |
| `role` | `string` | No | User role enum (e.g. admin, member, custom) |
| `role_name` | `string` | No | Display name of the role (from roles_resource) |
| `initials` | `string` | No | User initials for avatar display |
| `department_ids` | `string`[] | No | Associated department IDs |
| `primary_department_id` | `string` | No | Primary department ID |
| `permission_ids` | `string`[] | No | Permission resource UUIDs granted via the profile's role |
| `can_edit` | `boolean` | No | Whether the actor can edit this profile |
| `can_duplicate` | `boolean` | No | Whether the actor can duplicate this profile |
| `can_delete` | `boolean` | No | Whether the actor can delete this profile |
| `can_emulate` | `boolean` | No | Whether the actor can emulate this profile |
| `is_emulated` | `boolean` | No | Whether this profile is currently being emulated by the actor |
| `is_inactive` | `boolean` | No | Whether the profile is inactive |
| `pending_status` | `string` | No | Pending soft_calls_entry status (e.g. 'pending') |
| `pending_operation` | `string` | No | Pending operation (create/update/delete/duplicate) |
| `pending_call_id` | `string` | No | Originating tool call id for ack |

---

## `MvInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Materialized view name |
| `definition` | `string` | Yes | SQL definition of the view |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the view |

---

## `OperationInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Operation name |
| `description` | `string` | Yes | Human-readable description of the operation |
| `params` | [`ParamInfo`](#paraminfo)[] | Yes | List of operation parameters |
| `returns` | `object` | No | Return type schema |

---

## `OperationPrompts`

Starter prompts keyed by operation name.

Each key is an operation (e.g. "create", "search", "draft", "export")
and the value is a list of starter prompts for that operation.
The client picks from the operations the caller has permission for
and rotates through them.

| Field | Type | Required | Description |
|---|---|---|---|
| `prompts` | `object` | No | Map of operation name to starter prompts |

---

## `PageMetaItem`

| Field | Type | Required | Description |
|---|---|---|---|
| `title` | `string` | Yes | — |
| `description` | `string` | Yes | — |

---

## `ParamInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Parameter name |
| `type` | `string` | Yes | Parameter data type |
| `required` | `boolean` | Yes | Whether the parameter is required |
| `default` | `any` | No | Default value if not required |

---

## `ProducedMedia`

One asset produced by a generation run.

``resource_id`` is the canonical id the per-artifact download tools
accept (e.g. ``Scenario_Image_Download(image_id=resource_id)`` for
``modality="image"``). It maps to ``images_resource.id`` /
``videos_resource.id`` / ``audios_resource.id`` depending on the
modality.

| Field | Type | Required | Description |
|---|---|---|---|
| `modality` | `"image"` \| `"video"` \| `"audio"` | Yes | — |
| `resource_id` | `string` | Yes | — |
| `upload_id` | `string` | Yes | — |
| `mime_type` | `string` | No | — |
| `file_size` | `integer` | No | — |

---

## `ProfileDepartmentResource`

Department resource for profile.

| Field | Type | Required | Description |
|---|---|---|---|
| `department_id` | `string` | No | Unique resource identifier |
| `name` | `string` | No | Department display name |
| `description` | `string` | No | Department description text |
| `generated` | `boolean` | No | Whether the resource was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `ProfileEmailResource`

Email resource for profile.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique resource identifier |
| `email` | `string` | No | Email address |
| `is_primary` | `boolean` | No | Whether this is the profile's primary email |
| `generated` | `boolean` | No | Whether the email was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `ProfileFieldError`

Per-field error from value resolution.

| Field | Type | Required | Description |
|---|---|---|---|
| `field` | `string` | Yes | Name of the field that failed validation |
| `message` | `string` | Yes | Validation error message |

---

## `ProfileFlagResource`

Flag option row — one per (name, type, value) entry in flags_resource.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Flag resource identifier |
| `name` | `string` | No | Flag display name |
| `type` | `string` | No | Flag type (e.g. 'profile_active') |
| `value` | `boolean` | No | Underlying bool value of this option |
| `description` | `string` | No | Flag description text |
| `icon_id` | `string` | No | Icon identifier for the flag |
| `icon` | `string` | No | Resolved SVG markup for the icon (hydrated from icons_resource) |
| `generated` | `boolean` | No | Whether the flag was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `ProfileNameResource`

Name resource for profile.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique resource identifier |
| `name` | `string` | No | Profile display name |
| `generated` | `boolean` | No | Whether the name was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `ProfilePermissionResource`

Permission catalog row — one per (artifact, operation) pair.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Permission resource identifier |
| `artifact` | `string` | No | Artifact key (e.g. 'agent', 'profile') |
| `operation` | `string` | No | Operation key (e.g. 'create', 'update') |
| `name` | `string` | No | Display name |
| `description` | `string` | No | Description text |

---

## `ProfileRequestLimitDraftValue`

Draft value for an inline-creatable request limit (limit, interval).

id=null asks the server to create a new request_limits_resource row.
id present means the caller is re-linking an existing limit.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Existing request_limits_resource id when known |
| `limit` | `integer` | Yes | Maximum requests per interval |
| `interval` | `string` | Yes | Postgres interval string (e.g. '1 day', '30 minutes', '2 hours') |

---

## `ProfileRequestLimitResource`

Request-limit catalog/echo row.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Request limit resource identifier |
| `limit` | `integer` | No | Maximum number of requests per interval |
| `interval` | `string` | No | Postgres interval string (e.g. '1 day', '30 minutes') |

---

## `ProfileResultItem`

Per-item result within a bulk create/update response.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `profile_id` | `string` | No | UUID of the created or updated profile |
| `message` | `string` | Yes | Result message |
| `errors` | [`ProfileFieldError`](#profilefielderror)[] | No | Per-field validation errors |

---

## `ProfileRoleDraftValue`

Draft value for an inline-creatable role.

Roles are immutable on this surface — the user can either re-link an
existing role (id present) or create a new one (id=null + name + …).
Nested request_limits with id=null are inline-created first; their
resolved ids merge into request_limit_ids before role creation.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Existing roles_resource id when re-linking |
| `name` | `string` | No | Role name (required when creating) |
| `description` | `string` | No | Role description |
| `icon_id` | `string` | No | Icon resource identifier |
| `color_id` | `string` | No | Color resource identifier |
| `level` | `integer` | No | Role level for assignment filtering |
| `permission_ids` | `string`[] | No | Permission resource UUIDs to attach |
| `request_limit_ids` | `string`[] | No | Existing request_limits_resource ids |
| `request_limits` | [`ProfileRequestLimitDraftValue`](#profilerequestlimitdraftvalue)[] | No | Inline-creatable request limits; id=null entries are created server-side |

---

## `ProfileRoleResource`

Role resource for profile.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique resource identifier |
| `role` | `string` | No | Role key (e.g. admin, user, viewer) |
| `name` | `string` | No | Role display name |
| `description` | `string` | No | Role description text |
| `icon_id` | `string` | No | Icon identifier for the role |
| `icon` | `string` | No | Resolved SVG markup for the icon (hydrated from icons_resource) |
| `icon_value` | `string` | No | Legacy alias for resolved role icon SVG |
| `color_id` | `string` | No | Color identifier for the role |
| `color_hex` | `string` | No | Resolved role color hex code |
| `level` | `integer` | No | Role level for assignment filtering |
| `permission_ids` | `string`[] | No | Permission resource UUIDs attached to this role |
| `request_limit_ids` | `string`[] | No | Request limit resource UUIDs attached to this role |
| `generated` | `boolean` | No | Whether the role was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `ProfileSummary`

Caller identity derived from JWT — who you are on this page.

Superset of the old six-field version: now carries everything the client
needs so that ``/\{artifact\}/context`` fully replaces ``/profiles/context``
and the extra ``getLayoutContextData`` round-trip can be dropped.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Display name of the authenticated user |
| `role` | `string` | Yes | Role name (e.g. 'Super Administrator') |
| `role_level` | `integer` | Yes | Role hierarchy level (0 = highest privilege) |
| `department_ids` | `string`[] | Yes | Departments the user belongs to |
| `artifact_access` | `string`[] | Yes | Artifact types this role can access (sidebar visibility) |
| `role_permissions` | `any`[][] | Yes | Full (artifact, operation) permission tuples for granular page gating |
| `is_active` | `boolean` | Yes | Whether the user's profile is active |
| `id` | `string` | Yes | Profile UUID (SocketProvider, ProfileProvider) |
| `theme` | [`ThemeBundle`](#themebundle) | No | Resolved theme: hex primitives + derived oklch tokens + score thresholds |
| `session_id` | `string` | No | Current session UUID |
| `is_emulation` | `boolean` | No | Whether user is in emulation mode (ProfileProvider) |
| `role_resources` | [`QGetProfileContextV4RoleResource`](#qgetprofilecontextv4roleresource)[] | No | All role resources for emulation display (ProfileProvider) |
| `scoped_roles` | `string`[] | No | Roles the user can emulate (ProfileProvider) |
| `active` | `boolean` | No | Alias for is_active (ProfileProvider uses this name) |

---

## `QGetProfileContextV4RoleResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `role` | `string` | No | — |
| `name` | `string` | No | — |
| `description` | `string` | No | — |
| `icon_value` | `string` | No | — |
| `color_hex` | `string` | No | — |

---

## `RunStatus`

Outcome of one watched run.

| Field | Type | Required | Description |
|---|---|---|---|
| `run_id` | `string` | Yes | — |
| `status` | `"pending"` \| `"completed"` \| `"failed"` | Yes | — |
| `modality` | `string` | No | Modality of generated output (image, video, text…) |
| `resource_ids` | `string`[] | No | Resource UUIDs produced by this run (e.g. images_resource ids) |
| `error` | `string` | No | — |

---

## `TableInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Table name |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the table |

---

## `ThemeBundle`

Full theme payload for a page bootstrap.

Riding along on every ``/\{artifact\}/context`` response via
``ProfileSummary.theme``. Layers:
  - ``primitives`` / ``dark_primitives`` — hex inputs the settings
    editor reads/writes (light + dark palettes).
  - ``tokens`` / ``dark_tokens`` — oklch tokens the client paints with.
    ``ThemeStyle`` emits two ``<style>`` blocks: one scoped to
    ``:root:not(.dark)`` (light) and one to ``:root.dark`` (dark).
  - ``thresholds`` — numeric score thresholds for analytics components.
Empty-in → empty-out per token: missing values fall through to the
matching ``globals.css`` default.

| Field | Type | Required | Description |
|---|---|---|---|
| `primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (light palette, for the theme editor) |
| `tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for light mode (SSR CSS-var injection) |
| `dark_primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (dark palette, for the theme editor) |
| `dark_tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for dark mode (SSR CSS-var injection) |
| `thresholds` | [`Thresholds`](#thresholds) | No | Score thresholds resolved from the setting |

---

## `ThemePrimitives`

40 optional fields. The 17 essentials drive the rest; the other 23
are overrides for fine-tuning when derivation isn't what you want.

Empty primitive → empty token → client falls back to globals.css.

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `primary` | `string` | No | — |
| `accent` | `string` | No | — |
| `card` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `ring` | `string` | No | — |
| `border` | `string` | No | — |
| `destructive` | `string` | No | — |
| `success` | `string` | No | — |
| `warning` | `string` | No | — |
| `info` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `input` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `ThemeTokens`

40 fully-resolved CSS variable values (snake_case 1:1 with vars).

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `accent` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `border` | `string` | No | — |
| `input` | `string` | No | — |
| `ring` | `string` | No | — |
| `success` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `Thresholds`

Numeric score thresholds resolved from the active setting.

Server pre-buckets dashboard metrics into ``success | warning | danger |
neutral`` already, so most components don't need these values. Surface
them for chart reference lines, tooltips, and any client-side bucketing.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `integer` | Yes | Score >= this counts as success |
| `warning` | `integer` | Yes | Score >= this counts as warning |
| `danger` | `integer` | Yes | Score < success threshold but >= this counts as danger; below is neutral/no-data |

---

## `UpdateProfileItem`

Single profile item for update — profile_id required, all fields optional.

| Field | Type | Required | Description |
|---|---|---|---|
| `profile_id` | `string` | Yes | UUID of the profile to update |
| `name_id` | `string` | No | UUID of the name resource |
| `name` | `string` | No | Name value to resolve or create |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs |
| `active` | `boolean` | No | Denormalized profile_active flag state |
| `department_ids` | `string`[] | No | Department UUIDs to assign |
| `departments` | `string`[] | No | Department names to resolve |
| `email_ids` | `string`[] | No | Email resource UUIDs |
| `role_id` | `string` | No | Role resource UUID |
| `primary_department_id` | `string` | No | UUID of the department to designate as primary |

---

## `UpdateProfilePatch`

Shared patch for bulk-update-all-matching mode.

Inherits every field from ``UpdateProfileItem`` and just relaxes
``profile_id`` to optional — the bulk impl stamps the resolved id
onto a clone of the patch per matched row, so any client-supplied
id is ignored. Sparse semantics: only fields the client sets are
written.

| Field | Type | Required | Description |
|---|---|---|---|
| `profile_id` | `string` | No | Ignored — bulk impl stamps the resolved profile id per matched row |
| `name_id` | `string` | No | UUID of the name resource |
| `name` | `string` | No | Name value to resolve or create |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs |
| `active` | `boolean` | No | Denormalized profile_active flag state |
| `department_ids` | `string`[] | No | Department UUIDs to assign |
| `departments` | `string`[] | No | Department names to resolve |
| `email_ids` | `string`[] | No | Email resource UUIDs |
| `role_id` | `string` | No | Role resource UUID |
| `primary_department_id` | `string` | No | UUID of the department to designate as primary |

---

## `app__infra__profile__types__DraftFormState`

Server-authoritative form state returned after draft save.

| Field | Type | Required | Description |
|---|---|---|---|
| `name_id` | `string` | No | Resolved name resource UUID |
| `name` | `string` | No | Resolved name value |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs |
| `active` | `boolean` | No | Echoed profile_active flag state |
| `departments` | `string`[] | No | Resolved department names |
| `department_ids` | `string`[] | Yes | Assigned department UUIDs |
| `emails` | `string`[] | No | Resolved email values |
| `email_ids` | `string`[] | Yes | Assigned email resource UUIDs |
| `role` | `string` | No | Assigned role name |
| `role_id` | `string` | No | Assigned role resource UUID |
| `role_draft` | [`ProfileRoleDraftValue`](#profileroledraftvalue) | No | Echoed role draft with resolved request_limit_ids after inline-create |
| `primary_department_id` | `string` | No | Assigned primary department UUID |
| `pending_ids` | `string`[] | No | Pending resource UUIDs |

---

## `app__infra__profile__types__SectionFilter`

Per-section filter options for GET requests.

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Filter options by search text |
| `limit` | `integer` | No | Max options to return |
| `selected` | `boolean` | No | Only return selected items |
| `suggested` | `boolean` | No | Only return suggested items |
| `include` | `boolean` | No | Include this section in response (default true) |

---

---

# `GET` `/provider/watch`

Route: /api-reference/provider/get-provider-watch

# `GET` `/provider/watch`

Provider Watch

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `group_id` | query | No | — |
| `run_id` | query | No | Optional run filter. If provided, only events whose envelope run_id matches are streamed. Omit to receive every provider event in the group (the FE default). |

## Response

```
{}
```

---

# `POST` `/provider/call_download`

Route: /api-reference/provider/post-provider-call-download

# `POST` `/provider/call_download`

Download Call

Download a call file by call resource ID.

## Request Body (`CallDownloadProviderApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `call_id` | `string` | Yes | UUID of the calls_resource to download |

## Response

```
{}
```

---

# `POST` `/provider/context`

Route: /api-reference/provider/post-provider-context

# `POST` `/provider/context`

Get Provider Context

Get page context for the provider artifact.

Returns docs + profile identity + evaluated permissions in a single call.
Superset of /docs — clients can migrate from /docs to /context incrementally.

## Request Body (`DocsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entity_id` | `string` | No | — |
| `snapshot_key` | `string` | No | — |
| `schema` | `boolean` | No | If true, include MCP/tooling schema metadata (artifact, entries, resources, permission_docs, api_operations). Defaults to false for lean page-bootstrap responses. |

## Response (`ComposedContextResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Artifact name |
| `type` | `string` | Yes | Artifact type identifier |
| `description` | `string` | Yes | Human-readable description |
| `artifact` | [`DocsResponse`](/api-reference/provider/types#docsresponse) | No | Artifact tool documentation (None unless schema=true) |
| `entries` | [`DocsResponse`](/api-reference/provider/types#docsresponse)[] | No | Entry documentation list (None unless schema=true) |
| `resources` | [`DocsResponse`](/api-reference/provider/types#docsresponse)[] | No | Resource documentation list (None unless schema=true) |
| `permission_docs` | [`OperationInfo`](/api-reference/provider/types#operationinfo)[] | No | Permission function signatures for MCP/dev tooling (None unless schema=true) |
| `api_operations` | [`OperationInfo`](/api-reference/provider/types#operationinfo)[] | No | API operation documentation (None unless schema=true) |
| `page_metadata` | [`DocsApiResponse`](/api-reference/provider/types#docsapiresponse) | No | Page-level metadata |
| `prompts` | [`OperationPrompts`](/api-reference/provider/types#operationprompts) | No | Starter prompts keyed by operation |
| `profile` | [`ProfileSummary`](/api-reference/provider/types#profilesummary) | Yes | Caller identity from JWT |
| `caller_permissions` | [`CallerPermissions`](/api-reference/provider/types#callerpermissions) | Yes | Evaluated permissions for this caller |

---

# `POST` `/provider/create`

Route: /api-reference/provider/post-provider-create

# `POST` `/provider/create`

Create Provider

Create providers using composable infra architecture.

## Request Body (`CreateProviderApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `providers` | [`CreateProviderItem`](/api-reference/provider/types#createprovideritem)[] | Yes | List of providers to create |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant create |
| `soft` | `boolean` | No | Stage the create dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`CreateProviderApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`ProviderResultItem`](/api-reference/provider/types#providerresultitem)[] | Yes | List of operation results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |
| `providers` | [`ListProviderApiProvider`](/api-reference/provider/types#listproviderapiprovider)[] | No | Hydrated rows for the successfully-created providers (mirrors /provider/search shape) |

---

# `POST` `/provider/csv`

Route: /api-reference/provider/post-provider-csv

# `POST` `/provider/csv`

Parse Provider Csv

Parse a CSV file and return mapped items for preview.

## Request Body

| Field | Type | Required | Description |
|---|---|---|---|
| `file` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `soft` | `boolean` | No | — |
| `accept` | `boolean` | No | — |

## Response (`ParseProviderCsvApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `upload_id` | `string` | Yes | — |
| `items` | [`CreateProviderItem`](/api-reference/provider/types#createprovideritem)[] | Yes | — |
| `mapped_fields` | `string`[] | Yes | — |
| `row_count` | `integer` | Yes | — |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with `accept` to promote/reject the staged raw-CSV upload. NOTE: ack returns no items (the preview is only on the propose). |

---

# `POST` `/provider/decrypt`

Route: /api-reference/provider/post-provider-decrypt

# `POST` `/provider/decrypt`

Decrypt Provider Key

Decrypt a key scoped to a provider artifact.

## Request Body (`DecryptProviderKeyApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `provider_id` | `string` | Yes | Provider that owns the key |
| `key_id` | `string` | Yes | Key identifier to decrypt |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`DecryptProviderKeyApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `key` | `string` | No | Decrypted API key value |
| `name` | `string` | No | Key display name |
| `actor_name` | `string` | No | Display name of the current actor |

---

# `POST` `/provider/delete`

Route: /api-reference/provider/post-provider-delete

# `POST` `/provider/delete`

Delete Provider

Bulk delete providers — composable infra architecture.

## Request Body (`DeleteProviderApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `provider_ids` | `string`[] | No | UUIDs of providers to delete (required on first call when ``all`` is false) |
| `all` | `boolean` | No | When true, delete every provider matching the filter fields below (minus ``excluded_ids``) |
| `excluded_ids` | `string`[] | No | UUIDs to skip even when matched by ``all``-mode filters |
| `search` | `string` | No | Full-text search query |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `filter_model_ids` | `string`[] | No | Filter by model UUIDs |
| `filter_status` | `string`[] | No | Filter by status values (active/inactive) |
| `department_search` | `string` | No | Search text for department facet (no-op for row filtering) |
| `model_search` | `string` | No | Search text for model facet (no-op for row filtering) |
| `flag_search` | `string` | No | Search text for flag facet (no-op for row filtering) |
| `idempotency_key` | `string` | No | Operation key for ack — confirms or rejects a dormant delete |
| `soft` | `boolean` | No | Stage the delete dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (confirm) or reject dormant state. Only meaningful with idempotency_key |

## Response (`DeleteProviderApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`DeleteProviderResult`](/api-reference/provider/types#deleteproviderresult)[] | Yes | List of deletion results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/provider/draft`

Route: /api-reference/provider/post-provider-draft

# `POST` `/provider/draft`

Patch Provider Draft

Patch provider draft — composable infra architecture.

## Request Body (`PatchProviderDraftApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `draft_id` | `string` | No | Existing draft ID to update |
| `input_draft_id` | `string` | No | Legacy alias for existing draft ID to update |
| `name` | `string` | No | Display name value |
| `name_id` | `string` | No | Name resource identifier |
| `description` | `string` | No | Description text value |
| `description_id` | `string` | No | Description resource identifier |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical |
| `active` | `boolean` | No | Denormalized provider_active flag state; resolved to a flag_ids entry server-side |
| `departments` | `string`[] | No | Department names to match |
| `department_ids` | `string`[] | No | Department identifiers |
| `endpoint` | `string` | No | Provider endpoint URL |
| `endpoint_id` | `string` | No | Endpoint resource identifier |
| `endpoint_ids` | `string`[] | No | Endpoint resource identifiers |
| `key` | `string` | No | Provider key value |
| `key_name` | `string` | No | Provider key display name |
| `key_description` | `string` | No | Provider key description |
| `key_id` | `string` | No | Key resource identifier |
| `key_ids` | `string`[] | No | API key resource identifiers |
| `value` | `string` | No | Provider identifier value |
| `value_id` | `string` | No | Value resource identifier |
| `pending_ids` | `string`[] | No | Pending resource identifiers to preserve |
| `idempotency_key` | `string` | No | Operation key for ack semantics |
| `soft` | `boolean` | No | Stage the draft dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept or reject acknowledgement when idempotency_key is supplied |

## Response (`PatchProviderDraftApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the draft save succeeded |
| `draft_id` | `string` | Yes | Draft unique identifier |
| `idempotency_key` | `string` | No | Operation key echoed back for client correlation |
| `message` | `string` | Yes | Result message |
| `form_state` | [`app__infra__provider__types__DraftFormState`](/api-reference/provider/types#app-infra-provider-types-draftformstate) | No | Server-authoritative form state |

---

# `POST` `/provider/drafts`

Route: /api-reference/provider/post-provider-drafts

# `POST` `/provider/drafts`

Get Provider Drafts

List provider drafts owned by the current profile.

## Request Body (`GetProviderDraftsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE substring) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GetProviderDraftsApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entries` | [`GetProviderDraftResponse`](/api-reference/provider/types#getproviderdraftresponse)[] | No | List of provider draft entries |

---

# `POST` `/provider/duplicate`

Route: /api-reference/provider/post-provider-duplicate

# `POST` `/provider/duplicate`

Duplicate Provider

Duplicate a provider — composable infra architecture.

## Request Body (`DuplicateProviderApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | UUID of the provider to duplicate |
| `provider_id` | `string` | No | Legacy alias for id — prefer id |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant duplicate |
| `soft` | `boolean` | No | Stage the duplicate dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`DuplicateProviderApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the duplication succeeded |
| `provider_id` | `string` | Yes | New duplicated provider identifier |
| `message` | `string` | Yes | Result message |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |
| `providers` | [`ListProviderApiProvider`](/api-reference/provider/types#listproviderapiprovider)[] | No | Hydrated row for the newly-created duplicate provider (mirrors /provider/search shape) |

---

# `POST` `/provider/export`

Route: /api-reference/provider/post-provider-export

# `POST` `/provider/export`

Export Providers

Export all providers as a clean, denormalized CSV.

## Request Body (`ExportProviderApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `provider_id` | `string` | No | Provider identifier to export |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior export instead of re-running |
| `soft` | `boolean` | No | Stage the export dormant (active=False); ack with accept activates it |
| `accept` | `boolean` | No | Ack: True promotes the staged export, False rejects. Only meaningful with idempotency_key |

## Response (`ExportProviderApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource holding the export CSV |
| `file_name` | `string` | Yes | Suggested download file name |
| `row_count` | `integer` | Yes | Number of data rows in the export |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with `accept` to promote/reject the staged export. |

---

# `POST` `/provider/file_download`

Route: /api-reference/provider/post-provider-file-download

# `POST` `/provider/file_download`

Download File

Download a file by file resource ID.

## Request Body (`FileDownloadProviderApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource to download |

## Response

```
{}
```

---

# `POST` `/provider/generate`

Route: /api-reference/provider/post-provider-generate

# `POST` `/provider/generate`

Generate Provider

Trigger provider generation. Returns immediately; progress via events.

## Request Body (`ArtifactGenerateRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `instructions` | `string`[] | No | — |
| `config` | [`GenerateConfig`](/api-reference/provider/types#generateconfig) | No | — |
| `modalities` | `string`[] | No | — |
| `audios_id` | `string` | No | — |
| `conversation_id` | `string` | No | — |
| `trace_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `accept` | `boolean` | No | — |
| `wait_for_complete` | `boolean` | No | — |

## Response (`ArtifactGenerateResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `run_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `eval` | [`EvalSetup`](/api-reference/provider/types#evalsetup) | No | — |
| `produced_media` | [`ProducedMedia`](/api-reference/provider/types#producedmedia)[] | No | — |

---

# `POST` `/provider/generations`

Route: /api-reference/provider/post-provider-generations

# `POST` `/provider/generations`

Generations Provider

List provider generation groups — composable infra architecture.

## Request Body (`GenerationsProviderApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GenerationsProviderApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `items` | [`GenerationsProviderListItem`](/api-reference/provider/types#generationsproviderlistitem)[] | No | Generation groups |
| `total_count` | `integer` | No | Total number of matching generations |

---

# `POST` `/provider/get`

Route: /api-reference/provider/post-provider-get

# `POST` `/provider/get`

Get Provider

Get provider information using the canonical shared provider operation.

## Request Body (`GetProviderApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Provider unique identifier |
| `provider_id` | `string` | No | Legacy alias for provider unique identifier |
| `draft_id` | `string` | No | Draft unique identifier |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |
| `names` | [`app__infra__provider__types__SectionFilter`](/api-reference/provider/types#app-infra-provider-types-sectionfilter) | No | Filter options for names |
| `descriptions` | [`app__infra__provider__types__SectionFilter`](/api-reference/provider/types#app-infra-provider-types-sectionfilter) | No | Filter options for descriptions |
| `flags` | [`app__infra__provider__types__SectionFilter`](/api-reference/provider/types#app-infra-provider-types-sectionfilter) | No | Filter options for flags |
| `departments` | [`app__infra__provider__types__SectionFilter`](/api-reference/provider/types#app-infra-provider-types-sectionfilter) | No | Filter options for departments |
| `values` | [`app__infra__provider__types__SectionFilter`](/api-reference/provider/types#app-infra-provider-types-sectionfilter) | No | Filter options for values |
| `endpoints` | [`app__infra__provider__types__SectionFilter`](/api-reference/provider/types#app-infra-provider-types-sectionfilter) | No | Filter options for endpoints |
| `keys` | [`app__infra__provider__types__SectionFilter`](/api-reference/provider/types#app-infra-provider-types-sectionfilter) | No | Filter options for keys |

## Response (`GetProviderApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `provider_exists` | `boolean` | No | Whether the provider exists |
| `can_edit` | `boolean` | No | Whether the current user can edit |
| `disabled_reason` | `string` | No | Reason editing is disabled |
| `group_id` | `string` | No | Group identifier for the provider |
| `draft_name` | `string` | No | Immutable draft label from the active draft entry, when a ``draft_id`` was supplied. ``None`` for non-draft fetches. |
| `provider_id` | `string` | No | Provider identifier |
| `show_ai_generate` | `boolean` | No | Whether any step should show AI generate |
| `basic_show_ai_generate` | `boolean` | No | Show AI generate for basic step |
| `integrations_show_ai_generate` | `boolean` | No | Show AI generate for integrations step |
| `pending_ids` | `string`[] | No | Pending resource identifiers when available |
| `names` | [`ProviderNameResource`](/api-reference/provider/types#providernameresource)[] | No | Name resources |
| `descriptions` | [`ProviderDescriptionResource`](/api-reference/provider/types#providerdescriptionresource)[] | No | Description resources |
| `flags` | [`ProviderFlagResource`](/api-reference/provider/types#providerflagresource)[] | No | Flag resources (one per flags_resource row, value=true/false) |
| `departments` | [`ProviderDepartmentResource`](/api-reference/provider/types#providerdepartmentresource)[] | No | Department resources |
| `values` | [`ProviderValueResource`](/api-reference/provider/types#providervalueresource)[] | No | Value resources |
| `endpoints` | [`ProviderEndpointResource`](/api-reference/provider/types#providerendpointresource)[] | No | Endpoint resources |
| `keys` | [`ProviderKeyResource`](/api-reference/provider/types#providerkeyresource)[] | No | Key resources |

---

# `POST` `/provider/group`

Route: /api-reference/provider/post-provider-group

# `POST` `/provider/group`

Group Provider

Resolve or create a provider group with optional naming.

## Request Body (`GroupProviderApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | No | Existing group UUID (omit to create or reuse via time window) |
| `snapshot_key` | `string` | No | Snapshot key for SETNX-race convergence on a single group across concurrent reads (e.g. parallel /context + /group + /search fan-out on page load). Echoed back in the response. |

## Response (`GroupProviderApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Resolved or newly created group UUID |
| `name` | `string` | No | The group's current title (latest active group_names_entry, or 'New Chat' fallback for freshly minted groups) |
| `snapshot_key` | `string` | No | Snapshot key echoed back — the UUID concurrent fan-out reads converged on via SETNX. Mirrors the resolved group_id. |
| `runs` | [`GroupRun`](/api-reference/provider/types#grouprun)[] | No | Conversation history — populated when resolving an existing group for fetch |
| `group_exists` | `boolean` | No | (detail) Whether the group exists in storage — populated when ``include_resources=True`` |
| `actor_name` | `string` | No | (detail) Display name of the current actor (caller profile) |
| `total_message_count` | `integer` | No | (detail) Total number of messages in the group |
| `models` | [`GroupResource`](/api-reference/provider/types#groupresource)[] | No | (detail) Models used in the group |
| `agents` | [`GroupResource`](/api-reference/provider/types#groupresource)[] | No | (detail) Agents used in the group |
| `profiles` | [`GroupResource`](/api-reference/provider/types#groupresource)[] | No | (detail) Profiles that authored runs in this group |

---

# `POST` `/provider/problem`

Route: /api-reference/provider/post-provider-problem

# `POST` `/provider/problem`

Problem Provider

Report a provider problem — composable infra architecture.

## Request Body (`ProblemProviderApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | `string` | Yes | Problem type: feature, bug, question, other |
| `message` | `string` | Yes | Problem description (max 1000 chars) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant problem |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`ProblemProviderApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `problem_id` | `string` | Yes | UUID of the created problem |
| `success` | `boolean` | No | Whether the problem was created |
| `message` | `string` | No | Status message |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/provider/refresh`

Route: /api-reference/provider/post-provider-refresh

# `POST` `/provider/refresh`

Provider Refresh

Refresh provider materialized views and invalidate caches.

## Request Body (`RefreshProviderApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `targets` | `string`[] | No | MV targets to refresh (omit for all). Options: provider_drafts_mv |
| `idempotency_key` | `string` | No | Operation key for ack |
| `accept` | `boolean` | No | Accept or reject. Only meaningful with idempotency_key |
| `soft` | `boolean` | No | Stage the refresh as a pending (held) request — recorded but not enqueued; ack with accept releases/enqueues it |

## Response (`RefreshResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | — |
| `refreshed_views` | `string`[] | Yes | — |
| `invalidated_tags` | `string`[] | Yes | — |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/provider/search`

Route: /api-reference/provider/post-provider-search

# `POST` `/provider/search`

Search Provider

Search providers — composable infra architecture.

## Request Body (`SearchProviderApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | — |
| `filter_department_ids` | `string`[] | No | — |
| `filter_model_ids` | `string`[] | No | — |
| `filter_status` | `string`[] | No | — |
| `department_search` | `string` | No | — |
| `model_search` | `string` | No | — |
| `page_size` | `integer` | No | — |
| `page_offset` | `integer` | No | — |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`ListProviderApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `providers` | [`ListProviderApiProvider`](/api-reference/provider/types#listproviderapiprovider)[] | No | List of provider entries |
| `department_filter` | [`ListFilterSection`](/api-reference/provider/types#listfiltersection) | No | Department filter options |
| `model_filter` | [`ListFilterSection`](/api-reference/provider/types#listfiltersection) | No | Model filter options |
| `status_filter` | [`ListFilterSection`](/api-reference/provider/types#listfiltersection) | No | Status filter options |
| `flag_filter` | [`ListFilterSection`](/api-reference/provider/types#listfiltersection) | No | Filter options for flags in list UI |
| `total_count` | `integer` | No | Total number of providers |
| `import_fields` | [`ImportField`](/api-reference/provider/types#importfield)[] | No | CSV import column schema for the bulk-import dialog |

---

# `POST` `/provider/text_download`

Route: /api-reference/provider/post-provider-text-download

# `POST` `/provider/text_download`

Download Text

Download a text file by text resource ID.

## Request Body (`TextDownloadProviderApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `text_id` | `string` | Yes | UUID of the texts_resource to download |

## Response

```
{}
```

---

# `POST` `/provider/title`

Route: /api-reference/provider/post-provider-title

# `POST` `/provider/title`

Title Provider

Rename a provider's group (writes group_names_entry).

## Request Body (`TitleProviderApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Group to rename |
| `title` | `string` | Yes | New title (display name) for the group |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant rename |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`TitleProviderApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | The group that was renamed |
| `group_name_id` | `string` | Yes | UUID of the new group_names_entry row |
| `title` | `string` | Yes | The title that was set |
| `idempotency_key` | `string` | No | Operation key echoed back |

---

# `POST` `/provider/update`

Route: /api-reference/provider/post-provider-update

# `POST` `/provider/update`

Update Provider

Update providers using composable infra architecture.

## Request Body (`UpdateProviderApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `providers` | [`UpdateProviderItem`](/api-reference/provider/types#updateprovideritem)[] | No | List of providers to update (required on first call when ``all`` is false) |
| `all` | `boolean` | No | When true, apply ``patch`` to every provider matching the filter fields below (minus ``excluded_ids``) |
| `excluded_ids` | `string`[] | No | UUIDs to skip even when matched by ``all``-mode filters |
| `patch` | [`UpdateProviderPatch`](/api-reference/provider/types#updateproviderpatch) | No | Shared change set applied to every matched row when ``all=true`` (sparse — only set fields are updated; ``patch.id`` ignored) |
| `search` | `string` | No | Full-text search query |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `filter_model_ids` | `string`[] | No | Filter by model UUIDs |
| `filter_status` | `string`[] | No | Filter by status values (active/inactive) |
| `department_search` | `string` | No | Search text for department facet (no-op for row filtering) |
| `model_search` | `string` | No | Search text for model facet (no-op for row filtering) |
| `flag_search` | `string` | No | Search text for flag facet (no-op for row filtering) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant update |
| `soft` | `boolean` | No | Stage the update dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`UpdateProviderApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`ProviderResultItem`](/api-reference/provider/types#providerresultitem)[] | Yes | List of operation results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |
| `providers` | [`ListProviderApiProvider`](/api-reference/provider/types#listproviderapiprovider)[] | No | Hydrated rows for the successfully-updated providers (mirrors /provider/search shape) |

---

# `POST` `/provider/watch`

Route: /api-reference/provider/post-provider-watch

# `POST` `/provider/watch`

Provider Watch Once

One-shot snapshot of run state, snapshot-replayable via ``snapshot_key``.

## Request Body (`WatchApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Chat group whose events we watch |
| `run_id` | `string` | No | Specific run to watch (e.g. the ``run_id`` returned by a prior ``X_Generate`` call). If None, watches every active run in the group at call time. |
| `wait_for_complete` | `boolean` | No | If True, block until the watched run reaches a terminal (complete/failed) event or timeout fires. If False, return current state and exit immediately. |
| `timeout_seconds` | `integer` | No | Max wait time when ``wait_for_complete=True``. |
| `snapshot_key` | `string` | No | Read snapshot key — on the one-shot POST /watch, the audit wrapper records this watch's point-in-time view (latest run state at call time) keyed by it and replays the same view on any later call with the same key. Ignored by the SSE GET stream. |

## Response (`WatchApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `runs` | [`RunStatus`](/api-reference/provider/types#runstatus)[] | Yes | — |
| `timed_out` | `boolean` | No | — |
| `waited_seconds` | `number` | No | — |

---

# Provider Types

Route: /api-reference/provider/types

# Provider Types

## `CallerPermissions`

Evaluated permissions for the current caller on this artifact type.

| Field | Type | Required | Description |
|---|---|---|---|
| `can_create` | `boolean` | Yes | Whether the caller can create new artifacts |
| `can_draft` | `boolean` | Yes | Whether the caller can create/update drafts |
| `can_duplicate` | `boolean` | Yes | Whether the caller can duplicate artifacts |
| `has_access` | `boolean` | No | Whether the caller can view this entity |
| `can_edit` | `boolean` | No | Whether the caller can edit this entity |
| `can_delete` | `boolean` | No | Whether the caller can delete this entity |
| `disabled_reason` | `string` | No | Human-readable reason if editing is disabled |

---

## `ColumnInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Column name |
| `type` | `string` | Yes | Column data type |
| `nullable` | `boolean` | Yes | Whether the column is nullable |

---

## `CreateProviderItem`

Single provider item for create — no provider_id.

Required fields (name): provide ID or value.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Client-provided UUID for the new provider |
| `resource_id` | `string` | No | Optional preset UUID for the resource snapshot |
| `name_id` | `string` | No | REQUIRED FOR CREATE (or pass ``name``). UUID of an existing name resource. |
| `name` | `string` | No | REQUIRED FOR CREATE (or pass ``name_id``). Display name text — creates a new name resource on the fly. |
| `description_id` | `string` | No | Description resource identifier |
| `description` | `string` | No | Description text value |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs |
| `active` | `boolean` | No | Denormalized provider_active flag state |
| `department_ids` | `string`[] | No | Department identifiers |
| `departments` | `string`[] | No | Department names to match |
| `endpoint_ids` | `string`[] | No | Endpoint resource identifiers |
| `key_ids` | `string`[] | No | API key resource identifiers |
| `value_id` | `string` | No | Value resource identifier |
| `endpoint` | `string` | No | Provider API endpoint URL |
| `key` | `string` | No | Provider API key |
| `value` | `string` | No | Provider identifier value |

---

## `DeleteProviderResult`

Per-item result within a bulk delete response.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the deletion succeeded |
| `provider_id` | `string` | No | Deleted provider identifier (None for soft-skipped not-found rows under ``all=true``) |
| `message` | `string` | Yes | Result message |

---

## `DocsApiResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `list` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `detail` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `new` | [`PageMetaItem`](#pagemetaitem) | Yes | — |

---

## `DocsResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Resource or entry name |
| `type` | `string` | Yes | Resource or entry type identifier |
| `description` | `string` | Yes | Human-readable description |
| `materialized_view` | [`MvInfo`](#mvinfo) | No | Materialized view metadata |
| `tables` | [`TableInfo`](#tableinfo)[] | Yes | Related database tables |
| `operations` | [`OperationInfo`](#operationinfo)[] | Yes | Available operations |

---

## `EvalSetup`

Run-level eval scaffold — first-class on the generate response.

Audit's ``**output`` spread carries this onto
``<artifact>.generate.completed``. Null when no rubric-bearing
agent participated.

| Field | Type | Required | Description |
|---|---|---|---|
| `test_id` | `string` | Yes | — |
| `invocations` | [`InvocationSlot`](#invocationslot)[] | Yes | — |

---

## `GenerateConfig`

Developer configuration — all optional with sensible defaults.

| Field | Type | Required | Description |
|---|---|---|---|
| `operations` | `string`[] | No | — |
| `dangerous` | `boolean` | No | — |
| `params` | `object` | No | — |
| `group_id` | `string` | No | — |

---

## `GenerationsProviderListItem`

Single generation group in the provider generations response.

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | UUID of the generation group |
| `session_id` | `string` | No | UUID of the parent session |
| `group_name` | `string` | No | Name of the generation group |
| `created_at` | `string` | No | Timestamp of the generation |

---

## `GetProviderDraftResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | UUID of the draft |
| `created_at` | `string` | Yes | Creation timestamp |
| `generated` | `boolean` | Yes | Whether this was AI-generated |
| `mcp` | `boolean` | Yes | Whether MCP tooling was used |
| `active` | `boolean` | Yes | Whether this draft is active |
| `session_id` | `string` | Yes | Associated session UUID |
| `name` | `string` | No | Immutable draft label set at create time |
| `department_ids` | `string`[] | Yes | Associated department UUIDs |
| `description_ids` | `string`[] | Yes | Associated description UUIDs |
| `endpoint_ids` | `string`[] | Yes | Associated endpoint UUIDs |
| `flag_ids` | `string`[] | Yes | Associated flag UUIDs |
| `key_ids` | `string`[] | Yes | Associated key UUIDs |
| `name_ids` | `string`[] | Yes | Associated name UUIDs |
| `profile_ids` | `string`[] | Yes | Associated profile UUIDs |
| `value_id` | `string` | No | Associated value UUID |
| `pending_department_ids` | `string`[] | No | Pending department UUIDs |
| `pending_description_ids` | `string`[] | No | Pending description UUIDs |
| `pending_endpoint_ids` | `string`[] | No | Pending endpoint UUIDs |
| `pending_flag_ids` | `string`[] | No | Pending flag UUIDs |
| `pending_key_ids` | `string`[] | No | Pending key UUIDs |
| `pending_name_ids` | `string`[] | No | Pending name UUIDs |
| `pending_value_ids` | `string`[] | No | Pending value UUIDs |

---

## `GroupCall`

Tool call referenced by a message.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `tool_name` | `string` | No | — |
| `template_name` | `string` | No | — |
| `tool` | `object` | No | — |
| `ledger_status` | `string` | No | — |
| `ledger_operation` | `string` | No | — |
| `ledger_artifact` | `string` | No | — |
| `ledger_artifact_id` | `string` | No | — |

---

## `GroupMessage`

Message within a run.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `role` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `text_ids` | `string`[] | No | — |
| `audio_ids` | `string`[] | No | — |
| `image_ids` | `string`[] | No | — |
| `video_ids` | `string`[] | No | — |
| `file_ids` | `string`[] | No | — |
| `call_ids` | `string`[] | No | — |
| `calls` | [`GroupCall`](#groupcall)[] | No | — |
| `reasoning` | `boolean` | No | True when this row is a chain-of-thought trace persisted alongside the assistant answer (rendered as a collapsed accordion). |
| `in_context` | `boolean` | No | Whether this message is included in the LLM context for the next generation. Mirrors the dedup pass that builds chat history (see in_context_reason). |
| `in_context_reason` | `string` | No | Why this message is in/out of LLM context. 'kept' = included; 'deduped_read' = older read-only call to a tool that has a fresher result later in the group; future values may include 'trimmed_top_n'. |

---

## `GroupResource`

Lightweight `\{id, name\}` for cross-referencing run-level ids
(``model_id`` / ``agent_id`` / ``profile_id``) against human-readable
names on the analytics panel. Names come from the canonical
``get_models`` / ``get_agents`` / ``get_profiles`` black boxes.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `name` | `string` | No | — |

---

## `GroupRun`

Run within a group, with its messages.

Carries token / cost / model / agent / profile attribution so the
analytics view can render per-run cost + actor info without a
parallel detail shape. ``profile_id`` is the authoring profile
(human user), ``agent_id`` is the LLM-side actor, ``model_id`` is
the model used by that agent. All optional — runs predating these
columns or with unresolved attributions surface ``None``.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `input_tokens` | `integer` | No | — |
| `output_tokens` | `integer` | No | — |
| `cached_input_tokens` | `integer` | No | — |
| `cost` | `number` | No | — |
| `model_id` | `string` | No | — |
| `agent_id` | `string` | No | — |
| `profile_id` | `string` | No | — |
| `previous_context_start_index` | `integer` | No | Index in ``messages`` where the current run's own messages begin; earlier rows are previous-context replay. ``None`` when the run has no previous context attached. |
| `messages` | [`GroupMessage`](#groupmessage)[] | No | — |

---

## `ImportField`

Field descriptor for CSV import column mapping.

| Field | Type | Required | Description |
|---|---|---|---|
| `key` | `string` | Yes | — |
| `label` | `string` | Yes | — |
| `required` | `boolean` | No | — |
| `multi` | `boolean` | No | — |
| `type` | `string` | No | — |
| `example` | `string` | No | — |
| `description` | `string` | No | — |

---

## `InvocationSlot`

One agent's slot in a multi-agent generation pool.

Populated by ``setup_generation_test`` when an agent carries a
rubric. The client uses these IDs to drive the eval workflow:
review the candidate's output, optionally fire a grader against
its ``invocation_id``, and promote/reject by call_id via the
existing ``idempotency_key + accept`` pattern.

| Field | Type | Required | Description |
|---|---|---|---|
| `invocation_id` | `string` | Yes | — |
| `agent_id` | `string` | Yes | — |
| `rubric_id` | `string` | No | — |

---

## `ListFilterOption`

Standardized option for list endpoint filter sections.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier for this filter option |
| `name` | `string` | No | Display name |
| `count` | `integer` | No | Number of matching records |
| `hex_code` | `string` | No | Hex color code for display |
| `value` | `string` | No | Internal value |
| `type` | `string` | No | Option type discriminator |

---

## `ListFilterSection`

Filter section with options and echoed request state.

| Field | Type | Required | Description |
|---|---|---|---|
| `options` | [`ListFilterOption`](#listfilteroption)[] | No | Available filter options |
| `selected_ids` | `string`[] | No | Currently selected filter option IDs |
| `search` | `string` | No | Active search text for filtering |

---

## `ListProviderApiProvider`

Provider type for list endpoint with computed permissions.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Provider artifact UUID (canonical id; mirrors provider_id) |
| `provider_id` | `string` | No | Provider unique identifier |
| `name` | `string` | No | Display name of the provider |
| `description` | `string` | No | Provider description text |
| `value` | `string` | No | Internal value or model identifier |
| `active` | `boolean` | No | Whether this provider is currently active |
| `is_inactive` | `boolean` | No | Whether the provider is inactive |
| `updated_at` | `string` | No | Timestamp of last update |
| `department_ids` | `string`[] | No | Associated department identifiers |
| `model_usage_count` | `integer` | No | Number of models using this provider |
| `model_ids` | `string`[] | No | Associated model identifiers |
| `can_edit` | `boolean` | No | Whether the current user can edit |
| `can_delete` | `boolean` | No | Whether the current user can delete |
| `can_duplicate` | `boolean` | No | Whether the current user can duplicate |
| `pending_status` | `string` | No | Pending soft_calls_entry status (e.g. 'pending') |
| `pending_operation` | `string` | No | Pending operation (create/update/delete/duplicate) |
| `pending_call_id` | `string` | No | Originating tool call id for ack |

---

## `MvInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Materialized view name |
| `definition` | `string` | Yes | SQL definition of the view |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the view |

---

## `OperationInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Operation name |
| `description` | `string` | Yes | Human-readable description of the operation |
| `params` | [`ParamInfo`](#paraminfo)[] | Yes | List of operation parameters |
| `returns` | `object` | No | Return type schema |

---

## `OperationPrompts`

Starter prompts keyed by operation name.

Each key is an operation (e.g. "create", "search", "draft", "export")
and the value is a list of starter prompts for that operation.
The client picks from the operations the caller has permission for
and rotates through them.

| Field | Type | Required | Description |
|---|---|---|---|
| `prompts` | `object` | No | Map of operation name to starter prompts |

---

## `PageMetaItem`

| Field | Type | Required | Description |
|---|---|---|---|
| `title` | `string` | Yes | — |
| `description` | `string` | Yes | — |

---

## `ParamInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Parameter name |
| `type` | `string` | Yes | Parameter data type |
| `required` | `boolean` | Yes | Whether the parameter is required |
| `default` | `any` | No | Default value if not required |

---

## `ProducedMedia`

One asset produced by a generation run.

``resource_id`` is the canonical id the per-artifact download tools
accept (e.g. ``Scenario_Image_Download(image_id=resource_id)`` for
``modality="image"``). It maps to ``images_resource.id`` /
``videos_resource.id`` / ``audios_resource.id`` depending on the
modality.

| Field | Type | Required | Description |
|---|---|---|---|
| `modality` | `"image"` \| `"video"` \| `"audio"` | Yes | — |
| `resource_id` | `string` | Yes | — |
| `upload_id` | `string` | Yes | — |
| `mime_type` | `string` | No | — |
| `file_size` | `integer` | No | — |

---

## `ProfileSummary`

Caller identity derived from JWT — who you are on this page.

Superset of the old six-field version: now carries everything the client
needs so that ``/\{artifact\}/context`` fully replaces ``/profiles/context``
and the extra ``getLayoutContextData`` round-trip can be dropped.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Display name of the authenticated user |
| `role` | `string` | Yes | Role name (e.g. 'Super Administrator') |
| `role_level` | `integer` | Yes | Role hierarchy level (0 = highest privilege) |
| `department_ids` | `string`[] | Yes | Departments the user belongs to |
| `artifact_access` | `string`[] | Yes | Artifact types this role can access (sidebar visibility) |
| `role_permissions` | `any`[][] | Yes | Full (artifact, operation) permission tuples for granular page gating |
| `is_active` | `boolean` | Yes | Whether the user's profile is active |
| `id` | `string` | Yes | Profile UUID (SocketProvider, ProfileProvider) |
| `theme` | [`ThemeBundle`](#themebundle) | No | Resolved theme: hex primitives + derived oklch tokens + score thresholds |
| `session_id` | `string` | No | Current session UUID |
| `is_emulation` | `boolean` | No | Whether user is in emulation mode (ProfileProvider) |
| `role_resources` | [`QGetProfileContextV4RoleResource`](#qgetprofilecontextv4roleresource)[] | No | All role resources for emulation display (ProfileProvider) |
| `scoped_roles` | `string`[] | No | Roles the user can emulate (ProfileProvider) |
| `active` | `boolean` | No | Alias for is_active (ProfileProvider uses this name) |

---

## `ProviderDepartmentResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `department_id` | `string` | No | Department identifier |
| `name` | `string` | No | Department name |
| `description` | `string` | No | Department description |
| `generated` | `boolean` | No | Whether the department was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `ProviderDescriptionResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Description resource identifier |
| `description` | `string` | No | Provider description |
| `generated` | `boolean` | No | Whether the description was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `ProviderEndpointResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Endpoint resource identifier |
| `base_url` | `string` | No | Endpoint base URL |
| `generated` | `boolean` | No | Whether the endpoint was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `ProviderFieldError`

Per-field error from value resolution.

| Field | Type | Required | Description |
|---|---|---|---|
| `field` | `string` | Yes | Field name that caused the error |
| `message` | `string` | Yes | Error message describing the issue |

---

## `ProviderFlagResource`

Flag option row — one per (name, type, value) entry in flags_resource.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Flag resource identifier |
| `name` | `string` | No | Flag display name |
| `type` | `string` | No | Flag type (e.g. 'provider_active') |
| `value` | `boolean` | No | Underlying bool value of this option |
| `description` | `string` | No | Flag description |
| `icon_id` | `string` | No | Icon identifier for the flag |
| `icon` | `string` | No | Resolved SVG markup for the icon (hydrated from icons_resource) |
| `generated` | `boolean` | No | Whether this flag was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `ProviderKeyResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Key resource identifier |
| `key` | `string` | No | Provider key value |
| `name` | `string` | No | Key display name |
| `description` | `string` | No | Key description |
| `generated` | `boolean` | No | Whether the key was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `ProviderNameResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Name resource identifier |
| `name` | `string` | No | Provider display name |
| `generated` | `boolean` | No | Whether the name was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `ProviderResultItem`

Per-item result within a bulk create/update response.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `provider_id` | `string` | No | Provider unique identifier |
| `message` | `string` | Yes | Result message |
| `errors` | [`ProviderFieldError`](#providerfielderror)[] | No | List of field-level errors |

---

## `ProviderValueResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Value resource identifier |
| `value` | `string` | No | Provider value |
| `value_type` | `string` | No | Stored value type |
| `generated` | `boolean` | No | Whether the value was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `QGetProfileContextV4RoleResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `role` | `string` | No | — |
| `name` | `string` | No | — |
| `description` | `string` | No | — |
| `icon_value` | `string` | No | — |
| `color_hex` | `string` | No | — |

---

## `RunStatus`

Outcome of one watched run.

| Field | Type | Required | Description |
|---|---|---|---|
| `run_id` | `string` | Yes | — |
| `status` | `"pending"` \| `"completed"` \| `"failed"` | Yes | — |
| `modality` | `string` | No | Modality of generated output (image, video, text…) |
| `resource_ids` | `string`[] | No | Resource UUIDs produced by this run (e.g. images_resource ids) |
| `error` | `string` | No | — |

---

## `TableInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Table name |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the table |

---

## `ThemeBundle`

Full theme payload for a page bootstrap.

Riding along on every ``/\{artifact\}/context`` response via
``ProfileSummary.theme``. Layers:
  - ``primitives`` / ``dark_primitives`` — hex inputs the settings
    editor reads/writes (light + dark palettes).
  - ``tokens`` / ``dark_tokens`` — oklch tokens the client paints with.
    ``ThemeStyle`` emits two ``<style>`` blocks: one scoped to
    ``:root:not(.dark)`` (light) and one to ``:root.dark`` (dark).
  - ``thresholds`` — numeric score thresholds for analytics components.
Empty-in → empty-out per token: missing values fall through to the
matching ``globals.css`` default.

| Field | Type | Required | Description |
|---|---|---|---|
| `primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (light palette, for the theme editor) |
| `tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for light mode (SSR CSS-var injection) |
| `dark_primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (dark palette, for the theme editor) |
| `dark_tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for dark mode (SSR CSS-var injection) |
| `thresholds` | [`Thresholds`](#thresholds) | No | Score thresholds resolved from the setting |

---

## `ThemePrimitives`

40 optional fields. The 17 essentials drive the rest; the other 23
are overrides for fine-tuning when derivation isn't what you want.

Empty primitive → empty token → client falls back to globals.css.

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `primary` | `string` | No | — |
| `accent` | `string` | No | — |
| `card` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `ring` | `string` | No | — |
| `border` | `string` | No | — |
| `destructive` | `string` | No | — |
| `success` | `string` | No | — |
| `warning` | `string` | No | — |
| `info` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `input` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `ThemeTokens`

40 fully-resolved CSS variable values (snake_case 1:1 with vars).

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `accent` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `border` | `string` | No | — |
| `input` | `string` | No | — |
| `ring` | `string` | No | — |
| `success` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `Thresholds`

Numeric score thresholds resolved from the active setting.

Server pre-buckets dashboard metrics into ``success | warning | danger |
neutral`` already, so most components don't need these values. Surface
them for chart reference lines, tooltips, and any client-side bucketing.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `integer` | Yes | Score >= this counts as success |
| `warning` | `integer` | Yes | Score >= this counts as warning |
| `danger` | `integer` | Yes | Score < success threshold but >= this counts as danger; below is neutral/no-data |

---

## `UpdateProviderItem`

Single provider item for update — provider_id required, all fields optional.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | Target provider identifier to update |
| `name_id` | `string` | No | Name resource identifier |
| `name` | `string` | No | Display name value |
| `description_id` | `string` | No | Description resource identifier |
| `description` | `string` | No | Description text value |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs |
| `active` | `boolean` | No | Denormalized provider_active flag state |
| `department_ids` | `string`[] | No | Department identifiers |
| `departments` | `string`[] | No | Department names to match |
| `endpoint_ids` | `string`[] | No | Endpoint resource identifiers |
| `key_ids` | `string`[] | No | API key resource identifiers |
| `value_id` | `string` | No | Value resource identifier |

---

## `UpdateProviderPatch`

Shared patch for bulk-update-all-matching mode.

Inherits every field from ``UpdateProviderItem`` and just relaxes
``id`` to optional — the bulk impl stamps the resolved id onto a
clone of the patch per matched row, so any client-supplied id is
ignored. Sparse semantics: only fields the client sets are written.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Ignored — bulk impl stamps the resolved provider id per matched row |
| `name_id` | `string` | No | Name resource identifier |
| `name` | `string` | No | Display name value |
| `description_id` | `string` | No | Description resource identifier |
| `description` | `string` | No | Description text value |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs |
| `active` | `boolean` | No | Denormalized provider_active flag state |
| `department_ids` | `string`[] | No | Department identifiers |
| `departments` | `string`[] | No | Department names to match |
| `endpoint_ids` | `string`[] | No | Endpoint resource identifiers |
| `key_ids` | `string`[] | No | API key resource identifiers |
| `value_id` | `string` | No | Value resource identifier |

---

## `app__infra__provider__types__DraftFormState`

Server-authoritative form state returned after draft save.

| Field | Type | Required | Description |
|---|---|---|---|
| `name_id` | `string` | No | Resolved name resource identifier |
| `name` | `string` | No | Resolved name value |
| `description_id` | `string` | No | Resolved description resource identifier |
| `description` | `string` | No | Resolved description value |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs |
| `active` | `boolean` | No | Echoed provider_active flag state |
| `departments` | `string`[] | No | Resolved department names |
| `department_ids` | `string`[] | Yes | Department identifiers |
| `endpoint` | `string` | No | Resolved endpoint value |
| `endpoint_id` | `string` | No | Resolved endpoint resource identifier |
| `endpoint_ids` | `string`[] | Yes | Endpoint resource identifiers |
| `key` | `string` | No | Resolved key value |
| `key_name` | `string` | No | Resolved key display name |
| `key_description` | `string` | No | Resolved key description |
| `key_id` | `string` | No | Resolved key resource identifier |
| `key_ids` | `string`[] | Yes | API key resource identifiers |
| `value` | `string` | No | Resolved value |
| `value_id` | `string` | No | Value resource identifier |
| `pending_ids` | `string`[] | No | Pending resource identifiers |

---

## `app__infra__provider__types__SectionFilter`

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Filter options by search text |
| `limit` | `integer` | No | Max options to return |
| `selected` | `boolean` | No | Only return selected items |
| `suggested` | `boolean` | No | Only return suggested items |
| `include` | `boolean` | No | Include this section in response (default true) |

---

---

# `GET` `/`

Route: /api-reference/root

# `GET` `/`

Root Info

## Response

```
{}
```

---

# `GET` `/rubric/watch`

Route: /api-reference/rubric/get-rubric-watch

# `GET` `/rubric/watch`

Rubric Watch

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `group_id` | query | No | — |
| `run_id` | query | No | Optional run filter. If provided, only events whose envelope run_id matches are streamed. Omit to receive every rubric event in the group (the FE default). |

## Response

```
{}
```

---

# `POST` `/rubric/call_download`

Route: /api-reference/rubric/post-rubric-call-download

# `POST` `/rubric/call_download`

Download Call

Download a call file by call resource ID.

## Request Body (`CallDownloadRubricApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `call_id` | `string` | Yes | UUID of the calls_resource to download |

## Response

```
{}
```

---

# `POST` `/rubric/context`

Route: /api-reference/rubric/post-rubric-context

# `POST` `/rubric/context`

Get Rubric Context

Get page context for the rubric artifact.

Returns docs + profile identity + evaluated permissions in a single call.
Superset of /docs — clients can migrate from /docs to /context incrementally.

## Request Body (`DocsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entity_id` | `string` | No | — |
| `snapshot_key` | `string` | No | — |
| `schema` | `boolean` | No | If true, include MCP/tooling schema metadata (artifact, entries, resources, permission_docs, api_operations). Defaults to false for lean page-bootstrap responses. |

## Response (`ComposedContextResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Artifact name |
| `type` | `string` | Yes | Artifact type identifier |
| `description` | `string` | Yes | Human-readable description |
| `artifact` | [`DocsResponse`](/api-reference/rubric/types#docsresponse) | No | Artifact tool documentation (None unless schema=true) |
| `entries` | [`DocsResponse`](/api-reference/rubric/types#docsresponse)[] | No | Entry documentation list (None unless schema=true) |
| `resources` | [`DocsResponse`](/api-reference/rubric/types#docsresponse)[] | No | Resource documentation list (None unless schema=true) |
| `permission_docs` | [`OperationInfo`](/api-reference/rubric/types#operationinfo)[] | No | Permission function signatures for MCP/dev tooling (None unless schema=true) |
| `api_operations` | [`OperationInfo`](/api-reference/rubric/types#operationinfo)[] | No | API operation documentation (None unless schema=true) |
| `page_metadata` | [`DocsApiResponse`](/api-reference/rubric/types#docsapiresponse) | No | Page-level metadata |
| `prompts` | [`OperationPrompts`](/api-reference/rubric/types#operationprompts) | No | Starter prompts keyed by operation |
| `profile` | [`ProfileSummary`](/api-reference/rubric/types#profilesummary) | Yes | Caller identity from JWT |
| `caller_permissions` | [`CallerPermissions`](/api-reference/rubric/types#callerpermissions) | Yes | Evaluated permissions for this caller |

---

# `POST` `/rubric/create`

Route: /api-reference/rubric/post-rubric-create

# `POST` `/rubric/create`

Create Rubric

Create rubrics using composable infra architecture.

## Request Body (`CreateRubricApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `rubrics` | [`CreateRubricItem`](/api-reference/rubric/types#createrubricitem)[] | Yes | List of rubrics to create |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant create |
| `soft` | `boolean` | No | Stage the create dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`CreateRubricApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`RubricResultItem`](/api-reference/rubric/types#rubricresultitem)[] | Yes | List of operation results |
| `rubrics` | [`ListRubricApiRubric`](/api-reference/rubric/types#listrubricapirubric)[] | No | Hydrated rubric rows for the rubrics just created (omitted on soft writes) |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/rubric/csv`

Route: /api-reference/rubric/post-rubric-csv

# `POST` `/rubric/csv`

Parse Rubric Csv

Parse a CSV file and return mapped items for preview.

## Request Body

| Field | Type | Required | Description |
|---|---|---|---|
| `file` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `soft` | `boolean` | No | — |
| `accept` | `boolean` | No | — |

## Response (`ParseRubricCsvApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `upload_id` | `string` | Yes | — |
| `items` | [`CreateRubricItem`](/api-reference/rubric/types#createrubricitem)[] | Yes | — |
| `mapped_fields` | `string`[] | Yes | — |
| `row_count` | `integer` | Yes | — |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with `accept` to promote/reject the staged raw-CSV upload. NOTE: ack returns no items (the preview is only on the propose). |

---

# `POST` `/rubric/delete`

Route: /api-reference/rubric/post-rubric-delete

# `POST` `/rubric/delete`

Delete Rubric

Bulk delete rubrics — composable infra architecture.

## Request Body (`DeleteRubricApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `rubric_ids` | `string`[] | No | Rubric UUIDs to delete (required on first call when ``all`` is false) |
| `all` | `boolean` | No | When true, delete every rubric matching the filter fields below (minus ``excluded_ids``) |
| `excluded_ids` | `string`[] | No | UUIDs to skip even when matched by ``all``-mode filters |
| `search` | `string` | No | Full-text search query |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `filter_simulation_ids` | `string`[] | No | Filter by simulation UUIDs |
| `department_search` | `string` | No | Search text for department facet (no-op for row filtering) |
| `simulation_search` | `string` | No | Search text for simulation facet (no-op for row filtering) |
| `flag_search` | `string` | No | Search text for flag facet (no-op for row filtering) |
| `idempotency_key` | `string` | No | Operation key for ack — confirms or rejects a dormant delete |
| `soft` | `boolean` | No | Stage the delete dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (confirm) or reject dormant state. Only meaningful with idempotency_key |

## Response (`DeleteRubricApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`DeleteRubricResult`](/api-reference/rubric/types#deleterubricresult)[] | Yes | List of operation results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/rubric/draft`

Route: /api-reference/rubric/post-rubric-draft

# `POST` `/rubric/draft`

Patch Rubric Draft

Patch rubric draft — composable infra architecture.

## Request Body (`PatchRubricDraftApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `draft_id` | `string` | No | Existing draft UUID to update |
| `input_draft_id` | `string` | No | Existing draft UUID to patch |
| `name` | `string` | No | Name value to create a resource |
| `name_id` | `string` | No | Existing name resource UUID |
| `description` | `string` | No | Description value to create a resource |
| `description_id` | `string` | No | Existing description resource UUID |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `active` | `boolean` | No | Denormalized rubric_active flag state |
| `simulation_rubric` | `boolean` | No | Denormalized simulation_rubric flag state |
| `video_rubric` | `boolean` | No | Denormalized video_rubric flag state |
| `departments` | `string`[] | No | Department names to resolve |
| `department_ids` | `string`[] | No | Department UUIDs |
| `pass_points_id` | `string` | No | Pass-type Points resource UUID |
| `pass_points` | `integer` | No | Pass points value (resolves to a pass-type Points resource) |
| `standard_group_ids` | `string`[] | No | Standard group UUIDs |
| `standard_groups` | [`RubricStandardGroupDraftValue`](/api-reference/rubric/types#rubricstandardgroupdraftvalue)[] | No | Inline-created standard groups. Entries without id are created; resulting IDs merge into standard_group_ids. |
| `standard_ids` | `string`[] | No | Standard UUIDs |
| `standards` | [`RubricStandardDraftValue`](/api-reference/rubric/types#rubricstandarddraftvalue)[] | No | Grid-editor standards. Entries without id are created; resulting IDs merge into standard_ids. |
| `pending_ids` | `string`[] | No | Resource IDs to keep pending where supported |
| `idempotency_key` | `string` | No | Operation key for ack or retry |
| `soft` | `boolean` | No | Stage the draft dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept or reject dormant state |

## Response (`PatchRubricDraftApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `draft_id` | `string` | Yes | Draft UUID |
| `idempotency_key` | `string` | No | Idempotency key for this draft operation |
| `message` | `string` | Yes | Human-readable result message |
| `form_state` | [`app__infra__rubric__types__DraftFormState`](/api-reference/rubric/types#app-infra-rubric-types-draftformstate) | No | Server-authoritative form state |

---

# `POST` `/rubric/drafts`

Route: /api-reference/rubric/post-rubric-drafts

# `POST` `/rubric/drafts`

Get Rubric Drafts

List rubric drafts owned by the current profile.

## Request Body (`GetRubricDraftsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE substring) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GetRubricDraftsApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entries` | [`GetRubricDraftResponse`](/api-reference/rubric/types#getrubricdraftresponse)[] | No | List of rubric draft entries |

---

# `POST` `/rubric/duplicate`

Route: /api-reference/rubric/post-rubric-duplicate

# `POST` `/rubric/duplicate`

Duplicate Rubric

Duplicate a rubric — composable infra architecture.

## Request Body (`DuplicateRubricApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `rubric_id` | `string` | Yes | Rubric UUID to duplicate |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant duplicate |
| `soft` | `boolean` | No | Stage the duplicate dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`DuplicateRubricApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `rubric_id` | `string` | Yes | Newly created rubric UUID |
| `message` | `string` | Yes | Human-readable result message |
| `rubrics` | [`ListRubricApiRubric`](/api-reference/rubric/types#listrubricapirubric)[] | No | Hydrated rubric row for the duplicate (single-element list; omitted on soft writes) |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/rubric/export`

Route: /api-reference/rubric/post-rubric-export

# `POST` `/rubric/export`

Export Rubrics

Render a rubric PDF and register it as a downloadable file.

## Request Body (`ExportRubricApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `rubric_id` | `string` | Yes | Rubric UUID to export |
| `chat_id` | `string` | No | Optional attempt chat UUID. When provided, the PDF highlights achieved/passed standards and renders per-standard feedback resolved from the chat's latest grade. Without it, an empty rubric template is returned. |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior export instead of re-running |
| `soft` | `boolean` | No | Stage the export dormant (active=False); ack with accept activates it |
| `accept` | `boolean` | No | Ack: True promotes the staged export, False rejects. Only meaningful with idempotency_key |

## Response (`ExportRubricApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource holding the export |
| `file_name` | `string` | Yes | Suggested download file name |
| `row_count` | `integer` | Yes | Number of rows in the export (rubric standards) |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with `accept` to promote/reject the staged export. |

---

# `POST` `/rubric/file_download`

Route: /api-reference/rubric/post-rubric-file-download

# `POST` `/rubric/file_download`

Download File

Download a file by file resource ID.

## Request Body (`FileDownloadRubricApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource to download |

## Response

```
{}
```

---

# `POST` `/rubric/generate`

Route: /api-reference/rubric/post-rubric-generate

# `POST` `/rubric/generate`

Generate Rubric

Trigger rubric generation. Returns immediately; progress via events.

## Request Body (`ArtifactGenerateRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `instructions` | `string`[] | No | — |
| `config` | [`GenerateConfig`](/api-reference/rubric/types#generateconfig) | No | — |
| `modalities` | `string`[] | No | — |
| `audios_id` | `string` | No | — |
| `conversation_id` | `string` | No | — |
| `trace_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `accept` | `boolean` | No | — |
| `wait_for_complete` | `boolean` | No | — |

## Response (`ArtifactGenerateResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `run_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `eval` | [`EvalSetup`](/api-reference/rubric/types#evalsetup) | No | — |
| `produced_media` | [`ProducedMedia`](/api-reference/rubric/types#producedmedia)[] | No | — |

---

# `POST` `/rubric/generations`

Route: /api-reference/rubric/post-rubric-generations

# `POST` `/rubric/generations`

Generations Rubric

List rubric generation groups — composable infra architecture.

## Request Body (`GenerationsRubricApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GenerationsRubricApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `items` | [`GenerationsRubricListItem`](/api-reference/rubric/types#generationsrubriclistitem)[] | No | Generation groups |
| `total_count` | `integer` | No | Total number of matching generations |

---

# `POST` `/rubric/get`

Route: /api-reference/rubric/post-rubric-get

# `POST` `/rubric/get`

Get Rubric

Get rubric information using the canonical shared rubric operation.

## Request Body (`GetRubricApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Rubric UUID to retrieve |
| `rubric_id` | `string` | No | Legacy rubric UUID to retrieve |
| `draft_id` | `string` | No | Draft UUID to load from |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |
| `names` | [`app__infra__rubric__types__SectionFilter`](/api-reference/rubric/types#app-infra-rubric-types-sectionfilter) | No | Filter options for names section |
| `descriptions` | [`app__infra__rubric__types__SectionFilter`](/api-reference/rubric/types#app-infra-rubric-types-sectionfilter) | No | Filter options for descriptions section |
| `flags` | [`app__infra__rubric__types__SectionFilter`](/api-reference/rubric/types#app-infra-rubric-types-sectionfilter) | No | Filter options for flags section |
| `departments` | [`app__infra__rubric__types__SectionFilter`](/api-reference/rubric/types#app-infra-rubric-types-sectionfilter) | No | Filter options for departments section |
| `points` | [`app__infra__rubric__types__SectionFilter`](/api-reference/rubric/types#app-infra-rubric-types-sectionfilter) | No | Filter options for points section |
| `standard_groups` | [`app__infra__rubric__types__SectionFilter`](/api-reference/rubric/types#app-infra-rubric-types-sectionfilter) | No | Filter options for standard groups section |
| `standards` | [`app__infra__rubric__types__SectionFilter`](/api-reference/rubric/types#app-infra-rubric-types-sectionfilter) | No | Filter options for standards section |

## Response (`GetRubricApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current user |
| `rubric_exists` | `boolean` | No | Whether the rubric exists |
| `can_edit` | `boolean` | No | Whether the current user can edit |
| `disabled_reason` | `string` | No | Reason editing is disabled |
| `group_id` | `string` | No | Associated group UUID |
| `draft_name` | `string` | No | Immutable draft label from the active draft entry, when a ``draft_id`` was supplied. ``None`` for non-draft fetches. |
| `show_ai_generate` | `boolean` | No | Whether any section supports AI generation |
| `basic_show_ai_generate` | `boolean` | No | Whether to show AI generate for the basic step |
| `content_show_ai_generate` | `boolean` | No | Whether to show AI generate for the content step |
| `pending_ids` | `string`[] | No | Pending resource identifiers when available |
| `names` | [`RubricNameResource`](/api-reference/rubric/types#rubricnameresource)[] | No | Name resources |
| `descriptions` | [`RubricDescriptionResource`](/api-reference/rubric/types#rubricdescriptionresource)[] | No | Description resources |
| `flags` | [`RubricFlagResource`](/api-reference/rubric/types#rubricflagresource)[] | No | Flag resources (one per flags_resource row, value=true/false) |
| `departments` | [`RubricDepartmentResource`](/api-reference/rubric/types#rubricdepartmentresource)[] | No | Department resources |
| `points` | [`RubricPointResource`](/api-reference/rubric/types#rubricpointresource)[] | No | Point resources |
| `standard_groups` | [`RubricStandardGroupResource`](/api-reference/rubric/types#rubricstandardgroupresource)[] | No | Standard group resources |
| `standards` | [`RubricStandardResource`](/api-reference/rubric/types#rubricstandardresource)[] | No | Standard resources |

---

# `POST` `/rubric/group`

Route: /api-reference/rubric/post-rubric-group

# `POST` `/rubric/group`

Group Rubric

Resolve or create a rubric group with optional naming.

## Request Body (`GroupRubricApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | No | Existing group UUID (omit to create or reuse via time window) |
| `snapshot_key` | `string` | No | Snapshot key for SETNX-race convergence on a single group across concurrent reads (e.g. parallel /context + /group + /search fan-out on page load). Echoed back in the response. |

## Response (`GroupRubricApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Resolved or newly created group UUID |
| `name` | `string` | No | The group's current title (latest active group_names_entry, or 'New Chat' fallback for freshly minted groups) |
| `snapshot_key` | `string` | No | Snapshot key echoed back — the UUID concurrent fan-out reads converged on via SETNX. Mirrors the resolved group_id. |
| `runs` | [`GroupRun`](/api-reference/rubric/types#grouprun)[] | No | Conversation history — populated when resolving an existing group for fetch |
| `group_exists` | `boolean` | No | (detail) Whether the group exists in storage — populated when ``include_resources=True`` |
| `actor_name` | `string` | No | (detail) Display name of the current actor (caller profile) |
| `total_message_count` | `integer` | No | (detail) Total number of messages in the group |
| `models` | [`GroupResource`](/api-reference/rubric/types#groupresource)[] | No | (detail) Models used in the group |
| `agents` | [`GroupResource`](/api-reference/rubric/types#groupresource)[] | No | (detail) Agents used in the group |
| `profiles` | [`GroupResource`](/api-reference/rubric/types#groupresource)[] | No | (detail) Profiles that authored runs in this group |

---

# `POST` `/rubric/problem`

Route: /api-reference/rubric/post-rubric-problem

# `POST` `/rubric/problem`

Problem Rubric

Report a rubric problem — composable infra architecture.

## Request Body (`ProblemRubricApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | `string` | Yes | Problem type: feature, bug, question, other |
| `message` | `string` | Yes | Problem description (max 1000 chars) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant problem |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`ProblemRubricApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `problem_id` | `string` | Yes | UUID of the created problem |
| `success` | `boolean` | No | Whether the problem was created |
| `message` | `string` | No | Status message |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/rubric/refresh`

Route: /api-reference/rubric/post-rubric-refresh

# `POST` `/rubric/refresh`

Rubric Refresh

Refresh rubric materialized views and invalidate caches.

## Request Body (`RefreshRubricApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `targets` | `string`[] | No | MV targets to refresh (omit for all). Options: rubric_drafts_mv |
| `idempotency_key` | `string` | No | Operation key for ack |
| `accept` | `boolean` | No | Accept or reject. Only meaningful with idempotency_key |
| `soft` | `boolean` | No | Stage the refresh as a pending (held) request — recorded but not enqueued; ack with accept releases/enqueues it |

## Response (`RefreshResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | — |
| `refreshed_views` | `string`[] | Yes | — |
| `invalidated_tags` | `string`[] | Yes | — |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/rubric/search`

Route: /api-reference/rubric/post-rubric-search

# `POST` `/rubric/search`

Search Rubric

Search rubrics — composable infra architecture.

## Request Body (`SearchRubricApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | — |
| `filter_department_ids` | `string`[] | No | — |
| `filter_simulation_ids` | `string`[] | No | — |
| `department_search` | `string` | No | — |
| `simulation_search` | `string` | No | — |
| `page_size` | `integer` | No | — |
| `page_offset` | `integer` | No | — |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`ListRubricApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current user |
| `rubrics` | [`ListRubricApiRubric`](/api-reference/rubric/types#listrubricapirubric)[] | No | List of rubrics |
| `standard_groups` | [`ListRubricApiStandardGroup`](/api-reference/rubric/types#listrubricapistandardgroup)[] | No | List of standard groups |
| `standards` | [`ListRubricApiStandard`](/api-reference/rubric/types#listrubricapistandard)[] | No | List of standards |
| `department_filter` | [`ListFilterSection`](/api-reference/rubric/types#listfiltersection) | No | Filter options for departments in list UI |
| `simulation_filter` | [`ListFilterSection`](/api-reference/rubric/types#listfiltersection) | No | Filter options for simulations in list UI |
| `flag_filter` | [`ListFilterSection`](/api-reference/rubric/types#listfiltersection) | No | Filter options for flags in list UI |
| `eval_filter` | [`ListFilterSection`](/api-reference/rubric/types#listfiltersection) | No | Filter options for evals in list UI |
| `total_count` | `integer` | No | Total number of matching records |
| `import_fields` | [`ImportField`](/api-reference/rubric/types#importfield)[] | No | CSV import column schema for the bulk-import dialog |

---

# `POST` `/rubric/text_download`

Route: /api-reference/rubric/post-rubric-text-download

# `POST` `/rubric/text_download`

Download Text

Download a text file by text resource ID.

## Request Body (`TextDownloadRubricApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `text_id` | `string` | Yes | UUID of the texts_resource to download |

## Response

```
{}
```

---

# `POST` `/rubric/title`

Route: /api-reference/rubric/post-rubric-title

# `POST` `/rubric/title`

Title Rubric

Rename a rubric's group (writes group_names_entry).

## Request Body (`TitleRubricApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Group to rename |
| `title` | `string` | Yes | New title (display name) for the group |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant rename |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`TitleRubricApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | The group that was renamed |
| `group_name_id` | `string` | Yes | UUID of the new group_names_entry row |
| `title` | `string` | Yes | The title that was set |
| `idempotency_key` | `string` | No | Operation key echoed back |

---

# `POST` `/rubric/update`

Route: /api-reference/rubric/post-rubric-update

# `POST` `/rubric/update`

Update Rubric

Update rubrics using composable infra architecture.

## Request Body (`UpdateRubricApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `rubrics` | [`UpdateRubricItem`](/api-reference/rubric/types#updaterubricitem)[] | No | List of rubrics to update (required on first call when ``all`` is false) |
| `all` | `boolean` | No | When true, apply ``patch`` to every rubric matching the filter fields below (minus ``excluded_ids``) |
| `excluded_ids` | `string`[] | No | UUIDs to skip even when matched by ``all``-mode filters |
| `patch` | [`UpdateRubricPatch`](/api-reference/rubric/types#updaterubricpatch) | No | Shared change set applied to every matched row when ``all=true`` (sparse — only set fields are updated; ``patch.id`` ignored) |
| `search` | `string` | No | Full-text search query |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `filter_simulation_ids` | `string`[] | No | Filter by simulation UUIDs |
| `department_search` | `string` | No | Search text for department facet (no-op for row filtering) |
| `simulation_search` | `string` | No | Search text for simulation facet (no-op for row filtering) |
| `flag_search` | `string` | No | Search text for flag facet (no-op for row filtering) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant update |
| `soft` | `boolean` | No | Stage the update dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`UpdateRubricApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`RubricResultItem`](/api-reference/rubric/types#rubricresultitem)[] | Yes | List of operation results |
| `rubrics` | [`ListRubricApiRubric`](/api-reference/rubric/types#listrubricapirubric)[] | No | Hydrated rubric rows for the rubrics just updated (omitted on soft writes) |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/rubric/watch`

Route: /api-reference/rubric/post-rubric-watch

# `POST` `/rubric/watch`

Rubric Watch Once

One-shot snapshot of run state, snapshot-replayable via ``snapshot_key``.

## Request Body (`WatchApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Chat group whose events we watch |
| `run_id` | `string` | No | Specific run to watch (e.g. the ``run_id`` returned by a prior ``X_Generate`` call). If None, watches every active run in the group at call time. |
| `wait_for_complete` | `boolean` | No | If True, block until the watched run reaches a terminal (complete/failed) event or timeout fires. If False, return current state and exit immediately. |
| `timeout_seconds` | `integer` | No | Max wait time when ``wait_for_complete=True``. |
| `snapshot_key` | `string` | No | Read snapshot key — on the one-shot POST /watch, the audit wrapper records this watch's point-in-time view (latest run state at call time) keyed by it and replays the same view on any later call with the same key. Ignored by the SSE GET stream. |

## Response (`WatchApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `runs` | [`RunStatus`](/api-reference/rubric/types#runstatus)[] | Yes | — |
| `timed_out` | `boolean` | No | — |
| `waited_seconds` | `number` | No | — |

---

# Rubric Types

Route: /api-reference/rubric/types

# Rubric Types

## `CallerPermissions`

Evaluated permissions for the current caller on this artifact type.

| Field | Type | Required | Description |
|---|---|---|---|
| `can_create` | `boolean` | Yes | Whether the caller can create new artifacts |
| `can_draft` | `boolean` | Yes | Whether the caller can create/update drafts |
| `can_duplicate` | `boolean` | Yes | Whether the caller can duplicate artifacts |
| `has_access` | `boolean` | No | Whether the caller can view this entity |
| `can_edit` | `boolean` | No | Whether the caller can edit this entity |
| `can_delete` | `boolean` | No | Whether the caller can delete this entity |
| `disabled_reason` | `string` | No | Human-readable reason if editing is disabled |

---

## `ColumnInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Column name |
| `type` | `string` | Yes | Column data type |
| `nullable` | `boolean` | Yes | Whether the column is nullable |

---

## `CreateRubricItem`

Single rubric item for create — no rubric_id.

Required fields (name): provide ID or value.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Optional pre-assigned UUID for the new rubric |
| `resource_id` | `string` | No | Optional preset UUID for the resource snapshot |
| `name_id` | `string` | No | REQUIRED FOR CREATE (or pass `name`): UUID of an existing name resource |
| `name` | `string` | No | REQUIRED FOR CREATE (or pass `name_id`): display name text (creates new resource if name_id not provided) |
| `description_id` | `string` | No | UUID of an existing description resource |
| `description` | `string` | No | Rubric description text (creates new resource if description_id not provided) |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `active` | `boolean` | No | Denormalized rubric_active flag state; resolved to a flag_ids entry server-side |
| `simulation_rubric` | `boolean` | No | Denormalized simulation_rubric flag state; resolved to a flag_ids entry server-side |
| `video_rubric` | `boolean` | No | Denormalized video_rubric flag state; resolved to a flag_ids entry server-side |
| `department_ids` | `string`[] | No | Department UUIDs |
| `departments` | `string`[] | No | Department names for resolution |
| `pass_points_id` | `string` | No | Pass-type Points resource UUID |
| `pass_points` | `integer` | No | Pass points value (resolves to a pass-type Points resource) |
| `standard_group_ids` | `string`[] | No | Standard group UUIDs |
| `standard_ids` | `string`[] | No | Standard UUIDs |

---

## `DeleteRubricResult`

Per-item result within a bulk delete response.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `rubric_id` | `string` | No | Rubric UUID |
| `message` | `string` | Yes | Human-readable result message |

---

## `DocsApiResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `list` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `detail` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `new` | [`PageMetaItem`](#pagemetaitem) | Yes | — |

---

## `DocsResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Resource or entry name |
| `type` | `string` | Yes | Resource or entry type identifier |
| `description` | `string` | Yes | Human-readable description |
| `materialized_view` | [`MvInfo`](#mvinfo) | No | Materialized view metadata |
| `tables` | [`TableInfo`](#tableinfo)[] | Yes | Related database tables |
| `operations` | [`OperationInfo`](#operationinfo)[] | Yes | Available operations |

---

## `EvalSetup`

Run-level eval scaffold — first-class on the generate response.

Audit's ``**output`` spread carries this onto
``<artifact>.generate.completed``. Null when no rubric-bearing
agent participated.

| Field | Type | Required | Description |
|---|---|---|---|
| `test_id` | `string` | Yes | — |
| `invocations` | [`InvocationSlot`](#invocationslot)[] | Yes | — |

---

## `GenerateConfig`

Developer configuration — all optional with sensible defaults.

| Field | Type | Required | Description |
|---|---|---|---|
| `operations` | `string`[] | No | — |
| `dangerous` | `boolean` | No | — |
| `params` | `object` | No | — |
| `group_id` | `string` | No | — |

---

## `GenerationsRubricListItem`

Single generation group in the rubric generations response.

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | UUID of the generation group |
| `session_id` | `string` | No | UUID of the parent session |
| `group_name` | `string` | No | Name of the generation group |
| `created_at` | `string` | No | Timestamp of the generation |

---

## `GetRubricDraftResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | UUID of the draft |
| `created_at` | `string` | Yes | Creation timestamp |
| `generated` | `boolean` | Yes | Whether this was AI-generated |
| `mcp` | `boolean` | Yes | Whether MCP tooling was used |
| `active` | `boolean` | Yes | Whether this draft is active |
| `session_id` | `string` | Yes | Associated session UUID |
| `name` | `string` | No | Immutable draft label set at create time |
| `department_ids` | `string`[] | Yes | Associated department UUIDs |
| `description_ids` | `string`[] | Yes | Associated description UUIDs |
| `flag_ids` | `string`[] | Yes | Associated flag UUIDs |
| `name_ids` | `string`[] | Yes | Associated name UUIDs |
| `point_ids` | `string`[] | Yes | Associated point UUIDs |
| `profile_ids` | `string`[] | Yes | Associated profile UUIDs |
| `standard_group_ids` | `string`[] | Yes | Associated standard group UUIDs |
| `standard_ids` | `string`[] | Yes | Associated standard UUIDs |
| `pending_department_ids` | `string`[] | No | Associated pending department UUIDs |
| `pending_description_ids` | `string`[] | No | Associated pending description UUIDs |
| `pending_flag_ids` | `string`[] | No | Associated pending flag UUIDs |
| `pending_name_ids` | `string`[] | No | Associated pending name UUIDs |
| `pending_point_ids` | `string`[] | No | Associated pending point UUIDs |
| `pending_standard_group_ids` | `string`[] | No | Associated pending standard group UUIDs |
| `pending_standard_ids` | `string`[] | No | Associated pending standard UUIDs |

---

## `GroupCall`

Tool call referenced by a message.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `tool_name` | `string` | No | — |
| `template_name` | `string` | No | — |
| `tool` | `object` | No | — |
| `ledger_status` | `string` | No | — |
| `ledger_operation` | `string` | No | — |
| `ledger_artifact` | `string` | No | — |
| `ledger_artifact_id` | `string` | No | — |

---

## `GroupMessage`

Message within a run.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `role` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `text_ids` | `string`[] | No | — |
| `audio_ids` | `string`[] | No | — |
| `image_ids` | `string`[] | No | — |
| `video_ids` | `string`[] | No | — |
| `file_ids` | `string`[] | No | — |
| `call_ids` | `string`[] | No | — |
| `calls` | [`GroupCall`](#groupcall)[] | No | — |
| `reasoning` | `boolean` | No | True when this row is a chain-of-thought trace persisted alongside the assistant answer (rendered as a collapsed accordion). |
| `in_context` | `boolean` | No | Whether this message is included in the LLM context for the next generation. Mirrors the dedup pass that builds chat history (see in_context_reason). |
| `in_context_reason` | `string` | No | Why this message is in/out of LLM context. 'kept' = included; 'deduped_read' = older read-only call to a tool that has a fresher result later in the group; future values may include 'trimmed_top_n'. |

---

## `GroupResource`

Lightweight `\{id, name\}` for cross-referencing run-level ids
(``model_id`` / ``agent_id`` / ``profile_id``) against human-readable
names on the analytics panel. Names come from the canonical
``get_models`` / ``get_agents`` / ``get_profiles`` black boxes.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `name` | `string` | No | — |

---

## `GroupRun`

Run within a group, with its messages.

Carries token / cost / model / agent / profile attribution so the
analytics view can render per-run cost + actor info without a
parallel detail shape. ``profile_id`` is the authoring profile
(human user), ``agent_id`` is the LLM-side actor, ``model_id`` is
the model used by that agent. All optional — runs predating these
columns or with unresolved attributions surface ``None``.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `input_tokens` | `integer` | No | — |
| `output_tokens` | `integer` | No | — |
| `cached_input_tokens` | `integer` | No | — |
| `cost` | `number` | No | — |
| `model_id` | `string` | No | — |
| `agent_id` | `string` | No | — |
| `profile_id` | `string` | No | — |
| `previous_context_start_index` | `integer` | No | Index in ``messages`` where the current run's own messages begin; earlier rows are previous-context replay. ``None`` when the run has no previous context attached. |
| `messages` | [`GroupMessage`](#groupmessage)[] | No | — |

---

## `ImportField`

Field descriptor for CSV import column mapping.

| Field | Type | Required | Description |
|---|---|---|---|
| `key` | `string` | Yes | — |
| `label` | `string` | Yes | — |
| `required` | `boolean` | No | — |
| `multi` | `boolean` | No | — |
| `type` | `string` | No | — |
| `example` | `string` | No | — |
| `description` | `string` | No | — |

---

## `InvocationSlot`

One agent's slot in a multi-agent generation pool.

Populated by ``setup_generation_test`` when an agent carries a
rubric. The client uses these IDs to drive the eval workflow:
review the candidate's output, optionally fire a grader against
its ``invocation_id``, and promote/reject by call_id via the
existing ``idempotency_key + accept`` pattern.

| Field | Type | Required | Description |
|---|---|---|---|
| `invocation_id` | `string` | Yes | — |
| `agent_id` | `string` | Yes | — |
| `rubric_id` | `string` | No | — |

---

## `ListFilterOption`

Standardized option for list endpoint filter sections.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier for this filter option |
| `name` | `string` | No | Display name |
| `count` | `integer` | No | Number of matching records |
| `hex_code` | `string` | No | Hex color code for display |
| `value` | `string` | No | Internal value |
| `type` | `string` | No | Option type discriminator |

---

## `ListFilterSection`

Filter section with options and echoed request state.

| Field | Type | Required | Description |
|---|---|---|---|
| `options` | [`ListFilterOption`](#listfilteroption)[] | No | Available filter options |
| `selected_ids` | `string`[] | No | Currently selected filter option IDs |
| `search` | `string` | No | Active search text for filtering |

---

## `ListRubricApiRubric`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Rubric artifact UUID (canonical id; mirrors rubric_id) |
| `rubric_id` | `string` | No | Rubric UUID |
| `name` | `string` | No | Rubric name |
| `description` | `string` | No | Rubric description |
| `points` | `integer` | No | Total points |
| `pass_points` | `integer` | No | Points required to pass |
| `pass_percentage` | `integer` | No | Percentage required to pass |
| `department_ids` | `string`[] | No | Associated department IDs |
| `simulation_ids` | `string`[] | No | Associated simulation IDs |
| `active_simulation_count` | `integer` | No | Number of active simulations using this rubric |
| `can_edit` | `boolean` | No | Whether the current user can edit |
| `can_delete` | `boolean` | No | Whether the current user can delete |
| `can_duplicate` | `boolean` | No | Whether the current user can duplicate |
| `standard_group_ids` | `string`[] | No | Associated standard group UUIDs |
| `eval_ids` | `string`[] | No | Eval artifact UUIDs that reference this rubric (via model_rubrics_resource) |
| `is_inactive` | `boolean` | No | Whether the rubric is inactive |
| `pending_status` | `string` | No | Pending soft_calls_entry status (e.g. 'pending') |
| `pending_operation` | `string` | No | Pending operation (create/update/delete/duplicate) |
| `pending_call_id` | `string` | No | Originating tool call id for ack |

---

## `ListRubricApiStandard`

| Field | Type | Required | Description |
|---|---|---|---|
| `standard_id` | `string` | No | Standard UUID |
| `standard_group_id` | `string` | No | Parent standard group UUID |
| `name` | `string` | No | Standard name |
| `description` | `string` | No | Standard description |
| `points` | `integer` | No | Points for this standard |

---

## `ListRubricApiStandardGroup`

| Field | Type | Required | Description |
|---|---|---|---|
| `standard_group_id` | `string` | No | Standard group UUID |
| `rubric_id` | `string` | No | Parent rubric UUID |
| `name` | `string` | No | Standard group name |
| `description` | `string` | No | Standard group description |
| `points` | `integer` | No | Total points for this group |
| `pass_points` | `integer` | No | Points required to pass this group |

---

## `MvInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Materialized view name |
| `definition` | `string` | Yes | SQL definition of the view |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the view |

---

## `OperationInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Operation name |
| `description` | `string` | Yes | Human-readable description of the operation |
| `params` | [`ParamInfo`](#paraminfo)[] | Yes | List of operation parameters |
| `returns` | `object` | No | Return type schema |

---

## `OperationPrompts`

Starter prompts keyed by operation name.

Each key is an operation (e.g. "create", "search", "draft", "export")
and the value is a list of starter prompts for that operation.
The client picks from the operations the caller has permission for
and rotates through them.

| Field | Type | Required | Description |
|---|---|---|---|
| `prompts` | `object` | No | Map of operation name to starter prompts |

---

## `PageMetaItem`

| Field | Type | Required | Description |
|---|---|---|---|
| `title` | `string` | Yes | — |
| `description` | `string` | Yes | — |

---

## `ParamInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Parameter name |
| `type` | `string` | Yes | Parameter data type |
| `required` | `boolean` | Yes | Whether the parameter is required |
| `default` | `any` | No | Default value if not required |

---

## `ProducedMedia`

One asset produced by a generation run.

``resource_id`` is the canonical id the per-artifact download tools
accept (e.g. ``Scenario_Image_Download(image_id=resource_id)`` for
``modality="image"``). It maps to ``images_resource.id`` /
``videos_resource.id`` / ``audios_resource.id`` depending on the
modality.

| Field | Type | Required | Description |
|---|---|---|---|
| `modality` | `"image"` \| `"video"` \| `"audio"` | Yes | — |
| `resource_id` | `string` | Yes | — |
| `upload_id` | `string` | Yes | — |
| `mime_type` | `string` | No | — |
| `file_size` | `integer` | No | — |

---

## `ProfileSummary`

Caller identity derived from JWT — who you are on this page.

Superset of the old six-field version: now carries everything the client
needs so that ``/\{artifact\}/context`` fully replaces ``/profiles/context``
and the extra ``getLayoutContextData`` round-trip can be dropped.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Display name of the authenticated user |
| `role` | `string` | Yes | Role name (e.g. 'Super Administrator') |
| `role_level` | `integer` | Yes | Role hierarchy level (0 = highest privilege) |
| `department_ids` | `string`[] | Yes | Departments the user belongs to |
| `artifact_access` | `string`[] | Yes | Artifact types this role can access (sidebar visibility) |
| `role_permissions` | `any`[][] | Yes | Full (artifact, operation) permission tuples for granular page gating |
| `is_active` | `boolean` | Yes | Whether the user's profile is active |
| `id` | `string` | Yes | Profile UUID (SocketProvider, ProfileProvider) |
| `theme` | [`ThemeBundle`](#themebundle) | No | Resolved theme: hex primitives + derived oklch tokens + score thresholds |
| `session_id` | `string` | No | Current session UUID |
| `is_emulation` | `boolean` | No | Whether user is in emulation mode (ProfileProvider) |
| `role_resources` | [`QGetProfileContextV4RoleResource`](#qgetprofilecontextv4roleresource)[] | No | All role resources for emulation display (ProfileProvider) |
| `scoped_roles` | `string`[] | No | Roles the user can emulate (ProfileProvider) |
| `active` | `boolean` | No | Alias for is_active (ProfileProvider uses this name) |

---

## `QGetProfileContextV4RoleResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `role` | `string` | No | — |
| `name` | `string` | No | — |
| `description` | `string` | No | — |
| `icon_value` | `string` | No | — |
| `color_hex` | `string` | No | — |

---

## `RubricDepartmentResource`

Department resource for rubric.

| Field | Type | Required | Description |
|---|---|---|---|
| `department_id` | `string` | No | Department identifier |
| `id` | `string` | No | Department identifier |
| `name` | `string` | No | Department name |
| `description` | `string` | No | Department description |
| `department_ids` | `string`[] | No | Associated department identifiers |
| `setting_ids` | `string`[] | No | Associated setting identifiers |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `RubricDescriptionResource`

Description resource for rubric.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `description` | `string` | No | Description text |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `RubricFieldError`

Per-field error from value resolution.

| Field | Type | Required | Description |
|---|---|---|---|
| `field` | `string` | Yes | Field name that has the error |
| `message` | `string` | Yes | Human-readable error message |

---

## `RubricFlagResource`

Flag option row — one per (name, type, value) entry in flags_resource.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Flag resource identifier |
| `name` | `string` | No | Flag display name |
| `type` | `string` | No | Flag type (e.g. 'rubric_active', 'simulation_rubric', 'video_rubric') |
| `value` | `boolean` | No | Underlying bool value of this option |
| `description` | `string` | No | Flag description text |
| `icon_id` | `string` | No | Icon identifier for the flag |
| `icon` | `string` | No | Resolved SVG markup (hydrated from icons_resource) |
| `generated` | `boolean` | No | Whether the flag was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `RubricNameResource`

Name resource for rubric.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `name` | `string` | No | Display name |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `RubricPointResource`

Point resource for rubric.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `value` | `integer` | No | Point value |
| `type` | `string` | No | Point type |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `RubricResultItem`

Per-item result within a bulk create/update response.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `rubric_id` | `string` | No | Rubric UUID |
| `message` | `string` | Yes | Human-readable result message |
| `errors` | [`RubricFieldError`](#rubricfielderror)[] | No | List of per-field errors |

---

## `RubricStandardDraftValue`

Value-object for authoring a standard inline from the rubric grid.

The grid editor sends these instead of (or alongside) standard_ids. Entries
without an `id` are created server-side; entries with an `id` are trusted
as-is. Append-only: updates are modeled as create-new-id, old rows become
orphans and stop appearing in the draft once the client drops them.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Existing standard UUID, if any |
| `name` | `string` | Yes | Level name (column header) |
| `description` | `string` | No | Cell description text |
| `points` | `integer` | Yes | Implied points from column index |
| `standard_group_id` | `string` | Yes | Parent standard group UUID (row) |

---

## `RubricStandardGroupDraftValue`

Value-object for authoring a standard group inline from the rubric editor.

Entries without `id` are created server-side; resulting IDs merge into
standard_group_ids. Group-level `points`/`pass_points` drive the grid's
column count and passing threshold per row.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Existing standard group UUID, if any |
| `name` | `string` | Yes | Group display name |
| `description` | `string` | No | Group description |
| `points` | `integer` | No | Max points for this group (drives grid columns) |
| `pass_points` | `integer` | No | Passing threshold for this group |

---

## `RubricStandardGroupResource`

Standard group resource for rubric.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `standard_group_id` | `string` | No | Standard group identifier |
| `name` | `string` | No | Standard group name |
| `short_name` | `string` | No | Standard group short name |
| `description` | `string` | No | Standard group description |
| `points` | `integer` | No | Total points for this group |
| `pass_points` | `integer` | No | Pass points for this group |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `RubricStandardResource`

Standard resource for rubric.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `standard_id` | `string` | No | Standard identifier |
| `standard_group_id` | `string` | No | Parent standard group identifier |
| `name` | `string` | No | Standard name |
| `description` | `string` | No | Standard description |
| `points` | `integer` | No | Points for this standard |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `RunStatus`

Outcome of one watched run.

| Field | Type | Required | Description |
|---|---|---|---|
| `run_id` | `string` | Yes | — |
| `status` | `"pending"` \| `"completed"` \| `"failed"` | Yes | — |
| `modality` | `string` | No | Modality of generated output (image, video, text…) |
| `resource_ids` | `string`[] | No | Resource UUIDs produced by this run (e.g. images_resource ids) |
| `error` | `string` | No | — |

---

## `TableInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Table name |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the table |

---

## `ThemeBundle`

Full theme payload for a page bootstrap.

Riding along on every ``/\{artifact\}/context`` response via
``ProfileSummary.theme``. Layers:
  - ``primitives`` / ``dark_primitives`` — hex inputs the settings
    editor reads/writes (light + dark palettes).
  - ``tokens`` / ``dark_tokens`` — oklch tokens the client paints with.
    ``ThemeStyle`` emits two ``<style>`` blocks: one scoped to
    ``:root:not(.dark)`` (light) and one to ``:root.dark`` (dark).
  - ``thresholds`` — numeric score thresholds for analytics components.
Empty-in → empty-out per token: missing values fall through to the
matching ``globals.css`` default.

| Field | Type | Required | Description |
|---|---|---|---|
| `primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (light palette, for the theme editor) |
| `tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for light mode (SSR CSS-var injection) |
| `dark_primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (dark palette, for the theme editor) |
| `dark_tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for dark mode (SSR CSS-var injection) |
| `thresholds` | [`Thresholds`](#thresholds) | No | Score thresholds resolved from the setting |

---

## `ThemePrimitives`

40 optional fields. The 17 essentials drive the rest; the other 23
are overrides for fine-tuning when derivation isn't what you want.

Empty primitive → empty token → client falls back to globals.css.

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `primary` | `string` | No | — |
| `accent` | `string` | No | — |
| `card` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `ring` | `string` | No | — |
| `border` | `string` | No | — |
| `destructive` | `string` | No | — |
| `success` | `string` | No | — |
| `warning` | `string` | No | — |
| `info` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `input` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `ThemeTokens`

40 fully-resolved CSS variable values (snake_case 1:1 with vars).

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `accent` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `border` | `string` | No | — |
| `input` | `string` | No | — |
| `ring` | `string` | No | — |
| `success` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `Thresholds`

Numeric score thresholds resolved from the active setting.

Server pre-buckets dashboard metrics into ``success | warning | danger |
neutral`` already, so most components don't need these values. Surface
them for chart reference lines, tooltips, and any client-side bucketing.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `integer` | Yes | Score >= this counts as success |
| `warning` | `integer` | Yes | Score >= this counts as warning |
| `danger` | `integer` | Yes | Score < success threshold but >= this counts as danger; below is neutral/no-data |

---

## `UpdateRubricItem`

Single rubric item for update — rubric_id required, all fields optional.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | Rubric UUID to update |
| `name_id` | `string` | No | Name resource UUID |
| `name` | `string` | No | Name value for resolution |
| `description_id` | `string` | No | Description resource UUID |
| `description` | `string` | No | Description value for resolution |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `active` | `boolean` | No | Denormalized rubric_active flag state; resolved to a flag_ids entry server-side |
| `simulation_rubric` | `boolean` | No | Denormalized simulation_rubric flag state; resolved to a flag_ids entry server-side |
| `video_rubric` | `boolean` | No | Denormalized video_rubric flag state; resolved to a flag_ids entry server-side |
| `department_ids` | `string`[] | No | Department UUIDs |
| `departments` | `string`[] | No | Department names for resolution |
| `pass_points_id` | `string` | No | Pass-type Points resource UUID |
| `pass_points` | `integer` | No | Pass points value (resolves to a pass-type Points resource) |
| `standard_group_ids` | `string`[] | No | Standard group UUIDs |
| `standard_ids` | `string`[] | No | Standard UUIDs |

---

## `UpdateRubricPatch`

Shared patch for bulk-update-all-matching mode.

Inherits every field from ``UpdateRubricItem`` and just relaxes
``id`` to optional — the bulk impl stamps the resolved id onto a
clone of the patch per matched row, so any client-supplied id is
ignored. Sparse semantics: only fields the client sets are written.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Ignored — bulk impl stamps the resolved rubric id per matched row |
| `name_id` | `string` | No | Name resource UUID |
| `name` | `string` | No | Name value for resolution |
| `description_id` | `string` | No | Description resource UUID |
| `description` | `string` | No | Description value for resolution |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `active` | `boolean` | No | Denormalized rubric_active flag state; resolved to a flag_ids entry server-side |
| `simulation_rubric` | `boolean` | No | Denormalized simulation_rubric flag state; resolved to a flag_ids entry server-side |
| `video_rubric` | `boolean` | No | Denormalized video_rubric flag state; resolved to a flag_ids entry server-side |
| `department_ids` | `string`[] | No | Department UUIDs |
| `departments` | `string`[] | No | Department names for resolution |
| `pass_points_id` | `string` | No | Pass-type Points resource UUID |
| `pass_points` | `integer` | No | Pass points value (resolves to a pass-type Points resource) |
| `standard_group_ids` | `string`[] | No | Standard group UUIDs |
| `standard_ids` | `string`[] | No | Standard UUIDs |

---

## `app__infra__rubric__types__DraftFormState`

Server-authoritative form state returned after draft save.

| Field | Type | Required | Description |
|---|---|---|---|
| `name_id` | `string` | No | Selected name resource UUID |
| `name` | `string` | No | Echoed name value |
| `description_id` | `string` | No | Selected description resource UUID |
| `description` | `string` | No | Echoed description value |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs |
| `active` | `boolean` | No | Echoed rubric_active flag state |
| `simulation_rubric` | `boolean` | No | Echoed simulation_rubric flag state |
| `video_rubric` | `boolean` | No | Echoed video_rubric flag state |
| `department_ids` | `string`[] | No | Selected department UUIDs |
| `pass_points_id` | `string` | No | Pass-type Points resource UUID |
| `pass_points` | `integer` | No | Denormalized pass points value |
| `total_points_id` | `string` | No | Total-type Points resource UUID (computed) |
| `total_points` | `integer` | No | Denormalized total points value (sum of standard groups) |
| `standard_group_ids` | `string`[] | No | Selected standard group UUIDs |
| `standard_groups` | [`RubricStandardGroupDraftValue`](#rubricstandardgroupdraftvalue)[] | No | Resolved inline-created standard groups (all ids filled in). |
| `standard_ids` | `string`[] | No | Selected standard UUIDs |
| `standards` | [`RubricStandardDraftValue`](#rubricstandarddraftvalue)[] | No | Resolved grid-editor standards (all ids filled in). |
| `pending_ids` | `string`[] | No | Pending resource identifiers |

---

## `app__infra__rubric__types__SectionFilter`

Per-section filter options for GET requests.

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Filter options by search text |
| `limit` | `integer` | No | Max options to return |
| `selected` | `boolean` | No | Only return selected items |
| `suggested` | `boolean` | No | Only return suggested items |
| `include` | `boolean` | No | Include this section in response (default true) |
| `parameter_ids` | `string`[] | No | Reserved for compatibility with shared filter parsing |

---

---

# `GET` `/scenario/watch`

Route: /api-reference/scenario/get-scenario-watch

# `GET` `/scenario/watch`

Scenario Watch

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `group_id` | query | No | — |
| `run_id` | query | No | Optional run filter. If provided, only events whose envelope run_id matches are streamed — useful for per-run live feeds. Omit to receive every scenario event in the group (the FE default). |

## Response

```
{}
```

---

# `POST` `/scenario/call_download`

Route: /api-reference/scenario/post-scenario-call-download

# `POST` `/scenario/call_download`

Download Call

Download a call file by call resource ID.

## Request Body (`CallDownloadScenarioApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `call_id` | `string` | Yes | UUID of the calls_resource to download |

## Response

```
{}
```

---

# `POST` `/scenario/context`

Route: /api-reference/scenario/post-scenario-context

# `POST` `/scenario/context`

Get Scenario Context

Get page context for the scenario artifact.

Returns docs + profile identity + evaluated permissions in a single call.
Superset of /docs — clients can migrate from /docs to /context incrementally.

## Request Body (`DocsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entity_id` | `string` | No | — |
| `snapshot_key` | `string` | No | — |
| `schema` | `boolean` | No | If true, include MCP/tooling schema metadata (artifact, entries, resources, permission_docs, api_operations). Defaults to false for lean page-bootstrap responses. |

## Response (`ComposedContextResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Artifact name |
| `type` | `string` | Yes | Artifact type identifier |
| `description` | `string` | Yes | Human-readable description |
| `artifact` | [`DocsResponse`](/api-reference/scenario/types#docsresponse) | No | Artifact tool documentation (None unless schema=true) |
| `entries` | [`DocsResponse`](/api-reference/scenario/types#docsresponse)[] | No | Entry documentation list (None unless schema=true) |
| `resources` | [`DocsResponse`](/api-reference/scenario/types#docsresponse)[] | No | Resource documentation list (None unless schema=true) |
| `permission_docs` | [`OperationInfo`](/api-reference/scenario/types#operationinfo)[] | No | Permission function signatures for MCP/dev tooling (None unless schema=true) |
| `api_operations` | [`OperationInfo`](/api-reference/scenario/types#operationinfo)[] | No | API operation documentation (None unless schema=true) |
| `page_metadata` | [`DocsApiResponse`](/api-reference/scenario/types#docsapiresponse) | No | Page-level metadata |
| `prompts` | [`OperationPrompts`](/api-reference/scenario/types#operationprompts) | No | Starter prompts keyed by operation |
| `profile` | [`ProfileSummary`](/api-reference/scenario/types#profilesummary) | Yes | Caller identity from JWT |
| `caller_permissions` | [`CallerPermissions`](/api-reference/scenario/types#callerpermissions) | Yes | Evaluated permissions for this caller |

---

# `POST` `/scenario/create`

Route: /api-reference/scenario/post-scenario-create

# `POST` `/scenario/create`

Create Scenario

Create scenarios using composable infra architecture.

## Request Body (`CreateScenarioApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `scenarios` | [`CreateScenarioItem`](/api-reference/scenario/types#createscenarioitem)[] | Yes | List of scenarios to create |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant create |
| `soft` | `boolean` | No | Stage the create dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`CreateScenarioApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`ScenarioResultItem`](/api-reference/scenario/types#scenarioresultitem)[] | Yes | List of operation results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |
| `scenarios` | [`ListScenarioApiScenario`](/api-reference/scenario/types#listscenarioapiscenario)[] | No | Hydrated rows for the successfully-created scenarios (mirrors /scenario/search shape) |

---

# `POST` `/scenario/csv`

Route: /api-reference/scenario/post-scenario-csv

# `POST` `/scenario/csv`

Parse Scenario Csv

Parse a CSV file and return mapped items for preview.

## Request Body

| Field | Type | Required | Description |
|---|---|---|---|
| `file` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `soft` | `boolean` | No | — |
| `accept` | `boolean` | No | — |

## Response (`ParseScenarioCsvApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `upload_id` | `string` | Yes | UUID of the uploaded CSV file |
| `items` | [`CreateScenarioItem`](/api-reference/scenario/types#createscenarioitem)[] | Yes | Parsed scenario items for preview |
| `mapped_fields` | `string`[] | Yes | Column keys that were auto-mapped |
| `row_count` | `integer` | Yes | Number of data rows parsed |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with `accept` to promote/reject the staged raw-CSV upload. NOTE: ack returns no items (the preview is only on the propose). |

---

# `POST` `/scenario/delete`

Route: /api-reference/scenario/post-scenario-delete

# `POST` `/scenario/delete`

Delete Scenario

Bulk delete scenarios — composable infra architecture.

## Request Body (`DeleteScenarioApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `scenario_ids` | `string`[] | No | UUIDs of scenarios to delete (required on first call when ``all`` is false) |
| `all` | `boolean` | No | When true, delete every scenario matching the filter fields below (minus ``excluded_ids``) |
| `excluded_ids` | `string`[] | No | UUIDs to skip even when matched by ``all``-mode filters |
| `search` | `string` | No | Full-text search query |
| `persona_ids` | `string`[] | No | Filter by persona UUIDs |
| `simulation_ids` | `string`[] | No | Filter by simulation UUIDs |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `persona_search` | `string` | No | Search text for persona facet (no-op for row filtering) |
| `simulation_search` | `string` | No | Search text for simulation facet (no-op for row filtering) |
| `department_search` | `string` | No | Search text for department facet (no-op for row filtering) |
| `flag_search` | `string` | No | Search text for flag facet (no-op for row filtering) |
| `idempotency_key` | `string` | No | Operation key for ack — confirms or rejects a dormant delete |
| `soft` | `boolean` | No | Stage the delete dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (confirm deletion) or reject (restore). Only meaningful with idempotency_key |

## Response (`DeleteScenarioApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`DeleteScenarioResult`](/api-reference/scenario/types#deletescenarioresult)[] | Yes | List of operation results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/scenario/draft`

Route: /api-reference/scenario/post-scenario-draft

# `POST` `/scenario/draft`

Patch Scenario Draft

Patch scenario draft — composable infra architecture.

## Request Body (`PatchScenarioDraftApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `input_draft_id` | `string` | No | UUID of the input draft |
| `name` | `string` | No | Display name value |
| `name_id` | `string` | No | UUID of the name resource |
| `description` | `string` | No | Description text value |
| `description_id` | `string` | No | UUID of the description resource |
| `problem_statement` | `string` | No | Problem statement text value |
| `problem_statement_id` | `string` | No | UUID of the problem statement resource |
| `objectives` | `string`[] | No | Objective texts to create |
| `objective_ids` | `string`[] | No | Existing objective UUIDs |
| `images` | [`app__infra__scenario__types__DraftImageValue`](/api-reference/scenario/types#app-infra-scenario-types-draftimagevalue)[] | No | Image values to create |
| `image_ids` | `string`[] | No | Existing image UUIDs |
| `videos` | [`app__infra__scenario__types__DraftVideoValue`](/api-reference/scenario/types#app-infra-scenario-types-draftvideovalue)[] | No | Video values to create |
| `video_ids` | `string`[] | No | Existing video UUIDs |
| `questions` | [`app__infra__scenario__types__DraftQuestionValue`](/api-reference/scenario/types#app-infra-scenario-types-draftquestionvalue)[] | No | Question values to create |
| `question_ids` | `string`[] | No | Existing question UUIDs |
| `options` | [`app__infra__scenario__types__DraftOptionValue`](/api-reference/scenario/types#app-infra-scenario-types-draftoptionvalue)[] | No | Option values to create |
| `option_ids` | `string`[] | No | Existing option UUIDs |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `active` | `boolean` | No | Denormalized scenario_active flag state |
| `video_enabled` | `boolean` | No | Denormalized video_enabled flag state |
| `problem_statement_enabled` | `boolean` | No | Denormalized problem_statement_enabled flag state |
| `objectives_enabled` | `boolean` | No | Denormalized objectives_enabled flag state |
| `images_enabled` | `boolean` | No | Denormalized images_enabled flag state |
| `questions_enabled` | `boolean` | No | Denormalized questions_enabled flag state |
| `department_ids` | `string`[] | No | Associated department UUIDs |
| `persona_ids` | `string`[] | No | Associated persona UUIDs |
| `document_ids` | `string`[] | No | Associated document UUIDs |
| `parameter_field_ids` | `string`[] | No | Associated parameter field UUIDs |
| `pending_ids` | `string`[] | No | Resource IDs to keep as pending (active=false on connection) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant draft |
| `soft` | `boolean` | No | Stage the draft dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`PatchScenarioDraftApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `draft_id` | `string` | Yes | UUID of the saved draft |
| `idempotency_key` | `string` | Yes | Idempotency key for this draft operation (same as draft entry ID) |
| `message` | `string` | Yes | Human-readable result message |
| `form_state` | [`ScenarioDraftFormState`](/api-reference/scenario/types#scenariodraftformstate) | Yes | Server-authoritative form state |

---

# `POST` `/scenario/drafts`

Route: /api-reference/scenario/post-scenario-drafts

# `POST` `/scenario/drafts`

Get Scenario Drafts

List scenario drafts owned by the current profile.

## Request Body (`GetScenarioDraftsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE substring) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GetScenarioDraftsApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entries` | [`GetScenarioDraftResponse`](/api-reference/scenario/types#getscenariodraftresponse)[] | No | List of scenario draft entries |

---

# `POST` `/scenario/duplicate`

Route: /api-reference/scenario/post-scenario-duplicate

# `POST` `/scenario/duplicate`

Duplicate Scenario

Duplicate a scenario — composable infra architecture.

## Request Body (`DuplicateScenarioApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `scenario_id` | `string` | Yes | UUID of the scenario to duplicate |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant duplicate |
| `soft` | `boolean` | No | Stage the duplicate dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`DuplicateScenarioApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `scenario_id` | `string` | Yes | UUID of the duplicated scenario |
| `message` | `string` | Yes | Human-readable result message |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |
| `scenarios` | [`ListScenarioApiScenario`](/api-reference/scenario/types#listscenarioapiscenario)[] | No | Hydrated row for the newly-created duplicate scenario (single-element list) |

---

# `POST` `/scenario/export`

Route: /api-reference/scenario/post-scenario-export

# `POST` `/scenario/export`

Export Scenarios

Export all scenarios as a clean, denormalized CSV.

## Request Body (`ExportScenarioApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `scenario_id` | `string` | No | UUID of the scenario to export |
| `search` | `string` | No | Search query text |
| `persona_ids` | `string`[] | No | Filter by persona UUIDs |
| `simulation_ids` | `string`[] | No | Filter by simulation UUIDs |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior export instead of re-running |

## Response (`ExportScenarioApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `content` | `string` | Yes | Exported file content |
| `file_name` | `string` | Yes | Suggested file name for download |
| `mime_type` | `string` | Yes | MIME type of the exported content |
| `row_count` | `integer` | Yes | Total number of exported rows |

---

# `POST` `/scenario/file_download`

Route: /api-reference/scenario/post-scenario-file-download

# `POST` `/scenario/file_download`

Download File

Download a file by file resource ID with range support.

## Request Body (`FileDownloadScenarioApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource to download |

## Response

```
{}
```

---

# `POST` `/scenario/file_preview`

Route: /api-reference/scenario/post-scenario-file-preview

# `POST` `/scenario/file_preview`

Preview File

Return a PNG preview of the first page of a PDF file resource.

## Request Body (`FilePreviewScenarioApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource to preview |

## Response

```
{}
```

---

# `POST` `/scenario/generate`

Route: /api-reference/scenario/post-scenario-generate

# `POST` `/scenario/generate`

Generate Scenario

Trigger scenario generation. Returns immediately; progress via events.

## Request Body (`ArtifactGenerateRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `instructions` | `string`[] | No | — |
| `config` | [`GenerateConfig`](/api-reference/scenario/types#generateconfig) | No | — |
| `modalities` | `string`[] | No | — |
| `audios_id` | `string` | No | — |
| `conversation_id` | `string` | No | — |
| `trace_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `accept` | `boolean` | No | — |
| `wait_for_complete` | `boolean` | No | — |

## Response (`ArtifactGenerateResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `run_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `eval` | [`EvalSetup`](/api-reference/scenario/types#evalsetup) | No | — |
| `produced_media` | [`ProducedMedia`](/api-reference/scenario/types#producedmedia)[] | No | — |

---

# `POST` `/scenario/generations`

Route: /api-reference/scenario/post-scenario-generations

# `POST` `/scenario/generations`

Generations Scenario

List scenario generation groups — composable infra architecture.

## Request Body (`GenerationsScenarioApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GenerationsScenarioApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `items` | [`GenerationsScenarioListItem`](/api-reference/scenario/types#generationsscenariolistitem)[] | No | Generation groups |
| `total_count` | `integer` | No | Total number of matching generations |

---

# `POST` `/scenario/get`

Route: /api-reference/scenario/post-scenario-get

# `POST` `/scenario/get`

Get Scenario

Get scenario information using the canonical shared scenario operation.

## Request Body (`GetScenarioApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | UUID of the scenario to retrieve |
| `draft_id` | `string` | No | UUID of the draft |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |
| `names` | [`app__infra__persona__types__SectionFilter`](/api-reference/scenario/types#app-infra-persona-types-sectionfilter) | No | — |
| `descriptions` | [`app__infra__persona__types__SectionFilter`](/api-reference/scenario/types#app-infra-persona-types-sectionfilter) | No | — |
| `problem_statements` | [`app__infra__persona__types__SectionFilter`](/api-reference/scenario/types#app-infra-persona-types-sectionfilter) | No | — |
| `flags` | [`app__infra__persona__types__SectionFilter`](/api-reference/scenario/types#app-infra-persona-types-sectionfilter) | No | — |
| `departments` | [`app__infra__persona__types__SectionFilter`](/api-reference/scenario/types#app-infra-persona-types-sectionfilter) | No | — |
| `personas` | [`app__infra__persona__types__SectionFilter`](/api-reference/scenario/types#app-infra-persona-types-sectionfilter) | No | — |
| `documents` | [`app__infra__persona__types__SectionFilter`](/api-reference/scenario/types#app-infra-persona-types-sectionfilter) | No | — |
| `parameters` | [`app__infra__persona__types__SectionFilter`](/api-reference/scenario/types#app-infra-persona-types-sectionfilter) | No | — |
| `parameter_fields` | [`app__infra__persona__types__SectionFilter`](/api-reference/scenario/types#app-infra-persona-types-sectionfilter) | No | — |
| `objectives` | [`app__infra__persona__types__SectionFilter`](/api-reference/scenario/types#app-infra-persona-types-sectionfilter) | No | — |
| `images` | [`app__infra__persona__types__SectionFilter`](/api-reference/scenario/types#app-infra-persona-types-sectionfilter) | No | — |
| `videos` | [`app__infra__persona__types__SectionFilter`](/api-reference/scenario/types#app-infra-persona-types-sectionfilter) | No | — |
| `questions` | [`app__infra__persona__types__SectionFilter`](/api-reference/scenario/types#app-infra-persona-types-sectionfilter) | No | — |
| `options` | [`app__infra__persona__types__SectionFilter`](/api-reference/scenario/types#app-infra-persona-types-sectionfilter) | No | — |

## Response (`GetScenarioApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `scenario_exists` | `boolean` | No | Whether the scenario exists |
| `can_edit` | `boolean` | No | Whether the current user can edit |
| `disabled_reason` | `string` | No | Reason the scenario is disabled |
| `group_id` | `string` | No | UUID of the owning group |
| `draft_name` | `string` | No | Immutable draft label from the active draft entry, when a ``draft_id`` was supplied. ``None`` for non-draft fetches. |
| `show_ai_generate` | `boolean` | No | Whether AI generation is available |
| `resolved_parameter_ids` | `string`[] | No | Resolved parameter IDs from saved fields |
| `names` | [`ScenarioNameResource`](/api-reference/scenario/types#scenarionameresource)[] | No | Name resources |
| `descriptions` | [`ScenarioDescriptionResource`](/api-reference/scenario/types#scenariodescriptionresource)[] | No | Description resources |
| `problem_statements` | [`ScenarioProblemStatement`](/api-reference/scenario/types#scenarioproblemstatement)[] | No | Problem statement resources |
| `flags` | [`ScenarioFlagResource`](/api-reference/scenario/types#scenarioflagresource)[] | No | Flag configs |
| `departments` | [`ScenarioDepartment`](/api-reference/scenario/types#scenariodepartment)[] | No | Department resources |
| `personas` | [`ScenarioPersona`](/api-reference/scenario/types#scenariopersona)[] | No | Persona resources |
| `documents` | [`ScenarioDocument`](/api-reference/scenario/types#scenariodocument)[] | No | Document resources |
| `parameters` | `any`[] | No | Parameter resources |
| `parameter_fields` | [`ScenarioField`](/api-reference/scenario/types#scenariofield)[] | No | Parameter field resources |
| `objectives` | [`ScenarioObjective`](/api-reference/scenario/types#scenarioobjective)[] | No | Objective resources |
| `images` | [`ScenarioImage`](/api-reference/scenario/types#scenarioimage)[] | No | Image resources |
| `videos` | [`ScenarioVideo`](/api-reference/scenario/types#scenariovideo)[] | No | Video resources |
| `questions` | [`ScenarioQuestion`](/api-reference/scenario/types#scenarioquestion)[] | No | Question resources |
| `options` | [`ScenarioOption`](/api-reference/scenario/types#scenariooption)[] | No | Option resources |

---

# `POST` `/scenario/group`

Route: /api-reference/scenario/post-scenario-group

# `POST` `/scenario/group`

Group Scenario

Resolve or create a scenario group with optional naming.

## Request Body (`GroupScenarioApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | No | Existing group UUID (omit to create or reuse via time window) |
| `snapshot_key` | `string` | No | Snapshot key for SETNX-race convergence on a single group across concurrent reads (e.g. parallel /context + /group + /search fan-out on page load). Echoed back in the response. |

## Response (`GroupScenarioApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Resolved or newly created group UUID |
| `name` | `string` | No | The group's current title (latest active group_names_entry, or 'New Chat' fallback for freshly minted groups) |
| `snapshot_key` | `string` | No | Snapshot key echoed back — the UUID concurrent fan-out reads converged on via SETNX. Mirrors the resolved group_id. |
| `runs` | [`GroupRun`](/api-reference/scenario/types#grouprun)[] | No | Conversation history — populated when resolving an existing group for fetch |
| `group_exists` | `boolean` | No | (detail) Whether the group exists in storage — populated when ``include_resources=True`` |
| `actor_name` | `string` | No | (detail) Display name of the current actor (caller profile) |
| `total_message_count` | `integer` | No | (detail) Total number of messages in the group |
| `models` | [`GroupResource`](/api-reference/scenario/types#groupresource)[] | No | (detail) Models used in the group |
| `agents` | [`GroupResource`](/api-reference/scenario/types#groupresource)[] | No | (detail) Agents used in the group |
| `profiles` | [`GroupResource`](/api-reference/scenario/types#groupresource)[] | No | (detail) Profiles that authored runs in this group |

---

# `POST` `/scenario/image_download`

Route: /api-reference/scenario/post-scenario-image-download

# `POST` `/scenario/image_download`

Download Image

Download an image file by image resource ID.

## Request Body (`ImageDownloadScenarioApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `image_id` | `string` | Yes | UUID of the images_resource to download |

## Response

```
{}
```

---

# `POST` `/scenario/image_upload`

Route: /api-reference/scenario/post-scenario-image-upload

# `POST` `/scenario/image_upload`

Upload Image

Upload an image for later use in scenarios (soft/accept dormant flow).

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `name` | query | No | — |
| `description` | query | No | — |

## Request Body

| Field | Type | Required | Description |
|---|---|---|---|
| `file` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `soft` | `boolean` | No | — |
| `accept` | `boolean` | No | — |

## Response (`ImageUploadScenarioApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `image_id` | `string` | Yes | UUID of the created images_resource |
| `upload_id` | `string` | Yes | UUID of the uploads_entry (file on disk) |
| `idempotency_key` | `string` | No | Server-minted soft-call key; echo with accept to promote/reject the staged upload. |

---

# `POST` `/scenario/problem`

Route: /api-reference/scenario/post-scenario-problem

# `POST` `/scenario/problem`

Problem Scenario

Report a scenario problem — composable infra architecture.

## Request Body (`ProblemScenarioApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | `string` | Yes | Problem type: feature, bug, question, other |
| `message` | `string` | Yes | Problem description (max 1000 chars) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant problem |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`ProblemScenarioApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `problem_id` | `string` | Yes | UUID of the created problem |
| `success` | `boolean` | No | Whether the problem was created |
| `message` | `string` | No | Status message |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/scenario/refresh`

Route: /api-reference/scenario/post-scenario-refresh

# `POST` `/scenario/refresh`

Scenario Refresh

Refresh scenario materialized views and invalidate caches.

## Request Body (`RefreshScenarioApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `targets` | `string`[] | No | MV targets to refresh (omit for all). Options: scenario_drafts_mv, runs_mv, messages_mv, calls_mv, groups_mv, group_names_mv |
| `idempotency_key` | `string` | No | Operation key for ack |
| `accept` | `boolean` | No | Accept or reject. Only meaningful with idempotency_key |
| `soft` | `boolean` | No | Stage the refresh as a pending (held) request — recorded but not enqueued; ack with accept releases/enqueues it |

## Response (`RefreshResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | — |
| `refreshed_views` | `string`[] | Yes | — |
| `invalidated_tags` | `string`[] | Yes | — |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/scenario/search`

Route: /api-reference/scenario/post-scenario-search

# `POST` `/scenario/search`

Search Scenario

Search scenarios — composable infra architecture.

## Request Body (`SearchScenarioApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | — |
| `persona_ids` | `string`[] | No | — |
| `simulation_ids` | `string`[] | No | — |
| `filter_department_ids` | `string`[] | No | — |
| `persona_search` | `string` | No | — |
| `simulation_search` | `string` | No | — |
| `department_search` | `string` | No | — |
| `flag_search` | `string` | No | — |
| `page_size` | `integer` | No | — |
| `page_offset` | `integer` | No | — |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`ListScenarioApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `scenarios` | [`ListScenarioApiScenario`](/api-reference/scenario/types#listscenarioapiscenario)[] | No | List of scenario items |
| `objectives` | [`ListScenarioApiObjective`](/api-reference/scenario/types#listscenarioapiobjective)[] | No | List of objective items |
| `fields` | [`ListScenarioApiField`](/api-reference/scenario/types#listscenarioapifield)[] | No | List of field items |
| `cohorts` | [`ListScenarioApiCohort`](/api-reference/scenario/types#listscenarioapicohort)[] | No | List of cohort items |
| `personas` | [`ListScenarioApiPersona`](/api-reference/scenario/types#listscenarioapipersona)[] | No | List of persona items |
| `simulations` | [`ListScenarioApiSimulation`](/api-reference/scenario/types#listscenarioapisimulation)[] | No | List of simulation items |
| `departments` | [`ListScenarioApiDepartment`](/api-reference/scenario/types#listscenarioapidepartment)[] | No | List of department items |
| `persona_filter` | [`ListFilterSection`](/api-reference/scenario/types#listfiltersection) | No | Filter options for personas |
| `simulation_filter` | [`ListFilterSection`](/api-reference/scenario/types#listfiltersection) | No | Filter options for simulations |
| `department_filter` | [`ListFilterSection`](/api-reference/scenario/types#listfiltersection) | No | Filter options for departments |
| `flag_filter` | [`ListFilterSection`](/api-reference/scenario/types#listfiltersection) | No | Filter options for flags |
| `total_count` | `integer` | No | Total number of matching records |
| `import_fields` | [`ImportField`](/api-reference/scenario/types#importfield)[] | No | CSV import column schema for the bulk-import dialog |

---

# `POST` `/scenario/text_download`

Route: /api-reference/scenario/post-scenario-text-download

# `POST` `/scenario/text_download`

Download Text

Download a text file by text resource ID.

## Request Body (`TextDownloadScenarioApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `text_id` | `string` | Yes | UUID of the texts_resource to download |

## Response

```
{}
```

---

# `POST` `/scenario/title`

Route: /api-reference/scenario/post-scenario-title

# `POST` `/scenario/title`

Title Scenario

Rename a scenario's group (writes group_names_entry).

## Request Body (`TitleScenarioApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Group to rename |
| `title` | `string` | Yes | New title (display name) for the group |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant rename |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`TitleScenarioApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | The group that was renamed |
| `group_name_id` | `string` | Yes | UUID of the new group_names_entry row |
| `title` | `string` | Yes | The title that was set |
| `idempotency_key` | `string` | No | Operation key echoed back |

---

# `POST` `/scenario/update`

Route: /api-reference/scenario/post-scenario-update

# `POST` `/scenario/update`

Update Scenario

Update scenarios using composable infra architecture.

## Request Body (`UpdateScenarioApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `scenarios` | [`UpdateScenarioItem`](/api-reference/scenario/types#updatescenarioitem)[] | No | List of scenarios to update (required on first call when ``all`` is false) |
| `all` | `boolean` | No | When true, apply ``patch`` to every scenario matching the filter fields below (minus ``excluded_ids``) |
| `excluded_ids` | `string`[] | No | UUIDs to skip even when matched by ``all``-mode filters |
| `patch` | [`UpdateScenarioPatch`](/api-reference/scenario/types#updatescenariopatch) | No | Shared change set applied to every matched row when ``all=true`` (sparse — only set fields are updated; ``patch.id`` ignored) |
| `search` | `string` | No | Full-text search query |
| `persona_ids` | `string`[] | No | Filter by persona UUIDs |
| `simulation_ids` | `string`[] | No | Filter by simulation UUIDs |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `persona_search` | `string` | No | Search text for persona facet (no-op for row filtering) |
| `simulation_search` | `string` | No | Search text for simulation facet (no-op for row filtering) |
| `department_search` | `string` | No | Search text for department facet (no-op for row filtering) |
| `flag_search` | `string` | No | Search text for flag facet (no-op for row filtering) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant update |
| `soft` | `boolean` | No | Stage the update dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`UpdateScenarioApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`ScenarioResultItem`](/api-reference/scenario/types#scenarioresultitem)[] | Yes | List of operation results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |
| `scenarios` | [`ListScenarioApiScenario`](/api-reference/scenario/types#listscenarioapiscenario)[] | No | Hydrated rows for the successfully-updated scenarios (mirrors /scenario/search shape) |

---

# `POST` `/scenario/video_download`

Route: /api-reference/scenario/post-scenario-video-download

# `POST` `/scenario/video_download`

Download Video

Download a video file by video resource ID with range support.

## Request Body (`VideoDownloadScenarioApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `video_id` | `string` | Yes | UUID of the videos_resource to download |

## Response

```
{}
```

---

# `POST` `/scenario/video_upload`

Route: /api-reference/scenario/post-scenario-video-upload

# `POST` `/scenario/video_upload`

Upload Video

Upload a video for later use in scenarios (soft/accept dormant flow).

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `name` | query | No | — |
| `description` | query | No | — |

## Request Body

| Field | Type | Required | Description |
|---|---|---|---|
| `file` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `soft` | `boolean` | No | — |
| `accept` | `boolean` | No | — |

## Response (`VideoUploadScenarioApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `video_id` | `string` | Yes | UUID of the created videos_resource |
| `upload_id` | `string` | Yes | UUID of the uploads_entry (file on disk) |
| `idempotency_key` | `string` | No | Server-minted soft-call key; echo with accept to promote/reject the staged upload. |

---

# `POST` `/scenario/watch`

Route: /api-reference/scenario/post-scenario-watch

# `POST` `/scenario/watch`

Scenario Watch Once

One-shot snapshot of run state, snapshot-replayable via ``snapshot_key``.

## Request Body (`WatchApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Chat group whose events we watch |
| `run_id` | `string` | No | Specific run to watch (e.g. the ``run_id`` returned by a prior ``X_Generate`` call). If None, watches every active run in the group at call time. |
| `wait_for_complete` | `boolean` | No | If True, block until the watched run reaches a terminal (complete/failed) event or timeout fires. If False, return current state and exit immediately. |
| `timeout_seconds` | `integer` | No | Max wait time when ``wait_for_complete=True``. |
| `snapshot_key` | `string` | No | Read snapshot key — on the one-shot POST /watch, the audit wrapper records this watch's point-in-time view (latest run state at call time) keyed by it and replays the same view on any later call with the same key. Ignored by the SSE GET stream. |

## Response (`WatchApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `runs` | [`RunStatus`](/api-reference/scenario/types#runstatus)[] | Yes | — |
| `timed_out` | `boolean` | No | — |
| `waited_seconds` | `number` | No | — |

---

# Scenario Types

Route: /api-reference/scenario/types

# Scenario Types

## `CallerPermissions`

Evaluated permissions for the current caller on this artifact type.

| Field | Type | Required | Description |
|---|---|---|---|
| `can_create` | `boolean` | Yes | Whether the caller can create new artifacts |
| `can_draft` | `boolean` | Yes | Whether the caller can create/update drafts |
| `can_duplicate` | `boolean` | Yes | Whether the caller can duplicate artifacts |
| `has_access` | `boolean` | No | Whether the caller can view this entity |
| `can_edit` | `boolean` | No | Whether the caller can edit this entity |
| `can_delete` | `boolean` | No | Whether the caller can delete this entity |
| `disabled_reason` | `string` | No | Human-readable reason if editing is disabled |

---

## `ColumnInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Column name |
| `type` | `string` | Yes | Column data type |
| `nullable` | `boolean` | Yes | Whether the column is nullable |

---

## `CreateScenarioItem`

Single scenario item for create — no scenario_id.

Required fields (name): provide ID or value.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Client-provided UUID for the scenario |
| `resource_id` | `string` | No | Optional preset UUID for the resource snapshot |
| `name_id` | `string` | No | UUID of the name resource |
| `name` | `string` | No | Display name value |
| `description_id` | `string` | No | UUID of the description resource |
| `description` | `string` | No | Description text value |
| `problem_statement_id` | `string` | No | UUID of the problem statement resource |
| `problem_statement` | `string` | No | Problem statement text value |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `department_ids` | `string`[] | No | Associated department UUIDs |
| `persona_ids` | `string`[] | No | Associated persona UUIDs |
| `document_ids` | `string`[] | No | Associated document UUIDs |
| `parameter_ids` | `string`[] | No | Associated parameter UUIDs |
| `parameter_field_ids` | `string`[] | No | Associated parameter field UUIDs |
| `image_ids` | `string`[] | No | Associated image UUIDs |
| `objective_ids` | `string`[] | No | Associated objective UUIDs |
| `video_ids` | `string`[] | No | Associated video UUIDs |
| `question_ids` | `string`[] | No | Associated question UUIDs |
| `option_ids` | `string`[] | No | Associated option UUIDs |
| `departments` | `string`[] | No | Department names for matching |
| `personas` | `string`[] | No | Persona names for matching |
| `documents` | `string`[] | No | Document names for matching |
| `parameter_fields` | `string`[] | No | Parameter field names for matching |
| `objectives` | `string`[] | No | Objective texts for matching |
| `images` | `string`[] | No | Image names for matching |
| `videos` | `string`[] | No | Video names for matching |
| `questions` | `string`[] | No | Question texts for matching |
| `options` | `string`[] | No | Option texts for matching |

---

## `DeleteScenarioResult`

Per-item result from bulk delete.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | No | Whether the operation succeeded |
| `scenario_id` | `string` | No | UUID of the deleted scenario |
| `message` | `string` | No | Human-readable result message |

---

## `DocsApiResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `list` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `detail` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `new` | [`PageMetaItem`](#pagemetaitem) | Yes | — |

---

## `DocsResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Resource or entry name |
| `type` | `string` | Yes | Resource or entry type identifier |
| `description` | `string` | Yes | Human-readable description |
| `materialized_view` | [`MvInfo`](#mvinfo) | No | Materialized view metadata |
| `tables` | [`TableInfo`](#tableinfo)[] | Yes | Related database tables |
| `operations` | [`OperationInfo`](#operationinfo)[] | Yes | Available operations |

---

## `EvalSetup`

Run-level eval scaffold — first-class on the generate response.

Audit's ``**output`` spread carries this onto
``<artifact>.generate.completed``. Null when no rubric-bearing
agent participated.

| Field | Type | Required | Description |
|---|---|---|---|
| `test_id` | `string` | Yes | — |
| `invocations` | [`InvocationSlot`](#invocationslot)[] | Yes | — |

---

## `GenerateConfig`

Developer configuration — all optional with sensible defaults.

| Field | Type | Required | Description |
|---|---|---|---|
| `operations` | `string`[] | No | — |
| `dangerous` | `boolean` | No | — |
| `params` | `object` | No | — |
| `group_id` | `string` | No | — |

---

## `GenerationsScenarioListItem`

Single generation group in the scenario generations response.

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | UUID of the generation group |
| `session_id` | `string` | No | UUID of the parent session |
| `group_name` | `string` | No | Name of the generation group |
| `created_at` | `string` | No | Timestamp of the generation |

---

## `GetScenarioDraftResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | UUID of the draft |
| `created_at` | `string` | Yes | Creation timestamp |
| `generated` | `boolean` | Yes | Whether this was AI-generated |
| `mcp` | `boolean` | Yes | Whether MCP tooling was used |
| `active` | `boolean` | Yes | Whether this draft is active |
| `session_id` | `string` | Yes | Associated session UUID |
| `name` | `string` | No | Immutable draft label set at create time |
| `department_ids` | `string`[] | Yes | Associated department UUIDs |
| `description_ids` | `string`[] | Yes | Associated description UUIDs |
| `document_ids` | `string`[] | Yes | Associated document UUIDs |
| `flag_ids` | `string`[] | Yes | Associated flag UUIDs |
| `image_ids` | `string`[] | Yes | Associated image UUIDs |
| `name_ids` | `string`[] | Yes | Associated name UUIDs |
| `objective_ids` | `string`[] | Yes | Associated objective UUIDs |
| `option_ids` | `string`[] | Yes | Associated option UUIDs |
| `parameter_field_ids` | `string`[] | Yes | Associated parameter field UUIDs |
| `persona_ids` | `string`[] | Yes | Associated persona UUIDs |
| `problem_statement_ids` | `string`[] | Yes | Associated problem statement UUIDs |
| `profile_ids` | `string`[] | Yes | Associated profile UUIDs |
| `question_ids` | `string`[] | Yes | Associated question UUIDs |
| `video_ids` | `string`[] | Yes | Associated video UUIDs |
| `pending_name_ids` | `string`[] | No | Pending name UUIDs |
| `pending_description_ids` | `string`[] | No | Pending description UUIDs |
| `pending_problem_statement_ids` | `string`[] | No | Pending problem statement UUIDs |
| `pending_department_ids` | `string`[] | No | Pending department UUIDs |
| `pending_persona_ids` | `string`[] | No | Pending persona UUIDs |
| `pending_document_ids` | `string`[] | No | Pending document UUIDs |
| `pending_objective_ids` | `string`[] | No | Pending objective UUIDs |
| `pending_image_ids` | `string`[] | No | Pending image UUIDs |
| `pending_video_ids` | `string`[] | No | Pending video UUIDs |
| `pending_question_ids` | `string`[] | No | Pending question UUIDs |
| `pending_option_ids` | `string`[] | No | Pending option UUIDs |
| `pending_flag_ids` | `string`[] | No | Pending flag UUIDs |
| `pending_parameter_field_ids` | `string`[] | No | Pending parameter field UUIDs |

---

## `GroupCall`

Tool call referenced by a message.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `tool_name` | `string` | No | — |
| `template_name` | `string` | No | — |
| `tool` | `object` | No | — |
| `ledger_status` | `string` | No | — |
| `ledger_operation` | `string` | No | — |
| `ledger_artifact` | `string` | No | — |
| `ledger_artifact_id` | `string` | No | — |

---

## `GroupMessage`

Message within a run.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `role` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `text_ids` | `string`[] | No | — |
| `audio_ids` | `string`[] | No | — |
| `image_ids` | `string`[] | No | — |
| `video_ids` | `string`[] | No | — |
| `file_ids` | `string`[] | No | — |
| `call_ids` | `string`[] | No | — |
| `calls` | [`GroupCall`](#groupcall)[] | No | — |
| `reasoning` | `boolean` | No | True when this row is a chain-of-thought trace persisted alongside the assistant answer (rendered as a collapsed accordion). |
| `in_context` | `boolean` | No | Whether this message is included in the LLM context for the next generation. Mirrors the dedup pass that builds chat history (see in_context_reason). |
| `in_context_reason` | `string` | No | Why this message is in/out of LLM context. 'kept' = included; 'deduped_read' = older read-only call to a tool that has a fresher result later in the group; future values may include 'trimmed_top_n'. |

---

## `GroupResource`

Lightweight `\{id, name\}` for cross-referencing run-level ids
(``model_id`` / ``agent_id`` / ``profile_id``) against human-readable
names on the analytics panel. Names come from the canonical
``get_models`` / ``get_agents`` / ``get_profiles`` black boxes.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `name` | `string` | No | — |

---

## `GroupRun`

Run within a group, with its messages.

Carries token / cost / model / agent / profile attribution so the
analytics view can render per-run cost + actor info without a
parallel detail shape. ``profile_id`` is the authoring profile
(human user), ``agent_id`` is the LLM-side actor, ``model_id`` is
the model used by that agent. All optional — runs predating these
columns or with unresolved attributions surface ``None``.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `input_tokens` | `integer` | No | — |
| `output_tokens` | `integer` | No | — |
| `cached_input_tokens` | `integer` | No | — |
| `cost` | `number` | No | — |
| `model_id` | `string` | No | — |
| `agent_id` | `string` | No | — |
| `profile_id` | `string` | No | — |
| `previous_context_start_index` | `integer` | No | Index in ``messages`` where the current run's own messages begin; earlier rows are previous-context replay. ``None`` when the run has no previous context attached. |
| `messages` | [`GroupMessage`](#groupmessage)[] | No | — |

---

## `ImportField`

Field descriptor for CSV import column mapping.

| Field | Type | Required | Description |
|---|---|---|---|
| `key` | `string` | Yes | — |
| `label` | `string` | Yes | — |
| `required` | `boolean` | No | — |
| `multi` | `boolean` | No | — |
| `type` | `string` | No | — |
| `example` | `string` | No | — |
| `description` | `string` | No | — |

---

## `InvocationSlot`

One agent's slot in a multi-agent generation pool.

Populated by ``setup_generation_test`` when an agent carries a
rubric. The client uses these IDs to drive the eval workflow:
review the candidate's output, optionally fire a grader against
its ``invocation_id``, and promote/reject by call_id via the
existing ``idempotency_key + accept`` pattern.

| Field | Type | Required | Description |
|---|---|---|---|
| `invocation_id` | `string` | Yes | — |
| `agent_id` | `string` | Yes | — |
| `rubric_id` | `string` | No | — |

---

## `ListFilterOption`

Standardized option for list endpoint filter sections.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier for this filter option |
| `name` | `string` | No | Display name |
| `count` | `integer` | No | Number of matching records |
| `hex_code` | `string` | No | Hex color code for display |
| `value` | `string` | No | Internal value |
| `type` | `string` | No | Option type discriminator |

---

## `ListFilterSection`

Filter section with options and echoed request state.

| Field | Type | Required | Description |
|---|---|---|---|
| `options` | [`ListFilterOption`](#listfilteroption)[] | No | Available filter options |
| `selected_ids` | `string`[] | No | Currently selected filter option IDs |
| `search` | `string` | No | Active search text for filtering |

---

## `ListScenarioApiCohort`

Cohort in list response.

| Field | Type | Required | Description |
|---|---|---|---|
| `cohort_id` | `string` | No | UUID of the cohort |
| `name` | `string` | No | Cohort name |
| `description` | `string` | No | Cohort description text |

---

## `ListScenarioApiDepartment`

Department in list response.

| Field | Type | Required | Description |
|---|---|---|---|
| `department_id` | `string` | No | UUID of the department |
| `name` | `string` | No | Department name |
| `description` | `string` | No | Department description text |

---

## `ListScenarioApiField`

Field in list response.

| Field | Type | Required | Description |
|---|---|---|---|
| `field_id` | `string` | No | UUID of the field |
| `name` | `string` | No | Field name |
| `description` | `string` | No | Field description text |

---

## `ListScenarioApiObjective`

Objective in list response.

| Field | Type | Required | Description |
|---|---|---|---|
| `objective_id` | `string` | No | UUID of the objective |
| `name` | `string` | No | Objective name |
| `description` | `string` | No | Objective description text |

---

## `ListScenarioApiPersona`

Persona in list response.

| Field | Type | Required | Description |
|---|---|---|---|
| `persona_id` | `string` | No | UUID of the persona |
| `name` | `string` | No | Persona name |
| `description` | `string` | No | Persona description text |
| `color` | `string` | No | Display color for the persona |
| `icon` | `string` | No | Icon identifier for the persona |

---

## `ListScenarioApiScenario`

Scenario item in list response with Python-computed permissions.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Scenario artifact UUID (canonical id; mirrors scenario_id) |
| `scenario_id` | `string` | No | UUID of the scenario |
| `name` | `string` | No | Display name |
| `problem_statement` | `string` | No | Problem statement text |
| `is_inactive` | `boolean` | No | Whether the scenario is inactive |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `mcp` | `boolean` | No | Whether this is an MCP scenario |
| `department_ids` | `string`[] | No | Associated department UUIDs |
| `objective_ids` | `string`[] | No | Associated objective UUIDs |
| `persona_ids` | `string`[] | No | Associated persona UUIDs |
| `field_ids` | `string`[] | No | Associated field UUIDs |
| `simulation_ids` | `string`[] | No | Associated simulation UUIDs |
| `num_simulations` | `integer` | No | Total number of simulations |
| `active_simulation_count` | `integer` | No | Number of active simulations |
| `can_edit` | `boolean` | No | Whether the current user can edit |
| `can_delete` | `boolean` | No | Whether the current user can delete |
| `can_duplicate` | `boolean` | No | Whether the current user can duplicate |
| `cohort_ids` | `string`[] | No | Associated cohort UUIDs |
| `pending_status` | `string` | No | Latest soft_calls_mv status: 'pending' / 'accepted' / 'rejected' |
| `pending_operation` | `string` | No | Operation type ('create'|'update'|'delete'|'duplicate') of the pending op |
| `pending_call_id` | `string` | No | call_id (idempotency key for ack) of the pending op |
| `updated_at` | `string` | No | Last updated timestamp |

---

## `ListScenarioApiSimulation`

Simulation in list response.

| Field | Type | Required | Description |
|---|---|---|---|
| `simulation_id` | `string` | No | UUID of the simulation |
| `name` | `string` | No | Simulation name |
| `description` | `string` | No | Simulation description text |
| `department_ids` | `string`[] | No | Associated department UUIDs |

---

## `MvInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Materialized view name |
| `definition` | `string` | Yes | SQL definition of the view |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the view |

---

## `OperationInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Operation name |
| `description` | `string` | Yes | Human-readable description of the operation |
| `params` | [`ParamInfo`](#paraminfo)[] | Yes | List of operation parameters |
| `returns` | `object` | No | Return type schema |

---

## `OperationPrompts`

Starter prompts keyed by operation name.

Each key is an operation (e.g. "create", "search", "draft", "export")
and the value is a list of starter prompts for that operation.
The client picks from the operations the caller has permission for
and rotates through them.

| Field | Type | Required | Description |
|---|---|---|---|
| `prompts` | `object` | No | Map of operation name to starter prompts |

---

## `PageMetaItem`

| Field | Type | Required | Description |
|---|---|---|---|
| `title` | `string` | Yes | — |
| `description` | `string` | Yes | — |

---

## `ParamInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Parameter name |
| `type` | `string` | Yes | Parameter data type |
| `required` | `boolean` | Yes | Whether the parameter is required |
| `default` | `any` | No | Default value if not required |

---

## `ProducedMedia`

One asset produced by a generation run.

``resource_id`` is the canonical id the per-artifact download tools
accept (e.g. ``Scenario_Image_Download(image_id=resource_id)`` for
``modality="image"``). It maps to ``images_resource.id`` /
``videos_resource.id`` / ``audios_resource.id`` depending on the
modality.

| Field | Type | Required | Description |
|---|---|---|---|
| `modality` | `"image"` \| `"video"` \| `"audio"` | Yes | — |
| `resource_id` | `string` | Yes | — |
| `upload_id` | `string` | Yes | — |
| `mime_type` | `string` | No | — |
| `file_size` | `integer` | No | — |

---

## `ProfileSummary`

Caller identity derived from JWT — who you are on this page.

Superset of the old six-field version: now carries everything the client
needs so that ``/\{artifact\}/context`` fully replaces ``/profiles/context``
and the extra ``getLayoutContextData`` round-trip can be dropped.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Display name of the authenticated user |
| `role` | `string` | Yes | Role name (e.g. 'Super Administrator') |
| `role_level` | `integer` | Yes | Role hierarchy level (0 = highest privilege) |
| `department_ids` | `string`[] | Yes | Departments the user belongs to |
| `artifact_access` | `string`[] | Yes | Artifact types this role can access (sidebar visibility) |
| `role_permissions` | `any`[][] | Yes | Full (artifact, operation) permission tuples for granular page gating |
| `is_active` | `boolean` | Yes | Whether the user's profile is active |
| `id` | `string` | Yes | Profile UUID (SocketProvider, ProfileProvider) |
| `theme` | [`ThemeBundle`](#themebundle) | No | Resolved theme: hex primitives + derived oklch tokens + score thresholds |
| `session_id` | `string` | No | Current session UUID |
| `is_emulation` | `boolean` | No | Whether user is in emulation mode (ProfileProvider) |
| `role_resources` | [`QGetProfileContextV4RoleResource`](#qgetprofilecontextv4roleresource)[] | No | All role resources for emulation display (ProfileProvider) |
| `scoped_roles` | `string`[] | No | Roles the user can emulate (ProfileProvider) |
| `active` | `boolean` | No | Alias for is_active (ProfileProvider uses this name) |

---

## `QGetProfileContextV4RoleResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `role` | `string` | No | — |
| `name` | `string` | No | — |
| `description` | `string` | No | — |
| `icon_value` | `string` | No | — |
| `color_hex` | `string` | No | — |

---

## `RunStatus`

Outcome of one watched run.

| Field | Type | Required | Description |
|---|---|---|---|
| `run_id` | `string` | Yes | — |
| `status` | `"pending"` \| `"completed"` \| `"failed"` | Yes | — |
| `modality` | `string` | No | Modality of generated output (image, video, text…) |
| `resource_ids` | `string`[] | No | Resource UUIDs produced by this run (e.g. images_resource ids) |
| `error` | `string` | No | — |

---

## `ScenarioDepartment`

Department for scenario.

| Field | Type | Required | Description |
|---|---|---|---|
| `department_id` | `string` | No | UUID of the department |
| `name` | `string` | No | Department name |
| `description` | `string` | No | Department description text |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `selected` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `ScenarioDescriptionResource`

Description resource for scenario.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | UUID of the description resource |
| `description` | `string` | No | Description text |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `selected` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `ScenarioDocument`

Document for scenario.

| Field | Type | Required | Description |
|---|---|---|---|
| `document_id` | `string` | No | UUID of the document |
| `name` | `string` | No | Document name |
| `description` | `string` | No | Document description text |
| `file_id` | `string` | No | UUID of the files_resource (used for download) |
| `file_path` | `string` | No | Storage path of the file |
| `mime_type` | `string` | No | MIME type of the document |
| `upload_id` | `string` | No | UUID of the associated upload |
| `html` | `boolean` | No | Whether the document is HTML content |
| `parameter_ids` | `string`[] | No | Linked parameter UUIDs |
| `field_ids` | `string`[] | No | Linked field UUIDs |
| `parent_document_id` | `string` | No | UUID of the parent document |
| `video_document` | `boolean` | No | Has linked parameter with video enabled |
| `non_video_document` | `boolean` | No | Has linked parameter with video disabled |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `selected` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `ScenarioDraftFormState`

Full form state after draft patch — server is source of truth.

Client replaces its local form state with this after every successful patch.

| Field | Type | Required | Description |
|---|---|---|---|
| `name_id` | `string` | No | UUID of the selected name resource |
| `description_id` | `string` | No | UUID of the selected description resource |
| `problem_statement_id` | `string` | No | UUID of the selected problem statement resource |
| `flag_ids` | `string`[] | No | Selected flag UUIDs |
| `active` | `boolean` | No | Echoed scenario_active flag state |
| `video_enabled` | `boolean` | No | Echoed video_enabled flag state |
| `problem_statement_enabled` | `boolean` | No | Echoed problem_statement_enabled flag state |
| `objectives_enabled` | `boolean` | No | Echoed objectives_enabled flag state |
| `images_enabled` | `boolean` | No | Echoed images_enabled flag state |
| `questions_enabled` | `boolean` | No | Echoed questions_enabled flag state |
| `department_ids` | `string`[] | No | Selected department UUIDs |
| `persona_ids` | `string`[] | No | Selected persona UUIDs |
| `document_ids` | `string`[] | No | Selected document UUIDs |
| `parameter_field_ids` | `string`[] | No | Selected parameter field UUIDs |
| `objective_ids` | `string`[] | No | Selected objective UUIDs |
| `image_ids` | `string`[] | No | Selected image UUIDs |
| `video_ids` | `string`[] | No | Selected video UUIDs |
| `question_ids` | `string`[] | No | Selected question UUIDs |
| `option_ids` | `string`[] | No | Selected option UUIDs |

---

## `ScenarioField`

Field for scenario.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | UUID of the parameter_fields_resource junction row; required by the client picker to select a field |
| `field_id` | `string` | No | UUID of the field |
| `name` | `string` | No | Field name |
| `description` | `string` | No | Field description text |
| `parameter_id` | `string` | No | UUID of the linked parameter |
| `parameter_name` | `string` | No | Name of the linked parameter |
| `conditional_parameter_ids` | `string`[] | No | Conditional parameter UUIDs |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `selected` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `ScenarioFieldError`

Per-field error from value resolution.

| Field | Type | Required | Description |
|---|---|---|---|
| `field` | `string` | Yes | Name of the field with the error |
| `message` | `string` | Yes | Human-readable error message |

---

## `ScenarioFlagResource`

Flag option row — one per (name, type, value) entry in flags_resource.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Flag resource identifier |
| `name` | `string` | No | Flag display name |
| `type` | `string` | No | Flag type (e.g. 'scenario_active') |
| `value` | `boolean` | No | Underlying bool value of this option |
| `description` | `string` | No | Flag description text |
| `icon_id` | `string` | No | Icon identifier for the flag |
| `icon` | `string` | No | Resolved SVG markup (hydrated from icons_resource) |
| `generated` | `boolean` | No | Whether the flag was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `ScenarioImage`

Image for scenario.

| Field | Type | Required | Description |
|---|---|---|---|
| `image_id` | `string` | No | UUID of the image |
| `name` | `string` | No | Image name |
| `file_path` | `string` | No | Storage path of the image file |
| `mime_type` | `string` | No | MIME type of the image |
| `upload_id` | `string` | No | UUID of the associated upload |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `selected` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `ScenarioNameResource`

Name resource for scenario.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | UUID of the name resource |
| `name` | `string` | No | Display name |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `selected` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `ScenarioObjective`

Objective for scenario.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | UUID of the objective |
| `objective` | `string` | No | Objective text |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `selected` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `ScenarioOption`

Option for scenario.

| Field | Type | Required | Description |
|---|---|---|---|
| `option_id` | `string` | No | UUID of the option |
| `option_text` | `string` | No | Option text content |
| `is_correct` | `boolean` | No | Whether this is the correct option |
| `question_id` | `string` | No | UUID of the parent question |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `selected` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `ScenarioPersona`

Persona for scenario.

| Field | Type | Required | Description |
|---|---|---|---|
| `persona_id` | `string` | No | UUID of the persona |
| `name` | `string` | No | Persona name |
| `description` | `string` | No | Persona description text |
| `color` | `string` | No | Display color for the persona |
| `icon` | `string` | No | Icon identifier for the persona |
| `image_model` | `boolean` | No | Whether this persona uses an image model |
| `parameter_ids` | `string`[] | No | Linked parameter UUIDs |
| `field_ids` | `string`[] | No | Linked field UUIDs |
| `example` | `string` | No | Example text for the persona |
| `video_persona` | `boolean` | No | Has linked parameter with video enabled |
| `non_video_persona` | `boolean` | No | Has linked parameter with video disabled |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `selected` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `ScenarioProblemStatement`

Problem statement for scenario.

| Field | Type | Required | Description |
|---|---|---|---|
| `problem_statement_id` | `string` | No | UUID of the problem statement |
| `name` | `string` | No | Problem statement name |
| `problem_statement` | `string` | No | Problem statement text |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `selected` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `ScenarioQuestion`

Question for scenario.

| Field | Type | Required | Description |
|---|---|---|---|
| `question_id` | `string` | No | UUID of the question |
| `question_text` | `string` | No | Question text content |
| `allow_multiple` | `boolean` | No | Whether multiple answers are allowed |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `selected` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `ScenarioResultItem`

Per-item result within a bulk create/update response.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `scenario_id` | `string` | No | UUID of the affected scenario |
| `message` | `string` | Yes | Human-readable result message |
| `errors` | [`ScenarioFieldError`](#scenariofielderror)[] | No | List of per-field errors |

---

## `ScenarioVideo`

Video for scenario.

| Field | Type | Required | Description |
|---|---|---|---|
| `video_id` | `string` | No | UUID of the video |
| `name` | `string` | No | Video name |
| `file_path` | `string` | No | Storage path of the video file |
| `mime_type` | `string` | No | MIME type of the video |
| `upload_id` | `string` | No | UUID of the associated upload |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `selected` | `boolean` | No | — |
| `suggested` | `boolean` | No | — |
| `pending` | `boolean` | No | — |

---

## `TableInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Table name |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the table |

---

## `ThemeBundle`

Full theme payload for a page bootstrap.

Riding along on every ``/\{artifact\}/context`` response via
``ProfileSummary.theme``. Layers:
  - ``primitives`` / ``dark_primitives`` — hex inputs the settings
    editor reads/writes (light + dark palettes).
  - ``tokens`` / ``dark_tokens`` — oklch tokens the client paints with.
    ``ThemeStyle`` emits two ``<style>`` blocks: one scoped to
    ``:root:not(.dark)`` (light) and one to ``:root.dark`` (dark).
  - ``thresholds`` — numeric score thresholds for analytics components.
Empty-in → empty-out per token: missing values fall through to the
matching ``globals.css`` default.

| Field | Type | Required | Description |
|---|---|---|---|
| `primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (light palette, for the theme editor) |
| `tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for light mode (SSR CSS-var injection) |
| `dark_primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (dark palette, for the theme editor) |
| `dark_tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for dark mode (SSR CSS-var injection) |
| `thresholds` | [`Thresholds`](#thresholds) | No | Score thresholds resolved from the setting |

---

## `ThemePrimitives`

40 optional fields. The 17 essentials drive the rest; the other 23
are overrides for fine-tuning when derivation isn't what you want.

Empty primitive → empty token → client falls back to globals.css.

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `primary` | `string` | No | — |
| `accent` | `string` | No | — |
| `card` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `ring` | `string` | No | — |
| `border` | `string` | No | — |
| `destructive` | `string` | No | — |
| `success` | `string` | No | — |
| `warning` | `string` | No | — |
| `info` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `input` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `ThemeTokens`

40 fully-resolved CSS variable values (snake_case 1:1 with vars).

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `accent` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `border` | `string` | No | — |
| `input` | `string` | No | — |
| `ring` | `string` | No | — |
| `success` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `Thresholds`

Numeric score thresholds resolved from the active setting.

Server pre-buckets dashboard metrics into ``success | warning | danger |
neutral`` already, so most components don't need these values. Surface
them for chart reference lines, tooltips, and any client-side bucketing.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `integer` | Yes | Score >= this counts as success |
| `warning` | `integer` | Yes | Score >= this counts as warning |
| `danger` | `integer` | Yes | Score < success threshold but >= this counts as danger; below is neutral/no-data |

---

## `UpdateScenarioItem`

Single scenario item for update — scenario_id required, all fields optional.

Only provided fields are updated (partial update).

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | UUID of the scenario to update |
| `name_id` | `string` | No | UUID of the name resource |
| `name` | `string` | No | Display name value |
| `description_id` | `string` | No | UUID of the description resource |
| `description` | `string` | No | Description text value |
| `problem_statement_id` | `string` | No | UUID of the problem statement resource |
| `problem_statement` | `string` | No | Problem statement text value |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `department_ids` | `string`[] | No | Associated department UUIDs |
| `persona_ids` | `string`[] | No | Associated persona UUIDs |
| `document_ids` | `string`[] | No | Associated document UUIDs |
| `parameter_ids` | `string`[] | No | Associated parameter UUIDs |
| `parameter_field_ids` | `string`[] | No | Associated parameter field UUIDs |
| `image_ids` | `string`[] | No | Associated image UUIDs |
| `objective_ids` | `string`[] | No | Associated objective UUIDs |
| `video_ids` | `string`[] | No | Associated video UUIDs |
| `question_ids` | `string`[] | No | Associated question UUIDs |
| `option_ids` | `string`[] | No | Associated option UUIDs |
| `departments` | `string`[] | No | Department names for matching |
| `personas` | `string`[] | No | Persona names for matching |
| `documents` | `string`[] | No | Document names for matching |
| `parameter_fields` | `string`[] | No | Parameter field names for matching |
| `objectives` | `string`[] | No | Objective texts for matching |
| `images` | `string`[] | No | Image names for matching |
| `videos` | `string`[] | No | Video names for matching |
| `questions` | `string`[] | No | Question texts for matching |
| `options` | `string`[] | No | Option texts for matching |

---

## `UpdateScenarioPatch`

Shared patch for bulk-update-all-matching mode.

Inherits every field from ``UpdateScenarioItem`` and just relaxes
``id`` to optional — the bulk impl stamps the resolved id onto a
clone of the patch per matched row, so any client-supplied id is
ignored. Sparse semantics: only fields the client sets are written.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Ignored — bulk impl stamps the resolved scenario id per matched row |
| `name_id` | `string` | No | UUID of the name resource |
| `name` | `string` | No | Display name value |
| `description_id` | `string` | No | UUID of the description resource |
| `description` | `string` | No | Description text value |
| `problem_statement_id` | `string` | No | UUID of the problem statement resource |
| `problem_statement` | `string` | No | Problem statement text value |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `department_ids` | `string`[] | No | Associated department UUIDs |
| `persona_ids` | `string`[] | No | Associated persona UUIDs |
| `document_ids` | `string`[] | No | Associated document UUIDs |
| `parameter_ids` | `string`[] | No | Associated parameter UUIDs |
| `parameter_field_ids` | `string`[] | No | Associated parameter field UUIDs |
| `image_ids` | `string`[] | No | Associated image UUIDs |
| `objective_ids` | `string`[] | No | Associated objective UUIDs |
| `video_ids` | `string`[] | No | Associated video UUIDs |
| `question_ids` | `string`[] | No | Associated question UUIDs |
| `option_ids` | `string`[] | No | Associated option UUIDs |
| `departments` | `string`[] | No | Department names for matching |
| `personas` | `string`[] | No | Persona names for matching |
| `documents` | `string`[] | No | Document names for matching |
| `parameter_fields` | `string`[] | No | Parameter field names for matching |
| `objectives` | `string`[] | No | Objective texts for matching |
| `images` | `string`[] | No | Image names for matching |
| `videos` | `string`[] | No | Video names for matching |
| `questions` | `string`[] | No | Question texts for matching |
| `options` | `string`[] | No | Option texts for matching |

---

## `app__infra__persona__types__SectionFilter`

Per-section filter options for GET requests.

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Filter options by search text |
| `limit` | `integer` | No | Max options to return |
| `selected` | `boolean` | No | Only return selected items |
| `suggested` | `boolean` | No | Only return suggested items |
| `include` | `boolean` | No | Include this section in response (default true) |
| `parameter_ids` | `string`[] | No | Parameter group IDs to filter by (parameter_fields section only) |

---

## `app__infra__scenario__types__DraftImageValue`

Value for creating an image via the draft endpoint.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Image name |
| `description` | `string` | Yes | Image description text |
| `upload_id` | `string` | No | UUID of the associated upload |

---

## `app__infra__scenario__types__DraftOptionValue`

Value for creating an option via the draft endpoint.

| Field | Type | Required | Description |
|---|---|---|---|
| `option_text` | `string` | Yes | Option text content |
| `question_id` | `string` | No | UUID of the parent question |

---

## `app__infra__scenario__types__DraftQuestionValue`

Value for creating a question via the draft endpoint.

| Field | Type | Required | Description |
|---|---|---|---|
| `question_text` | `string` | Yes | Question text content |
| `time` | `integer` | No | Time limit in seconds |
| `allow_multiple` | `boolean` | No | Whether multiple answers are allowed |

---

## `app__infra__scenario__types__DraftVideoValue`

Value for creating a video via the draft endpoint.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Video name |
| `description` | `string` | Yes | Video description text |
| `upload_id` | `string` | No | UUID of the associated upload |
| `length_seconds` | `integer` | No | Video length in seconds |

---

---

# `GET` `/setting/watch`

Route: /api-reference/setting/get-setting-watch

# `GET` `/setting/watch`

Setting Watch

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `group_id` | query | No | — |
| `run_id` | query | No | Optional run filter. If provided, only events whose envelope run_id matches are streamed. Omit to receive every setting event in the group (the FE default). |

## Response

```
{}
```

---

# `POST` `/setting/call_download`

Route: /api-reference/setting/post-setting-call-download

# `POST` `/setting/call_download`

Download Call

Download a call file by call resource ID.

## Request Body (`CallDownloadSettingApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `call_id` | `string` | Yes | UUID of the calls_resource to download |

## Response

```
{}
```

---

# `POST` `/setting/context`

Route: /api-reference/setting/post-setting-context

# `POST` `/setting/context`

Get Setting Context

Get page context for the setting artifact.

Returns docs + profile identity + evaluated permissions in a single call.
Superset of /docs — clients can migrate from /docs to /context incrementally.

## Request Body (`DocsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entity_id` | `string` | No | — |
| `snapshot_key` | `string` | No | — |
| `schema` | `boolean` | No | If true, include MCP/tooling schema metadata (artifact, entries, resources, permission_docs, api_operations). Defaults to false for lean page-bootstrap responses. |

## Response (`ComposedContextResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Artifact name |
| `type` | `string` | Yes | Artifact type identifier |
| `description` | `string` | Yes | Human-readable description |
| `artifact` | [`DocsResponse`](/api-reference/setting/types#docsresponse) | No | Artifact tool documentation (None unless schema=true) |
| `entries` | [`DocsResponse`](/api-reference/setting/types#docsresponse)[] | No | Entry documentation list (None unless schema=true) |
| `resources` | [`DocsResponse`](/api-reference/setting/types#docsresponse)[] | No | Resource documentation list (None unless schema=true) |
| `permission_docs` | [`OperationInfo`](/api-reference/setting/types#operationinfo)[] | No | Permission function signatures for MCP/dev tooling (None unless schema=true) |
| `api_operations` | [`OperationInfo`](/api-reference/setting/types#operationinfo)[] | No | API operation documentation (None unless schema=true) |
| `page_metadata` | [`DocsApiResponse`](/api-reference/setting/types#docsapiresponse) | No | Page-level metadata |
| `prompts` | [`OperationPrompts`](/api-reference/setting/types#operationprompts) | No | Starter prompts keyed by operation |
| `profile` | [`ProfileSummary`](/api-reference/setting/types#profilesummary) | Yes | Caller identity from JWT |
| `caller_permissions` | [`CallerPermissions`](/api-reference/setting/types#callerpermissions) | Yes | Evaluated permissions for this caller |

---

# `POST` `/setting/create`

Route: /api-reference/setting/post-setting-create

# `POST` `/setting/create`

Create Setting

Create settings using composable infra architecture.

## Request Body (`CreateSettingApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `settings` | [`CreateSettingItem`](/api-reference/setting/types#createsettingitem)[] | Yes | List of settings to create |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant create |
| `soft` | `boolean` | No | Stage the create dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`CreateSettingApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`SettingResultItem`](/api-reference/setting/types#settingresultitem)[] | Yes | Per-item creation results |
| `settings` | [`ListSettingApiSetting`](/api-reference/setting/types#listsettingapisetting)[] | No | Hydrated list rows for the newly-created settings. Mirrors the shape of ``/setting/search`` result rows so the client's ghost rail can materialize the new card directly from the audit ``.completed`` payload — no follow-up refresh needed. |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/setting/csv`

Route: /api-reference/setting/post-setting-csv

# `POST` `/setting/csv`

Parse Setting Csv

Parse a CSV file and return mapped items for preview.

## Request Body

| Field | Type | Required | Description |
|---|---|---|---|
| `file` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `soft` | `boolean` | No | — |
| `accept` | `boolean` | No | — |

## Response (`ParseSettingCsvApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `upload_id` | `string` | Yes | — |
| `items` | [`CreateSettingItem`](/api-reference/setting/types#createsettingitem)[] | Yes | — |
| `mapped_fields` | `string`[] | Yes | — |
| `row_count` | `integer` | Yes | — |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with `accept` to promote/reject the staged raw-CSV upload. NOTE: ack returns no items (the preview is only on the propose). |

---

# `POST` `/setting/decrypt`

Route: /api-reference/setting/post-setting-decrypt

# `POST` `/setting/decrypt`

Decrypt Setting Key

Decrypt a key scoped to a setting artifact.

## Request Body (`DecryptSettingKeyApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `setting_id` | `string` | Yes | UUID of the parent setting |
| `key_id` | `string` | Yes | UUID of the key to decrypt |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`DecryptSettingKeyApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `key` | `string` | No | Decrypted key value |
| `name` | `string` | No | Key display name |
| `actor_name` | `string` | No | Display name of the acting user |

---

# `POST` `/setting/delete`

Route: /api-reference/setting/post-setting-delete

# `POST` `/setting/delete`

Delete Setting

Bulk delete settings — composable infra architecture.

## Request Body (`DeleteSettingApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `setting_ids` | `string`[] | No | UUIDs of settings to delete (required on first call when ``all`` is false) |
| `all` | `boolean` | No | When true, delete every setting matching the filter fields below (minus ``excluded_ids``) |
| `excluded_ids` | `string`[] | No | UUIDs to skip even when matched by ``all``-mode filters |
| `search` | `string` | No | Full-text search query |
| `flag_ids` | `string`[] | No | Filter by flag UUIDs |
| `provider_ids` | `string`[] | No | Filter by provider UUIDs |
| `auth_ids` | `string`[] | No | Filter by auth UUIDs |
| `system_ids` | `string`[] | No | Filter by system UUIDs |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `flag_search` | `string` | No | Search text for flag facet (no-op for row filtering) |
| `provider_search` | `string` | No | Search text for provider facet (no-op for row filtering) |
| `auth_search` | `string` | No | Search text for auth facet (no-op for row filtering) |
| `system_search` | `string` | No | Search text for system facet (no-op for row filtering) |
| `department_search` | `string` | No | Search text for department facet (no-op for row filtering) |
| `idempotency_key` | `string` | No | Operation key for ack — confirms or rejects a dormant delete |
| `soft` | `boolean` | No | Stage the delete dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (confirm) or reject dormant state. Only meaningful with idempotency_key |

## Response (`DeleteSettingApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`DeleteSettingResult`](/api-reference/setting/types#deletesettingresult)[] | Yes | Per-item deletion results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/setting/draft`

Route: /api-reference/setting/post-setting-draft

# `POST` `/setting/draft`

Patch Setting Draft

Patch setting draft — composable infra architecture.

## Request Body (`PatchSettingDraftApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `draft_id` | `string` | No | Existing draft UUID to update |
| `input_draft_id` | `string` | No | Legacy draft UUID alias |
| `idempotency_key` | `string` | No | Operation key for accept/reject acknowledgement |
| `soft` | `boolean` | No | Stage the draft dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept or reject pending draft state when used with idempotency_key |
| `name` | `string` | No | Name value to resolve or create |
| `name_id` | `string` | No | UUID of the name resource |
| `description` | `string` | No | Description value to resolve or create |
| `description_id` | `string` | No | UUID of the description resource |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `active` | `boolean` | No | Denormalized setting_active flag state; resolved to a flag_ids entry server-side |
| `mcp` | `boolean` | No | Denormalized mcp flag state; resolved to a flag_ids entry server-side |
| `departments` | `string`[] | No | Department names to resolve |
| `department_ids` | `string`[] | No | Department UUIDs to assign |
| `color_ids` | `string`[] | No | Color resource UUIDs |
| `logins_ids` | `string`[] | No | Logins resource UUIDs to assign |
| `system_ids` | `string`[] | No | System UUIDs to assign |
| `mcp_id` | `string` | No | MCP resource UUID to assign (single) |
| `threshold_ids` | `string`[] | No | Threshold UUIDs to assign |
| `provider_key_ids` | `string`[] | No | Provider key UUIDs |
| `auth_item_key_ids` | `string`[] | No | Auth item key UUIDs |
| `auth_item_value_ids` | `string`[] | No | Auth item value UUIDs |
| `auth_ids` | `string`[] | No | Auth resource UUIDs to assign |
| `provider_ids` | `string`[] | No | Provider resource UUIDs to assign |
| `provider_keys` | [`SettingProviderKeyDraftValue`](/api-reference/setting/types#settingproviderkeydraftvalue)[] | No | Inline-creatable (provider × key) value entries; id=null requests server to resolve or create |
| `auth_item_keys` | [`SettingAuthItemKeyDraftValue`](/api-reference/setting/types#settingauthitemkeydraftvalue)[] | No | Inline-creatable (auth × key) value entries |
| `auth_item_values` | [`SettingAuthItemValueDraftValue`](/api-reference/setting/types#settingauthitemvaluedraftvalue)[] | No | Inline-creatable (auth × item × value) entries |
| `mcp_values` | [`SettingMcpDraftValue`](/api-reference/setting/types#settingmcpdraftvalue)[] | No | Inline-creatable mcp value entries |
| `system_values` | [`SettingSystemDraftValue`](/api-reference/setting/types#settingsystemdraftvalue)[] | No | Inline-creatable systems_resource value entries |
| `threshold_values` | [`SettingThresholdDraftValue`](/api-reference/setting/types#settingthresholddraftvalue)[] | No | Per-type threshold slider values; server finds or creates a row per (type, value) and swaps the matching type into threshold_ids |
| `logins` | [`SettingLoginDraftValue`](/api-reference/setting/types#settinglogindraftvalue)[] | No | Inline-creatable logins_resource value entries (auth or profile buttons) |
| `pending_ids` | `string`[] | No | Resource IDs to retain as pending inactive connections |

## Response (`PatchSettingDraftApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the draft save succeeded |
| `draft_id` | `string` | Yes | UUID of the saved draft |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |
| `message` | `string` | Yes | Result message |
| `form_state` | [`app__infra__setting__types__DraftFormState`](/api-reference/setting/types#app-infra-setting-types-draftformstate) | No | Server-authoritative form state |

---

# `POST` `/setting/drafts`

Route: /api-reference/setting/post-setting-drafts

# `POST` `/setting/drafts`

Get Setting Drafts

List setting drafts owned by the current profile.

## Request Body (`GetSettingDraftsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE substring) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GetSettingDraftsApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entries` | [`GetSettingDraftResponse`](/api-reference/setting/types#getsettingdraftresponse)[] | No | List of setting draft entries |

---

# `POST` `/setting/duplicate`

Route: /api-reference/setting/post-setting-duplicate

# `POST` `/setting/duplicate`

Duplicate Setting

Duplicate a setting — composable infra architecture.

## Request Body (`DuplicateSettingApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `setting_id` | `string` | Yes | UUID of the setting to duplicate |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant duplicate |
| `soft` | `boolean` | No | Stage the duplicate dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`DuplicateSettingApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the duplication succeeded |
| `setting_id` | `string` | Yes | UUID of the newly created setting |
| `message` | `string` | Yes | Result message |
| `settings` | [`ListSettingApiSetting`](/api-reference/setting/types#listsettingapisetting)[] | No | Hydrated list row(s) for the duplicated setting. Single-element list (kept as a list for shape consistency with create/update) so the client's ghost rail can materialize the new card directly. |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/setting/export`

Route: /api-reference/setting/post-setting-export

# `POST` `/setting/export`

Export Settings

Export all settings as a clean, denormalized CSV.

## Request Body (`ExportSettingApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `setting_id` | `string` | No | UUID of the setting to export |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior export instead of re-running |
| `soft` | `boolean` | No | Stage the export dormant (active=False); ack with accept activates it |
| `accept` | `boolean` | No | Ack: True promotes the staged export, False rejects. Only meaningful with idempotency_key |

## Response (`ExportSettingApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource holding the export CSV |
| `file_name` | `string` | Yes | Suggested download file name |
| `row_count` | `integer` | Yes | Number of data rows in the export |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with `accept` to promote/reject the staged export. |

---

# `POST` `/setting/file_download`

Route: /api-reference/setting/post-setting-file-download

# `POST` `/setting/file_download`

Download File

Download a file by file resource ID.

## Request Body (`FileDownloadSettingApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource to download |

## Response

```
{}
```

---

# `POST` `/setting/generate`

Route: /api-reference/setting/post-setting-generate

# `POST` `/setting/generate`

Generate Setting

Trigger setting generation. Returns immediately; progress via events.

## Request Body (`ArtifactGenerateRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `instructions` | `string`[] | No | — |
| `config` | [`GenerateConfig`](/api-reference/setting/types#generateconfig) | No | — |
| `modalities` | `string`[] | No | — |
| `audios_id` | `string` | No | — |
| `conversation_id` | `string` | No | — |
| `trace_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `accept` | `boolean` | No | — |
| `wait_for_complete` | `boolean` | No | — |

## Response (`ArtifactGenerateResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `run_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `eval` | [`EvalSetup`](/api-reference/setting/types#evalsetup) | No | — |
| `produced_media` | [`ProducedMedia`](/api-reference/setting/types#producedmedia)[] | No | — |

---

# `POST` `/setting/generations`

Route: /api-reference/setting/post-setting-generations

# `POST` `/setting/generations`

Generations Setting

List setting generation groups — composable infra architecture.

## Request Body (`GenerationsSettingApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GenerationsSettingApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `items` | [`GenerationsSettingListItem`](/api-reference/setting/types#generationssettinglistitem)[] | No | Generation groups |
| `total_count` | `integer` | No | Total number of matching generations |

---

# `POST` `/setting/get`

Route: /api-reference/setting/post-setting-get

# `POST` `/setting/get`

Get Setting

Get setting information using the canonical shared setting operation.

## Request Body (`GetSettingApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | UUID of the setting to retrieve |
| `setting_id` | `string` | No | Legacy setting identifier |
| `settings_id` | `string` | No | Legacy alias for setting identifier |
| `draft_id` | `string` | No | UUID of the draft to load |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |
| `names` | [`app__infra__setting__types__SectionFilter`](/api-reference/setting/types#app-infra-setting-types-sectionfilter) | No | Filter options for names |
| `descriptions` | [`app__infra__setting__types__SectionFilter`](/api-reference/setting/types#app-infra-setting-types-sectionfilter) | No | Filter options for descriptions |
| `colors` | [`app__infra__setting__types__SectionFilter`](/api-reference/setting/types#app-infra-setting-types-sectionfilter) | No | Filter options for colors |
| `flags` | [`app__infra__setting__types__SectionFilter`](/api-reference/setting/types#app-infra-setting-types-sectionfilter) | No | Filter options for flags |
| `departments` | [`app__infra__setting__types__SectionFilter`](/api-reference/setting/types#app-infra-setting-types-sectionfilter) | No | Filter options for departments |
| `logins` | [`app__infra__setting__types__SectionFilter`](/api-reference/setting/types#app-infra-setting-types-sectionfilter) | No | Filter options for logins |
| `systems` | [`app__infra__setting__types__SectionFilter`](/api-reference/setting/types#app-infra-setting-types-sectionfilter) | No | Filter options for systems |
| `mcp` | [`app__infra__setting__types__SectionFilter`](/api-reference/setting/types#app-infra-setting-types-sectionfilter) | No | Filter options for MCP configs |
| `thresholds` | [`app__infra__setting__types__SectionFilter`](/api-reference/setting/types#app-infra-setting-types-sectionfilter) | No | Filter options for thresholds |
| `provider_keys` | [`app__infra__setting__types__SectionFilter`](/api-reference/setting/types#app-infra-setting-types-sectionfilter) | No | Filter options for provider keys |
| `auth_item_keys` | [`app__infra__setting__types__SectionFilter`](/api-reference/setting/types#app-infra-setting-types-sectionfilter) | No | Filter options for auth item keys |
| `auth_item_values` | [`app__infra__setting__types__SectionFilter`](/api-reference/setting/types#app-infra-setting-types-sectionfilter) | No | Filter options for auth item values |

## Response (`GetSettingApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the acting user |
| `setting_exists` | `boolean` | No | Whether the setting exists |
| `can_edit` | `boolean` | No | Whether the actor can edit this setting |
| `disabled_reason` | `string` | No | Reason editing is disabled, if any |
| `group_id` | `string` | No | Group UUID for draft collaboration |
| `draft_name` | `string` | No | Immutable draft label from the active draft entry, when a ``draft_id`` was supplied. ``None`` for non-draft fetches. |
| `show_ai_generate` | `boolean` | No | Whether any section should show AI generate |
| `basic_show_ai_generate` | `boolean` | No | Whether the basic section should show AI generate |
| `pending_ids` | `string`[] | No | Pending resource identifiers when available |
| `names` | [`SettingNameResource`](/api-reference/setting/types#settingnameresource)[] | No | Name resources |
| `descriptions` | [`SettingDescriptionResource`](/api-reference/setting/types#settingdescriptionresource)[] | No | Description resources |
| `colors` | [`SettingColorResource`](/api-reference/setting/types#settingcolorresource)[] | No | Color resources |
| `flags` | [`SettingFlagResource`](/api-reference/setting/types#settingflagresource)[] | No | Flag resources (one per flags_resource row, value=true/false) |
| `departments` | [`SettingDepartmentResource`](/api-reference/setting/types#settingdepartmentresource)[] | No | Department resources |
| `logins` | [`SettingLoginsResource`](/api-reference/setting/types#settingloginsresource)[] | No | Logins resources |
| `systems` | [`SettingSystemResource`](/api-reference/setting/types#settingsystemresource)[] | No | System resources |
| `mcp` | [`SettingMcpResource`](/api-reference/setting/types#settingmcpresource)[] | No | MCP resources |
| `thresholds` | [`SettingThresholdResource`](/api-reference/setting/types#settingthresholdresource)[] | No | Threshold resources |
| `provider_keys` | [`SettingProviderKeyResource`](/api-reference/setting/types#settingproviderkeyresource)[] | No | Provider key resources |
| `auth_item_keys` | [`SettingAuthItemKeyResource`](/api-reference/setting/types#settingauthitemkeyresource)[] | No | Auth item key resources |
| `auth_item_values` | [`SettingAuthItemValueResource`](/api-reference/setting/types#settingauthitemvalueresource)[] | No | Auth item value resources |
| `providers` | [`SettingProviderCatalogResource`](/api-reference/setting/types#settingprovidercatalogresource)[] | No | Provider catalog used by provider key editing |
| `keys` | [`SettingKeyCatalogResource`](/api-reference/setting/types#settingkeycatalogresource)[] | No | Key catalog used by provider key and auth item key editing |
| `items` | [`SettingItemCatalogResource`](/api-reference/setting/types#settingitemcatalogresource)[] | No | Claim item catalog used by auth item key/value editing |
| `profiles` | [`SettingProfileCatalogResource`](/api-reference/setting/types#settingprofilecatalogresource)[] | No | Profile catalog used by logins editing |
| `auths` | [`SettingAuthCatalogResource`](/api-reference/setting/types#settingauthcatalogresource)[] | No | Auth catalog used by logins and auth item editing |
| `icons` | [`SettingIconCatalogResource`](/api-reference/setting/types#settingiconcatalogresource)[] | No | Icon catalog used by logins editing |
| `agents` | [`SettingAgentCatalogResource`](/api-reference/setting/types#settingagentcatalogresource)[] | No | Agent catalog used by mcp and systems editing |
| `provider_key_options` | [`SettingProviderKeyOption`](/api-reference/setting/types#settingproviderkeyoption)[] | No | Curated (provider × key) options for the ProviderKeys picker |
| `auth_item_key_options` | [`SettingAuthItemKeyOption`](/api-reference/setting/types#settingauthitemkeyoption)[] | No | Curated (auth × key) options for the AuthItemKeys picker |
| `auth_item_value_options` | [`SettingAuthItemValueOption`](/api-reference/setting/types#settingauthitemvalueoption)[] | No | Curated (auth × item) options for the AuthItemValues picker |
| `mcp_options` | [`SettingMcpOption`](/api-reference/setting/types#settingmcpoption)[] | No | Curated per-agent options for the MCP picker |
| `login_options` | [`SettingLoginOption`](/api-reference/setting/types#settingloginoption)[] | No | Curated (auth × profile) options for the Logins picker |

---

# `POST` `/setting/group`

Route: /api-reference/setting/post-setting-group

# `POST` `/setting/group`

Group Setting

Resolve or create a setting group with optional naming.

## Request Body (`GroupSettingApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | No | Existing group UUID (omit to create or reuse via time window) |
| `snapshot_key` | `string` | No | Snapshot key for SETNX-race convergence on a single group across concurrent reads (e.g. parallel /context + /group + /search fan-out on page load). Echoed back in the response. |

## Response (`GroupSettingApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Resolved or newly created group UUID |
| `name` | `string` | No | The group's current title (latest active group_names_entry, or 'New Chat' fallback for freshly minted groups) |
| `snapshot_key` | `string` | No | Snapshot key echoed back — the UUID concurrent fan-out reads converged on via SETNX. Mirrors the resolved group_id. |
| `runs` | [`GroupRun`](/api-reference/setting/types#grouprun)[] | No | Conversation history — populated when resolving an existing group for fetch |
| `group_exists` | `boolean` | No | (detail) Whether the group exists in storage — populated when ``include_resources=True`` |
| `actor_name` | `string` | No | (detail) Display name of the current actor (caller profile) |
| `total_message_count` | `integer` | No | (detail) Total number of messages in the group |
| `models` | [`GroupResource`](/api-reference/setting/types#groupresource)[] | No | (detail) Models used in the group |
| `agents` | [`GroupResource`](/api-reference/setting/types#groupresource)[] | No | (detail) Agents used in the group |
| `profiles` | [`GroupResource`](/api-reference/setting/types#groupresource)[] | No | (detail) Profiles that authored runs in this group |

---

# `POST` `/setting/problem`

Route: /api-reference/setting/post-setting-problem

# `POST` `/setting/problem`

Problem Setting

Report a setting problem — composable infra architecture.

## Request Body (`ProblemSettingApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | `string` | Yes | Problem type: feature, bug, question, other |
| `message` | `string` | Yes | Problem description (max 1000 chars) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant problem |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`ProblemSettingApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `problem_id` | `string` | Yes | UUID of the created problem |
| `success` | `boolean` | No | Whether the problem was created |
| `message` | `string` | No | Status message |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/setting/refresh`

Route: /api-reference/setting/post-setting-refresh

# `POST` `/setting/refresh`

Setting Refresh

Refresh setting materialized views and invalidate caches.

## Request Body (`RefreshSettingApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `targets` | `string`[] | No | MV targets to refresh (omit for all). Options: setting_drafts_mv |
| `idempotency_key` | `string` | No | Operation key for ack |
| `accept` | `boolean` | No | Accept or reject. Only meaningful with idempotency_key |
| `soft` | `boolean` | No | Stage the refresh as a pending (held) request — recorded but not enqueued; ack with accept releases/enqueues it |

## Response (`RefreshResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | — |
| `refreshed_views` | `string`[] | Yes | — |
| `invalidated_tags` | `string`[] | Yes | — |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/setting/search`

Route: /api-reference/setting/post-setting-search

# `POST` `/setting/search`

Search Setting

Search settings — composable infra architecture.

## Request Body (`SearchSettingApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`ListSettingApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the acting user |
| `user_role` | `string` | No | Role of the acting user |
| `settings` | [`ListSettingApiSetting`](/api-reference/setting/types#listsettingapisetting)[] | No | List of setting items |
| `keys` | [`ListSettingApiKey`](/api-reference/setting/types#listsettingapikey)[] | No | List of key items |
| `flag_filter` | [`ListFilterSection`](/api-reference/setting/types#listfiltersection) | No | Filter options for flags in list UI |
| `providers_filter` | [`ListFilterSection`](/api-reference/setting/types#listfiltersection) | No | Filter options for providers in list UI |
| `auth_filter` | [`ListFilterSection`](/api-reference/setting/types#listfiltersection) | No | Filter options for auths in list UI |
| `systems_filter` | [`ListFilterSection`](/api-reference/setting/types#listfiltersection) | No | Filter options for systems in list UI |
| `import_fields` | [`ImportField`](/api-reference/setting/types#importfield)[] | No | CSV import column schema for the bulk-import dialog |

---

# `POST` `/setting/text_download`

Route: /api-reference/setting/post-setting-text-download

# `POST` `/setting/text_download`

Download Text

Download a text file by text resource ID.

## Request Body (`TextDownloadSettingApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `text_id` | `string` | Yes | UUID of the texts_resource to download |

## Response

```
{}
```

---

# `POST` `/setting/title`

Route: /api-reference/setting/post-setting-title

# `POST` `/setting/title`

Title Setting

Rename a setting's group (writes group_names_entry).

## Request Body (`TitleSettingApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Group to rename |
| `title` | `string` | Yes | New title (display name) for the group |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant rename |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`TitleSettingApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | The group that was renamed |
| `group_name_id` | `string` | Yes | UUID of the new group_names_entry row |
| `title` | `string` | Yes | The title that was set |
| `idempotency_key` | `string` | No | Operation key echoed back |

---

# `POST` `/setting/update`

Route: /api-reference/setting/post-setting-update

# `POST` `/setting/update`

Update Setting

Update settings using composable infra architecture.

## Request Body (`UpdateSettingApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `settings` | [`UpdateSettingItem`](/api-reference/setting/types#updatesettingitem)[] | No | List of settings to update (required on first call when ``all`` is false) |
| `all` | `boolean` | No | When true, apply ``patch`` to every setting matching the filter fields below (minus ``excluded_ids``) |
| `excluded_ids` | `string`[] | No | UUIDs to skip even when matched by ``all``-mode filters |
| `patch` | [`UpdateSettingPatch`](/api-reference/setting/types#updatesettingpatch) | No | Shared change set applied to every matched row when ``all=true`` (sparse — only set fields are updated; ``patch.id`` ignored) |
| `search` | `string` | No | Full-text search query |
| `flag_ids` | `string`[] | No | Filter by flag UUIDs |
| `provider_ids` | `string`[] | No | Filter by provider UUIDs |
| `auth_ids` | `string`[] | No | Filter by auth UUIDs |
| `system_ids` | `string`[] | No | Filter by system UUIDs |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `flag_search` | `string` | No | Search text for flag facet (no-op for row filtering) |
| `provider_search` | `string` | No | Search text for provider facet (no-op for row filtering) |
| `auth_search` | `string` | No | Search text for auth facet (no-op for row filtering) |
| `system_search` | `string` | No | Search text for system facet (no-op for row filtering) |
| `department_search` | `string` | No | Search text for department facet (no-op for row filtering) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant update |
| `soft` | `boolean` | No | Stage the update dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`UpdateSettingApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`SettingResultItem`](/api-reference/setting/types#settingresultitem)[] | Yes | Per-item update results |
| `settings` | [`ListSettingApiSetting`](/api-reference/setting/types#listsettingapisetting)[] | No | Hydrated list rows for the updated settings. Mirrors the shape of ``/setting/search`` result rows so the client's ghost rail can swap the live card without a refresh. |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/setting/watch`

Route: /api-reference/setting/post-setting-watch

# `POST` `/setting/watch`

Setting Watch Once

One-shot snapshot of run state, snapshot-replayable via ``snapshot_key``.

## Request Body (`WatchApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Chat group whose events we watch |
| `run_id` | `string` | No | Specific run to watch (e.g. the ``run_id`` returned by a prior ``X_Generate`` call). If None, watches every active run in the group at call time. |
| `wait_for_complete` | `boolean` | No | If True, block until the watched run reaches a terminal (complete/failed) event or timeout fires. If False, return current state and exit immediately. |
| `timeout_seconds` | `integer` | No | Max wait time when ``wait_for_complete=True``. |
| `snapshot_key` | `string` | No | Read snapshot key — on the one-shot POST /watch, the audit wrapper records this watch's point-in-time view (latest run state at call time) keyed by it and replays the same view on any later call with the same key. Ignored by the SSE GET stream. |

## Response (`WatchApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `runs` | [`RunStatus`](/api-reference/setting/types#runstatus)[] | Yes | — |
| `timed_out` | `boolean` | No | — |
| `waited_seconds` | `number` | No | — |

---

# Setting Types

Route: /api-reference/setting/types

# Setting Types

## `CallerPermissions`

Evaluated permissions for the current caller on this artifact type.

| Field | Type | Required | Description |
|---|---|---|---|
| `can_create` | `boolean` | Yes | Whether the caller can create new artifacts |
| `can_draft` | `boolean` | Yes | Whether the caller can create/update drafts |
| `can_duplicate` | `boolean` | Yes | Whether the caller can duplicate artifacts |
| `has_access` | `boolean` | No | Whether the caller can view this entity |
| `can_edit` | `boolean` | No | Whether the caller can edit this entity |
| `can_delete` | `boolean` | No | Whether the caller can delete this entity |
| `disabled_reason` | `string` | No | Human-readable reason if editing is disabled |

---

## `ColumnInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Column name |
| `type` | `string` | Yes | Column data type |
| `nullable` | `boolean` | Yes | Whether the column is nullable |

---

## `CreateSettingItem`

Single setting item for create — no setting_id.

Required fields (name): provide ID or value.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Optional preset UUID for the new setting artifact |
| `resource_id` | `string` | No | Optional preset UUID for the settings_resource snapshot |
| `name_id` | `string` | No | REQUIRED FOR CREATE (or pass `name`). UUID of an existing name resource |
| `name` | `string` | No | REQUIRED FOR CREATE (or pass `name_id`). Name value to resolve or create |
| `description_id` | `string` | No | UUID of the description resource |
| `description` | `string` | No | Description value to resolve or create |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `active_flag_id` | `string` | No | DEPRECATED — use flag_ids. UUID of the active flag option |
| `active_flag` | `boolean` | No | DEPRECATED — use flag_ids. Whether the setting is active |
| `department_ids` | `string`[] | No | Department UUIDs to assign |
| `departments` | `string`[] | No | Department names to resolve |
| `color_ids` | `string`[] | No | Color resource UUIDs |
| `logins_ids` | `string`[] | No | Logins resource UUIDs to assign |
| `system_ids` | `string`[] | No | System UUIDs to assign |
| `mcp_id` | `string` | No | MCP resource UUID to assign (single) |
| `threshold_ids` | `string`[] | No | Threshold UUIDs to assign |
| `provider_key_ids` | `string`[] | No | Provider key UUIDs |
| `auth_item_key_ids` | `string`[] | No | Auth item key UUIDs |
| `auth_item_value_ids` | `string`[] | No | Auth item value UUIDs |
| `auth_ids` | `string`[] | No | Auth resource UUIDs to assign |
| `provider_ids` | `string`[] | No | Provider resource UUIDs to assign |
| `setting_resource_ids` | `string`[] | No | Setting resource UUIDs |

---

## `DeleteSettingResult`

Per-item result within a bulk delete response.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the deletion succeeded |
| `setting_id` | `string` | No | UUID of the deleted setting (None when soft-skipped due to not-found) |
| `message` | `string` | Yes | Result message |

---

## `DocsApiResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `list` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `detail` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `new` | [`PageMetaItem`](#pagemetaitem) | Yes | — |

---

## `DocsResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Resource or entry name |
| `type` | `string` | Yes | Resource or entry type identifier |
| `description` | `string` | Yes | Human-readable description |
| `materialized_view` | [`MvInfo`](#mvinfo) | No | Materialized view metadata |
| `tables` | [`TableInfo`](#tableinfo)[] | Yes | Related database tables |
| `operations` | [`OperationInfo`](#operationinfo)[] | Yes | Available operations |

---

## `EvalSetup`

Run-level eval scaffold — first-class on the generate response.

Audit's ``**output`` spread carries this onto
``<artifact>.generate.completed``. Null when no rubric-bearing
agent participated.

| Field | Type | Required | Description |
|---|---|---|---|
| `test_id` | `string` | Yes | — |
| `invocations` | [`InvocationSlot`](#invocationslot)[] | Yes | — |

---

## `GenerateConfig`

Developer configuration — all optional with sensible defaults.

| Field | Type | Required | Description |
|---|---|---|---|
| `operations` | `string`[] | No | — |
| `dangerous` | `boolean` | No | — |
| `params` | `object` | No | — |
| `group_id` | `string` | No | — |

---

## `GenerationsSettingListItem`

Single generation group in the setting generations response.

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | UUID of the generation group |
| `session_id` | `string` | No | UUID of the parent session |
| `group_name` | `string` | No | Name of the generation group |
| `created_at` | `string` | No | Timestamp of the generation |

---

## `GetSettingDraftResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | UUID of the draft |
| `created_at` | `string` | Yes | Creation timestamp |
| `generated` | `boolean` | Yes | Whether this was AI-generated |
| `mcp` | `boolean` | Yes | Whether MCP tooling was used |
| `active` | `boolean` | Yes | Whether this draft is active |
| `session_id` | `string` | Yes | Associated session UUID |
| `name` | `string` | No | Immutable draft label set at create time |
| `system_ids` | `string`[] | Yes | Associated system UUIDs |
| `auth_item_key_ids` | `string`[] | Yes | Associated auth item key UUIDs |
| `auth_ids` | `string`[] | Yes | Associated auth UUIDs |
| `color_ids` | `string`[] | Yes | Associated color UUIDs |
| `department_ids` | `string`[] | Yes | Associated department UUIDs |
| `description_ids` | `string`[] | Yes | Associated description UUIDs |
| `flag_ids` | `string`[] | Yes | Associated flag UUIDs |
| `item_ids` | `string`[] | Yes | Associated item UUIDs |
| `name_ids` | `string`[] | Yes | Associated name UUIDs |
| `provider_ids` | `string`[] | Yes | Associated provider UUIDs |
| `provider_key_ids` | `string`[] | Yes | Associated provider key UUIDs |
| `threshold_ids` | `string`[] | Yes | Associated threshold UUIDs |
| `mcp_ids` | `string`[] | No | — |
| `logins_ids` | `string`[] | No | — |
| `pending_system_ids` | `string`[] | No | Pending system UUIDs |
| `pending_auth_item_key_ids` | `string`[] | No | Pending auth item key UUIDs |
| `pending_auth_ids` | `string`[] | No | Pending auth UUIDs |
| `pending_color_ids` | `string`[] | No | Pending color UUIDs |
| `pending_department_ids` | `string`[] | No | Pending department UUIDs |
| `pending_description_ids` | `string`[] | No | Pending description UUIDs |
| `pending_flag_ids` | `string`[] | No | Pending flag UUIDs |
| `pending_item_ids` | `string`[] | No | Pending item UUIDs |
| `pending_name_ids` | `string`[] | No | Pending name UUIDs |
| `pending_provider_ids` | `string`[] | No | Pending provider UUIDs |
| `pending_provider_key_ids` | `string`[] | No | Pending provider key UUIDs |
| `pending_threshold_ids` | `string`[] | No | Pending threshold UUIDs |
| `pending_mcp_ids` | `string`[] | No | — |
| `pending_logins_ids` | `string`[] | No | — |

---

## `GroupCall`

Tool call referenced by a message.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `tool_name` | `string` | No | — |
| `template_name` | `string` | No | — |
| `tool` | `object` | No | — |
| `ledger_status` | `string` | No | — |
| `ledger_operation` | `string` | No | — |
| `ledger_artifact` | `string` | No | — |
| `ledger_artifact_id` | `string` | No | — |

---

## `GroupMessage`

Message within a run.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `role` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `text_ids` | `string`[] | No | — |
| `audio_ids` | `string`[] | No | — |
| `image_ids` | `string`[] | No | — |
| `video_ids` | `string`[] | No | — |
| `file_ids` | `string`[] | No | — |
| `call_ids` | `string`[] | No | — |
| `calls` | [`GroupCall`](#groupcall)[] | No | — |
| `reasoning` | `boolean` | No | True when this row is a chain-of-thought trace persisted alongside the assistant answer (rendered as a collapsed accordion). |
| `in_context` | `boolean` | No | Whether this message is included in the LLM context for the next generation. Mirrors the dedup pass that builds chat history (see in_context_reason). |
| `in_context_reason` | `string` | No | Why this message is in/out of LLM context. 'kept' = included; 'deduped_read' = older read-only call to a tool that has a fresher result later in the group; future values may include 'trimmed_top_n'. |

---

## `GroupResource`

Lightweight `\{id, name\}` for cross-referencing run-level ids
(``model_id`` / ``agent_id`` / ``profile_id``) against human-readable
names on the analytics panel. Names come from the canonical
``get_models`` / ``get_agents`` / ``get_profiles`` black boxes.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `name` | `string` | No | — |

---

## `GroupRun`

Run within a group, with its messages.

Carries token / cost / model / agent / profile attribution so the
analytics view can render per-run cost + actor info without a
parallel detail shape. ``profile_id`` is the authoring profile
(human user), ``agent_id`` is the LLM-side actor, ``model_id`` is
the model used by that agent. All optional — runs predating these
columns or with unresolved attributions surface ``None``.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `input_tokens` | `integer` | No | — |
| `output_tokens` | `integer` | No | — |
| `cached_input_tokens` | `integer` | No | — |
| `cost` | `number` | No | — |
| `model_id` | `string` | No | — |
| `agent_id` | `string` | No | — |
| `profile_id` | `string` | No | — |
| `previous_context_start_index` | `integer` | No | Index in ``messages`` where the current run's own messages begin; earlier rows are previous-context replay. ``None`` when the run has no previous context attached. |
| `messages` | [`GroupMessage`](#groupmessage)[] | No | — |

---

## `ImportField`

Field descriptor for CSV import column mapping.

| Field | Type | Required | Description |
|---|---|---|---|
| `key` | `string` | Yes | — |
| `label` | `string` | Yes | — |
| `required` | `boolean` | No | — |
| `multi` | `boolean` | No | — |
| `type` | `string` | No | — |
| `example` | `string` | No | — |
| `description` | `string` | No | — |

---

## `InvocationSlot`

One agent's slot in a multi-agent generation pool.

Populated by ``setup_generation_test`` when an agent carries a
rubric. The client uses these IDs to drive the eval workflow:
review the candidate's output, optionally fire a grader against
its ``invocation_id``, and promote/reject by call_id via the
existing ``idempotency_key + accept`` pattern.

| Field | Type | Required | Description |
|---|---|---|---|
| `invocation_id` | `string` | Yes | — |
| `agent_id` | `string` | Yes | — |
| `rubric_id` | `string` | No | — |

---

## `ListFilterOption`

Standardized option for list endpoint filter sections.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier for this filter option |
| `name` | `string` | No | Display name |
| `count` | `integer` | No | Number of matching records |
| `hex_code` | `string` | No | Hex color code for display |
| `value` | `string` | No | Internal value |
| `type` | `string` | No | Option type discriminator |

---

## `ListFilterSection`

Filter section with options and echoed request state.

| Field | Type | Required | Description |
|---|---|---|---|
| `options` | [`ListFilterOption`](#listfilteroption)[] | No | Available filter options |
| `selected_ids` | `string`[] | No | Currently selected filter option IDs |
| `search` | `string` | No | Active search text for filtering |

---

## `ListSettingApiKey`

Key type for list endpoint.

| Field | Type | Required | Description |
|---|---|---|---|
| `key_id` | `string` | No | Unique key identifier |
| `name` | `string` | No | Key display name |
| `key_masked` | `string` | No | Masked key value for display |
| `description` | `string` | No | Key description text |
| `active` | `boolean` | No | Whether the key is currently active |
| `department_ids` | `string`[] | No | Associated department IDs |

---

## `ListSettingApiSetting`

Setting type for list endpoint with computed permissions.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Setting artifact UUID (canonical id; mirrors settings_id) |
| `settings_id` | `string` | No | Unique setting identifier |
| `created_at` | `string` | No | Timestamp when setting was created |
| `active` | `boolean` | No | Whether the setting is currently active |
| `is_inactive` | `boolean` | No | Whether the setting is inactive |
| `name` | `string` | No | Setting display name |
| `description` | `string` | No | Setting description text |
| `department_ids` | `string`[] | No | Associated department IDs |
| `provider_ids` | `string`[] | No | Provider resource UUIDs assigned to this setting |
| `auth_ids` | `string`[] | No | Auth resource UUIDs assigned to this setting |
| `system_ids` | `string`[] | No | System resource UUIDs assigned to this setting |
| `can_edit` | `boolean` | No | Whether the actor can edit this setting |
| `can_delete` | `boolean` | No | Whether the actor can delete this setting |
| `can_duplicate` | `boolean` | No | Whether the actor can duplicate this setting |
| `pending_status` | `string` | No | Latest soft_calls_mv status: 'pending' / 'accepted' / 'rejected' |
| `pending_operation` | `string` | No | Operation type ('create'|'update'|'delete'|'duplicate') of the pending op |
| `pending_call_id` | `string` | No | call_id (idempotency key for ack) of the pending op |

---

## `MvInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Materialized view name |
| `definition` | `string` | Yes | SQL definition of the view |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the view |

---

## `OperationInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Operation name |
| `description` | `string` | Yes | Human-readable description of the operation |
| `params` | [`ParamInfo`](#paraminfo)[] | Yes | List of operation parameters |
| `returns` | `object` | No | Return type schema |

---

## `OperationPrompts`

Starter prompts keyed by operation name.

Each key is an operation (e.g. "create", "search", "draft", "export")
and the value is a list of starter prompts for that operation.
The client picks from the operations the caller has permission for
and rotates through them.

| Field | Type | Required | Description |
|---|---|---|---|
| `prompts` | `object` | No | Map of operation name to starter prompts |

---

## `PageMetaItem`

| Field | Type | Required | Description |
|---|---|---|---|
| `title` | `string` | Yes | — |
| `description` | `string` | Yes | — |

---

## `ParamInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Parameter name |
| `type` | `string` | Yes | Parameter data type |
| `required` | `boolean` | Yes | Whether the parameter is required |
| `default` | `any` | No | Default value if not required |

---

## `ProducedMedia`

One asset produced by a generation run.

``resource_id`` is the canonical id the per-artifact download tools
accept (e.g. ``Scenario_Image_Download(image_id=resource_id)`` for
``modality="image"``). It maps to ``images_resource.id`` /
``videos_resource.id`` / ``audios_resource.id`` depending on the
modality.

| Field | Type | Required | Description |
|---|---|---|---|
| `modality` | `"image"` \| `"video"` \| `"audio"` | Yes | — |
| `resource_id` | `string` | Yes | — |
| `upload_id` | `string` | Yes | — |
| `mime_type` | `string` | No | — |
| `file_size` | `integer` | No | — |

---

## `ProfileSummary`

Caller identity derived from JWT — who you are on this page.

Superset of the old six-field version: now carries everything the client
needs so that ``/\{artifact\}/context`` fully replaces ``/profiles/context``
and the extra ``getLayoutContextData`` round-trip can be dropped.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Display name of the authenticated user |
| `role` | `string` | Yes | Role name (e.g. 'Super Administrator') |
| `role_level` | `integer` | Yes | Role hierarchy level (0 = highest privilege) |
| `department_ids` | `string`[] | Yes | Departments the user belongs to |
| `artifact_access` | `string`[] | Yes | Artifact types this role can access (sidebar visibility) |
| `role_permissions` | `any`[][] | Yes | Full (artifact, operation) permission tuples for granular page gating |
| `is_active` | `boolean` | Yes | Whether the user's profile is active |
| `id` | `string` | Yes | Profile UUID (SocketProvider, ProfileProvider) |
| `theme` | [`ThemeBundle`](#themebundle) | No | Resolved theme: hex primitives + derived oklch tokens + score thresholds |
| `session_id` | `string` | No | Current session UUID |
| `is_emulation` | `boolean` | No | Whether user is in emulation mode (ProfileProvider) |
| `role_resources` | [`QGetProfileContextV4RoleResource`](#qgetprofilecontextv4roleresource)[] | No | All role resources for emulation display (ProfileProvider) |
| `scoped_roles` | `string`[] | No | Roles the user can emulate (ProfileProvider) |
| `active` | `boolean` | No | Alias for is_active (ProfileProvider uses this name) |

---

## `QGetProfileContextV4RoleResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `role` | `string` | No | — |
| `name` | `string` | No | — |
| `description` | `string` | No | — |
| `icon_value` | `string` | No | — |
| `color_hex` | `string` | No | — |

---

## `RunStatus`

Outcome of one watched run.

| Field | Type | Required | Description |
|---|---|---|---|
| `run_id` | `string` | Yes | — |
| `status` | `"pending"` \| `"completed"` \| `"failed"` | Yes | — |
| `modality` | `string` | No | Modality of generated output (image, video, text…) |
| `resource_ids` | `string`[] | No | Resource UUIDs produced by this run (e.g. images_resource ids) |
| `error` | `string` | No | — |

---

## `SettingAgentCatalogResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `agent_id` | `string` | No | Agent identifier |
| `name` | `string` | No | Agent display name |
| `description` | `string` | No | Agent description |

---

## `SettingAuthCatalogResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Auth provider identifier (canonical for picker selection) |
| `auth_id` | `string` | No | Auth provider identifier (alias for id) |
| `name` | `string` | No | Auth display name |
| `description` | `string` | No | Auth description |
| `slug` | `string` | No | Auth slug |
| `protocol` | `string` | No | Auth protocol |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `SettingAuthItemKeyDraftValue`

Draft value object for an inline-creatable (auth × item × key) triple.

Same two flows as SettingProviderKeyDraftValue: server encrypts
`key_value` and creates a fresh `keys_resource` row when supplied.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Existing auth_item_keys_resource id when known |
| `auth_id` | `string` | Yes | Auth provider identifier |
| `item_id` | `string` | Yes | Claim item identifier |
| `key_id` | `string` | No | Existing keys_resource id (optional when key_value provided) |
| `key_value` | `string` | No | Plaintext key/secret. Server encrypts and creates a keys_resource row. |
| `key_name` | `string` | No | Optional display name for the new keys_resource row |

---

## `SettingAuthItemKeyOption`

Server-curated (auth × item × key) catalog option for the AuthItemKeys picker.

| Field | Type | Required | Description |
|---|---|---|---|
| `auth_id` | `string` | No | Auth provider identifier |
| `item_id` | `string` | No | Claim item identifier |
| `key_id` | `string` | No | Key identifier |
| `auth_name` | `string` | No | Auth display name |
| `item_name` | `string` | No | Claim item display name |
| `key_name` | `string` | No | Key display name |
| `masked_key` | `string` | No | Masked key value for display |

---

## `SettingAuthItemKeyResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Auth item key identifier |
| `auth_id` | `string` | No | Auth identifier |
| `item_id` | `string` | No | Item identifier |
| `key_id` | `string` | No | Key identifier |
| `generated` | `boolean` | No | Whether the auth-item-key pair was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `SettingAuthItemValueDraftValue`

Draft value object for an inline-creatable (auth × item × value) triple.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Existing auth_item_values_resource id when known |
| `auth_id` | `string` | Yes | Auth provider identifier |
| `item_id` | `string` | Yes | Claim item identifier |
| `value` | `string` | Yes | Literal claim value |

---

## `SettingAuthItemValueOption`

Server-curated (auth × item) catalog option for the AuthItemValues picker.

| Field | Type | Required | Description |
|---|---|---|---|
| `auth_id` | `string` | No | Auth provider identifier |
| `item_id` | `string` | No | Claim item identifier |
| `auth_name` | `string` | No | Auth display name |
| `item_name` | `string` | No | Claim item display name |
| `item_description` | `string` | No | Claim item description |
| `encrypted` | `boolean` | No | Whether the value must be stored encrypted |

---

## `SettingAuthItemValueResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Auth item value identifier |
| `auth_id` | `string` | No | Auth provider identifier |
| `item_id` | `string` | No | Claim item identifier |
| `value` | `string` | No | Literal claim value |
| `generated` | `boolean` | No | Whether the value was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `SettingColorResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Color resource identifier |
| `name` | `string` | No | Color display name |
| `description` | `string` | No | Color description |
| `hex_code` | `string` | No | Hex color value |
| `type` | `string` | No | Color role — 'primary', 'secondary', 'accent', etc. |
| `generated` | `boolean` | No | Whether the color was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `SettingDepartmentResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `department_id` | `string` | No | Department identifier |
| `name` | `string` | No | Department name |
| `description` | `string` | No | Department description |
| `generated` | `boolean` | No | Whether the department was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `SettingDescriptionResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Description resource identifier |
| `description` | `string` | No | Setting description |
| `generated` | `boolean` | No | Whether the description was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `SettingFieldError`

Per-field error from value resolution.

| Field | Type | Required | Description |
|---|---|---|---|
| `field` | `string` | Yes | Name of the field that failed validation |
| `message` | `string` | Yes | Validation error message |

---

## `SettingFlagResource`

Flag option row — one per (name, type, value) entry in flags_resource.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Flag resource identifier |
| `name` | `string` | No | Flag display name |
| `type` | `string` | No | Flag type (e.g. 'setting_active', 'mcp') |
| `value` | `boolean` | No | Underlying bool value of this option |
| `description` | `string` | No | Flag description text |
| `icon_id` | `string` | No | Icon identifier for the flag |
| `icon` | `string` | No | Resolved SVG markup (hydrated from icons_resource) |
| `generated` | `boolean` | No | Whether the flag was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `SettingIconCatalogResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `icon_id` | `string` | No | Icon identifier |
| `name` | `string` | No | Icon display name |
| `description` | `string` | No | Icon description |
| `value` | `string` | No | Icon value (SVG markup or slug) |

---

## `SettingItemCatalogResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `item_id` | `string` | No | Claim item identifier |
| `name` | `string` | No | Claim item display name (e.g. clientId) |
| `description` | `string` | No | Claim item description |
| `encrypted` | `boolean` | No | Whether the item value must be stored encrypted |
| `position` | `integer` | No | Display ordering position |

---

## `SettingKeyCatalogResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `key_id` | `string` | No | Key identifier |
| `name` | `string` | No | Key display name |
| `description` | `string` | No | Key description |
| `masked_key` | `string` | No | Masked key value for display |

---

## `SettingLoginDraftValue`

Draft value object for an inline-creatable logins_resource row.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Existing logins_resource id when known |
| `login_type` | `string` | Yes | 'auth' or 'profile' |
| `auth_id` | `string` | No | Auth id — required when login_type='auth' |
| `profile_id` | `string` | No | Profile id — required when login_type='profile' |
| `display_name` | `string` | No | Override label; falls back to Auth/Profile catalog name |
| `icon_id` | `string` | No | Override icon; falls back to defaults |

---

## `SettingLoginOption`

Server-curated catalog option for the Logins picker.

| Field | Type | Required | Description |
|---|---|---|---|
| `login_type` | `string` | No | 'auth' or 'profile' |
| `auth_id` | `string` | No | Auth identifier for login_type='auth' |
| `profile_id` | `string` | No | Profile identifier for login_type='profile' |
| `display_name` | `string` | No | Default button label |
| `icon_id` | `string` | No | Default icon (when Auth or Profile catalog provides one) |
| `icon` | `string` | No | Resolved SVG markup for the icon (when available) |

---

## `SettingLoginsResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `logins_id` | `string` | No | Logins resource identifier |
| `profile_id` | `string` | No | Profile for test login |
| `auth_id` | `string` | No | Auth provider for OIDC login |
| `icon_id` | `string` | No | Icon for login button |
| `icon` | `string` | No | Resolved SVG markup for the icon (hydrated from icons_resource) |
| `display_name` | `string` | No | Display text for login button |
| `login_type` | `string` | No | Login type: 'auth' or 'profile' |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `SettingMcpDraftValue`

Draft value object for an inline-creatable mcp row.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Existing mcp_resource id when known |
| `agent_id` | `string` | Yes | Agent identifier |
| `name` | `string` | No | Optional display name — defaults to agent.name |
| `description` | `string` | No | Optional description |

---

## `SettingMcpOption`

Server-curated per-agent catalog option for the MCP picker.

| Field | Type | Required | Description |
|---|---|---|---|
| `agent_id` | `string` | No | Agent identifier |
| `agent_name` | `string` | No | Agent display name |
| `agent_description` | `string` | No | Agent description |

---

## `SettingMcpResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `mcp_id` | `string` | No | MCP resource identifier |
| `agent_id` | `string` | No | Agent providing MCP tools |
| `name` | `string` | No | MCP config display name |
| `description` | `string` | No | MCP config description |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `SettingNameResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Name resource identifier |
| `name` | `string` | No | Setting display name |
| `generated` | `boolean` | No | Whether the name was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `SettingProfileCatalogResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `profile_id` | `string` | No | Profile identifier |
| `name` | `string` | No | Profile display name |
| `description` | `string` | No | Profile description |

---

## `SettingProviderCatalogResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Provider identifier (canonical for picker selection) |
| `provider_id` | `string` | No | Provider identifier (alias for id) |
| `name` | `string` | No | Provider display name |
| `description` | `string` | No | Provider description |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `SettingProviderKeyDraftValue`

Draft value object for an inline-creatable (provider × key) pair.

Two flows:
- Create-by-value: caller supplies `key_value` (and optional `key_name`).
  Server encrypts it, creates a fresh `keys_resource` row, and links a
  `provider_keys_resource` row for (provider_id, new_key_id).
- Re-link existing: caller supplies `key_id` referencing an existing
  `keys_resource` row. Server upserts the junction.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Existing provider_keys_resource id when known |
| `provider_id` | `string` | Yes | Provider identifier |
| `key_id` | `string` | No | Existing keys_resource id (optional when key_value provided) |
| `key_value` | `string` | No | Plaintext API key. Server encrypts and creates a keys_resource row. |
| `key_name` | `string` | No | Optional display name for the new keys_resource row |

---

## `SettingProviderKeyOption`

Server-curated (provider × key) catalog option for the ProviderKeys picker.

| Field | Type | Required | Description |
|---|---|---|---|
| `provider_id` | `string` | No | Provider identifier |
| `key_id` | `string` | No | Key identifier |
| `provider_name` | `string` | No | Provider display name |
| `key_name` | `string` | No | Key display name |
| `masked_key` | `string` | No | Masked key value for display |

---

## `SettingProviderKeyResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Provider key identifier |
| `provider_id` | `string` | No | Provider identifier |
| `key_id` | `string` | No | Key identifier |
| `key` | `string` | No | Key value |
| `name` | `string` | No | Key display name |
| `description` | `string` | No | Key description |
| `generated` | `boolean` | No | Whether the provider-key pair was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `SettingResultItem`

Per-item result within a bulk create/update response.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `setting_id` | `string` | No | UUID of the created or updated setting |
| `message` | `string` | Yes | Result message |
| `errors` | [`SettingFieldError`](#settingfielderror)[] | No | Per-field validation errors |

---

## `SettingSystemDraftValue`

Draft value object for an inline-creatable systems_resource row.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Existing systems_resource id when known |
| `name` | `string` | Yes | System display name |
| `description` | `string` | No | Optional description |
| `agent_ids` | `string`[] | No | Agents that this system routes to |

---

## `SettingSystemResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `system_id` | `string` | No | System identifier |
| `name` | `string` | No | System display name |
| `description` | `string` | No | System description |
| `agent_ids` | `string`[] | No | Linked agent identifiers |
| `generated` | `boolean` | No | Whether the system was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `SettingThresholdDraftValue`

Draft value object for a per-type threshold slider.

Server resolver finds an existing thresholds_resource row matching
(type, value) or creates one if none exists, then merges the id
into request.threshold_ids (dropping any prior id of the same type
so each type keeps exactly one assignment).

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Existing thresholds_resource id when known |
| `type` | `string` | Yes | Threshold type — e.g. 'success', 'warning', 'danger' |
| `value` | `integer` | Yes | Integer threshold value (0–100) |

---

## `SettingThresholdResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Threshold resource identifier |
| `type` | `string` | No | Threshold type (e.g. 'success') |
| `value` | `integer` | No | Threshold integer value |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `TableInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Table name |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the table |

---

## `ThemeBundle`

Full theme payload for a page bootstrap.

Riding along on every ``/\{artifact\}/context`` response via
``ProfileSummary.theme``. Layers:
  - ``primitives`` / ``dark_primitives`` — hex inputs the settings
    editor reads/writes (light + dark palettes).
  - ``tokens`` / ``dark_tokens`` — oklch tokens the client paints with.
    ``ThemeStyle`` emits two ``<style>`` blocks: one scoped to
    ``:root:not(.dark)`` (light) and one to ``:root.dark`` (dark).
  - ``thresholds`` — numeric score thresholds for analytics components.
Empty-in → empty-out per token: missing values fall through to the
matching ``globals.css`` default.

| Field | Type | Required | Description |
|---|---|---|---|
| `primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (light palette, for the theme editor) |
| `tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for light mode (SSR CSS-var injection) |
| `dark_primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (dark palette, for the theme editor) |
| `dark_tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for dark mode (SSR CSS-var injection) |
| `thresholds` | [`Thresholds`](#thresholds) | No | Score thresholds resolved from the setting |

---

## `ThemePrimitives`

40 optional fields. The 17 essentials drive the rest; the other 23
are overrides for fine-tuning when derivation isn't what you want.

Empty primitive → empty token → client falls back to globals.css.

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `primary` | `string` | No | — |
| `accent` | `string` | No | — |
| `card` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `ring` | `string` | No | — |
| `border` | `string` | No | — |
| `destructive` | `string` | No | — |
| `success` | `string` | No | — |
| `warning` | `string` | No | — |
| `info` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `input` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `ThemeTokens`

40 fully-resolved CSS variable values (snake_case 1:1 with vars).

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `accent` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `border` | `string` | No | — |
| `input` | `string` | No | — |
| `ring` | `string` | No | — |
| `success` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `Thresholds`

Numeric score thresholds resolved from the active setting.

Server pre-buckets dashboard metrics into ``success | warning | danger |
neutral`` already, so most components don't need these values. Surface
them for chart reference lines, tooltips, and any client-side bucketing.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `integer` | Yes | Score >= this counts as success |
| `warning` | `integer` | Yes | Score >= this counts as warning |
| `danger` | `integer` | Yes | Score < success threshold but >= this counts as danger; below is neutral/no-data |

---

## `UpdateSettingItem`

Single setting item for update — setting_id required, all fields optional.

Only provided fields are updated (partial update).

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | UUID of the setting to update |
| `name_id` | `string` | No | UUID of the name resource |
| `name` | `string` | No | Name value to resolve or create |
| `description_id` | `string` | No | UUID of the description resource |
| `description` | `string` | No | Description value to resolve or create |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `active_flag_id` | `string` | No | DEPRECATED — use flag_ids. UUID of the active flag option |
| `active_flag` | `boolean` | No | DEPRECATED — use flag_ids. Whether the setting is active |
| `department_ids` | `string`[] | No | Department UUIDs to assign |
| `departments` | `string`[] | No | Department names to resolve |
| `color_ids` | `string`[] | No | Color resource UUIDs |
| `logins_ids` | `string`[] | No | Logins resource UUIDs to assign |
| `system_ids` | `string`[] | No | System UUIDs to assign |
| `mcp_id` | `string` | No | MCP resource UUID to assign (single) |
| `threshold_ids` | `string`[] | No | Threshold UUIDs to assign |
| `provider_key_ids` | `string`[] | No | Provider key UUIDs |
| `auth_item_key_ids` | `string`[] | No | Auth item key UUIDs |
| `auth_item_value_ids` | `string`[] | No | Auth item value UUIDs |
| `auth_ids` | `string`[] | No | Auth resource UUIDs to assign |
| `provider_ids` | `string`[] | No | Provider resource UUIDs to assign |
| `setting_resource_ids` | `string`[] | No | Setting resource UUIDs |

---

## `UpdateSettingPatch`

Shared patch for bulk-update-all-matching mode.

Inherits every field from ``UpdateSettingItem`` and just relaxes
``id`` to optional — the bulk impl stamps the resolved id onto a
clone of the patch per matched row, so any client-supplied id is
ignored. Sparse semantics: only fields the client sets are written.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Ignored — bulk impl stamps the resolved setting id per matched row |
| `name_id` | `string` | No | UUID of the name resource |
| `name` | `string` | No | Name value to resolve or create |
| `description_id` | `string` | No | UUID of the description resource |
| `description` | `string` | No | Description value to resolve or create |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `active_flag_id` | `string` | No | DEPRECATED — use flag_ids. UUID of the active flag option |
| `active_flag` | `boolean` | No | DEPRECATED — use flag_ids. Whether the setting is active |
| `department_ids` | `string`[] | No | Department UUIDs to assign |
| `departments` | `string`[] | No | Department names to resolve |
| `color_ids` | `string`[] | No | Color resource UUIDs |
| `logins_ids` | `string`[] | No | Logins resource UUIDs to assign |
| `system_ids` | `string`[] | No | System UUIDs to assign |
| `mcp_id` | `string` | No | MCP resource UUID to assign (single) |
| `threshold_ids` | `string`[] | No | Threshold UUIDs to assign |
| `provider_key_ids` | `string`[] | No | Provider key UUIDs |
| `auth_item_key_ids` | `string`[] | No | Auth item key UUIDs |
| `auth_item_value_ids` | `string`[] | No | Auth item value UUIDs |
| `auth_ids` | `string`[] | No | Auth resource UUIDs to assign |
| `provider_ids` | `string`[] | No | Provider resource UUIDs to assign |
| `setting_resource_ids` | `string`[] | No | Setting resource UUIDs |

---

## `app__infra__setting__types__DraftFormState`

| Field | Type | Required | Description |
|---|---|---|---|
| `name_id` | `string` | No | Resolved name resource UUID |
| `name` | `string` | No | Echoed name value when available |
| `description_id` | `string` | No | Resolved description resource UUID |
| `description` | `string` | No | Echoed description value when available |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs |
| `active` | `boolean` | No | Echoed setting_active flag state |
| `mcp` | `boolean` | No | Echoed mcp flag state |
| `department_ids` | `string`[] | No | Assigned department UUIDs |
| `color_ids` | `string`[] | No | Assigned color UUIDs |
| `logins_ids` | `string`[] | No | Assigned logins resource UUIDs |
| `system_ids` | `string`[] | No | Assigned system UUIDs |
| `mcp_id` | `string` | No | Assigned MCP resource UUID |
| `threshold_ids` | `string`[] | No | Assigned threshold UUIDs |
| `provider_key_ids` | `string`[] | No | Assigned provider key UUIDs |
| `auth_item_key_ids` | `string`[] | No | Assigned auth item key UUIDs |
| `auth_item_value_ids` | `string`[] | No | Assigned auth item value UUIDs |
| `auth_ids` | `string`[] | No | Assigned auth resource UUIDs |
| `provider_ids` | `string`[] | No | Assigned provider resource UUIDs |
| `provider_keys` | [`SettingProviderKeyDraftValue`](#settingproviderkeydraftvalue)[] | No | Echoed (provider × key) value entries with resolved ids |
| `auth_item_keys` | [`SettingAuthItemKeyDraftValue`](#settingauthitemkeydraftvalue)[] | No | Echoed (auth × key) value entries with resolved ids |
| `auth_item_values` | [`SettingAuthItemValueDraftValue`](#settingauthitemvaluedraftvalue)[] | No | Echoed (auth × item × value) entries with resolved ids |
| `mcp_values` | [`SettingMcpDraftValue`](#settingmcpdraftvalue)[] | No | Echoed mcp value entries with resolved ids |
| `system_values` | [`SettingSystemDraftValue`](#settingsystemdraftvalue)[] | No | Echoed system value entries with resolved ids |
| `threshold_values` | [`SettingThresholdDraftValue`](#settingthresholddraftvalue)[] | No | Echoed per-type threshold values with resolved ids |
| `logins` | [`SettingLoginDraftValue`](#settinglogindraftvalue)[] | No | Echoed logins value entries with resolved ids |
| `pending_ids` | `string`[] | No | Pending resource identifiers |

---

## `app__infra__setting__types__SectionFilter`

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Filter options by search text |
| `limit` | `integer` | No | Max options to return |
| `selected` | `boolean` | No | Only return selected items |
| `suggested` | `boolean` | No | Only return suggested items |
| `include` | `boolean` | No | Include this section in response (default true) |
| `parameter_ids` | `string`[] | No | Reserved for compatibility with shared filter parsing |

---

---

# `GET` `/simulation/watch`

Route: /api-reference/simulation/get-simulation-watch

# `GET` `/simulation/watch`

Simulation Watch

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `group_id` | query | No | — |
| `run_id` | query | No | Optional run filter. If provided, only events whose envelope run_id matches are streamed. Omit to receive every simulation event in the group (the FE default). |

## Response

```
{}
```

---

# `POST` `/simulation/call_download`

Route: /api-reference/simulation/post-simulation-call-download

# `POST` `/simulation/call_download`

Download Call

Download a call file by call resource ID.

## Request Body (`CallDownloadSimulationApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `call_id` | `string` | Yes | UUID of the calls_resource to download |

## Response

```
{}
```

---

# `POST` `/simulation/context`

Route: /api-reference/simulation/post-simulation-context

# `POST` `/simulation/context`

Get Simulation Context

Get page context for the simulation artifact.

Returns docs + profile identity + evaluated permissions in a single call.
Superset of /docs — clients can migrate from /docs to /context incrementally.

## Request Body (`DocsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entity_id` | `string` | No | — |
| `snapshot_key` | `string` | No | — |
| `schema` | `boolean` | No | If true, include MCP/tooling schema metadata (artifact, entries, resources, permission_docs, api_operations). Defaults to false for lean page-bootstrap responses. |

## Response (`ComposedContextResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Artifact name |
| `type` | `string` | Yes | Artifact type identifier |
| `description` | `string` | Yes | Human-readable description |
| `artifact` | [`DocsResponse`](/api-reference/simulation/types#docsresponse) | No | Artifact tool documentation (None unless schema=true) |
| `entries` | [`DocsResponse`](/api-reference/simulation/types#docsresponse)[] | No | Entry documentation list (None unless schema=true) |
| `resources` | [`DocsResponse`](/api-reference/simulation/types#docsresponse)[] | No | Resource documentation list (None unless schema=true) |
| `permission_docs` | [`OperationInfo`](/api-reference/simulation/types#operationinfo)[] | No | Permission function signatures for MCP/dev tooling (None unless schema=true) |
| `api_operations` | [`OperationInfo`](/api-reference/simulation/types#operationinfo)[] | No | API operation documentation (None unless schema=true) |
| `page_metadata` | [`DocsApiResponse`](/api-reference/simulation/types#docsapiresponse) | No | Page-level metadata |
| `prompts` | [`OperationPrompts`](/api-reference/simulation/types#operationprompts) | No | Starter prompts keyed by operation |
| `profile` | [`ProfileSummary`](/api-reference/simulation/types#profilesummary) | Yes | Caller identity from JWT |
| `caller_permissions` | [`CallerPermissions`](/api-reference/simulation/types#callerpermissions) | Yes | Evaluated permissions for this caller |

---

# `POST` `/simulation/create`

Route: /api-reference/simulation/post-simulation-create

# `POST` `/simulation/create`

Create Simulation

Create simulations using composable infra architecture.

## Request Body (`CreateSimulationApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `simulations` | [`CreateSimulationItem`](/api-reference/simulation/types#createsimulationitem)[] | Yes | List of simulations to create |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant create |
| `soft` | `boolean` | No | Stage the create dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`CreateSimulationApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`SimulationResultItem`](/api-reference/simulation/types#simulationresultitem)[] | Yes | List of operation results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/simulation/csv`

Route: /api-reference/simulation/post-simulation-csv

# `POST` `/simulation/csv`

Parse Simulation Csv

Parse a CSV file and return mapped items for preview.

## Request Body

| Field | Type | Required | Description |
|---|---|---|---|
| `file` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `soft` | `boolean` | No | — |
| `accept` | `boolean` | No | — |

## Response (`ParseSimulationCsvApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `upload_id` | `string` | Yes | — |
| `items` | [`CreateSimulationItem`](/api-reference/simulation/types#createsimulationitem)[] | Yes | — |
| `mapped_fields` | `string`[] | Yes | — |
| `row_count` | `integer` | Yes | — |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with `accept` to promote/reject the staged raw-CSV upload. NOTE: ack returns no items (the preview is only on the propose). |

---

# `POST` `/simulation/delete`

Route: /api-reference/simulation/post-simulation-delete

# `POST` `/simulation/delete`

Delete Simulation

Bulk delete simulations — composable infra architecture.

## Request Body (`DeleteSimulationApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `simulation_ids` | `string`[] | No | UUIDs of simulations to delete (required on first call when ``all`` is false) |
| `all` | `boolean` | No | When true, delete every simulation matching the filter fields below (minus ``excluded_ids``) |
| `excluded_ids` | `string`[] | No | UUIDs to skip even when matched by ``all``-mode filters |
| `search` | `string` | No | Full-text search query |
| `filter_scenario_ids` | `string`[] | No | Filter by scenario UUIDs |
| `filter_cohort_ids` | `string`[] | No | Filter by cohort UUIDs |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `scenario_search` | `string` | No | Search text for scenario facet (no-op for row filtering) |
| `cohort_search` | `string` | No | Search text for cohort facet (no-op for row filtering) |
| `department_search` | `string` | No | Search text for department facet (no-op for row filtering) |
| `flag_search` | `string` | No | Search text for flag facet (no-op for row filtering) |
| `idempotency_key` | `string` | No | Operation key for ack — confirms or rejects a dormant delete |
| `soft` | `boolean` | No | Stage the delete dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (confirm deletion) or reject (restore). Only meaningful with idempotency_key |

## Response (`DeleteSimulationApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`DeleteSimulationResult`](/api-reference/simulation/types#deletesimulationresult)[] | Yes | List of operation results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/simulation/draft`

Route: /api-reference/simulation/post-simulation-draft

# `POST` `/simulation/draft`

Patch Simulation Draft

Patch simulation draft — composable infra architecture.

## Request Body (`PatchSimulationDraftApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `draft_id` | `string` | No | Existing draft UUID to patch |
| `input_draft_id` | `string` | No | Legacy alias for the input draft UUID |
| `name` | `string` | No | Display name value |
| `name_id` | `string` | No | UUID of the name resource |
| `description` | `string` | No | Description text value |
| `description_id` | `string` | No | UUID of the description resource |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `active` | `boolean` | No | Denormalized simulation_active flag state |
| `practice` | `boolean` | No | Denormalized practice flag state |
| `department_ids` | `string`[] | No | Associated department UUIDs |
| `scenario_ids` | `string`[] | No | Associated scenario UUIDs |
| `scenario_flag_ids` | `string`[] | No | Existing scenario flag UUIDs |
| `scenario_flags` | [`DraftScenarioFlagValue`](/api-reference/simulation/types#draftscenarioflagvalue)[] | No | Scenario flag values to create |
| `scenario_flag_values` | [`DraftScenarioFlagDenormValue`](/api-reference/simulation/types#draftscenarioflagdenormvalue)[] | No | Denormalized (scenario_id, type, value) entries resolved server-side to scenario_flags_resource rows |
| `scenario_position_ids` | `string`[] | No | Existing scenario position UUIDs |
| `scenario_positions` | [`DraftScenarioPositionValue`](/api-reference/simulation/types#draftscenariopositionvalue)[] | No | Scenario position values to create |
| `scenario_rubric_ids` | `string`[] | No | Existing scenario rubric UUIDs |
| `scenario_rubrics` | [`DraftScenarioRubricValue`](/api-reference/simulation/types#draftscenariorubricvalue)[] | No | Scenario rubric values to create |
| `scenario_time_limit_ids` | `string`[] | No | Existing scenario time limit UUIDs |
| `scenario_time_limits` | [`DraftScenarioTimeLimitValue`](/api-reference/simulation/types#draftscenariotimelimitvalue)[] | No | Scenario time limit values to create |
| `pending_ids` | `string`[] | No | Resource IDs to keep as pending where supported by the tool layer |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant draft |
| `soft` | `boolean` | No | Stage the draft dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`PatchSimulationDraftApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `draft_id` | `string` | Yes | UUID of the saved draft |
| `idempotency_key` | `string` | Yes | Idempotency key for this draft operation |
| `message` | `string` | Yes | Human-readable result message |
| `form_state` | [`app__infra__simulation__types__DraftFormState`](/api-reference/simulation/types#app-infra-simulation-types-draftformstate) | Yes | Server-authoritative form state |

---

# `POST` `/simulation/drafts`

Route: /api-reference/simulation/post-simulation-drafts

# `POST` `/simulation/drafts`

Get Simulation Drafts

List simulation drafts owned by the current profile.

## Request Body (`GetSimulationDraftsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE substring) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GetSimulationDraftsApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entries` | [`GetSimulationDraftResponse`](/api-reference/simulation/types#getsimulationdraftresponse)[] | No | List of simulation draft entries |

---

# `POST` `/simulation/duplicate`

Route: /api-reference/simulation/post-simulation-duplicate

# `POST` `/simulation/duplicate`

Duplicate Simulation

Duplicate a simulation — composable infra architecture.

## Request Body (`DuplicateSimulationApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `simulation_id` | `string` | Yes | UUID of the simulation to duplicate |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant duplicate |
| `soft` | `boolean` | No | Stage the duplicate dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`DuplicateSimulationApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `simulation_id` | `string` | Yes | UUID of the duplicated simulation |
| `message` | `string` | Yes | Human-readable result message |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/simulation/export`

Route: /api-reference/simulation/post-simulation-export

# `POST` `/simulation/export`

Export Simulations

Export all simulations as a clean, denormalized CSV.

## Request Body (`ExportSimulationApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `simulation_id` | `string` | No | UUID of the simulation to export |
| `search` | `string` | No | Search query text |
| `filter_scenario_ids` | `string`[] | No | Filter by scenario UUIDs |
| `filter_cohort_ids` | `string`[] | No | Filter by cohort UUIDs |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior export instead of re-running |
| `soft` | `boolean` | No | Stage the export dormant (active=False); ack with accept activates it |
| `accept` | `boolean` | No | Ack: True promotes the staged export, False rejects. Only meaningful with idempotency_key |

## Response (`ExportSimulationApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource holding the export CSV |
| `file_name` | `string` | Yes | Suggested download file name |
| `row_count` | `integer` | Yes | Number of data rows in the export |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with `accept` to promote/reject the staged export. |

---

# `POST` `/simulation/file_download`

Route: /api-reference/simulation/post-simulation-file-download

# `POST` `/simulation/file_download`

Download File

Download a file by file resource ID.

## Request Body (`FileDownloadSimulationApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource to download |

## Response

```
{}
```

---

# `POST` `/simulation/generate`

Route: /api-reference/simulation/post-simulation-generate

# `POST` `/simulation/generate`

Generate Simulation

Trigger simulation generation. Returns immediately; progress via events.

## Request Body (`ArtifactGenerateRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `instructions` | `string`[] | No | — |
| `config` | [`GenerateConfig`](/api-reference/simulation/types#generateconfig) | No | — |
| `modalities` | `string`[] | No | — |
| `audios_id` | `string` | No | — |
| `conversation_id` | `string` | No | — |
| `trace_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `accept` | `boolean` | No | — |
| `wait_for_complete` | `boolean` | No | — |

## Response (`ArtifactGenerateResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `run_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `eval` | [`EvalSetup`](/api-reference/simulation/types#evalsetup) | No | — |
| `produced_media` | [`ProducedMedia`](/api-reference/simulation/types#producedmedia)[] | No | — |

---

# `POST` `/simulation/generations`

Route: /api-reference/simulation/post-simulation-generations

# `POST` `/simulation/generations`

Generations Simulation

List simulation generation groups — composable infra architecture.

## Request Body (`GenerationsSimulationApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GenerationsSimulationApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `items` | [`GenerationsSimulationListItem`](/api-reference/simulation/types#generationssimulationlistitem)[] | No | Generation groups |
| `total_count` | `integer` | No | Total number of matching generations |

---

# `POST` `/simulation/get`

Route: /api-reference/simulation/post-simulation-get

# `POST` `/simulation/get`

Get Simulation

Get simulation information using the canonical shared simulation operation.

## Request Body (`GetSimulationApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | UUID of the simulation to retrieve |
| `simulation_id` | `string` | No | Legacy alias for the simulation UUID |
| `draft_id` | `string` | No | UUID of the draft to load instead of published state |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |
| `names` | [`app__infra__simulation__types__SectionFilter`](/api-reference/simulation/types#app-infra-simulation-types-sectionfilter) | No | Filter options for names section |
| `descriptions` | [`app__infra__simulation__types__SectionFilter`](/api-reference/simulation/types#app-infra-simulation-types-sectionfilter) | No | Filter options for descriptions section |
| `flags` | [`app__infra__simulation__types__SectionFilter`](/api-reference/simulation/types#app-infra-simulation-types-sectionfilter) | No | Filter options for flags section |
| `departments` | [`app__infra__simulation__types__SectionFilter`](/api-reference/simulation/types#app-infra-simulation-types-sectionfilter) | No | Filter options for departments section |
| `scenarios` | [`app__infra__simulation__types__SectionFilter`](/api-reference/simulation/types#app-infra-simulation-types-sectionfilter) | No | Filter options for scenarios section |
| `scenario_flags` | [`app__infra__simulation__types__SectionFilter`](/api-reference/simulation/types#app-infra-simulation-types-sectionfilter) | No | Filter options for scenario flags section |
| `scenario_positions` | [`app__infra__simulation__types__SectionFilter`](/api-reference/simulation/types#app-infra-simulation-types-sectionfilter) | No | Filter options for scenario positions section |
| `scenario_rubrics` | [`app__infra__simulation__types__SectionFilter`](/api-reference/simulation/types#app-infra-simulation-types-sectionfilter) | No | Filter options for scenario rubrics section |
| `scenario_time_limits` | [`app__infra__simulation__types__SectionFilter`](/api-reference/simulation/types#app-infra-simulation-types-sectionfilter) | No | Filter options for scenario time limits section |
| `filter_scenario_ids` | `string`[] | No | Legacy scenario ID filter for nested scenario resources |
| `scenario_search` | `string` | No | Legacy search text for scenarios |
| `scenario_show_selected` | `boolean` | No | Legacy selected-only filter for scenarios |

## Response (`GetSimulationApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `simulation_exists` | `boolean` | No | Whether the simulation exists |
| `can_edit` | `boolean` | No | Whether the current user can edit |
| `disabled_reason` | `string` | No | Reason the simulation is disabled |
| `group_id` | `string` | No | UUID of the owning group |
| `draft_name` | `string` | No | Immutable draft label from the active draft entry, when a ``draft_id`` was supplied. ``None`` for non-draft fetches. |
| `show_ai_generate` | `boolean` | No | Whether AI generation is available |
| `basic_show_ai_generate` | `boolean` | No | Legacy basic-step AI generate flag |
| `names` | [`SimulationNameResource`](/api-reference/simulation/types#simulationnameresource)[] | No | Name resources with selected/suggested flags |
| `descriptions` | [`SimulationDescriptionResource`](/api-reference/simulation/types#simulationdescriptionresource)[] | No | Description resources with selected/suggested flags |
| `flags` | [`SimulationFlagResource`](/api-reference/simulation/types#simulationflagresource)[] | No | Flag configs with selected/suggested flags |
| `departments` | [`SimulationDepartment`](/api-reference/simulation/types#simulationdepartment)[] | No | Department resources with selected/suggested flags |
| `scenarios` | [`SimulationScenario`](/api-reference/simulation/types#simulationscenario)[] | No | Scenario resources with selected/suggested flags |
| `scenario_flags` | [`SimulationScenarioFlag`](/api-reference/simulation/types#simulationscenarioflag)[] | No | Scenario flag resources with selected/suggested flags |
| `scenario_flag_options` | [`SimulationScenarioFlagOption`](/api-reference/simulation/types#simulationscenarioflagoption)[] | No | Cross-product of (scenario × flag type × value) for the ScenarioFlags picker |
| `scenario_positions` | [`SimulationScenarioPosition`](/api-reference/simulation/types#simulationscenarioposition)[] | No | Scenario position resources with selected/suggested flags |
| `scenario_rubrics` | [`SimulationScenarioRubric`](/api-reference/simulation/types#simulationscenariorubric)[] | No | Scenario rubric resources with selected/suggested flags |
| `scenario_time_limits` | [`SimulationScenarioTimeLimit`](/api-reference/simulation/types#simulationscenariotimelimit)[] | No | Scenario time limit resources with selected/suggested flags |
| `rubrics` | [`SimulationRubric`](/api-reference/simulation/types#simulationrubric)[] | No | Available rubric catalog items |

---

# `POST` `/simulation/group`

Route: /api-reference/simulation/post-simulation-group

# `POST` `/simulation/group`

Group Simulation

Resolve or create a simulation group with optional naming.

## Request Body (`GroupSimulationApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | No | Existing group UUID (omit to create or reuse via time window) |
| `snapshot_key` | `string` | No | Snapshot key for SETNX-race convergence on a single group across concurrent reads (e.g. parallel /context + /group + /search fan-out on page load). Echoed back in the response. |

## Response (`GroupSimulationApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Resolved or newly created group UUID |
| `name` | `string` | No | The group's current title (latest active group_names_entry, or 'New Chat' fallback for freshly minted groups) |
| `snapshot_key` | `string` | No | Snapshot key echoed back — the UUID concurrent fan-out reads converged on via SETNX. Mirrors the resolved group_id. |
| `runs` | [`GroupRun`](/api-reference/simulation/types#grouprun)[] | No | Conversation history — populated when resolving an existing group for fetch |
| `group_exists` | `boolean` | No | (detail) Whether the group exists in storage — populated when ``include_resources=True`` |
| `actor_name` | `string` | No | (detail) Display name of the current actor (caller profile) |
| `total_message_count` | `integer` | No | (detail) Total number of messages in the group |
| `models` | [`GroupResource`](/api-reference/simulation/types#groupresource)[] | No | (detail) Models used in the group |
| `agents` | [`GroupResource`](/api-reference/simulation/types#groupresource)[] | No | (detail) Agents used in the group |
| `profiles` | [`GroupResource`](/api-reference/simulation/types#groupresource)[] | No | (detail) Profiles that authored runs in this group |

---

# `POST` `/simulation/problem`

Route: /api-reference/simulation/post-simulation-problem

# `POST` `/simulation/problem`

Problem Simulation

Report a simulation problem — composable infra architecture.

## Request Body (`ProblemSimulationApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | `string` | Yes | Problem type: feature, bug, question, other |
| `message` | `string` | Yes | Problem description (max 1000 chars) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant problem |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`ProblemSimulationApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `problem_id` | `string` | Yes | UUID of the created problem |
| `success` | `boolean` | No | Whether the problem was created |
| `message` | `string` | No | Status message |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/simulation/refresh`

Route: /api-reference/simulation/post-simulation-refresh

# `POST` `/simulation/refresh`

Simulation Refresh

Refresh simulation materialized views and invalidate caches.

## Request Body (`RefreshSimulationApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `targets` | `string`[] | No | MV targets to refresh (omit for all). Options: simulation_drafts_mv, runs_mv, messages_mv, calls_mv, groups_mv, group_names_mv |
| `idempotency_key` | `string` | No | Operation key for ack |
| `accept` | `boolean` | No | Accept or reject. Only meaningful with idempotency_key |
| `soft` | `boolean` | No | Stage the refresh as a pending (held) request — recorded but not enqueued; ack with accept releases/enqueues it |

## Response (`RefreshResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | — |
| `refreshed_views` | `string`[] | Yes | — |
| `invalidated_tags` | `string`[] | Yes | — |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/simulation/search`

Route: /api-reference/simulation/post-simulation-search

# `POST` `/simulation/search`

Search Simulation

Search simulations — composable infra architecture.

## Request Body (`SearchSimulationApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | — |
| `filter_scenario_ids` | `string`[] | No | — |
| `filter_cohort_ids` | `string`[] | No | — |
| `filter_department_ids` | `string`[] | No | — |
| `scenario_search` | `string` | No | — |
| `cohort_search` | `string` | No | — |
| `department_search` | `string` | No | — |
| `flag_search` | `string` | No | — |
| `page_size` | `integer` | No | — |
| `page_offset` | `integer` | No | — |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`ListSimulationApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `simulations` | [`ListSimulationApiSimulation`](/api-reference/simulation/types#listsimulationapisimulation)[] | No | List of simulation items |
| `scenarios` | [`ListSimulationApiScenario`](/api-reference/simulation/types#listsimulationapiscenario)[] | No | List of scenario items |
| `scenario_filter` | [`ListFilterSection`](/api-reference/simulation/types#listfiltersection) | No | Filter options for scenarios |
| `cohort_filter` | [`ListFilterSection`](/api-reference/simulation/types#listfiltersection) | No | Filter options for cohorts |
| `department_filter` | [`ListFilterSection`](/api-reference/simulation/types#listfiltersection) | No | Filter options for departments |
| `flag_filter` | [`ListFilterSection`](/api-reference/simulation/types#listfiltersection) | No | Filter options for flags |
| `total_count` | `integer` | No | Total number of matching records |
| `import_fields` | [`ImportField`](/api-reference/simulation/types#importfield)[] | No | CSV import column schema for the bulk-import dialog |

---

# `POST` `/simulation/text_download`

Route: /api-reference/simulation/post-simulation-text-download

# `POST` `/simulation/text_download`

Download Text

Download a text file by text resource ID.

## Request Body (`TextDownloadSimulationApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `text_id` | `string` | Yes | UUID of the texts_resource to download |

## Response

```
{}
```

---

# `POST` `/simulation/title`

Route: /api-reference/simulation/post-simulation-title

# `POST` `/simulation/title`

Title Simulation

Rename a simulation's group (writes group_names_entry).

## Request Body (`TitleSimulationApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Group to rename |
| `title` | `string` | Yes | New title (display name) for the group |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant rename |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`TitleSimulationApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | The group that was renamed |
| `group_name_id` | `string` | Yes | UUID of the new group_names_entry row |
| `title` | `string` | Yes | The title that was set |
| `idempotency_key` | `string` | No | Operation key echoed back |

---

# `POST` `/simulation/update`

Route: /api-reference/simulation/post-simulation-update

# `POST` `/simulation/update`

Update Simulation

Update simulations using composable infra architecture.

## Request Body (`UpdateSimulationApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `simulations` | [`UpdateSimulationItem`](/api-reference/simulation/types#updatesimulationitem)[] | No | List of simulations to update (required on first call when ``all`` is false) |
| `all` | `boolean` | No | When true, apply ``patch`` to every simulation matching the filter fields below (minus ``excluded_ids``) |
| `excluded_ids` | `string`[] | No | UUIDs to skip even when matched by ``all``-mode filters |
| `patch` | [`UpdateSimulationPatch`](/api-reference/simulation/types#updatesimulationpatch) | No | Shared change set applied to every matched row when ``all=true`` (sparse — only set fields are updated; ``patch.id`` ignored) |
| `search` | `string` | No | Full-text search query |
| `filter_scenario_ids` | `string`[] | No | Filter by scenario UUIDs |
| `filter_cohort_ids` | `string`[] | No | Filter by cohort UUIDs |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `scenario_search` | `string` | No | Search text for scenario facet (no-op for row filtering) |
| `cohort_search` | `string` | No | Search text for cohort facet (no-op for row filtering) |
| `department_search` | `string` | No | Search text for department facet (no-op for row filtering) |
| `flag_search` | `string` | No | Search text for flag facet (no-op for row filtering) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant update |
| `soft` | `boolean` | No | Stage the update dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`UpdateSimulationApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`SimulationResultItem`](/api-reference/simulation/types#simulationresultitem)[] | Yes | List of operation results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/simulation/watch`

Route: /api-reference/simulation/post-simulation-watch

# `POST` `/simulation/watch`

Simulation Watch Once

One-shot snapshot of run state, snapshot-replayable via ``snapshot_key``.

## Request Body (`WatchApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Chat group whose events we watch |
| `run_id` | `string` | No | Specific run to watch (e.g. the ``run_id`` returned by a prior ``X_Generate`` call). If None, watches every active run in the group at call time. |
| `wait_for_complete` | `boolean` | No | If True, block until the watched run reaches a terminal (complete/failed) event or timeout fires. If False, return current state and exit immediately. |
| `timeout_seconds` | `integer` | No | Max wait time when ``wait_for_complete=True``. |
| `snapshot_key` | `string` | No | Read snapshot key — on the one-shot POST /watch, the audit wrapper records this watch's point-in-time view (latest run state at call time) keyed by it and replays the same view on any later call with the same key. Ignored by the SSE GET stream. |

## Response (`WatchApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `runs` | [`RunStatus`](/api-reference/simulation/types#runstatus)[] | Yes | — |
| `timed_out` | `boolean` | No | — |
| `waited_seconds` | `number` | No | — |

---

# Simulation Types

Route: /api-reference/simulation/types

# Simulation Types

## `CallerPermissions`

Evaluated permissions for the current caller on this artifact type.

| Field | Type | Required | Description |
|---|---|---|---|
| `can_create` | `boolean` | Yes | Whether the caller can create new artifacts |
| `can_draft` | `boolean` | Yes | Whether the caller can create/update drafts |
| `can_duplicate` | `boolean` | Yes | Whether the caller can duplicate artifacts |
| `has_access` | `boolean` | No | Whether the caller can view this entity |
| `can_edit` | `boolean` | No | Whether the caller can edit this entity |
| `can_delete` | `boolean` | No | Whether the caller can delete this entity |
| `disabled_reason` | `string` | No | Human-readable reason if editing is disabled |

---

## `ColumnInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Column name |
| `type` | `string` | Yes | Column data type |
| `nullable` | `boolean` | Yes | Whether the column is nullable |

---

## `CreateSimulationItem`

Single simulation item for create — no simulation_id.

Required fields (name): provide ID or value.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Client-provided UUID for the simulation |
| `resource_id` | `string` | No | Optional preset UUID for the resource snapshot |
| `name_id` | `string` | No | UUID of the name resource |
| `name` | `string` | No | Display name value |
| `description_id` | `string` | No | UUID of the description resource |
| `description` | `string` | No | Description text value |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `department_ids` | `string`[] | No | Associated department UUIDs |
| `scenario_ids` | `string`[] | No | Associated scenario UUIDs |
| `scenario_flag_ids` | `string`[] | No | Associated scenario flag UUIDs |
| `scenario_position_ids` | `string`[] | No | Associated scenario position UUIDs |
| `scenario_rubric_ids` | `string`[] | No | Associated scenario rubric UUIDs |
| `scenario_time_limit_ids` | `string`[] | No | Associated scenario time limit UUIDs |
| `departments` | `string`[] | No | Department names for matching |
| `scenarios` | `string`[] | No | Scenario names for matching |

---

## `DeleteSimulationResult`

Per-item result within a bulk delete response.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `simulation_id` | `string` | Yes | UUID of the deleted simulation |
| `message` | `string` | Yes | Human-readable result message |

---

## `DocsApiResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `list` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `detail` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `new` | [`PageMetaItem`](#pagemetaitem) | Yes | — |

---

## `DocsResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Resource or entry name |
| `type` | `string` | Yes | Resource or entry type identifier |
| `description` | `string` | Yes | Human-readable description |
| `materialized_view` | [`MvInfo`](#mvinfo) | No | Materialized view metadata |
| `tables` | [`TableInfo`](#tableinfo)[] | Yes | Related database tables |
| `operations` | [`OperationInfo`](#operationinfo)[] | Yes | Available operations |

---

## `DraftScenarioFlagDenormValue`

Denormalized scenario_flag value — resolved server-side to (scenario_id, flag_id).

Given (scenario_id, type, value), the server looks up the flags_resource
row matching (type, value) and upserts a scenario_flags_resource row for
(scenario_id, flag_id).

| Field | Type | Required | Description |
|---|---|---|---|
| `scenario_id` | `string` | Yes | UUID of the parent scenario |
| `type` | `string` | Yes | Flag type in flags_resource |
| `value` | `boolean` | Yes | Desired boolean value for this flag type |

---

## `DraftScenarioFlagValue`

Value for creating a scenario_flag resource via draft.

| Field | Type | Required | Description |
|---|---|---|---|
| `scenario_id` | `string` | Yes | UUID of the parent scenario |
| `flag_id` | `string` | Yes | UUID of the flag resource |

---

## `DraftScenarioPositionValue`

Value for creating a scenario_position resource via draft.

| Field | Type | Required | Description |
|---|---|---|---|
| `scenario_id` | `string` | Yes | UUID of the parent scenario |
| `value` | `integer` | Yes | Position value |

---

## `DraftScenarioRubricValue`

Value for creating a scenario_rubric resource via draft.

| Field | Type | Required | Description |
|---|---|---|---|
| `scenario_id` | `string` | Yes | UUID of the parent scenario |
| `rubric_id` | `string` | Yes | UUID of the rubric resource |

---

## `DraftScenarioTimeLimitValue`

Value for creating a scenario_time_limit resource via draft.

| Field | Type | Required | Description |
|---|---|---|---|
| `scenario_id` | `string` | Yes | UUID of the parent scenario |
| `time_limit_seconds` | `integer` | Yes | Time limit in seconds |
| `negative` | `boolean` | No | Whether the time limit is negative |

---

## `EvalSetup`

Run-level eval scaffold — first-class on the generate response.

Audit's ``**output`` spread carries this onto
``<artifact>.generate.completed``. Null when no rubric-bearing
agent participated.

| Field | Type | Required | Description |
|---|---|---|---|
| `test_id` | `string` | Yes | — |
| `invocations` | [`InvocationSlot`](#invocationslot)[] | Yes | — |

---

## `GenerateConfig`

Developer configuration — all optional with sensible defaults.

| Field | Type | Required | Description |
|---|---|---|---|
| `operations` | `string`[] | No | — |
| `dangerous` | `boolean` | No | — |
| `params` | `object` | No | — |
| `group_id` | `string` | No | — |

---

## `GenerationsSimulationListItem`

Single generation group in the simulation generations response.

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | UUID of the generation group |
| `session_id` | `string` | No | UUID of the parent session |
| `group_name` | `string` | No | Name of the generation group |
| `created_at` | `string` | No | Timestamp of the generation |

---

## `GetSimulationDraftResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | UUID of the draft |
| `created_at` | `string` | Yes | Creation timestamp |
| `generated` | `boolean` | Yes | Whether this was AI-generated |
| `mcp` | `boolean` | Yes | Whether MCP tooling was used |
| `active` | `boolean` | Yes | Whether this draft is active |
| `session_id` | `string` | Yes | Associated session UUID |
| `name` | `string` | No | Immutable draft label set at create time |
| `department_ids` | `string`[] | Yes | Associated department UUIDs |
| `description_ids` | `string`[] | Yes | Associated description UUIDs |
| `flag_ids` | `string`[] | Yes | Associated flag UUIDs |
| `name_ids` | `string`[] | Yes | Associated name UUIDs |
| `profile_ids` | `string`[] | Yes | Associated profile UUIDs |
| `scenario_flag_ids` | `string`[] | Yes | Associated scenario flag UUIDs |
| `scenario_position_ids` | `string`[] | Yes | Associated scenario position UUIDs |
| `scenario_rubric_ids` | `string`[] | Yes | Associated scenario rubric UUIDs |
| `scenario_time_limit_ids` | `string`[] | Yes | Associated scenario time limit UUIDs |
| `scenario_ids` | `string`[] | Yes | Associated scenario UUIDs |
| `pending_department_ids` | `string`[] | No | Pending department UUIDs |
| `pending_description_ids` | `string`[] | No | Pending description UUIDs |
| `pending_flag_ids` | `string`[] | No | Pending flag UUIDs |
| `pending_name_ids` | `string`[] | No | Pending name UUIDs |
| `pending_scenario_flag_ids` | `string`[] | No | Pending scenario flag UUIDs |
| `pending_scenario_position_ids` | `string`[] | No | Pending scenario position UUIDs |
| `pending_scenario_rubric_ids` | `string`[] | No | Pending scenario rubric UUIDs |
| `pending_scenario_time_limit_ids` | `string`[] | No | Pending scenario time limit UUIDs |
| `pending_scenario_ids` | `string`[] | No | Pending scenario UUIDs |

---

## `GroupCall`

Tool call referenced by a message.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `tool_name` | `string` | No | — |
| `template_name` | `string` | No | — |
| `tool` | `object` | No | — |
| `ledger_status` | `string` | No | — |
| `ledger_operation` | `string` | No | — |
| `ledger_artifact` | `string` | No | — |
| `ledger_artifact_id` | `string` | No | — |

---

## `GroupMessage`

Message within a run.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `role` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `text_ids` | `string`[] | No | — |
| `audio_ids` | `string`[] | No | — |
| `image_ids` | `string`[] | No | — |
| `video_ids` | `string`[] | No | — |
| `file_ids` | `string`[] | No | — |
| `call_ids` | `string`[] | No | — |
| `calls` | [`GroupCall`](#groupcall)[] | No | — |
| `reasoning` | `boolean` | No | True when this row is a chain-of-thought trace persisted alongside the assistant answer (rendered as a collapsed accordion). |
| `in_context` | `boolean` | No | Whether this message is included in the LLM context for the next generation. Mirrors the dedup pass that builds chat history (see in_context_reason). |
| `in_context_reason` | `string` | No | Why this message is in/out of LLM context. 'kept' = included; 'deduped_read' = older read-only call to a tool that has a fresher result later in the group; future values may include 'trimmed_top_n'. |

---

## `GroupResource`

Lightweight `\{id, name\}` for cross-referencing run-level ids
(``model_id`` / ``agent_id`` / ``profile_id``) against human-readable
names on the analytics panel. Names come from the canonical
``get_models`` / ``get_agents`` / ``get_profiles`` black boxes.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `name` | `string` | No | — |

---

## `GroupRun`

Run within a group, with its messages.

Carries token / cost / model / agent / profile attribution so the
analytics view can render per-run cost + actor info without a
parallel detail shape. ``profile_id`` is the authoring profile
(human user), ``agent_id`` is the LLM-side actor, ``model_id`` is
the model used by that agent. All optional — runs predating these
columns or with unresolved attributions surface ``None``.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `input_tokens` | `integer` | No | — |
| `output_tokens` | `integer` | No | — |
| `cached_input_tokens` | `integer` | No | — |
| `cost` | `number` | No | — |
| `model_id` | `string` | No | — |
| `agent_id` | `string` | No | — |
| `profile_id` | `string` | No | — |
| `previous_context_start_index` | `integer` | No | Index in ``messages`` where the current run's own messages begin; earlier rows are previous-context replay. ``None`` when the run has no previous context attached. |
| `messages` | [`GroupMessage`](#groupmessage)[] | No | — |

---

## `ImportField`

Field descriptor for CSV import column mapping.

| Field | Type | Required | Description |
|---|---|---|---|
| `key` | `string` | Yes | — |
| `label` | `string` | Yes | — |
| `required` | `boolean` | No | — |
| `multi` | `boolean` | No | — |
| `type` | `string` | No | — |
| `example` | `string` | No | — |
| `description` | `string` | No | — |

---

## `InvocationSlot`

One agent's slot in a multi-agent generation pool.

Populated by ``setup_generation_test`` when an agent carries a
rubric. The client uses these IDs to drive the eval workflow:
review the candidate's output, optionally fire a grader against
its ``invocation_id``, and promote/reject by call_id via the
existing ``idempotency_key + accept`` pattern.

| Field | Type | Required | Description |
|---|---|---|---|
| `invocation_id` | `string` | Yes | — |
| `agent_id` | `string` | Yes | — |
| `rubric_id` | `string` | No | — |

---

## `ListFilterOption`

Standardized option for list endpoint filter sections.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier for this filter option |
| `name` | `string` | No | Display name |
| `count` | `integer` | No | Number of matching records |
| `hex_code` | `string` | No | Hex color code for display |
| `value` | `string` | No | Internal value |
| `type` | `string` | No | Option type discriminator |

---

## `ListFilterSection`

Filter section with options and echoed request state.

| Field | Type | Required | Description |
|---|---|---|---|
| `options` | [`ListFilterOption`](#listfilteroption)[] | No | Available filter options |
| `selected_ids` | `string`[] | No | Currently selected filter option IDs |
| `search` | `string` | No | Active search text for filtering |

---

## `ListSimulationApiPersona`

Persona in list response (minimal: only for color dot rendering).

| Field | Type | Required | Description |
|---|---|---|---|
| `persona_id` | `string` | No | UUID of the persona |
| `color` | `string` | No | Display color for the persona |

---

## `ListSimulationApiScenario`

Scenario in list response (minimal: only for color dot rendering).

| Field | Type | Required | Description |
|---|---|---|---|
| `scenario_id` | `string` | No | UUID of the scenario |
| `name` | `string` | No | Scenario name |
| `persona_ids` | `string`[] | No | Associated persona UUIDs |
| `persona_mapping` | [`ListSimulationApiPersona`](#listsimulationapipersona)[] | No | Persona color mapping for rendering |

---

## `ListSimulationApiSimulation`

Simulation item in list response with Python-computed permissions.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Simulation artifact UUID (canonical id; mirrors simulation_id) |
| `simulation_id` | `string` | No | UUID of the simulation |
| `name` | `string` | No | Display name |
| `description` | `string` | No | Simulation description text |
| `department_ids` | `string`[] | No | Associated department UUIDs |
| `flag_ids` | `string`[] | No | Currently selected flag option UUIDs |
| `is_inactive` | `boolean` | No | Whether the simulation is inactive (derived from simulation_active flag) |
| `is_practice` | `boolean` | No | Whether this is a practice simulation (derived from practice flag) |
| `practice_simulation` | `boolean` | No | Legacy alias for is_practice — prefer is_practice |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `mcp` | `boolean` | No | Whether this is an MCP simulation |
| `scenario_ids` | `string`[] | No | Associated scenario UUIDs |
| `num_cohorts` | `integer` | No | Total number of cohorts |
| `cohort_usage_count` | `integer` | No | Number of cohorts using this simulation |
| `can_edit` | `boolean` | No | Whether the current user can edit |
| `can_delete` | `boolean` | No | Whether the current user can delete |
| `can_duplicate` | `boolean` | No | Whether the current user can duplicate |
| `cohort_ids` | `string`[] | No | Associated cohort UUIDs |
| `pending_status` | `string` | No | Latest soft_calls_mv status: 'pending' / 'accepted' / 'rejected' |
| `pending_operation` | `string` | No | Operation type ('create'|'update'|'delete'|'duplicate') of the pending op |
| `pending_call_id` | `string` | No | call_id (idempotency key for ack) of the pending op |
| `updated_at` | `string` | No | Last updated timestamp |

---

## `MvInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Materialized view name |
| `definition` | `string` | Yes | SQL definition of the view |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the view |

---

## `OperationInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Operation name |
| `description` | `string` | Yes | Human-readable description of the operation |
| `params` | [`ParamInfo`](#paraminfo)[] | Yes | List of operation parameters |
| `returns` | `object` | No | Return type schema |

---

## `OperationPrompts`

Starter prompts keyed by operation name.

Each key is an operation (e.g. "create", "search", "draft", "export")
and the value is a list of starter prompts for that operation.
The client picks from the operations the caller has permission for
and rotates through them.

| Field | Type | Required | Description |
|---|---|---|---|
| `prompts` | `object` | No | Map of operation name to starter prompts |

---

## `PageMetaItem`

| Field | Type | Required | Description |
|---|---|---|---|
| `title` | `string` | Yes | — |
| `description` | `string` | Yes | — |

---

## `ParamInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Parameter name |
| `type` | `string` | Yes | Parameter data type |
| `required` | `boolean` | Yes | Whether the parameter is required |
| `default` | `any` | No | Default value if not required |

---

## `ProducedMedia`

One asset produced by a generation run.

``resource_id`` is the canonical id the per-artifact download tools
accept (e.g. ``Scenario_Image_Download(image_id=resource_id)`` for
``modality="image"``). It maps to ``images_resource.id`` /
``videos_resource.id`` / ``audios_resource.id`` depending on the
modality.

| Field | Type | Required | Description |
|---|---|---|---|
| `modality` | `"image"` \| `"video"` \| `"audio"` | Yes | — |
| `resource_id` | `string` | Yes | — |
| `upload_id` | `string` | Yes | — |
| `mime_type` | `string` | No | — |
| `file_size` | `integer` | No | — |

---

## `ProfileSummary`

Caller identity derived from JWT — who you are on this page.

Superset of the old six-field version: now carries everything the client
needs so that ``/\{artifact\}/context`` fully replaces ``/profiles/context``
and the extra ``getLayoutContextData`` round-trip can be dropped.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Display name of the authenticated user |
| `role` | `string` | Yes | Role name (e.g. 'Super Administrator') |
| `role_level` | `integer` | Yes | Role hierarchy level (0 = highest privilege) |
| `department_ids` | `string`[] | Yes | Departments the user belongs to |
| `artifact_access` | `string`[] | Yes | Artifact types this role can access (sidebar visibility) |
| `role_permissions` | `any`[][] | Yes | Full (artifact, operation) permission tuples for granular page gating |
| `is_active` | `boolean` | Yes | Whether the user's profile is active |
| `id` | `string` | Yes | Profile UUID (SocketProvider, ProfileProvider) |
| `theme` | [`ThemeBundle`](#themebundle) | No | Resolved theme: hex primitives + derived oklch tokens + score thresholds |
| `session_id` | `string` | No | Current session UUID |
| `is_emulation` | `boolean` | No | Whether user is in emulation mode (ProfileProvider) |
| `role_resources` | [`QGetProfileContextV4RoleResource`](#qgetprofilecontextv4roleresource)[] | No | All role resources for emulation display (ProfileProvider) |
| `scoped_roles` | `string`[] | No | Roles the user can emulate (ProfileProvider) |
| `active` | `boolean` | No | Alias for is_active (ProfileProvider uses this name) |

---

## `QGetProfileContextV4RoleResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `role` | `string` | No | — |
| `name` | `string` | No | — |
| `description` | `string` | No | — |
| `icon_value` | `string` | No | — |
| `color_hex` | `string` | No | — |

---

## `RunStatus`

Outcome of one watched run.

| Field | Type | Required | Description |
|---|---|---|---|
| `run_id` | `string` | Yes | — |
| `status` | `"pending"` \| `"completed"` \| `"failed"` | Yes | — |
| `modality` | `string` | No | Modality of generated output (image, video, text…) |
| `resource_ids` | `string`[] | No | Resource UUIDs produced by this run (e.g. images_resource ids) |
| `error` | `string` | No | — |

---

## `SimulationDepartment`

Department for simulation.

| Field | Type | Required | Description |
|---|---|---|---|
| `department_id` | `string` | No | UUID of the department |
| `name` | `string` | No | Department name |
| `description` | `string` | No | Department description text |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `SimulationDescriptionResource`

Description resource for simulation.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | UUID of the description resource |
| `description` | `string` | No | Description text |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `SimulationFieldError`

Per-field error from value resolution.

| Field | Type | Required | Description |
|---|---|---|---|
| `field` | `string` | Yes | Name of the field with the error |
| `message` | `string` | Yes | Human-readable error message |

---

## `SimulationFlagResource`

Flag option row — one per (name, type, value) entry in flags_resource.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Flag resource identifier |
| `name` | `string` | No | Flag display name |
| `type` | `string` | No | Flag type (e.g. 'simulation_active', 'practice') |
| `value` | `boolean` | No | Underlying bool value of this option |
| `description` | `string` | No | Flag description text |
| `icon_id` | `string` | No | Icon identifier for the flag |
| `icon` | `string` | No | Resolved SVG markup (hydrated from icons_resource) |
| `generated` | `boolean` | No | Whether the flag was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `SimulationNameResource`

Name resource for simulation.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | UUID of the name resource |
| `name` | `string` | No | Display name |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `SimulationResultItem`

Per-item result within a bulk create/update response.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `simulation_id` | `string` | No | UUID of the affected simulation |
| `message` | `string` | Yes | Human-readable result message |
| `errors` | [`SimulationFieldError`](#simulationfielderror)[] | No | List of per-field errors |

---

## `SimulationRubric`

Rubric catalog item.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | UUID of the rubric |
| `name` | `string` | No | Rubric name |
| `description` | `string` | No | Rubric description text |
| `standard_group_ids` | `string`[] | No | Associated standard group UUIDs |

---

## `SimulationScenario`

Scenario for simulation.

| Field | Type | Required | Description |
|---|---|---|---|
| `scenario_id` | `string` | No | UUID of the scenario |
| `name` | `string` | No | Scenario name |
| `description` | `string` | No | Scenario description text |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `show_problem_statement` | `boolean` | No | Whether to show problem statement |
| `show_objectives` | `boolean` | No | Whether to show objectives |
| `show_video` | `boolean` | No | Whether to show video |
| `show_text` | `boolean` | No | Whether to show text input |
| `show_audio` | `boolean` | No | Whether to show audio input |
| `show_copy_paste` | `boolean` | No | Whether to show copy/paste |
| `show_images` | `boolean` | No | Whether to show images |
| `show_questions` | `boolean` | No | Whether to show questions |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `SimulationScenarioFlag`

Scenario flag (denormalized: includes flag name/description/icon/type/value).

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | UUID of the scenario flag |
| `scenario_id` | `string` | No | UUID of the parent scenario |
| `flag_id` | `string` | No | UUID of the flag resource |
| `name` | `string` | No | Flag name |
| `type` | `string` | No | Underlying flag type (e.g. 'audio_enabled') |
| `value` | `boolean` | No | Underlying flag boolean value |
| `description` | `string` | No | Flag description text |
| `icon` | `string` | No | Icon identifier for the flag |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `SimulationScenarioFlagOption`

Option row for ScenarioFlags picker — one per (scenario × flag_type × value).

The junction row of scenario_flags_resource links (scenario_id, flag_id);
the client needs a pre-computed cross-product so each (scenario, type)
pair can be rendered as a switch. `flag_id` here is the underlying
flags_resource row ID for that (type, value) pair.

| Field | Type | Required | Description |
|---|---|---|---|
| `scenario_id` | `string` | No | UUID of the parent scenario |
| `flag_id` | `string` | No | UUID of the underlying flag resource (value-specific) |
| `type` | `string` | No | Flag type |
| `value` | `boolean` | No | Underlying flag boolean value |
| `name` | `string` | No | Flag display name |
| `description` | `string` | No | Flag description text |
| `icon` | `string` | No | Resolved SVG markup |

---

## `SimulationScenarioPosition`

Scenario position.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | UUID of the scenario position |
| `scenario_id` | `string` | No | UUID of the parent scenario |
| `value` | `integer` | No | Position value |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `SimulationScenarioRubric`

Scenario rubric.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | UUID of the scenario rubric |
| `scenario_id` | `string` | No | UUID of the parent scenario |
| `rubric_id` | `string` | No | UUID of the rubric resource |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `SimulationScenarioTimeLimit`

Scenario time limit.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | UUID of the scenario time limit |
| `scenario_id` | `string` | No | UUID of the parent scenario |
| `time_limit_seconds` | `integer` | No | Time limit in seconds |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `negative` | `boolean` | No | Whether the time limit is negative |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `TableInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Table name |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the table |

---

## `ThemeBundle`

Full theme payload for a page bootstrap.

Riding along on every ``/\{artifact\}/context`` response via
``ProfileSummary.theme``. Layers:
  - ``primitives`` / ``dark_primitives`` — hex inputs the settings
    editor reads/writes (light + dark palettes).
  - ``tokens`` / ``dark_tokens`` — oklch tokens the client paints with.
    ``ThemeStyle`` emits two ``<style>`` blocks: one scoped to
    ``:root:not(.dark)`` (light) and one to ``:root.dark`` (dark).
  - ``thresholds`` — numeric score thresholds for analytics components.
Empty-in → empty-out per token: missing values fall through to the
matching ``globals.css`` default.

| Field | Type | Required | Description |
|---|---|---|---|
| `primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (light palette, for the theme editor) |
| `tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for light mode (SSR CSS-var injection) |
| `dark_primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (dark palette, for the theme editor) |
| `dark_tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for dark mode (SSR CSS-var injection) |
| `thresholds` | [`Thresholds`](#thresholds) | No | Score thresholds resolved from the setting |

---

## `ThemePrimitives`

40 optional fields. The 17 essentials drive the rest; the other 23
are overrides for fine-tuning when derivation isn't what you want.

Empty primitive → empty token → client falls back to globals.css.

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `primary` | `string` | No | — |
| `accent` | `string` | No | — |
| `card` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `ring` | `string` | No | — |
| `border` | `string` | No | — |
| `destructive` | `string` | No | — |
| `success` | `string` | No | — |
| `warning` | `string` | No | — |
| `info` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `input` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `ThemeTokens`

40 fully-resolved CSS variable values (snake_case 1:1 with vars).

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `accent` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `border` | `string` | No | — |
| `input` | `string` | No | — |
| `ring` | `string` | No | — |
| `success` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `Thresholds`

Numeric score thresholds resolved from the active setting.

Server pre-buckets dashboard metrics into ``success | warning | danger |
neutral`` already, so most components don't need these values. Surface
them for chart reference lines, tooltips, and any client-side bucketing.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `integer` | Yes | Score >= this counts as success |
| `warning` | `integer` | Yes | Score >= this counts as warning |
| `danger` | `integer` | Yes | Score < success threshold but >= this counts as danger; below is neutral/no-data |

---

## `UpdateSimulationItem`

Single simulation item for update — simulation_id required, all fields optional.

Only provided fields are updated (partial update).

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | UUID of the simulation to update |
| `name_id` | `string` | No | UUID of the name resource |
| `name` | `string` | No | Display name value |
| `description_id` | `string` | No | UUID of the description resource |
| `description` | `string` | No | Description text value |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `department_ids` | `string`[] | No | Associated department UUIDs |
| `scenario_ids` | `string`[] | No | Associated scenario UUIDs |
| `scenario_flag_ids` | `string`[] | No | Associated scenario flag UUIDs |
| `scenario_position_ids` | `string`[] | No | Associated scenario position UUIDs |
| `scenario_rubric_ids` | `string`[] | No | Associated scenario rubric UUIDs |
| `scenario_time_limit_ids` | `string`[] | No | Associated scenario time limit UUIDs |
| `departments` | `string`[] | No | Department names for matching |
| `scenarios` | `string`[] | No | Scenario names for matching |

---

## `UpdateSimulationPatch`

Shared patch for bulk-update-all-matching mode.

Inherits every field from ``UpdateSimulationItem`` and just relaxes
``id`` to optional — the bulk impl stamps the resolved id onto a
clone of the patch per matched row, so any client-supplied id is
ignored. Sparse semantics: only fields the client sets are written.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Ignored — bulk impl stamps the resolved simulation id per matched row |
| `name_id` | `string` | No | UUID of the name resource |
| `name` | `string` | No | Display name value |
| `description_id` | `string` | No | UUID of the description resource |
| `description` | `string` | No | Description text value |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `department_ids` | `string`[] | No | Associated department UUIDs |
| `scenario_ids` | `string`[] | No | Associated scenario UUIDs |
| `scenario_flag_ids` | `string`[] | No | Associated scenario flag UUIDs |
| `scenario_position_ids` | `string`[] | No | Associated scenario position UUIDs |
| `scenario_rubric_ids` | `string`[] | No | Associated scenario rubric UUIDs |
| `scenario_time_limit_ids` | `string`[] | No | Associated scenario time limit UUIDs |
| `departments` | `string`[] | No | Department names for matching |
| `scenarios` | `string`[] | No | Scenario names for matching |

---

## `app__infra__simulation__types__DraftFormState`

Full form state after draft patch — server is source of truth.

Client replaces its local form state with this after every successful patch.

| Field | Type | Required | Description |
|---|---|---|---|
| `name_id` | `string` | No | UUID of the selected name resource |
| `name` | `string` | No | Saved name value |
| `description_id` | `string` | No | UUID of the selected description resource |
| `description` | `string` | No | Saved description value |
| `flag_ids` | `string`[] | No | Selected flag UUIDs |
| `active` | `boolean` | No | Echoed simulation_active flag state |
| `practice` | `boolean` | No | Echoed practice flag state |
| `department_ids` | `string`[] | No | Selected department UUIDs |
| `scenario_ids` | `string`[] | No | Selected scenario UUIDs |
| `scenario_flag_ids` | `string`[] | No | Selected scenario flag UUIDs |
| `scenario_flag_values` | [`DraftScenarioFlagDenormValue`](#draftscenarioflagdenormvalue)[] | No | Echoed denormalized (scenario_id, type, value) entries |
| `scenario_position_ids` | `string`[] | No | Selected scenario position UUIDs |
| `scenario_rubric_ids` | `string`[] | No | Selected scenario rubric UUIDs |
| `scenario_time_limit_ids` | `string`[] | No | Selected scenario time limit UUIDs |
| `pending_ids` | `string`[] | No | Pending resource UUIDs (empty until tool-layer support exists) |

---

## `app__infra__simulation__types__SectionFilter`

Per-section filter options for GET requests.

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Filter options by search text |
| `limit` | `integer` | No | Max options to return |
| `selected` | `boolean` | No | Only return selected items |
| `suggested` | `boolean` | No | Only return suggested items |
| `include` | `boolean` | No | Include this section in response (default true) |
| `parameter_ids` | `string`[] | No | Reserved for parity with persona pattern |

---

---

# `GET` `/system/watch`

Route: /api-reference/system/get-system-watch

# `GET` `/system/watch`

System Watch

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `group_id` | query | No | — |
| `run_id` | query | No | Optional run filter. If provided, only events whose envelope run_id matches are streamed. Omit to receive every system event in the group (the FE default). |

## Response

```
{}
```

---

# `POST` `/system/activity`

Route: /api-reference/system/post-system-activity

# `POST` `/system/activity`

Get Activity

## Request Body (`ActivityRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `date_from` | `string` | No | Filter start date |
| `date_to` | `string` | No | Filter end date |
| `department_ids` | `string`[] | No | Department IDs to filter by |
| `role_ids` | `string`[] | No | Role resource IDs to filter profiles by |
| `page_limit` | `integer` | No | Max summary items per page |
| `page_offset` | `integer` | No | Summary pagination offset |
| `summary_profile_id` | `string` | No | Profile ID to focus the summary card |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`ActivityResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `sessions_count` | `integer` | No | Total number of sessions |
| `active_profiles_count` | `integer` | No | Number of active profiles |
| `logins_count` | `integer` | No | Total number of logins |
| `emulations_count` | `integer` | No | Total number of emulations |
| `profile_summary` | [`ProfileSummaryItem`](/api-reference/system/types#profilesummaryitem)[] | No | Per-profile activity summaries |
| `problems` | [`ActivityProblemItem`](/api-reference/system/types#activityproblemitem)[] | No | Recent problems for the activity panel |
| `resources` | [`ActivityResources`](/api-reference/system/types#activityresources) | No | Activity resource metadata |
| `analytics` | [`AnalyticsFacets`](/api-reference/system/types#analyticsfacets) | No | Inline analytics facets for SSR |
| `history` | [`ActivityHistoryResponse`](/api-reference/system/types#activityhistoryresponse) | No | Always null on /activity/get — use /system/sessions instead |

---

# `POST` `/system/audio_download`

Route: /api-reference/system/post-system-audio-download

# `POST` `/system/audio_download`

Download Audio

Download an audio file by audio resource ID with range support for seeking.

## Request Body (`AudioDownloadGroupApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `audio_id` | `string` | Yes | UUID of the audios_resource to download |

## Response

```
{}
```

---

# `POST` `/system/call_download`

Route: /api-reference/system/post-system-call-download

# `POST` `/system/call_download`

Download Call

Download a call file by call resource ID with range support.

## Request Body (`CallDownloadGroupApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `call_id` | `string` | Yes | UUID of the calls_resource to download |

## Response

```
{}
```

---

# `POST` `/system/context`

Route: /api-reference/system/post-system-context

# `POST` `/system/context`

Get System Context

Get page context for the system artifact.

Returns docs + profile identity + evaluated permissions in a single call.
Routed through the audit wrapper so ``snapshot_key`` replays a consistent
view across related reads.

## Request Body (`DocsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entity_id` | `string` | No | — |
| `snapshot_key` | `string` | No | — |
| `schema` | `boolean` | No | If true, include MCP/tooling schema metadata (artifact, entries, resources, permission_docs, api_operations). Defaults to false for lean page-bootstrap responses. |

## Response (`ComposedContextResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Artifact name |
| `type` | `string` | Yes | Artifact type identifier |
| `description` | `string` | Yes | Human-readable description |
| `artifact` | [`DocsResponse`](/api-reference/system/types#docsresponse) | No | Artifact tool documentation (None unless schema=true) |
| `entries` | [`DocsResponse`](/api-reference/system/types#docsresponse)[] | No | Entry documentation list (None unless schema=true) |
| `resources` | [`DocsResponse`](/api-reference/system/types#docsresponse)[] | No | Resource documentation list (None unless schema=true) |
| `permission_docs` | [`OperationInfo`](/api-reference/system/types#operationinfo)[] | No | Permission function signatures for MCP/dev tooling (None unless schema=true) |
| `api_operations` | [`OperationInfo`](/api-reference/system/types#operationinfo)[] | No | API operation documentation (None unless schema=true) |
| `page_metadata` | [`DocsApiResponse`](/api-reference/system/types#docsapiresponse) | No | Page-level metadata |
| `prompts` | [`OperationPrompts`](/api-reference/system/types#operationprompts) | No | Starter prompts keyed by operation |
| `profile` | [`ProfileSummary`](/api-reference/system/types#profilesummary) | Yes | Caller identity from JWT |
| `caller_permissions` | [`CallerPermissions`](/api-reference/system/types#callerpermissions) | Yes | Evaluated permissions for this caller |

---

# `POST` `/system/export`

Route: /api-reference/system/post-system-export

# `POST` `/system/export`

Export System

Artifact-level system export.

Dispatches on ``body.view`` to per-view exports (activity, pricing,
group, session, health) and returns ``\{file_id, file_name, row_count\}``.
Client downloads via ``/api/system/download/\{file_id\}`` (BFF) →
``/system/file/download``.

## Request Body (`ExportSystemApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `view` | `string` | Yes | View discriminator: 'activity' | 'pricing' | 'group' | 'session' | 'health' |
| `session_id` | `string` | No | Target session UUID (required for view='session') |
| `group_id` | `string` | No | Target group UUID (required for view='group') |
| `mode` | `string` | No | Optional sub-mode within a view. Currently recognized: view=reports → mode='brightspace' (gradebook CSV only); view=home → mode='certificate' (PDF cert only) or 'attempts' (CSV only). Default (None) returns the full per-view bundle. |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior export; on the ack, the server-minted soft key to activate/reject a staged export |
| `soft` | `boolean` | No | Stage the export dormant (file chain active=False) — agent proposes; accept activates. Sim-env 'dormant export' primitive. |
| `accept` | `boolean` | No | Ack: True activates the staged export, False rejects. Only meaningful with idempotency_key |

## Response (`ExportSystemApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource holding the export bytes |
| `file_name` | `string` | Yes | Suggested download file name |
| `row_count` | `integer` | Yes | Number of data rows in the export |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with accept to activate/reject the staged export. |

---

# `POST` `/system/file_download`

Route: /api-reference/system/post-system-file-download

# `POST` `/system/file_download`

Download File

Download a file by file resource ID.

## Request Body (`FileDownloadGroupApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource to download |

## Response

```
{}
```

---

# `POST` `/system/file_preview`

Route: /api-reference/system/post-system-file-preview

# `POST` `/system/file_preview`

Preview File

Return a PNG preview of the first page of a PDF upload.

## Request Body (`FilePreviewGroupApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource to preview |

## Response

```
{}
```

---

# `POST` `/system/generate`

Route: /api-reference/system/post-system-generate

# `POST` `/system/generate`

Generate System

Trigger system generation. Returns immediately; progress via events.

## Request Body (`ArtifactGenerateRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `instructions` | `string`[] | No | — |
| `config` | [`GenerateConfig`](/api-reference/system/types#generateconfig) | No | — |
| `modalities` | `string`[] | No | — |
| `audios_id` | `string` | No | — |
| `conversation_id` | `string` | No | — |
| `trace_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `accept` | `boolean` | No | — |
| `wait_for_complete` | `boolean` | No | — |

## Response (`ArtifactGenerateResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `run_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `eval` | [`EvalSetup`](/api-reference/system/types#evalsetup) | No | — |
| `produced_media` | [`ProducedMedia`](/api-reference/system/types#producedmedia)[] | No | — |

---

# `POST` `/system/generations`

Route: /api-reference/system/post-system-generations

# `POST` `/system/generations`

Generations System

List system generation groups — composable infra architecture.

## Request Body (`GenerationsSystemApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GenerationsSystemApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `items` | [`GenerationsSystemListItem`](/api-reference/system/types#generationssystemlistitem)[] | No | Generation groups |
| `total_count` | `integer` | No | Total number of matching generations |

---

# `POST` `/system/group`

Route: /api-reference/system/post-system-group

# `POST` `/system/group`

Group System

Resolve or create the session's system group, optionally naming it.

## Request Body (`GroupSystemApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | No | Existing group UUID (omit to create or reuse via time window) |
| `snapshot_key` | `string` | No | Snapshot key for SETNX-race convergence on a single group across concurrent reads (e.g. parallel /context + /group + /search fan-out on page load). Echoed back in the response. |
| `include_detail` | `boolean` | No | When True, embed runs+messages+hydrated resources alongside the lean resolve fields. |
| `message_limit` | `integer` | No | When include_detail=True: maximum number of messages per run to return. |
| `message_offset` | `integer` | No | When include_detail=True: message pagination offset. |

## Response (`GroupSystemApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Resolved or newly created group UUID |
| `name` | `string` | No | The group's current title (latest active group_names_entry, or 'New Chat' fallback for freshly minted groups) |
| `snapshot_key` | `string` | No | Snapshot key echoed back — the UUID concurrent fan-out reads converged on via SETNX. Mirrors the resolved group_id. |
| `runs` | [`GroupRun`](/api-reference/system/types#grouprun)[] | No | Conversation history — populated when resolving an existing group for fetch |
| `group_exists` | `boolean` | No | (detail) Whether the group exists in storage — populated when ``include_resources=True`` |
| `actor_name` | `string` | No | (detail) Display name of the current actor (caller profile) |
| `total_message_count` | `integer` | No | (detail) Total number of messages in the group |
| `models` | [`GroupResource`](/api-reference/system/types#groupresource)[] | No | (detail) Models used in the group |
| `agents` | [`GroupResource`](/api-reference/system/types#groupresource)[] | No | (detail) Agents used in the group |
| `profiles` | [`GroupResource`](/api-reference/system/types#groupresource)[] | No | (detail) Profiles that authored runs in this group |

---

# `POST` `/system/groups`

Route: /api-reference/system/post-system-groups

# `POST` `/system/groups`

Search Groups

Get paginated groups list with cost data (canonical groups list).

## Request Body (`ListPricingRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `start_date` | `string` | No | Filter start date |
| `end_date` | `string` | No | Filter end date |
| `date_from` | `string` | No | Alias for start date |
| `date_to` | `string` | No | Alias for end date |
| `department_ids` | `string`[] | No | Department IDs to filter by |
| `model_id` | `string` | No | Model UUID to filter by (legacy singular) |
| `model_ids` | `string`[] | No | Model UUIDs to filter by (multi, preferred) |
| `profile_ids` | `string`[] | No | Profile UUIDs (human users) to filter by |
| `agent_ids` | `string`[] | No | Agent UUIDs (LLM agents) to filter by |
| `search` | `string` | No | Group name search (ILIKE) |
| `page` | `integer` | No | Pagination page number |
| `page_size` | `integer` | No | Items per page |
| `sort_by` | `string` | No | Sort field (date | total_cost | total_tokens | run_count) |
| `sort_order` | `string` | No | Sort direction (asc or desc) |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`ListPricingResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | [`PricingGroupItem`](/api-reference/system/types#pricinggroupitem)[] | No | Pricing group rows |
| `total_count` | `integer` | No | Total number of matching records |
| `page` | `integer` | No | Current page number |
| `page_size` | `integer` | No | Items per page |
| `total_pages` | `integer` | No | Total number of pages |

---

# `POST` `/system/health`

Route: /api-reference/system/post-system-health

# `POST` `/system/health`

Get Health

Get health artifact data.

## Request Body (`HealthRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `service` | `string` | No | Service name to filter by |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`HealthResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `views` | [`HealthViews`](/api-reference/system/types#healthviews) | No | Health view data |
| `total_count` | `integer` | No | Total number of health entries |
| `analytics` | [`AnalyticsFacets`](/api-reference/system/types#analyticsfacets) | No | Analytics facets for filtering |

---

# `POST` `/system/image_download`

Route: /api-reference/system/post-system-image-download

# `POST` `/system/image_download`

Download Image

Download an image file by image resource ID.

## Request Body (`ImageDownloadGroupApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `image_id` | `string` | Yes | UUID of the images_resource to download |

## Response

```
{}
```

---

# `POST` `/system/pricing`

Route: /api-reference/system/post-system-pricing

# `POST` `/system/pricing`

Get Pricing

Get pricing top chart — daily cost aggregation + filter options.

## Request Body (`PricingRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `start_date` | `string` | No | Filter start date |
| `end_date` | `string` | No | Filter end date |
| `date_from` | `string` | No | Alias for start date |
| `date_to` | `string` | No | Alias for end date |
| `department_ids` | `string`[] | No | Department IDs to filter by |
| `page_limit` | `integer` | No | Max chart items per page |
| `page_offset` | `integer` | No | Chart pagination offset |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`PricingResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `daily` | [`PricingDailyItem`](/api-reference/system/types#pricingdailyitem)[] | No | Daily pricing aggregations |
| `resources` | [`PricingResources`](/api-reference/system/types#pricingresources) | No | Pricing resource metadata |
| `total_count` | `integer` | No | Total number of matching records |
| `model_options` | [`FilterOption`](/api-reference/system/types#filteroption)[] | No | Model filter options |
| `agent_options` | [`FilterOption`](/api-reference/system/types#filteroption)[] | No | Agent filter options |
| `analytics` | [`AnalyticsFacets`](/api-reference/system/types#analyticsfacets) | No | Inline analytics facets for SSR |
| `history` | [`PricingHistoryResponse`](/api-reference/system/types#pricinghistoryresponse) | No | Always null on /pricing/get — use /system/groups instead |

---

# `POST` `/system/problem`

Route: /api-reference/system/post-system-problem

# `POST` `/system/problem`

Problem System

Report a system problem — composable infra architecture.

## Request Body (`ProblemSystemApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | `string` | Yes | Problem type: feature, bug, question, other |
| `message` | `string` | Yes | Problem description (max 1000 chars) |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior call instead of re-running |

## Response (`ProblemSystemApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `problem_id` | `string` | Yes | UUID of the created problem |
| `success` | `boolean` | No | Whether the problem was created |
| `message` | `string` | No | Status message |

---

# `POST` `/system/refresh`

Route: /api-reference/system/post-system-refresh

# `POST` `/system/refresh`

System Refresh

Refresh system-scope caches (Phase A: invalidate tags only).

## Request Body

```
{
  "anyOf": [
    {
      "$ref": "#/components/schemas/RefreshApiRequest"
    },
    {
      "type": "null"
    }
  ],
  "title": "Request"
}
```

## Response (`RefreshResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | — |
| `refreshed_views` | `string`[] | Yes | — |
| `invalidated_tags` | `string`[] | Yes | — |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/system/resolve`

Route: /api-reference/system/post-system-resolve

# `POST` `/system/resolve`

Resolve Problem

Resolve or unresolve a problem entry.

## Request Body (`ResolveProblemApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `problem_id` | `string` | Yes | ID of the problem to resolve |
| `resolved` | `boolean` | No | Whether the problem is resolved |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior call instead of re-running |

## Response (`ResolveProblemApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `problem_id` | `string` | Yes | ID of the resolved problem |
| `resolved` | `boolean` | Yes | Current resolved status |
| `updated_at` | `string` | Yes | Timestamp of the update |

---

# `POST` `/system/session`

Route: /api-reference/system/post-system-session

# `POST` `/system/session`

Get Session

Get session detail with groups and timeline.

## Request Body (`GetSessionDetailRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `session_id` | `string` | Yes | UUID of the session to fetch |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GetSessionDetailResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `session_exists` | `boolean` | No | Whether the session exists |
| `session_id` | `string` | No | UUID of the session |
| `profile_id` | `string` | No | UUID of the user profile |
| `profile_name` | `string` | No | Display name of the user profile |
| `session_created_at` | `string` | No | Timestamp when session was created |
| `active` | `boolean` | No | Whether the session is active |
| `groups` | [`ArtifactSessionGroup`](/api-reference/system/types#artifactsessiongroup)[] | No | Groups in the session |
| `timeline` | [`SessionTimelineItem`](/api-reference/system/types#sessiontimelineitem)[] | No | Timeline events for the session |

---

# `POST` `/system/sessions`

Route: /api-reference/system/post-system-sessions

# `POST` `/system/sessions`

Search Sessions

Get paginated sessions list with activity data (canonical sessions list).

## Request Body (`ListActivityRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `date_from` | `string` | No | Filter start date |
| `date_to` | `string` | No | Filter end date |
| `department_ids` | `string`[] | No | Department IDs to filter by |
| `role_ids` | `string`[] | No | Role resource IDs to filter profiles by |
| `active` | `boolean` | No | Filter by active status |
| `page` | `integer` | No | Pagination page number |
| `page_size` | `integer` | No | Items per page |
| `sort_order` | `string` | No | Sort direction (asc or desc) |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`ListActivityResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | [`SessionListItem`](/api-reference/system/types#sessionlistitem)[] | No | Session history items |
| `total_count` | `integer` | No | Total number of matching records |
| `page` | `integer` | No | Current page number |
| `page_size` | `integer` | No | Items per page |
| `total_pages` | `integer` | No | Total number of pages |

---

# `POST` `/system/text_download`

Route: /api-reference/system/post-system-text-download

# `POST` `/system/text_download`

Download Text

Download a text file by text resource ID.

## Request Body (`TextDownloadGroupApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `text_id` | `string` | Yes | UUID of the texts_resource to download |

## Response

```
{}
```

---

# `POST` `/system/title`

Route: /api-reference/system/post-system-title

# `POST` `/system/title`

Title System

Rename a system's group (writes group_names_entry).

## Request Body (`TitleSystemApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Group to rename |
| `title` | `string` | Yes | New title (display name) for the group |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant rename |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`TitleSystemApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | The group that was renamed |
| `group_name_id` | `string` | Yes | UUID of the new group_names_entry row |
| `title` | `string` | Yes | The title that was set |
| `idempotency_key` | `string` | No | Operation key echoed back |

---

# `POST` `/system/video_download`

Route: /api-reference/system/post-system-video-download

# `POST` `/system/video_download`

Download Video

Download a video file by video resource ID with range support for seeking.

## Request Body (`VideoDownloadGroupApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `video_id` | `string` | Yes | UUID of the videos_resource to download |

## Response

```
{}
```

---

# `POST` `/system/watch`

Route: /api-reference/system/post-system-watch

# `POST` `/system/watch`

System Watch Once

One-shot snapshot of run state, snapshot-replayable via ``snapshot_key``.

## Request Body (`WatchApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Chat group whose events we watch |
| `run_id` | `string` | No | Specific run to watch (e.g. the ``run_id`` returned by a prior ``X_Generate`` call). If None, watches every active run in the group at call time. |
| `wait_for_complete` | `boolean` | No | If True, block until the watched run reaches a terminal (complete/failed) event or timeout fires. If False, return current state and exit immediately. |
| `timeout_seconds` | `integer` | No | Max wait time when ``wait_for_complete=True``. |
| `snapshot_key` | `string` | No | Read snapshot key — on the one-shot POST /watch, the audit wrapper records this watch's point-in-time view (latest run state at call time) keyed by it and replays the same view on any later call with the same key. Ignored by the SSE GET stream. |

## Response (`WatchApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `runs` | [`RunStatus`](/api-reference/system/types#runstatus)[] | Yes | — |
| `timed_out` | `boolean` | No | — |
| `waited_seconds` | `number` | No | — |

---

# System Types

Route: /api-reference/system/types

# System Types

## `ActivityHistoryResponse`

Embedded activity session history for the activity bundle endpoint.

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | [`SessionListItem`](#sessionlistitem)[] | No | Session history items |
| `total_count` | `integer` | No | Total number of matching records |
| `page` | `integer` | No | Current page number |
| `page_size` | `integer` | No | Items per page |
| `total_pages` | `integer` | No | Total number of pages |

---

## `ActivityProblemItem`

Recent problem displayed on the activity page.

| Field | Type | Required | Description |
|---|---|---|---|
| `problem_id` | `string` | Yes | Problem identifier |
| `profile_id` | `string` | No | Profile that reported the problem |
| `profile_name` | `string` | No | Profile display name |
| `session_id` | `string` | No | Associated session |
| `type` | `string` | Yes | Problem type |
| `message` | `string` | Yes | Problem message |
| `resolved` | `boolean` | No | Whether the problem is resolved |
| `created_at` | `string` | Yes | Problem creation timestamp |

---

## `ActivityResources`

Activity resource metadata.

| Field | Type | Required | Description |
|---|---|---|---|
| `profiles` | `object` | No | Profile resources keyed by ID |

---

## `AnalyticsFacets`

Resolved analytics facets — embeddable in any artifact response.

Contains filter field visibility, available options for dropdowns,
and date range boundaries. Returned inline from artifact get/search
responses so each page has its filter facets ready for SSR.

| Field | Type | Required | Description |
|---|---|---|---|
| `fields` | [`AnalyticsFilterFields`](#analyticsfilterfields) | Yes | Filter field visibility configuration |
| `department_options` | [`AnalyticsFilterOption`](#analyticsfilteroption)[] | No | Department dropdown options |
| `cohort_options` | [`AnalyticsFilterOption`](#analyticsfilteroption)[] | No | Cohort dropdown options |
| `role_options` | [`AnalyticsRoleOption`](#analyticsroleoption)[] | No | Available role resource options |
| `attempt_options` | `string`[] | No | Available attempt options |
| `date_range_earliest` | `string` | No | Earliest available date for filtering |
| `date_range_latest` | `string` | No | Latest available date for filtering |

---

## `AnalyticsFilterField`

Visibility/disabled state for a single filter field.

| Field | Type | Required | Description |
|---|---|---|---|
| `visible` | `boolean` | No | Whether the filter field is visible |
| `disabled` | `boolean` | No | Whether the filter field is disabled |

---

## `AnalyticsFilterFields`

Per-page filter field visibility configuration.

| Field | Type | Required | Description |
|---|---|---|---|
| `date_range` | [`AnalyticsFilterField`](#analyticsfilterfield) | No | Date range filter config |
| `departments` | [`AnalyticsFilterField`](#analyticsfilterfield) | No | Department filter config |
| `cohorts` | [`AnalyticsFilterField`](#analyticsfilterfield) | No | Cohort filter config |
| `roles` | [`AnalyticsFilterField`](#analyticsfilterfield) | No | Role filter config |
| `attempts` | [`AnalyticsFilterField`](#analyticsfilterfield) | No | Attempt filter config |

---

## `AnalyticsFilterOption`

A single filter option for dropdown selectors.

| Field | Type | Required | Description |
|---|---|---|---|
| `value` | `string` | Yes | Option value for the filter |
| `label` | `string` | Yes | Human-readable option label |

---

## `AnalyticsRoleOption`

Hydrated role resource option for analytics role filters.

| Field | Type | Required | Description |
|---|---|---|---|
| `value` | `string` | Yes | Option value for the filter |
| `label` | `string` | Yes | Human-readable option label |
| `id` | `string` | Yes | Role resource UUID |
| `name` | `string` | Yes | Role resource name |
| `description` | `string` | No | Role description |
| `icon_id` | `string` | No | Icon resource UUID |
| `color_id` | `string` | No | Color resource UUID |
| `level` | `integer` | Yes | Role privilege level |

---

## `ArtifactSessionGroup`

Single group entry for a session.

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | UUID of the group |
| `group_name` | `string` | No | Name of the group |
| `first_run_at` | `string` | No | Timestamp of the first run |
| `last_run_at` | `string` | No | Timestamp of the last run |
| `run_count` | `integer` | No | Number of runs in the group |
| `total_tokens` | `integer` | No | Total tokens used in the group |
| `total_cost` | `string` | No | Total cost of the group |

---

## `CallerPermissions`

Evaluated permissions for the current caller on this artifact type.

| Field | Type | Required | Description |
|---|---|---|---|
| `can_create` | `boolean` | Yes | Whether the caller can create new artifacts |
| `can_draft` | `boolean` | Yes | Whether the caller can create/update drafts |
| `can_duplicate` | `boolean` | Yes | Whether the caller can duplicate artifacts |
| `has_access` | `boolean` | No | Whether the caller can view this entity |
| `can_edit` | `boolean` | No | Whether the caller can edit this entity |
| `can_delete` | `boolean` | No | Whether the caller can delete this entity |
| `disabled_reason` | `string` | No | Human-readable reason if editing is disabled |

---

## `ColumnInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Column name |
| `type` | `string` | Yes | Column data type |
| `nullable` | `boolean` | Yes | Whether the column is nullable |

---

## `DocsApiResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `list` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `detail` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `new` | [`PageMetaItem`](#pagemetaitem) | Yes | — |

---

## `DocsResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Resource or entry name |
| `type` | `string` | Yes | Resource or entry type identifier |
| `description` | `string` | Yes | Human-readable description |
| `materialized_view` | [`MvInfo`](#mvinfo) | No | Materialized view metadata |
| `tables` | [`TableInfo`](#tableinfo)[] | Yes | Related database tables |
| `operations` | [`OperationInfo`](#operationinfo)[] | Yes | Available operations |

---

## `EvalSetup`

Run-level eval scaffold — first-class on the generate response.

Audit's ``**output`` spread carries this onto
``<artifact>.generate.completed``. Null when no rubric-bearing
agent participated.

| Field | Type | Required | Description |
|---|---|---|---|
| `test_id` | `string` | Yes | — |
| `invocations` | [`InvocationSlot`](#invocationslot)[] | Yes | — |

---

## `FilterOption`

A single filter option for dropdown selectors.

| Field | Type | Required | Description |
|---|---|---|---|
| `value` | `string` | Yes | Internal value for the filter option |
| `label` | `string` | No | Display label for the filter option |
| `count` | `integer` | No | Number of matching records |

---

## `GenerateConfig`

Developer configuration — all optional with sensible defaults.

| Field | Type | Required | Description |
|---|---|---|---|
| `operations` | `string`[] | No | — |
| `dangerous` | `boolean` | No | — |
| `params` | `object` | No | — |
| `group_id` | `string` | No | — |

---

## `GenerationsSystemListItem`

Single generation group in the system generations response.

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | UUID of the generation group |
| `session_id` | `string` | No | UUID of the parent session |
| `group_name` | `string` | No | Name of the generation group |
| `created_at` | `string` | No | Timestamp of the generation |

---

## `GetHealthResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `date_hour` | `string` | Yes | — |
| `service` | `string` | Yes | — |
| `check_count` | `integer` | Yes | — |
| `ok_count` | `integer` | Yes | — |
| `fail_count` | `integer` | Yes | — |
| `uptime_percent` | `number` | Yes | — |
| `avg_latency_ms` | `number` | Yes | — |
| `min_latency_ms` | `number` | Yes | — |
| `max_latency_ms` | `number` | Yes | — |
| `latest_ok` | `boolean` | Yes | — |
| `latest_error` | `string` | Yes | — |

---

## `GetMetricsSearchResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `date_hour` | `string` | Yes | — |
| `sample_count` | `integer` | Yes | — |
| `avg_cpu_percent` | `number` | Yes | — |
| `min_cpu_percent` | `number` | Yes | — |
| `max_cpu_percent` | `number` | Yes | — |
| `avg_latency_ms` | `number` | Yes | — |
| `min_latency_ms` | `number` | Yes | — |
| `max_latency_ms` | `number` | Yes | — |
| `avg_memory_bytes` | `integer` | Yes | — |
| `min_memory_bytes` | `integer` | Yes | — |
| `max_memory_bytes` | `integer` | Yes | — |
| `max_requests_total` | `integer` | Yes | — |
| `max_errors_total` | `integer` | Yes | — |

---

## `GroupCall`

Tool call referenced by a message.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `tool_name` | `string` | No | — |
| `template_name` | `string` | No | — |
| `tool` | `object` | No | — |
| `ledger_status` | `string` | No | — |
| `ledger_operation` | `string` | No | — |
| `ledger_artifact` | `string` | No | — |
| `ledger_artifact_id` | `string` | No | — |

---

## `GroupMessage`

Message within a run.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `role` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `text_ids` | `string`[] | No | — |
| `audio_ids` | `string`[] | No | — |
| `image_ids` | `string`[] | No | — |
| `video_ids` | `string`[] | No | — |
| `file_ids` | `string`[] | No | — |
| `call_ids` | `string`[] | No | — |
| `calls` | [`GroupCall`](#groupcall)[] | No | — |
| `reasoning` | `boolean` | No | True when this row is a chain-of-thought trace persisted alongside the assistant answer (rendered as a collapsed accordion). |
| `in_context` | `boolean` | No | Whether this message is included in the LLM context for the next generation. Mirrors the dedup pass that builds chat history (see in_context_reason). |
| `in_context_reason` | `string` | No | Why this message is in/out of LLM context. 'kept' = included; 'deduped_read' = older read-only call to a tool that has a fresher result later in the group; future values may include 'trimmed_top_n'. |

---

## `GroupResource`

Lightweight `\{id, name\}` for cross-referencing run-level ids
(``model_id`` / ``agent_id`` / ``profile_id``) against human-readable
names on the analytics panel. Names come from the canonical
``get_models`` / ``get_agents`` / ``get_profiles`` black boxes.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `name` | `string` | No | — |

---

## `GroupRun`

Run within a group, with its messages.

Carries token / cost / model / agent / profile attribution so the
analytics view can render per-run cost + actor info without a
parallel detail shape. ``profile_id`` is the authoring profile
(human user), ``agent_id`` is the LLM-side actor, ``model_id`` is
the model used by that agent. All optional — runs predating these
columns or with unresolved attributions surface ``None``.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `input_tokens` | `integer` | No | — |
| `output_tokens` | `integer` | No | — |
| `cached_input_tokens` | `integer` | No | — |
| `cost` | `number` | No | — |
| `model_id` | `string` | No | — |
| `agent_id` | `string` | No | — |
| `profile_id` | `string` | No | — |
| `previous_context_start_index` | `integer` | No | Index in ``messages`` where the current run's own messages begin; earlier rows are previous-context replay. ``None`` when the run has no previous context attached. |
| `messages` | [`GroupMessage`](#groupmessage)[] | No | — |

---

## `HealthViews`

Health view data.

| Field | Type | Required | Description |
|---|---|---|---|
| `service_hourly` | [`GetHealthResponse`](#gethealthresponse)[] | No | Hourly service health entries |
| `metrics_hourly` | [`GetMetricsSearchResponse`](#getmetricssearchresponse)[] | No | Hourly metrics entries |

---

## `InvocationSlot`

One agent's slot in a multi-agent generation pool.

Populated by ``setup_generation_test`` when an agent carries a
rubric. The client uses these IDs to drive the eval workflow:
review the candidate's output, optionally fire a grader against
its ``invocation_id``, and promote/reject by call_id via the
existing ``idempotency_key + accept`` pattern.

| Field | Type | Required | Description |
|---|---|---|---|
| `invocation_id` | `string` | Yes | — |
| `agent_id` | `string` | Yes | — |
| `rubric_id` | `string` | No | — |

---

## `MvInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Materialized view name |
| `definition` | `string` | Yes | SQL definition of the view |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the view |

---

## `OperationInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Operation name |
| `description` | `string` | Yes | Human-readable description of the operation |
| `params` | [`ParamInfo`](#paraminfo)[] | Yes | List of operation parameters |
| `returns` | `object` | No | Return type schema |

---

## `OperationPrompts`

Starter prompts keyed by operation name.

Each key is an operation (e.g. "create", "search", "draft", "export")
and the value is a list of starter prompts for that operation.
The client picks from the operations the caller has permission for
and rotates through them.

| Field | Type | Required | Description |
|---|---|---|---|
| `prompts` | `object` | No | Map of operation name to starter prompts |

---

## `PageMetaItem`

| Field | Type | Required | Description |
|---|---|---|---|
| `title` | `string` | Yes | — |
| `description` | `string` | Yes | — |

---

## `ParamInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Parameter name |
| `type` | `string` | Yes | Parameter data type |
| `required` | `boolean` | Yes | Whether the parameter is required |
| `default` | `any` | No | Default value if not required |

---

## `PricingDailyItem`

A single day+model aggregation bucket.

| Field | Type | Required | Description |
|---|---|---|---|
| `date_key` | `string` | Yes | Date bucket key |
| `model_id` | `string` | No | Associated model identifier |
| `total_cost` | `string` | No | Total cost for this bucket |
| `run_count` | `integer` | No | Number of runs in this bucket |

---

## `PricingGroupItem`

A single group row in the pricing list.

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Pricing group identifier |
| `session_id` | `string` | No | Associated session ID |
| `group_name` | `string` | No | Group display name |
| `first_run_at` | `string` | No | Timestamp of first run |
| `last_run_at` | `string` | No | Timestamp of last run |
| `run_count` | `integer` | No | Number of runs in the group |
| `total_input_tokens` | `integer` | No | Total input tokens consumed |
| `total_output_tokens` | `integer` | No | Total output tokens generated |
| `total_tokens` | `integer` | No | Total tokens used |
| `total_cost` | `string` | No | Total cost for the group |
| `agent_ids` | `string`[] | No | Associated agent IDs |
| `model_ids` | `string`[] | No | Associated model IDs |
| `profile_ids` | `string`[] | No | Profile IDs (human users) who triggered runs in this group |
| `agent_names` | `string`[] | No | Associated agent names |
| `model_names` | `string`[] | No | Associated model names |
| `profile_names` | `string`[] | No | Display names of the profiles (human users) who triggered runs in this group |

---

## `PricingHistoryResponse`

Embedded pricing group history for the pricing bundle endpoint.

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | [`PricingGroupItem`](#pricinggroupitem)[] | No | Pricing group rows |
| `total_count` | `integer` | No | Total number of matching records |
| `page` | `integer` | No | Current page number |
| `page_size` | `integer` | No | Items per page |
| `total_pages` | `integer` | No | Total number of pages |

---

## `PricingResources`

Pricing resource metadata.

| Field | Type | Required | Description |
|---|---|---|---|
| `agents` | `object` | No | Agent resources keyed by ID |
| `models` | `object` | No | Model resources keyed by ID |

---

## `ProducedMedia`

One asset produced by a generation run.

``resource_id`` is the canonical id the per-artifact download tools
accept (e.g. ``Scenario_Image_Download(image_id=resource_id)`` for
``modality="image"``). It maps to ``images_resource.id`` /
``videos_resource.id`` / ``audios_resource.id`` depending on the
modality.

| Field | Type | Required | Description |
|---|---|---|---|
| `modality` | `"image"` \| `"video"` \| `"audio"` | Yes | — |
| `resource_id` | `string` | Yes | — |
| `upload_id` | `string` | Yes | — |
| `mime_type` | `string` | No | — |
| `file_size` | `integer` | No | — |

---

## `ProfileSummary`

Caller identity derived from JWT — who you are on this page.

Superset of the old six-field version: now carries everything the client
needs so that ``/\{artifact\}/context`` fully replaces ``/profiles/context``
and the extra ``getLayoutContextData`` round-trip can be dropped.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Display name of the authenticated user |
| `role` | `string` | Yes | Role name (e.g. 'Super Administrator') |
| `role_level` | `integer` | Yes | Role hierarchy level (0 = highest privilege) |
| `department_ids` | `string`[] | Yes | Departments the user belongs to |
| `artifact_access` | `string`[] | Yes | Artifact types this role can access (sidebar visibility) |
| `role_permissions` | `any`[][] | Yes | Full (artifact, operation) permission tuples for granular page gating |
| `is_active` | `boolean` | Yes | Whether the user's profile is active |
| `id` | `string` | Yes | Profile UUID (SocketProvider, ProfileProvider) |
| `theme` | [`ThemeBundle`](#themebundle) | No | Resolved theme: hex primitives + derived oklch tokens + score thresholds |
| `session_id` | `string` | No | Current session UUID |
| `is_emulation` | `boolean` | No | Whether user is in emulation mode (ProfileProvider) |
| `role_resources` | [`QGetProfileContextV4RoleResource`](#qgetprofilecontextv4roleresource)[] | No | All role resources for emulation display (ProfileProvider) |
| `scoped_roles` | `string`[] | No | Roles the user can emulate (ProfileProvider) |
| `active` | `boolean` | No | Alias for is_active (ProfileProvider uses this name) |

---

## `ProfileSummaryItem`

Per-profile aggregate stats for the summary card.

| Field | Type | Required | Description |
|---|---|---|---|
| `profile_id` | `string` | No | Profile identifier |
| `profile_name` | `string` | No | Profile display name |
| `sessions_count` | `integer` | No | Number of sessions |
| `logins_count` | `integer` | No | Number of logins |
| `grants_count` | `integer` | No | Number of grants |
| `problems_count` | `integer` | No | Number of problems |
| `activity_count` | `integer` | No | Total activity count |

---

## `QGetProfileContextV4RoleResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `role` | `string` | No | — |
| `name` | `string` | No | — |
| `description` | `string` | No | — |
| `icon_value` | `string` | No | — |
| `color_hex` | `string` | No | — |

---

## `RunStatus`

Outcome of one watched run.

| Field | Type | Required | Description |
|---|---|---|---|
| `run_id` | `string` | Yes | — |
| `status` | `"pending"` \| `"completed"` \| `"failed"` | Yes | — |
| `modality` | `string` | No | Modality of generated output (image, video, text…) |
| `resource_ids` | `string`[] | No | Resource UUIDs produced by this run (e.g. images_resource ids) |
| `error` | `string` | No | — |

---

## `SessionListItem`

Single session in the list response with hydrated metadata.

| Field | Type | Required | Description |
|---|---|---|---|
| `session_id` | `string` | Yes | UUID of the session |
| `profile_id` | `string` | No | UUID of the user profile |
| `profile_name` | `string` | No | Display name of the user profile |
| `session_created_at` | `string` | No | Timestamp when session was created |
| `session_updated_at` | `string` | No | Timestamp when session was last updated |
| `active` | `boolean` | No | Whether the session is active |
| `group_count` | `integer` | No | Number of groups in the session |
| `run_count` | `integer` | No | Number of runs in the session |
| `first_run_at` | `string` | No | Timestamp of the first run |
| `last_run_at` | `string` | No | Timestamp of the last run |
| `total_tokens` | `integer` | No | Total tokens used in the session |
| `total_cost` | `string` | No | Total cost of the session |
| `chat_count` | `integer` | No | Number of chats in the session |
| `attempt_count` | `integer` | No | Number of attempts in the session |
| `message_count` | `integer` | No | Number of messages in the session |
| `problem_count` | `integer` | No | Number of problems in the session |

---

## `SessionTimelineItem`

Single event in the unified session timeline.

| Field | Type | Required | Description |
|---|---|---|---|
| `event_type` | `string` | No | Type of the timeline event |
| `entity_id` | `string` | No | UUID of the related entity |
| `entity_name` | `string` | No | Name of the related entity |
| `created_at` | `string` | No | Timestamp when the event occurred |
| `extra_1` | `string` | No | Additional context field 1 |
| `extra_2` | `string` | No | Additional context field 2 |

---

## `TableInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Table name |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the table |

---

## `ThemeBundle`

Full theme payload for a page bootstrap.

Riding along on every ``/\{artifact\}/context`` response via
``ProfileSummary.theme``. Layers:
  - ``primitives`` / ``dark_primitives`` — hex inputs the settings
    editor reads/writes (light + dark palettes).
  - ``tokens`` / ``dark_tokens`` — oklch tokens the client paints with.
    ``ThemeStyle`` emits two ``<style>`` blocks: one scoped to
    ``:root:not(.dark)`` (light) and one to ``:root.dark`` (dark).
  - ``thresholds`` — numeric score thresholds for analytics components.
Empty-in → empty-out per token: missing values fall through to the
matching ``globals.css`` default.

| Field | Type | Required | Description |
|---|---|---|---|
| `primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (light palette, for the theme editor) |
| `tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for light mode (SSR CSS-var injection) |
| `dark_primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (dark palette, for the theme editor) |
| `dark_tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for dark mode (SSR CSS-var injection) |
| `thresholds` | [`Thresholds`](#thresholds) | No | Score thresholds resolved from the setting |

---

## `ThemePrimitives`

40 optional fields. The 17 essentials drive the rest; the other 23
are overrides for fine-tuning when derivation isn't what you want.

Empty primitive → empty token → client falls back to globals.css.

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `primary` | `string` | No | — |
| `accent` | `string` | No | — |
| `card` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `ring` | `string` | No | — |
| `border` | `string` | No | — |
| `destructive` | `string` | No | — |
| `success` | `string` | No | — |
| `warning` | `string` | No | — |
| `info` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `input` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `ThemeTokens`

40 fully-resolved CSS variable values (snake_case 1:1 with vars).

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `accent` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `border` | `string` | No | — |
| `input` | `string` | No | — |
| `ring` | `string` | No | — |
| `success` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `Thresholds`

Numeric score thresholds resolved from the active setting.

Server pre-buckets dashboard metrics into ``success | warning | danger |
neutral`` already, so most components don't need these values. Surface
them for chart reference lines, tooltips, and any client-side bucketing.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `integer` | Yes | Score >= this counts as success |
| `warning` | `integer` | Yes | Score >= this counts as warning |
| `danger` | `integer` | Yes | Score < success threshold but >= this counts as danger; below is neutral/no-data |

---

---

# `GET` `/test/watch`

Route: /api-reference/test/get-test-watch

# `GET` `/test/watch`

Test Watch

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `group_id` | query | No | — |
| `run_id` | query | No | Optional run filter. If provided, only events whose envelope run_id matches are streamed. Omit to receive every test event in the group (the FE default). |

## Response

```
{}
```

---

# `POST` `/test/archive`

Route: /api-reference/test/post-test-archive

# `POST` `/test/archive`

Archive Test Artifacts

Archive or unarchive benchmark tests by IDs.

## Request Body (`ArchiveTestsRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `test_ids` | `string`[] | Yes | UUIDs of tests to archive/unarchive |
| `archived` | `boolean` | No | Whether to archive or unarchive |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior call; on the ack, the server-minted soft key to activate/reject a staged archive |
| `soft` | `boolean` | No | Stage the archive dormant (active=False); accept activates the whole set |
| `accept` | `boolean` | No | Ack: True activates the staged archive, False rejects. Only meaningful with idempotency_key |

## Response (`ArchiveTestsResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `updated_count` | `integer` | No | Number of tests updated |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with accept to activate/reject the staged archive. |

---

# `POST` `/test/benchmark`

Route: /api-reference/test/post-test-benchmark

# `POST` `/test/benchmark`

Get Benchmark

Get benchmark artifact data with the canonical shared benchmark operation.

## Request Body (`BenchmarkRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `start_date` | `string` | No | Filter start date |
| `end_date` | `string` | No | Filter end date |
| `department_ids` | `string`[] | No | Department IDs to filter by |
| `history_page` | `integer` | No | History pagination page number |
| `history_page_size` | `integer` | No | History items per page |
| `history_eval_ids` | `string`[] | No | Eval IDs for history filter |
| `history_search` | `string` | No | Search string for history |
| `history_archived` | `boolean` | No | Filter by archived status |
| `history_sort_by` | `string` | No | History sort field |
| `history_sort_order` | `string` | No | History sort direction |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`BenchmarkResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `evals` | [`BenchmarkEvalOperational`](/api-reference/test/types#benchmarkevaloperational)[] | No | Eval cards for benchmark page |
| `departments` | [`BenchmarkDepartmentItem`](/api-reference/test/types#benchmarkdepartmentitem)[] | No | Department resources |
| `department_options` | [`FilterOption`](/api-reference/test/types#filteroption)[] | No | Department filter options |
| `date_range_earliest` | `string` | No | Earliest date in data range |
| `date_range_latest` | `string` | No | Latest date in data range |
| `history` | [`BenchmarkHistoryResponse`](/api-reference/test/types#benchmarkhistoryresponse) | No | Paginated test history |
| `analytics` | [`AnalyticsFacets`](/api-reference/test/types#analyticsfacets) | No | Inline analytics facets for SSR |

---

# `POST` `/test/call_download`

Route: /api-reference/test/post-test-call-download

# `POST` `/test/call_download`

Test Call Download

Download call JSON for a test.

## Request Body (`CallDownloadTestApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `call_id` | `string` | Yes | UUID of the call resource to download |

## Response

```
{}
```

---

# `POST` `/test/complete`

Route: /api-reference/test/post-test-complete

# `POST` `/test/complete`

Complete Test

## Request Body (`TestCompletePayload`)

| Field | Type | Required | Description |
|---|---|---|---|
| `test_id` | `string` | Yes | UUID of the test |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior call; on the ack, the server-minted soft key to activate/reject the staged completion |
| `soft` | `boolean` | No | Stage the completion dormant (all completion rows active=False); accept activates the whole set |
| `accept` | `boolean` | No | Ack: True activates the staged completion, False rejects. Only meaningful with idempotency_key |

## Response (`TestCompleteInternalResult`)

| Field | Type | Required | Description |
|---|---|---|---|
| `test_id` | `string` | Yes | — |
| `success` | `boolean` | No | — |
| `completed_count` | `integer` | No | — |
| `idempotency_key` | `string` | No | — |

---

# `POST` `/test/context`

Route: /api-reference/test/post-test-context

# `POST` `/test/context`

Get Test Context

Get page context for the test artifact.

Returns docs + profile identity + evaluated permissions in a single call.
Superset of /docs — clients can migrate from /docs to /context incrementally.

## Request Body (`DocsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entity_id` | `string` | No | — |
| `snapshot_key` | `string` | No | — |
| `schema` | `boolean` | No | If true, include MCP/tooling schema metadata (artifact, entries, resources, permission_docs, api_operations). Defaults to false for lean page-bootstrap responses. |

## Response (`ComposedContextResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Artifact name |
| `type` | `string` | Yes | Artifact type identifier |
| `description` | `string` | Yes | Human-readable description |
| `artifact` | [`DocsResponse`](/api-reference/test/types#docsresponse) | No | Artifact tool documentation (None unless schema=true) |
| `entries` | [`DocsResponse`](/api-reference/test/types#docsresponse)[] | No | Entry documentation list (None unless schema=true) |
| `resources` | [`DocsResponse`](/api-reference/test/types#docsresponse)[] | No | Resource documentation list (None unless schema=true) |
| `permission_docs` | [`OperationInfo`](/api-reference/test/types#operationinfo)[] | No | Permission function signatures for MCP/dev tooling (None unless schema=true) |
| `api_operations` | [`OperationInfo`](/api-reference/test/types#operationinfo)[] | No | API operation documentation (None unless schema=true) |
| `page_metadata` | [`DocsApiResponse`](/api-reference/test/types#docsapiresponse) | No | Page-level metadata |
| `prompts` | [`OperationPrompts`](/api-reference/test/types#operationprompts) | No | Starter prompts keyed by operation |
| `profile` | [`ProfileSummary`](/api-reference/test/types#profilesummary) | Yes | Caller identity from JWT |
| `caller_permissions` | [`CallerPermissions`](/api-reference/test/types#callerpermissions) | Yes | Evaluated permissions for this caller |

---

# `POST` `/test/decrypt`

Route: /api-reference/test/post-test-decrypt

# `POST` `/test/decrypt`

Decrypt Invocation Key

Decrypt a key scoped to an invocation entry.

## Request Body (`DecryptInvocationKeyApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `invocation_id` | `string` | Yes | Invocation identifier |
| `key_id` | `string` | Yes | Key identifier to decrypt |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`DecryptInvocationKeyApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `key` | `string` | No | Decrypted key value |
| `name` | `string` | No | Key display name |
| `actor_name` | `string` | No | Name of the actor who decrypted |

---

# `POST` `/test/draft`

Route: /api-reference/test/post-test-draft

# `POST` `/test/draft`

Patch Invocation Draft

Patch invocation draft — composable infra architecture.

## Request Body (`PatchInvocationDraftApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `draft_id` | `string` | No | Existing draft identifier to update |
| `input_draft_id` | `string` | No | Legacy alias for draft_id |
| `name` | `string` | No | Name value to create |
| `name_id` | `string` | No | Selected name identifier |
| `description` | `string` | No | Description value to create |
| `description_id` | `string` | No | Selected description identifier |
| `value_id` | `string` | No | Selected value identifier |
| `flag_ids` | `string`[] | No | Selected flag identifiers |
| `department_ids` | `string`[] | No | Selected department identifiers |
| `key_id` | `string` | No | Selected key identifier |
| `endpoint_id` | `string` | No | Selected endpoint identifier |
| `modality_ids` | `string`[] | No | Selected modality identifiers |
| `temperature_level_id` | `string` | No | Selected temperature level identifier |
| `pricing_id` | `string` | No | Selected pricing identifier |
| `reasoning_level_id` | `string` | No | Selected reasoning level identifier |
| `quality_ids` | `string`[] | No | Selected quality identifiers |
| `voice_ids` | `string`[] | No | Selected voice identifiers |
| `model_flag_ids` | `string`[] | No | Selected model flag identifiers (junction-row ids) |
| `model_flags` | `object`[] | No | Inline-create: list of \{model_id, flag_id\} pairs to upsert into model_flag_ids |
| `model_flag_values` | [`InvocationModelFlagValue`](/api-reference/test/types#invocationmodelflagvalue)[] | No | Denormalized per-(model, type) entries resolved server-side via (type, value) -> flag_id |
| `model_position_ids` | `string`[] | No | Selected model position identifiers |
| `model_rubric_ids` | `string`[] | No | Selected model rubric identifiers |
| `pending_ids` | `string`[] | No | Resource IDs to keep pending where supported |
| `idempotency_key` | `string` | No | Operation key for ack-style replay |
| `accept` | `boolean` | No | Accept or reject a dormant change when used with idempotency_key |

## Response (`PatchInvocationDraftApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the save succeeded |
| `draft_id` | `string` | Yes | Draft identifier |
| `idempotency_key` | `string` | No | Operation key echoed back when present |
| `message` | `string` | Yes | Status message |
| `form_state` | [`app__infra__invocation__types__DraftFormState`](/api-reference/test/types#app-infra-invocation-types-draftformstate) | No | Authoritative form state after save |

---

# `POST` `/test/drafts`

Route: /api-reference/test/post-test-drafts

# `POST` `/test/drafts`

Get Invocation Drafts

List invocation drafts owned by the current profile.

## Request Body (`GetInvocationDraftsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE substring) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GetInvocationDraftsApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entries` | [`GetInvocationDraftResponse`](/api-reference/test/types#getinvocationdraftresponse)[] | No | List of invocation draft entries |

---

# `POST` `/test/export`

Route: /api-reference/test/post-test-export

# `POST` `/test/export`

Export Test

Artifact-level test export.

Dispatches on ``body.view`` to per-view exports and returns
``\{file_id, file_name, row_count\}``. Client downloads via
``/api/test/download/\{file_id\}`` (BFF) → ``/test/file/download``.

## Request Body (`ExportTestApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `view` | `string` | No | View discriminator: 'single' | 'benchmark' | 'invocation' |
| `test_id` | `string` | No | UUID of the target test (required for 'single' and 'invocation') |
| `invocation_id` | `string` | No | UUID of the target invocation entry (optional for 'invocation') |
| `draft_id` | `string` | No | Optional draft id for 'invocation' view |
| `mode` | `string` | No | Optional sub-mode within a view. Currently recognized: view=reports → mode='brightspace' (gradebook CSV only); view=home → mode='certificate' (PDF cert only) or 'attempts' (CSV only). Default (None) returns the full per-view bundle. |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior export; on the ack, the server-minted soft key to activate/reject a staged export |
| `soft` | `boolean` | No | Stage the export dormant (file chain active=False) — agent proposes; accept activates. Sim-env 'dormant export' primitive. |
| `accept` | `boolean` | No | Ack: True activates the staged export, False rejects. Only meaningful with idempotency_key |

## Response (`ExportTestApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource holding the export bytes |
| `file_name` | `string` | Yes | Suggested download file name |
| `row_count` | `integer` | Yes | Number of data rows in the export |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with accept to activate/reject the staged export. |

---

# `POST` `/test/feedback`

Route: /api-reference/test/post-test-feedback

# `POST` `/test/feedback`

Create Feedback

Create test feedback for a specific tool call.

## Request Body (`CreateFeedbackApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `grade_id` | `string` | Yes | Grade entry to attach feedback to |
| `tool_call_id` | `string` | Yes | Tool call being graded |
| `standard_group_id` | `string` | Yes | Rubric standard group being scored |
| `score` | `integer` | No | Score for this criterion (1-5) |
| `feedback` | `string` | No | Feedback text |
| `run_id` | `string` | No | Run ID for audit linkage |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior call instead of re-running |

## Response

```
{
  "additionalProperties": true,
  "type": "object",
  "title": "Response Create Feedback Test Feedback Post"
}
```

---

# `POST` `/test/file_download`

Route: /api-reference/test/post-test-file-download

# `POST` `/test/file_download`

Download File

Download a file by file resource ID.

## Request Body (`FileDownloadTestApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource to download |

## Response

```
{}
```

---

# `POST` `/test/generate`

Route: /api-reference/test/post-test-generate

# `POST` `/test/generate`

Generate Test

Trigger test generation. Returns immediately; progress via events.

## Request Body (`ArtifactGenerateRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `instructions` | `string`[] | No | — |
| `config` | [`GenerateConfig`](/api-reference/test/types#generateconfig) | No | — |
| `modalities` | `string`[] | No | — |
| `audios_id` | `string` | No | — |
| `conversation_id` | `string` | No | — |
| `trace_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `accept` | `boolean` | No | — |
| `wait_for_complete` | `boolean` | No | — |

## Response (`ArtifactGenerateResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `run_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `eval` | [`EvalSetup`](/api-reference/test/types#evalsetup) | No | — |
| `produced_media` | [`ProducedMedia`](/api-reference/test/types#producedmedia)[] | No | — |

---

# `POST` `/test/generations`

Route: /api-reference/test/post-test-generations

# `POST` `/test/generations`

Generations Test

List test generation groups — composable infra architecture.

## Request Body (`GenerationsTestApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GenerationsTestApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `items` | [`GenerationsTestListItem`](/api-reference/test/types#generationstestlistitem)[] | No | Generation groups |
| `total_count` | `integer` | No | Total number of matching generations |

---

# `POST` `/test/get`

Route: /api-reference/test/post-test-get

# `POST` `/test/get`

Get Test Artifact

Get benchmark test artifact details with tests/invocations in parallel.

## Request Body (`GetTestArtifactRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `test_id` | `string` | Yes | UUID of the test to fetch |
| `configs_groups_page` | `integer` | No | 1-indexed page of group section headers |
| `configs_groups_page_size` | `integer` | No | Group headers per page |
| `configs_expanded` | `string`[] | No | Group IDs the user has expanded; rows fetched only for these |
| `configs_expanded_page_size` | `integer` | No | Rows per expanded group |
| `configs_search` | `string` | No | Free-text filter on group name |
| `configs_selected` | `string`[] | No | Run IDs currently selected in the picker; messages preloaded for preview |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GetTestArtifactResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `test` | [`GetTestResponse`](/api-reference/test/types#gettestresponse) | No | Test entry data |
| `invocations` | [`GetTestInvocationResponse`](/api-reference/test/types#gettestinvocationresponse)[] | No | Test invocations |
| `status` | `string` | No | Overall test status |
| `eval_name` | `string` | No | Name of the eval |
| `eval_description` | `string` | No | Description of the eval |
| `rubric_name` | `string` | No | Name of the rubric |
| `infinite_mode` | `boolean` | No | Whether infinite mode is enabled |
| `runs` | [`TestRunItem`](/api-reference/test/types#testrunitem)[] | No | Run items derived from invocations |
| `configs` | [`TestConfigItem`](/api-reference/test/types#testconfigitem)[] | No | Run configs only for groups in configs_expanded |
| `configs_groups` | [`TestConfigGroup`](/api-reference/test/types#testconfiggroup)[] | No | Group section headers (current outer page) |
| `configs_total` | `integer` | No | Total run configs across all groups (universe size) |
| `configs_groups_total` | `integer` | No | Total groups matching filters (outer pagination universe) |
| `configs_per_group_total` | `object` | No | group_id → total row count (used by inner pagination 'Show more' math) |
| `status_summary` | [`TestStatusSummary`](/api-reference/test/types#teststatussummary) | No | Summary of invocation statuses |
| `show_controls` | `boolean` | No | Whether to show UI controls |
| `current_invocation_id` | `string` | No | ID of the current invocation |
| `has_runs_or_groups` | `boolean` | No | Whether the test has runs or groups |
| `next_invocation_id` | `string` | No | UUID of the next uncompleted invocation, or null if all are done |
| `invocation_details` | [`InvocationDetail`](/api-reference/test/types#invocationdetail)[] | No | Per-invocation graded payloads (rubric_structure + runs[] with grading_state) |
| `entries` | [`TestEntries`](/api-reference/test/types#testentries) | No | Entry payloads by type |
| `resources` | [`TestResources`](/api-reference/test/types#testresources) | No | Resource maps keyed by ID |

---

# `POST` `/test/grade`

Route: /api-reference/test/post-test-grade

# `POST` `/test/grade`

Create Grade

Create a test grade.

## Request Body (`CreateGradeApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `invocation_id` | `string` | Yes | Test invocation to grade |
| `run_id` | `string` | No | Run ID for audit linkage |
| `score` | `integer` | No | Overall score (ignored when full=True) |
| `full` | `boolean` | No | When true, server resolves the rubric and assigns score=total_points (max marks). Callers don't need to know the rubric ceiling ahead of time. Overrides any caller-supplied score. |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior call instead of re-running |

## Response

```
{
  "additionalProperties": true,
  "type": "object",
  "title": "Response Create Grade Test Grade Post"
}
```

---

# `POST` `/test/group`

Route: /api-reference/test/post-test-group

# `POST` `/test/group`

Group Test

Resolve or create a test group with optional naming.

## Request Body (`GroupTestApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | No | Existing group UUID (omit to create or reuse via time window) |
| `snapshot_key` | `string` | No | Snapshot key for SETNX-race convergence on a single group across concurrent reads (e.g. parallel /context + /group + /search fan-out on page load). Echoed back in the response. |

## Response (`GroupTestApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Resolved or newly created group UUID |
| `name` | `string` | No | The group's current title (latest active group_names_entry, or 'New Chat' fallback for freshly minted groups) |
| `snapshot_key` | `string` | No | Snapshot key echoed back — the UUID concurrent fan-out reads converged on via SETNX. Mirrors the resolved group_id. |
| `runs` | [`GroupRun`](/api-reference/test/types#grouprun)[] | No | Conversation history — populated when resolving an existing group for fetch |
| `group_exists` | `boolean` | No | (detail) Whether the group exists in storage — populated when ``include_resources=True`` |
| `actor_name` | `string` | No | (detail) Display name of the current actor (caller profile) |
| `total_message_count` | `integer` | No | (detail) Total number of messages in the group |
| `models` | [`GroupResource`](/api-reference/test/types#groupresource)[] | No | (detail) Models used in the group |
| `agents` | [`GroupResource`](/api-reference/test/types#groupresource)[] | No | (detail) Agents used in the group |
| `profiles` | [`GroupResource`](/api-reference/test/types#groupresource)[] | No | (detail) Profiles that authored runs in this group |

---

# `POST` `/test/invocation_complete`

Route: /api-reference/test/post-test-invocation-complete

# `POST` `/test/invocation_complete`

Complete Invocation

## Request Body (`TestInvocationCompletePayload`)

| Field | Type | Required | Description |
|---|---|---|---|
| `test_id` | `string` | Yes | UUID of the test |
| `test_invocation_id` | `string` | Yes | UUID of the test invocation |
| `message` | `string` | No | Optional completion message |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior call; on the ack, the server-minted soft key to activate/reject the staged completion |
| `soft` | `boolean` | No | Stage the completion dormant (active=False); accept activates it |
| `accept` | `boolean` | No | Ack: True activates the staged completion, False rejects. Only meaningful with idempotency_key |

## Response (`TestInvocationCompleteInternalResult`)

| Field | Type | Required | Description |
|---|---|---|---|
| `invocation_id` | `string` | Yes | — |
| `completion_id` | `string` | No | — |
| `success` | `boolean` | No | — |
| `idempotency_key` | `string` | No | — |

---

# `POST` `/test/invocation_create`

Route: /api-reference/test/post-test-invocation-create

# `POST` `/test/invocation_create`

Create Invocation Endpoint

Create an invocation within a test.

## Request Body (`CreateInvocationApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `test_id` | `string` | Yes | — |
| `invocation_id` | `string` | No | — |
| `title` | `string` | No | — |
| `use_custom` | `boolean` | No | — |
| `position` | `integer` | No | — |
| `agent_ids` | `string`[] | No | — |
| `rubric_ids` | `string`[] | No | — |
| `quality_ids` | `string`[] | No | — |
| `department_ids` | `string`[] | No | — |
| `voice_ids` | `string`[] | No | — |
| `reasoning_level_ids` | `string`[] | No | — |
| `temperature_level_ids` | `string`[] | No | — |
| `modality_ids` | `string`[] | No | — |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior call instead of re-running |

## Response (`CreateInvocationApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `invocation_id` | `string` | Yes | UUID of the created test invocation |

---

# `POST` `/test/invocation_get`

Route: /api-reference/test/post-test-invocation-get

# `POST` `/test/invocation_get`

Invocation Get

Get hydrated resources for benchmark bundle customization.

## Request Body (`GetInvocationApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Invocation identifier |
| `invocation_id` | `string` | No | Invocation identifier |
| `benchmark_bundle_entry_id` | `string` | No | Legacy invocation identifier |
| `test_id` | `string` | No | Owning test identifier |
| `draft_id` | `string` | No | Optional draft identifier |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |
| `names` | [`app__infra__invocation__types__SectionFilter`](/api-reference/test/types#app-infra-invocation-types-sectionfilter) | No | Filter options for names section |
| `descriptions` | [`app__infra__invocation__types__SectionFilter`](/api-reference/test/types#app-infra-invocation-types-sectionfilter) | No | Filter options for descriptions section |
| `values` | [`app__infra__invocation__types__SectionFilter`](/api-reference/test/types#app-infra-invocation-types-sectionfilter) | No | Filter options for values section |
| `flags` | [`app__infra__invocation__types__SectionFilter`](/api-reference/test/types#app-infra-invocation-types-sectionfilter) | No | Filter options for flags section |
| `departments` | [`app__infra__invocation__types__SectionFilter`](/api-reference/test/types#app-infra-invocation-types-sectionfilter) | No | Filter options for departments section |
| `keys` | [`app__infra__invocation__types__SectionFilter`](/api-reference/test/types#app-infra-invocation-types-sectionfilter) | No | Filter options for keys section |
| `endpoints` | [`app__infra__invocation__types__SectionFilter`](/api-reference/test/types#app-infra-invocation-types-sectionfilter) | No | Filter options for endpoints section |
| `modalities` | [`app__infra__invocation__types__SectionFilter`](/api-reference/test/types#app-infra-invocation-types-sectionfilter) | No | Filter options for modalities section |
| `temperature_levels` | [`app__infra__invocation__types__SectionFilter`](/api-reference/test/types#app-infra-invocation-types-sectionfilter) | No | Filter options for temperature levels section |
| `pricing` | [`app__infra__invocation__types__SectionFilter`](/api-reference/test/types#app-infra-invocation-types-sectionfilter) | No | Filter options for pricing section |
| `reasoning_levels` | [`app__infra__invocation__types__SectionFilter`](/api-reference/test/types#app-infra-invocation-types-sectionfilter) | No | Filter options for reasoning levels section |
| `qualities` | [`app__infra__invocation__types__SectionFilter`](/api-reference/test/types#app-infra-invocation-types-sectionfilter) | No | Filter options for qualities section |
| `voices` | [`app__infra__invocation__types__SectionFilter`](/api-reference/test/types#app-infra-invocation-types-sectionfilter) | No | Filter options for voices section |
| `descriptions_search` | `string` | No | Legacy search string for descriptions |

## Response (`GetSuiteResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the acting user |
| `test_id` | `string` | No | Owning test identifier |
| `invocation_id` | `string` | No | Invocation identifier |
| `profile_has_access` | `boolean` | No | Whether profile has access |
| `can_edit` | `boolean` | No | Whether the actor can edit this invocation draft |
| `disabled_reason` | `string` | No | Reason editing is disabled, if any |
| `group_id` | `string` | No | Associated group ID |
| `show_ai_generate` | `boolean` | No | Whether to show AI generate anywhere |
| `pending_ids` | `string`[] | No | Pending resource identifiers when available |
| `names` | [`InvocationNameResource`](/api-reference/test/types#invocationnameresource)[] | No | Name resources |
| `descriptions` | [`InvocationDescriptionResource`](/api-reference/test/types#invocationdescriptionresource)[] | No | Description resources |
| `values` | [`InvocationValueResource`](/api-reference/test/types#invocationvalueresource)[] | No | Value resources |
| `flags` | [`InvocationFlagResource`](/api-reference/test/types#invocationflagresource)[] | No | Flag resources |
| `departments` | [`InvocationDepartmentResource`](/api-reference/test/types#invocationdepartmentresource)[] | No | Department resources |
| `keys` | [`InvocationKeyResource`](/api-reference/test/types#invocationkeyresource)[] | No | Key resources |
| `endpoints` | [`InvocationEndpointResource`](/api-reference/test/types#invocationendpointresource)[] | No | Endpoint resources |
| `modalities` | [`InvocationModalityResource`](/api-reference/test/types#invocationmodalityresource)[] | No | Modality resources |
| `temperature_levels` | [`InvocationTemperatureLevelResource`](/api-reference/test/types#invocationtemperaturelevelresource)[] | No | Temperature level resources |
| `pricing` | [`InvocationPricingResource`](/api-reference/test/types#invocationpricingresource)[] | No | Pricing resources |
| `reasoning_levels` | [`InvocationReasoningLevelResource`](/api-reference/test/types#invocationreasoninglevelresource)[] | No | Reasoning level resources |
| `qualities` | [`InvocationQualityResource`](/api-reference/test/types#invocationqualityresource)[] | No | Quality resources |
| `voices` | [`InvocationVoiceResource`](/api-reference/test/types#invocationvoiceresource)[] | No | Voice resources |
| `model_flags` | [`InvocationModelFlagResource`](/api-reference/test/types#invocationmodelflagresource)[] | No | Per-model flag junction rows |
| `model_flag_options` | [`InvocationModelFlagOptionResource`](/api-reference/test/types#invocationmodelflagoptionresource)[] | No | Cross-product (model × flag-type × value) options for the ModelFlags picker. |

---

# `POST` `/test/invocation_run`

Route: /api-reference/test/post-test-invocation-run

# `POST` `/test/invocation_run`

Run Invocation

## Request Body (`TestRunPayload`)

| Field | Type | Required | Description |
|---|---|---|---|
| `test_id` | `string` | Yes | UUID of the test |
| `test_invocation_id` | `string` | Yes | UUID of the test invocation |
| `test_invocation_trace_id` | `string` | No | UUID of the parent trace (test_invocation_traces_entry) |
| `run_id` | `string` | Yes | UUID of the runs_entry to bind |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior call; on the ack, the server-minted soft key to activate/reject the staged run binding |
| `soft` | `boolean` | No | Stage the run binding dormant (active=False); accept activates it |
| `accept` | `boolean` | No | Ack: True activates the staged run binding, False rejects. Only meaningful with idempotency_key |

## Response (`TestRunInternalResult`)

| Field | Type | Required | Description |
|---|---|---|---|
| `test_invocation_run_id` | `string` | Yes | — |
| `success` | `boolean` | No | — |
| `idempotency_key` | `string` | No | — |

---

# `POST` `/test/invocation_terminate`

Route: /api-reference/test/post-test-invocation-terminate

# `POST` `/test/invocation_terminate`

Terminate Invocation

## Request Body (`TestRunEndPayload`)

| Field | Type | Required | Description |
|---|---|---|---|
| `test_invocation_run_id` | `string` | Yes | UUID of the test_invocation_runs_entry to finalize |
| `success` | `boolean` | No | — |
| `error` | `boolean` | No | — |
| `message` | `string` | No | — |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior call instead of re-running |

## Response (`TestRunEndResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `test_invocation_run_id` | `string` | Yes | — |
| `completion_id` | `string` | Yes | — |
| `success` | `boolean` | No | — |

---

# `POST` `/test/invocation_trace`

Route: /api-reference/test/post-test-invocation-trace

# `POST` `/test/invocation_trace`

Test Trace

## Request Body (`TestTracePayload`)

| Field | Type | Required | Description |
|---|---|---|---|
| `test_id` | `string` | Yes | UUID of the test |
| `test_invocation_id` | `string` | Yes | UUID of the test invocation |
| `run_id` | `string` | No | Historical run_id we're replaying against (optional) |
| `tool_ids` | `string`[] | No | — |
| `modality_ids` | `string`[] | No | — |
| `voice_ids` | `string`[] | No | — |
| `temperature_level_ids` | `string`[] | No | — |
| `reasoning_level_ids` | `string`[] | No | — |
| `quality_ids` | `string`[] | No | — |
| `prompt_ids` | `string`[] | No | — |
| `instruction_ids` | `string`[] | No | — |
| `prompt_text` | `string` | No | User-typed system prompt; minted as a prompts_resource |
| `instructions` | `string`[] | No | User-typed instruction templates; each minted separately |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior call; on the ack, the server-minted soft key to perform/discard the staged trace |
| `soft` | `boolean` | No | Stage the trace (store intent without creating); accept performs it |
| `accept` | `boolean` | No | Ack: True performs the staged trace, False discards. Only meaningful with idempotency_key |

## Response (`TestTraceInternalResult`)

| Field | Type | Required | Description |
|---|---|---|---|
| `test_invocation_trace_id` | `string` | Yes | — |
| `success` | `boolean` | No | — |
| `idempotency_key` | `string` | No | — |

---

# `POST` `/test/invocations`

Route: /api-reference/test/post-test-invocations

# `POST` `/test/invocations`

List Invocations

List test invocations with pagination and filters.

## Request Body (`BenchmarkRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `start_date` | `string` | No | Filter start date |
| `end_date` | `string` | No | Filter end date |
| `department_ids` | `string`[] | No | Department IDs to filter by |
| `history_page` | `integer` | No | History pagination page number |
| `history_page_size` | `integer` | No | History items per page |
| `history_eval_ids` | `string`[] | No | Eval IDs for history filter |
| `history_search` | `string` | No | Search string for history |
| `history_archived` | `boolean` | No | Filter by archived status |
| `history_sort_by` | `string` | No | History sort field |
| `history_sort_order` | `string` | No | History sort direction |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`BenchmarkHistoryResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | [`BenchmarkHistoryItem`](/api-reference/test/types#benchmarkhistoryitem)[] | No | History items |
| `total_count` | `integer` | No | Total number of matching records |
| `page` | `integer` | No | Current page number |
| `page_size` | `integer` | No | Items per page |
| `eval_options` | [`FilterOption`](/api-reference/test/types#filteroption)[] | No | Eval filter options |
| `model_options` | [`FilterOption`](/api-reference/test/types#filteroption)[] | No | Model filter options |
| `profile_options` | [`FilterOption`](/api-reference/test/types#filteroption)[] | No | Profile filter options |
| `rubric_options` | [`FilterOption`](/api-reference/test/types#filteroption)[] | No | Rubric filter options |

---

# `POST` `/test/problem`

Route: /api-reference/test/post-test-problem

# `POST` `/test/problem`

Problem Test

Report a test problem — composable infra architecture.

## Request Body (`ProblemTestApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | `string` | Yes | Problem type: feature, bug, question, other |
| `message` | `string` | Yes | Problem description (max 1000 chars) |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior call instead of re-running |

## Response (`ProblemTestApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `problem_id` | `string` | Yes | UUID of the created problem |
| `success` | `boolean` | No | Whether the problem was created |
| `message` | `string` | No | Status message |

---

# `POST` `/test/refresh`

Route: /api-reference/test/post-test-refresh

# `POST` `/test/refresh`

Test Refresh

Refresh test materialized views and invalidate caches.

## Request Body

```
{
  "anyOf": [
    {
      "$ref": "#/components/schemas/RefreshApiRequest"
    },
    {
      "type": "null"
    }
  ],
  "title": "Request"
}
```

## Response (`RefreshResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | — |
| `refreshed_views` | `string`[] | Yes | — |
| `invalidated_tags` | `string`[] | Yes | — |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/test/search`

Route: /api-reference/test/post-test-search

# `POST` `/test/search`

Search Test

Search tests — composable infra architecture.

## Request Body (`SearchTestApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `eval_ids` | `string`[] | No | — |
| `department_ids` | `string`[] | No | — |
| `is_archived` | `boolean` | No | — |
| `start_date` | `string` | No | — |
| `end_date` | `string` | No | — |
| `eval_search` | `string` | No | — |
| `department_search` | `string` | No | — |
| `page_size` | `integer` | No | — |
| `page_offset` | `integer` | No | — |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`SearchTestApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `tests` | [`SearchTestItem`](/api-reference/test/types#searchtestitem)[] | No | Search result test items |
| `eval_filter` | [`ListFilterSection`](/api-reference/test/types#listfiltersection) | No | Eval filter section |
| `department_filter` | [`ListFilterSection`](/api-reference/test/types#listfiltersection) | No | Department filter section |
| `total_count` | `integer` | No | Total number of matching results |

---

# `POST` `/test/start`

Route: /api-reference/test/post-test-start

# `POST` `/test/start`

Start Test

Create a new test.

## Request Body (`TestStartPayload`)

| Field | Type | Required | Description |
|---|---|---|---|
| `eval_id` | `string` | Yes | UUID of the eval to test |
| `infinite_mode` | `boolean` | No | Whether to run in infinite mode |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior call; on the ack, the server-minted soft key to activate/reject the staged test |
| `soft` | `boolean` | No | Stage the test dormant (test+benchmark_test active=False); accept activates it |
| `accept` | `boolean` | No | Ack: True activates the staged test, False rejects. Only meaningful with idempotency_key |

## Response (`StartTestApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `test_id` | `string` | Yes | — |
| `invocation_id` | `string` | No | — |
| `benchmark_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |

---

# `POST` `/test/stop`

Route: /api-reference/test/post-test-stop

# `POST` `/test/stop`

Stop Test

Stop current test execution.

## Request Body (`TestStopPayload`)

| Field | Type | Required | Description |
|---|---|---|---|
| `invocation_id` | `string` | Yes | UUID of the test invocation to stop |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior call; on the ack, the server-minted soft key to emit/discard the staged stop |
| `soft` | `boolean` | No | Stage the stop (record intent without emitting); accept emits it |
| `accept` | `boolean` | No | Ack: True emits the staged stop, False discards. Only meaningful with idempotency_key |

## Response (`StopTestApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `invocation_id` | `string` | Yes | — |
| `success` | `boolean` | Yes | — |
| `message` | `string` | No | — |
| `idempotency_key` | `string` | No | — |

---

# `POST` `/test/text_download`

Route: /api-reference/test/post-test-text-download

# `POST` `/test/text_download`

Test Text Download

Download text content for a test.

## Request Body (`TextDownloadTestApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `text_id` | `string` | Yes | UUID of the text resource to download |

## Response

```
{}
```

---

# `POST` `/test/title`

Route: /api-reference/test/post-test-title

# `POST` `/test/title`

Title Test

Rename a test's group (writes group_names_entry).

## Request Body (`TitleTestApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Group to rename |
| `title` | `string` | Yes | New title (display name) for the group |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant rename |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`TitleTestApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | The group that was renamed |
| `group_name_id` | `string` | Yes | UUID of the new group_names_entry row |
| `title` | `string` | Yes | The title that was set |
| `idempotency_key` | `string` | No | Operation key echoed back |

---

# `POST` `/test/watch`

Route: /api-reference/test/post-test-watch

# `POST` `/test/watch`

Test Watch Once

One-shot snapshot of run state, snapshot-replayable via ``snapshot_key``.

## Request Body (`WatchApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Chat group whose events we watch |
| `run_id` | `string` | No | Specific run to watch (e.g. the ``run_id`` returned by a prior ``X_Generate`` call). If None, watches every active run in the group at call time. |
| `wait_for_complete` | `boolean` | No | If True, block until the watched run reaches a terminal (complete/failed) event or timeout fires. If False, return current state and exit immediately. |
| `timeout_seconds` | `integer` | No | Max wait time when ``wait_for_complete=True``. |
| `snapshot_key` | `string` | No | Read snapshot key — on the one-shot POST /watch, the audit wrapper records this watch's point-in-time view (latest run state at call time) keyed by it and replays the same view on any later call with the same key. Ignored by the SSE GET stream. |

## Response (`WatchApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `runs` | [`RunStatus`](/api-reference/test/types#runstatus)[] | Yes | — |
| `timed_out` | `boolean` | No | — |
| `waited_seconds` | `number` | No | — |

---

# Test Types

Route: /api-reference/test/types

# Test Types

## `AnalysisEntry`

Analysis entry for chat-level analysis content.

| Field | Type | Required | Description |
|---|---|---|---|
| `content` | `string` | No | Analysis content text |

---

## `AnalyticsFacets`

Resolved analytics facets — embeddable in any artifact response.

Contains filter field visibility, available options for dropdowns,
and date range boundaries. Returned inline from artifact get/search
responses so each page has its filter facets ready for SSR.

| Field | Type | Required | Description |
|---|---|---|---|
| `fields` | [`AnalyticsFilterFields`](#analyticsfilterfields) | Yes | Filter field visibility configuration |
| `department_options` | [`AnalyticsFilterOption`](#analyticsfilteroption)[] | No | Department dropdown options |
| `cohort_options` | [`AnalyticsFilterOption`](#analyticsfilteroption)[] | No | Cohort dropdown options |
| `role_options` | [`AnalyticsRoleOption`](#analyticsroleoption)[] | No | Available role resource options |
| `attempt_options` | `string`[] | No | Available attempt options |
| `date_range_earliest` | `string` | No | Earliest available date for filtering |
| `date_range_latest` | `string` | No | Latest available date for filtering |

---

## `AnalyticsFilterField`

Visibility/disabled state for a single filter field.

| Field | Type | Required | Description |
|---|---|---|---|
| `visible` | `boolean` | No | Whether the filter field is visible |
| `disabled` | `boolean` | No | Whether the filter field is disabled |

---

## `AnalyticsFilterFields`

Per-page filter field visibility configuration.

| Field | Type | Required | Description |
|---|---|---|---|
| `date_range` | [`AnalyticsFilterField`](#analyticsfilterfield) | No | Date range filter config |
| `departments` | [`AnalyticsFilterField`](#analyticsfilterfield) | No | Department filter config |
| `cohorts` | [`AnalyticsFilterField`](#analyticsfilterfield) | No | Cohort filter config |
| `roles` | [`AnalyticsFilterField`](#analyticsfilterfield) | No | Role filter config |
| `attempts` | [`AnalyticsFilterField`](#analyticsfilterfield) | No | Attempt filter config |

---

## `AnalyticsFilterOption`

A single filter option for dropdown selectors.

| Field | Type | Required | Description |
|---|---|---|---|
| `value` | `string` | Yes | Option value for the filter |
| `label` | `string` | Yes | Human-readable option label |

---

## `AnalyticsRoleOption`

Hydrated role resource option for analytics role filters.

| Field | Type | Required | Description |
|---|---|---|---|
| `value` | `string` | Yes | Option value for the filter |
| `label` | `string` | Yes | Human-readable option label |
| `id` | `string` | Yes | Role resource UUID |
| `name` | `string` | Yes | Role resource name |
| `description` | `string` | No | Role description |
| `icon_id` | `string` | No | Icon resource UUID |
| `color_id` | `string` | No | Color resource UUID |
| `level` | `integer` | Yes | Role privilege level |

---

## `BenchmarkDepartmentItem`

Department resource for benchmark.

| Field | Type | Required | Description |
|---|---|---|---|
| `department_id` | `string` | Yes | Department identifier |
| `name` | `string` | No | Department display name |
| `description` | `string` | No | Department description |

---

## `BenchmarkEvalOperational`

Eval card for the benchmark page — analogous to ChatSimulationOperational.

| Field | Type | Required | Description |
|---|---|---|---|
| `eval_id` | `string` | Yes | Eval identifier |
| `eval_name` | `string` | No | Eval display name |
| `eval_description` | `string` | No | Eval description |
| `model_ids` | `string`[] | No | Associated model IDs |
| `total_tests` | `integer` | No | Total number of tests |
| `archived_tests` | `integer` | No | Number of archived tests |
| `total_invocations` | `integer` | No | Total number of invocations |
| `completed_invocations` | `integer` | No | Number of completed invocations |
| `highest_score` | `number` | No | Highest score achieved |
| `has_passed` | `boolean` | No | Whether eval has been passed |
| `status` | `string` | No | Eval status |
| `infinite_mode` | `boolean` | No | Whether eval uses infinite mode |
| `department_ids` | `string`[] | No | Associated department IDs |
| `rubric_ids` | `string`[] | No | Associated rubric IDs |

---

## `BenchmarkHistoryItem`

Single test row in benchmark history list — mirrors HistoryItem shape.

| Field | Type | Required | Description |
|---|---|---|---|
| `test_id` | `string` | Yes | Test identifier |
| `date` | `string` | No | Formatted date string of the test |
| `profile_id` | `string` | No | UUID of the profile who owns the test |
| `profile_name` | `string` | No | Display name of the profile |
| `eval_id` | `string` | No | Parent eval ID |
| `eval_name` | `string` | No | Parent eval name |
| `rubric_id` | `string` | No | Rubric ID for this test |
| `rubric_name` | `string` | No | Rubric display name |
| `num_models` | `integer` | No | Total number of models in the test |
| `num_models_completed` | `integer` | No | Number of models completed |
| `model_ids` | `string`[] | No | UUIDs of associated models |
| `model_names` | `string`[] | No | Display names of associated models |
| `score` | `integer` | No | Overall test score percent (0-100) |
| `score_status` | `string` | No | Score status label (e.g. high, medium, low) |
| `pass_pct` | `integer` | No | Pass percentage threshold from rubric |
| `show_view` | `boolean` | No | Whether the view action is available |
| `show_continue` | `boolean` | No | Whether the continue action is available |
| `is_archived` | `boolean` | No | Whether the test is archived |
| `infinite_mode` | `boolean` | No | Whether the test uses infinite mode |
| `department_ids` | `string`[] | No | Associated department IDs |

---

## `BenchmarkHistoryResponse`

Paginated history response.

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | [`BenchmarkHistoryItem`](#benchmarkhistoryitem)[] | No | History items |
| `total_count` | `integer` | No | Total number of matching records |
| `page` | `integer` | No | Current page number |
| `page_size` | `integer` | No | Items per page |
| `eval_options` | [`FilterOption`](#filteroption)[] | No | Eval filter options |
| `model_options` | [`FilterOption`](#filteroption)[] | No | Model filter options |
| `profile_options` | [`FilterOption`](#filteroption)[] | No | Profile filter options |
| `rubric_options` | [`FilterOption`](#filteroption)[] | No | Rubric filter options |

---

## `CallerPermissions`

Evaluated permissions for the current caller on this artifact type.

| Field | Type | Required | Description |
|---|---|---|---|
| `can_create` | `boolean` | Yes | Whether the caller can create new artifacts |
| `can_draft` | `boolean` | Yes | Whether the caller can create/update drafts |
| `can_duplicate` | `boolean` | Yes | Whether the caller can duplicate artifacts |
| `has_access` | `boolean` | No | Whether the caller can view this entity |
| `can_edit` | `boolean` | No | Whether the caller can edit this entity |
| `can_delete` | `boolean` | No | Whether the caller can delete this entity |
| `disabled_reason` | `string` | No | Human-readable reason if editing is disabled |

---

## `ColumnInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Column name |
| `type` | `string` | Yes | Column data type |
| `nullable` | `boolean` | Yes | Whether the column is nullable |

---

## `DocsApiResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `list` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `detail` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `new` | [`PageMetaItem`](#pagemetaitem) | Yes | — |

---

## `DocsResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Resource or entry name |
| `type` | `string` | Yes | Resource or entry type identifier |
| `description` | `string` | Yes | Human-readable description |
| `materialized_view` | [`MvInfo`](#mvinfo) | No | Materialized view metadata |
| `tables` | [`TableInfo`](#tableinfo)[] | Yes | Related database tables |
| `operations` | [`OperationInfo`](#operationinfo)[] | Yes | Available operations |

---

## `EvalSetup`

Run-level eval scaffold — first-class on the generate response.

Audit's ``**output`` spread carries this onto
``<artifact>.generate.completed``. Null when no rubric-bearing
agent participated.

| Field | Type | Required | Description |
|---|---|---|---|
| `test_id` | `string` | Yes | — |
| `invocations` | [`InvocationSlot`](#invocationslot)[] | Yes | — |

---

## `FeedbackEntry`

Feedback by standard for grading state.

standard_group_id is derived from standards metadata lookup.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | UUID of the feedback entry |
| `standard_id` | `string` | No | UUID of the associated standard |
| `standard_group_id` | `string` | No | UUID of the standard group |
| `total` | `number` | No | Total score for this standard |
| `feedback` | `string` | No | Feedback text for this standard |

---

## `FilterOption`

A single filter option for dropdown selectors.

| Field | Type | Required | Description |
|---|---|---|---|
| `value` | `string` | Yes | Internal value for the filter option |
| `label` | `string` | No | Display label for the filter option |
| `count` | `integer` | No | Number of matching records |

---

## `GenerateConfig`

Developer configuration — all optional with sensible defaults.

| Field | Type | Required | Description |
|---|---|---|---|
| `operations` | `string`[] | No | — |
| `dangerous` | `boolean` | No | — |
| `params` | `object` | No | — |
| `group_id` | `string` | No | — |

---

## `GenerationsTestListItem`

Single generation group in the test generations response.

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | UUID of the generation group |
| `session_id` | `string` | No | UUID of the parent session |
| `group_name` | `string` | No | Name of the generation group |
| `created_at` | `string` | No | Timestamp of the generation |

---

## `GetInvocationDraftResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | UUID of the draft |
| `created_at` | `string` | Yes | Creation timestamp |
| `generated` | `boolean` | Yes | Whether this was AI-generated |
| `mcp` | `boolean` | Yes | Whether MCP tooling was used |
| `active` | `boolean` | Yes | Whether this draft is active |
| `session_id` | `string` | Yes | Associated session UUID |
| `name` | `string` | No | Immutable draft label set at create time |
| `department_ids` | `string`[] | Yes | Associated department UUIDs |
| `description_ids` | `string`[] | Yes | Associated description UUIDs |
| `flag_ids` | `string`[] | Yes | Associated flag UUIDs |
| `key_ids` | `string`[] | Yes | Associated key UUIDs |
| `modality_ids` | `string`[] | No | Associated modality UUIDs |
| `quality_ids` | `string`[] | No | Associated quality UUIDs |
| `model_flag_ids` | `string`[] | Yes | Associated model flag UUIDs |
| `model_position_ids` | `string`[] | Yes | Associated model position UUIDs |
| `model_rubric_ids` | `string`[] | Yes | Associated model rubric UUIDs |
| `name_ids` | `string`[] | Yes | Associated name UUIDs |
| `profile_ids` | `string`[] | Yes | Associated profile UUIDs |
| `reasoning_level_ids` | `string`[] | Yes | Associated reasoning level UUIDs |
| `temperature_level_ids` | `string`[] | Yes | Associated temperature level UUIDs |
| `voice_ids` | `string`[] | Yes | Associated voice UUIDs |
| `value_id` | `string` | No | Associated value UUID |
| `pricing_ids` | `string`[] | Yes | Associated pricing UUIDs |
| `endpoint_ids` | `string`[] | Yes | Associated endpoint UUIDs |
| `pending_department_ids` | `string`[] | No | Pending department UUIDs |
| `pending_description_ids` | `string`[] | No | Pending description UUIDs |
| `pending_flag_ids` | `string`[] | No | Pending flag UUIDs |
| `pending_key_ids` | `string`[] | No | Pending key UUIDs |
| `pending_modality_ids` | `string`[] | No | Pending modality UUIDs |
| `pending_quality_ids` | `string`[] | No | Pending quality UUIDs |
| `pending_model_flag_ids` | `string`[] | No | Pending model flag UUIDs |
| `pending_model_position_ids` | `string`[] | No | Pending model position UUIDs |
| `pending_model_rubric_ids` | `string`[] | No | Pending model rubric UUIDs |
| `pending_name_ids` | `string`[] | No | Pending name UUIDs |
| `pending_reasoning_level_ids` | `string`[] | No | Pending reasoning level UUIDs |
| `pending_temperature_level_ids` | `string`[] | No | Pending temperature level UUIDs |
| `pending_voice_ids` | `string`[] | No | Pending voice UUIDs |
| `pending_value_ids` | `string`[] | No | Pending value UUIDs |
| `pending_pricing_ids` | `string`[] | No | Pending pricing UUIDs |
| `pending_endpoint_ids` | `string`[] | No | Pending endpoint UUIDs |

---

## `GetTestFeedbackResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `feedback_id` | `string` | Yes | — |
| `grade_id` | `string` | Yes | — |
| `call_id` | `string` | Yes | — |
| `tool_call_id` | `string` | Yes | — |
| `standard_id` | `string` | No | — |
| `total` | `integer` | Yes | — |
| `feedback` | `string` | Yes | — |
| `total_points` | `integer` | Yes | — |
| `pass_points` | `integer` | Yes | — |
| `created_at` | `string` | Yes | — |

---

## `GetTestGradeResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `invocation_id` | `string` | Yes | — |
| `created_at` | `string` | Yes | — |
| `updated_at` | `string` | Yes | — |
| `passed` | `boolean` | Yes | — |
| `score` | `integer` | Yes | — |
| `time_taken` | `integer` | Yes | — |
| `generated` | `boolean` | Yes | — |
| `mcp` | `boolean` | Yes | — |
| `active` | `boolean` | Yes | — |
| `call_id` | `string` | Yes | — |

---

## `GetTestInvocationResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `invocation_id` | `string` | Yes | — |
| `test_id` | `string` | Yes | — |
| `group_id` | `string` | Yes | — |
| `invocation_created_at` | `string` | Yes | — |
| `invocation_title` | `string` | Yes | — |
| `use_custom` | `boolean` | Yes | — |
| `position` | `integer` | Yes | — |
| `invocation_completed` | `boolean` | Yes | — |
| `grade_id` | `string` | Yes | — |
| `grade_score` | `number` | Yes | — |
| `grade_passed` | `boolean` | Yes | — |
| `grade_time_taken` | `number` | Yes | — |
| `rubric_id` | `string` | Yes | — |
| `agent_ids` | `string`[] | No | — |
| `quality_id` | `string` | No | — |
| `department_ids` | `string`[] | No | — |
| `voice_id` | `string` | No | — |
| `temperature_level_id` | `string` | No | — |
| `reasoning_level_id` | `string` | No | — |
| `modality_ids` | `string`[] | No | — |

---

## `GetTestInvocationRunsResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `test_invocation_id` | `string` | Yes | — |
| `test_invocation_traces_id` | `string` | No | — |
| `run_id` | `string` | No | — |
| `created_at` | `string` | Yes | — |
| `updated_at` | `string` | Yes | — |
| `generated` | `boolean` | Yes | — |
| `mcp` | `boolean` | Yes | — |
| `active` | `boolean` | Yes | — |

---

## `GetTestInvocationTracesResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `test_invocation_id` | `string` | Yes | — |
| `run_id` | `string` | No | — |
| `created_at` | `string` | Yes | — |
| `updated_at` | `string` | Yes | — |
| `generated` | `boolean` | Yes | — |
| `mcp` | `boolean` | Yes | — |
| `active` | `boolean` | Yes | — |
| `reasoning_level_ids` | `string`[] | No | — |
| `temperature_level_ids` | `string`[] | No | — |
| `voice_ids` | `string`[] | No | — |
| `prompt_ids` | `string`[] | No | — |
| `instruction_ids` | `string`[] | No | — |
| `tool_ids` | `string`[] | No | — |
| `quality_ids` | `string`[] | No | — |
| `modality_ids` | `string`[] | No | — |

---

## `GetTestResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `test_id` | `string` | Yes | — |
| `call_id` | `string` | Yes | — |
| `eval_id` | `string` | Yes | — |
| `profile_id` | `string` | Yes | — |
| `department_ids` | `string`[] | Yes | — |
| `test_name` | `string` | Yes | — |
| `test_description` | `string` | Yes | — |
| `num_invocations` | `integer` | Yes | — |
| `infinite_mode` | `boolean` | Yes | — |
| `is_dynamic` | `boolean` | Yes | — |
| `archived` | `boolean` | Yes | — |
| `test_created_at` | `string` | Yes | — |

---

## `GradeData`

Grade information for a chat (no id - not a resource).

| Field | Type | Required | Description |
|---|---|---|---|
| `score` | `number` | No | Grade score achieved |
| `passed` | `boolean` | No | Whether the grade is passing |
| `description` | `string` | No | Grade description text |
| `time_taken` | `integer` | No | Time taken in seconds |
| `total_points` | `number` | No | Total available points |
| `pass_points` | `number` | No | Points required to pass |

---

## `GradingStateData`

Grading state for a chat in Record format.

All fields are Records keyed by standard_id strings.
This is the exact format the client needs - no transformation required.

| Field | Type | Required | Description |
|---|---|---|---|
| `achieved_standards` | `object` | No | Map of standard_id to achieved status |
| `passed_standards` | `object` | No | Map of standard_id to passed status |
| `feedback_by_standard_id` | `object` | No | Map of standard_id to feedback text |

---

## `GroupCall`

Tool call referenced by a message.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `tool_name` | `string` | No | — |
| `template_name` | `string` | No | — |
| `tool` | `object` | No | — |
| `ledger_status` | `string` | No | — |
| `ledger_operation` | `string` | No | — |
| `ledger_artifact` | `string` | No | — |
| `ledger_artifact_id` | `string` | No | — |

---

## `GroupMessage`

Message within a run.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `role` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `text_ids` | `string`[] | No | — |
| `audio_ids` | `string`[] | No | — |
| `image_ids` | `string`[] | No | — |
| `video_ids` | `string`[] | No | — |
| `file_ids` | `string`[] | No | — |
| `call_ids` | `string`[] | No | — |
| `calls` | [`GroupCall`](#groupcall)[] | No | — |
| `reasoning` | `boolean` | No | True when this row is a chain-of-thought trace persisted alongside the assistant answer (rendered as a collapsed accordion). |
| `in_context` | `boolean` | No | Whether this message is included in the LLM context for the next generation. Mirrors the dedup pass that builds chat history (see in_context_reason). |
| `in_context_reason` | `string` | No | Why this message is in/out of LLM context. 'kept' = included; 'deduped_read' = older read-only call to a tool that has a fresher result later in the group; future values may include 'trimmed_top_n'. |

---

## `GroupResource`

Lightweight `\{id, name\}` for cross-referencing run-level ids
(``model_id`` / ``agent_id`` / ``profile_id``) against human-readable
names on the analytics panel. Names come from the canonical
``get_models`` / ``get_agents`` / ``get_profiles`` black boxes.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `name` | `string` | No | — |

---

## `GroupRun`

Run within a group, with its messages.

Carries token / cost / model / agent / profile attribution so the
analytics view can render per-run cost + actor info without a
parallel detail shape. ``profile_id`` is the authoring profile
(human user), ``agent_id`` is the LLM-side actor, ``model_id`` is
the model used by that agent. All optional — runs predating these
columns or with unresolved attributions surface ``None``.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `input_tokens` | `integer` | No | — |
| `output_tokens` | `integer` | No | — |
| `cached_input_tokens` | `integer` | No | — |
| `cost` | `number` | No | — |
| `model_id` | `string` | No | — |
| `agent_id` | `string` | No | — |
| `profile_id` | `string` | No | — |
| `previous_context_start_index` | `integer` | No | Index in ``messages`` where the current run's own messages begin; earlier rows are previous-context replay. ``None`` when the run has no previous context attached. |
| `messages` | [`GroupMessage`](#groupmessage)[] | No | — |

---

## `InvocationDepartmentResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `department_id` | `string` | No | Unique identifier |
| `name` | `string` | No | Display name |
| `description` | `string` | No | Description text |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `InvocationDescriptionResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `description` | `string` | No | Description text |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `InvocationDetail`

Per-invocation graded-view payload.

Mirrors ``ChatData`` from attempt — one of these per invocation,
each carrying its rubric structure and the list of runs that
executed against it. ``primary_run_id`` is the default local
selection (usually the most recent / row-summary grade).

| Field | Type | Required | Description |
|---|---|---|---|
| `invocation_id` | `string` | Yes | UUID of the test_invocation_entry |
| `rubric_id` | `string` | No | UUID of the rubric used to grade this invocation |
| `rubric_structure` | [`RubricStructureData`](#rubricstructuredata) | No | Rubric structure for TableRubric (standards / groups / mappings) |
| `primary_run_id` | `string` | No | Default selected run for this invocation |
| `agent_id` | `string` | No | UUID of the agent under test |
| `model_id` | `string` | No | UUID of the model the agent is set up with |
| `voice_id` | `string` | No | UUID of the voice resource |
| `temperature_level_id` | `string` | No | UUID of the temperature level |
| `reasoning_level_id` | `string` | No | UUID of the reasoning level |
| `quality_id` | `string` | No | UUID of the quality level |
| `modality_ids` | `string`[] | No | Modality resource ids |
| `runs` | [`InvocationRunDetail`](#invocationrundetail)[] | No | Per-execution detail |

---

## `InvocationEndpointResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `base_url` | `string` | No | Endpoint base URL |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `InvocationFlagResource`

Flag option row — one per (name, type, value) flags_resource entry.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Flag resource identifier |
| `name` | `string` | No | Flag display name |
| `type` | `string` | No | Flag type |
| `value` | `boolean` | No | Underlying bool value of this option |
| `description` | `string` | No | Flag description text |
| `icon_id` | `string` | No | Icon identifier for the flag |
| `icon` | `string` | No | Resolved SVG markup for the icon (hydrated from icons_resource) |
| `generated` | `boolean` | No | Whether the flag was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `InvocationKeyResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `key_id` | `string` | No | Resource identifier alias for picker compatibility |
| `name` | `string` | No | Display name |
| `description` | `string` | No | Description text |
| `key_masked` | `string` | No | Masked key preview |
| `masked_key` | `string` | No | Masked key preview alias |
| `active` | `boolean` | No | Whether this key is active |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `InvocationModalityResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `modality_id` | `string` | No | Resource identifier alias for picker compatibility |
| `modality` | `string` | No | Modality code |
| `name` | `string` | No | Human-readable modality name |
| `description` | `string` | No | Description text |
| `is_input` | `boolean` | No | Whether this modality is input-facing |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `InvocationModelFlagOptionResource`

Cross-product option row: one per (model_id, flag_type, value) tuple.

| Field | Type | Required | Description |
|---|---|---|---|
| `model_id` | `string` | No | Model identifier |
| `flag_id` | `string` | No | Flag resource identifier |
| `type` | `string` | No | Flag type, e.g. 'model_active' |
| `value` | `boolean` | No | Underlying flag value for this option |
| `name` | `string` | No | Display name from the flags_resource row |
| `description` | `string` | No | Description text from the flags_resource row |
| `icon` | `string` | No | Icon SVG markup hydrated from icons_resource |

---

## `InvocationModelFlagResource`

Per-model flag junction row for an invocation.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Model-flag resource identifier |
| `model_id` | `string` | No | Associated model identifier |
| `flag_id` | `string` | No | Associated flag identifier |
| `type` | `string` | No | Flag type (e.g. 'model_active') of the linked flags_resource row |
| `value` | `boolean` | No | Underlying bool value of the linked flags_resource row |
| `name` | `string` | No | Display name |
| `description` | `string` | No | Description text |
| `icon` | `string` | No | Icon SVG markup |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `InvocationModelFlagValue`

Denormalized per-(model, type) selection for draft requests.

| Field | Type | Required | Description |
|---|---|---|---|
| `model_id` | `string` | Yes | Target model identifier |
| `type` | `string` | Yes | Flag type, e.g. 'model_active' |
| `value` | `boolean` | Yes | Desired flag value |

---

## `InvocationNameResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `name` | `string` | No | Display name |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `InvocationPricingResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `pricing_id` | `string` | No | Resource identifier alias for picker compatibility |
| `pricing_type` | `string` | No | Pricing type |
| `price` | `number` | No | Price amount |
| `unit_name` | `string` | No | Unit name |
| `unit_category` | `string` | No | Unit category |
| `unit_value` | `integer` | No | Unit value |
| `name` | `string` | No | Display label |
| `description` | `string` | No | Description text |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `InvocationQualityResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `quality_id` | `string` | No | Resource identifier alias for picker compatibility |
| `quality` | `string` | No | Quality label |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `InvocationReasoningLevelResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `reasoning_level` | `string` | No | Reasoning level label |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `InvocationRunDetail`

Per-run grade + replay detail within an invocation.

One row per ``test_invocation_runs_entry`` binding. Carries the
TableRubric-ready ``grading_state`` plus the message/call ids the
client uses to slice ``entries.messages`` / ``entries.calls``.

| Field | Type | Required | Description |
|---|---|---|---|
| `run_id` | `string` | Yes | UUID of the runs_entry row this binding executed |
| `binding_id` | `string` | Yes | UUID of the test_invocation_runs_entry binding row |
| `grade_id` | `string` | No | UUID of the test_grade_entry, if graded |
| `created_at` | `string` | No | When the binding was created |
| `completed` | `boolean` | No | Whether the binding has a completion record |
| `grade` | [`GradeData`](#gradedata) | No | Score / passed / time_taken summary |
| `grading_state` | [`GradingStateData`](#gradingstatedata) | No | Achieved/passed/feedback maps keyed by standard_id |
| `feedbacks` | [`FeedbackEntry`](#feedbackentry)[] | No | Per-standard feedback rows |
| `analyses` | [`AnalysisEntry`](#analysisentry)[] | No | Chat-level analysis content (currently unused for tests) |
| `message_ids` | `string`[] | No | Message ids belonging to this run |
| `call_ids` | `string`[] | No | Tool-call ids belonging to this run |

---

## `InvocationSlot`

One agent's slot in a multi-agent generation pool.

Populated by ``setup_generation_test`` when an agent carries a
rubric. The client uses these IDs to drive the eval workflow:
review the candidate's output, optionally fire a grader against
its ``invocation_id``, and promote/reject by call_id via the
existing ``idempotency_key + accept`` pattern.

| Field | Type | Required | Description |
|---|---|---|---|
| `invocation_id` | `string` | Yes | — |
| `agent_id` | `string` | Yes | — |
| `rubric_id` | `string` | No | — |

---

## `InvocationTemperatureLevelResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `temperature` | `number` | No | Temperature numeric value |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `InvocationValueResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `value` | `string` | No | Value text |
| `type` | `string` | No | Value type |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `InvocationVoiceResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier |
| `voice` | `string` | No | Voice label |
| `generated` | `boolean` | No | Whether this was AI-generated |
| `suggested` | `boolean` | No | Whether this is a suggested option |
| `selected` | `boolean` | No | Whether this is currently selected |
| `pending` | `boolean` | No | Whether this selection is pending acceptance |

---

## `ListFilterOption`

Standardized option for list endpoint filter sections.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier for this filter option |
| `name` | `string` | No | Display name |
| `count` | `integer` | No | Number of matching records |
| `hex_code` | `string` | No | Hex color code for display |
| `value` | `string` | No | Internal value |
| `type` | `string` | No | Option type discriminator |

---

## `ListFilterSection`

Filter section with options and echoed request state.

| Field | Type | Required | Description |
|---|---|---|---|
| `options` | [`ListFilterOption`](#listfilteroption)[] | No | Available filter options |
| `selected_ids` | `string`[] | No | Currently selected filter option IDs |
| `search` | `string` | No | Active search text for filtering |

---

## `MvInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Materialized view name |
| `definition` | `string` | Yes | SQL definition of the view |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the view |

---

## `OperationInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Operation name |
| `description` | `string` | Yes | Human-readable description of the operation |
| `params` | [`ParamInfo`](#paraminfo)[] | Yes | List of operation parameters |
| `returns` | `object` | No | Return type schema |

---

## `OperationPrompts`

Starter prompts keyed by operation name.

Each key is an operation (e.g. "create", "search", "draft", "export")
and the value is a list of starter prompts for that operation.
The client picks from the operations the caller has permission for
and rotates through them.

| Field | Type | Required | Description |
|---|---|---|---|
| `prompts` | `object` | No | Map of operation name to starter prompts |

---

## `PageMetaItem`

| Field | Type | Required | Description |
|---|---|---|---|
| `title` | `string` | Yes | — |
| `description` | `string` | Yes | — |

---

## `ParamInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Parameter name |
| `type` | `string` | Yes | Parameter data type |
| `required` | `boolean` | Yes | Whether the parameter is required |
| `default` | `any` | No | Default value if not required |

---

## `ProducedMedia`

One asset produced by a generation run.

``resource_id`` is the canonical id the per-artifact download tools
accept (e.g. ``Scenario_Image_Download(image_id=resource_id)`` for
``modality="image"``). It maps to ``images_resource.id`` /
``videos_resource.id`` / ``audios_resource.id`` depending on the
modality.

| Field | Type | Required | Description |
|---|---|---|---|
| `modality` | `"image"` \| `"video"` \| `"audio"` | Yes | — |
| `resource_id` | `string` | Yes | — |
| `upload_id` | `string` | Yes | — |
| `mime_type` | `string` | No | — |
| `file_size` | `integer` | No | — |

---

## `ProfileSummary`

Caller identity derived from JWT — who you are on this page.

Superset of the old six-field version: now carries everything the client
needs so that ``/\{artifact\}/context`` fully replaces ``/profiles/context``
and the extra ``getLayoutContextData`` round-trip can be dropped.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Display name of the authenticated user |
| `role` | `string` | Yes | Role name (e.g. 'Super Administrator') |
| `role_level` | `integer` | Yes | Role hierarchy level (0 = highest privilege) |
| `department_ids` | `string`[] | Yes | Departments the user belongs to |
| `artifact_access` | `string`[] | Yes | Artifact types this role can access (sidebar visibility) |
| `role_permissions` | `any`[][] | Yes | Full (artifact, operation) permission tuples for granular page gating |
| `is_active` | `boolean` | Yes | Whether the user's profile is active |
| `id` | `string` | Yes | Profile UUID (SocketProvider, ProfileProvider) |
| `theme` | [`ThemeBundle`](#themebundle) | No | Resolved theme: hex primitives + derived oklch tokens + score thresholds |
| `session_id` | `string` | No | Current session UUID |
| `is_emulation` | `boolean` | No | Whether user is in emulation mode (ProfileProvider) |
| `role_resources` | [`QGetProfileContextV4RoleResource`](#qgetprofilecontextv4roleresource)[] | No | All role resources for emulation display (ProfileProvider) |
| `scoped_roles` | `string`[] | No | Roles the user can emulate (ProfileProvider) |
| `active` | `boolean` | No | Alias for is_active (ProfileProvider uses this name) |

---

## `QGetProfileContextV4RoleResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `role` | `string` | No | — |
| `name` | `string` | No | — |
| `description` | `string` | No | — |
| `icon_value` | `string` | No | — |
| `color_hex` | `string` | No | — |

---

## `RubricStructureData`

Rubric structure data in Record format.

All fields are Records keyed by standard_group_id or standard_id strings.
This is the exact format the client needs - no transformation required.

| Field | Type | Required | Description |
|---|---|---|---|
| `standard_groups` | `object` | No | Map of group_id to standard_id lists |
| `standard_groups_mapping` | `object` | No | Map of group_id to group metadata |
| `standards_mapping` | `object` | No | Map of standard_id to standard metadata |

---

## `RunStatus`

Outcome of one watched run.

| Field | Type | Required | Description |
|---|---|---|---|
| `run_id` | `string` | Yes | — |
| `status` | `"pending"` \| `"completed"` \| `"failed"` | Yes | — |
| `modality` | `string` | No | Modality of generated output (image, video, text…) |
| `resource_ids` | `string`[] | No | Resource UUIDs produced by this run (e.g. images_resource ids) |
| `error` | `string` | No | — |

---

## `SearchMessageResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `message_id` | `string` | Yes | UUID of the message |
| `run_id` | `string` | Yes | UUID of the parent run |
| `role` | `string` | Yes | Message role (e.g. user, assistant) |
| `message_created_at` | `string` | Yes | Message creation timestamp |
| `text_ids` | `string`[] | Yes | UUIDs of text resources |
| `audio_ids` | `string`[] | Yes | UUIDs of audio resources |
| `image_ids` | `string`[] | Yes | UUIDs of image resources |
| `video_ids` | `string`[] | Yes | UUIDs of video resources |
| `file_ids` | `string`[] | Yes | UUIDs of file resources |
| `call_ids` | `string`[] | Yes | UUIDs of call resources |
| `reasoning` | `boolean` | No | Chain-of-thought trace row |

---

## `SearchTestItem`

Single test row in search results.

| Field | Type | Required | Description |
|---|---|---|---|
| `test_id` | `string` | Yes | UUID of the test |
| `eval_id` | `string` | No | UUID of the eval |
| `eval_name` | `string` | No | Name of the eval |
| `eval_description` | `string` | No | Description of the eval |
| `department_ids` | `string`[] | No | UUIDs of associated departments |
| `test_name` | `string` | No | Name of the test |
| `test_description` | `string` | No | Description of the test |
| `num_invocations` | `integer` | No | Number of invocations |
| `infinite_mode` | `boolean` | No | Whether infinite mode is enabled |
| `is_dynamic` | `boolean` | No | Whether the test is dynamic |
| `archived` | `boolean` | No | Whether the test is archived |
| `created_at` | `string` | No | ISO timestamp when test was created |

---

## `TableInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Table name |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the table |

---

## `TestConfigGroup`

A group bucket for the picker — used as the section header.

Renders one accordion section per row. `run_count` is the total
rows in the group (across the whole inner pagination universe,
not just the current expanded window). `last_run_at` drives the
outer ordering (most-recent-group first).

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | UUID of the group |
| `name` | `string` | No | Human-readable group name (or null if unnamed) |
| `run_count` | `integer` | No | Total run configs in this group |
| `last_run_at` | `string` | No | ISO timestamp of the most recent run in this group |

---

## `TestConfigItem`

A reusable run configuration the picker can queue.

Sources from runs_entry rows. Each row is a distinct config
(agent + model + bundle) that can be re-fired any number of times
into fresh trace executions. The bundle ids carried here come from
the historical run's agent_resource — the picker passes them as
`RunPanelState` to /test/invocation/trace so the new trace records the same
prompt + tool + instruction set the original run executed against.

| Field | Type | Required | Description |
|---|---|---|---|
| `run_id` | `string` | Yes | UUID of the runs_entry config |
| `group_id` | `string` | No | UUID of the parent group (for grouping in the picker) |
| `agent_name` | `string` | No | Display name of the agent |
| `model_name` | `string` | No | Display name of the underlying model |
| `label` | `string` | Yes | Human-readable picker label |
| `created_at` | `string` | No | When this config was first created |
| `prompt_ids` | `string`[] | No | Prompt resource ids from the historical agent |
| `tool_ids` | `string`[] | No | Tool resource ids from the historical agent |
| `instruction_ids` | `string`[] | No | Instruction resource ids from the historical agent |
| `model_id` | `string` | No | Model id from the historical agent |
| `temperature` | `number` | No | Temperature value from the historical agent |
| `reasoning` | `string` | No | Reasoning level value from the historical agent |
| `quality` | `string` | No | Quality value from the historical agent |
| `permissions` | `any`[][] | No | Historical (artifact, operation) pairs this run executed |

---

## `TestEntries`

Entry payloads grouped by type.

| Field | Type | Required | Description |
|---|---|---|---|
| `tests` | [`GetTestResponse`](#gettestresponse)[] | No | Test entry payloads |
| `invocations` | [`GetTestInvocationResponse`](#gettestinvocationresponse)[] | No | Invocation entry payloads |
| `runs` | [`GetTestInvocationRunsResponse`](#gettestinvocationrunsresponse)[] | No | Run entry payloads |
| `groups` | [`GetTestInvocationTracesResponse`](#gettestinvocationtracesresponse)[] | No | Group entry payloads |
| `grades` | [`GetTestGradeResponse`](#gettestgraderesponse)[] | No | Grade entry payloads |
| `feedback` | [`GetTestFeedbackResponse`](#gettestfeedbackresponse)[] | No | Feedback entry payloads |
| `messages` | [`SearchMessageResponse`](#searchmessageresponse)[] | No | Message entry payloads |
| `calls` | `any`[] | No | Tool call entries from original run |

---

## `TestResources`

Resource maps keyed by ID string.

| Field | Type | Required | Description |
|---|---|---|---|
| `evals` | `object` | No | Eval resources keyed by ID |
| `rubrics` | `object` | No | Rubric resources keyed by ID |
| `agents` | `object` | No | Agent resources keyed by ID |
| `models` | `object` | No | Model resources keyed by ID |
| `voices` | `object` | No | Voice resources keyed by ID |
| `temperature_levels` | `object` | No | Temperature level resources keyed by ID |
| `reasoning_levels` | `object` | No | Reasoning level resources keyed by ID |
| `modalities` | `object` | No | Modality resources keyed by ID |
| `prompts` | `object` | No | Prompt resources keyed by ID |
| `instructions` | `object` | No | Instruction resources keyed by ID |
| `tools` | `object` | No | Tool resources keyed by ID |
| `qualities` | `object` | No | Quality resources keyed by ID |
| `standard_groups` | `object` | No | Standard group resources keyed by ID |
| `standards` | `object` | No | Standard resources keyed by ID |

---

## `TestRunItem`

A single run row for the UI table, derived from a benchmark invocation.

| Field | Type | Required | Description |
|---|---|---|---|
| `chat_id` | `string` | Yes | ID of the chat |
| `invocation_id` | `string` | Yes | ID of the invocation |
| `run_id` | `string` | No | ID of the run |
| `group_id` | `string` | No | ID of the group |
| `suite_entry_id` | `string` | No | ID of the suite entry |
| `model_name` | `string` | No | Name of the model used |
| `agent_name` | `string` | No | Name of the agent used |
| `status` | `string` | No | Run status |
| `grade_score` | `number` | No | Grade score for the run |
| `grade_passed` | `boolean` | No | Whether the run passed grading |

---

## `TestStatusSummary`

| Field | Type | Required | Description |
|---|---|---|---|
| `total` | `integer` | No | Total number of invocations |
| `completed` | `integer` | No | Number of completed invocations |
| `in_progress` | `integer` | No | Number of in-progress invocations |
| `not_started` | `integer` | No | Number of not-started invocations |

---

## `ThemeBundle`

Full theme payload for a page bootstrap.

Riding along on every ``/\{artifact\}/context`` response via
``ProfileSummary.theme``. Layers:
  - ``primitives`` / ``dark_primitives`` — hex inputs the settings
    editor reads/writes (light + dark palettes).
  - ``tokens`` / ``dark_tokens`` — oklch tokens the client paints with.
    ``ThemeStyle`` emits two ``<style>`` blocks: one scoped to
    ``:root:not(.dark)`` (light) and one to ``:root.dark`` (dark).
  - ``thresholds`` — numeric score thresholds for analytics components.
Empty-in → empty-out per token: missing values fall through to the
matching ``globals.css`` default.

| Field | Type | Required | Description |
|---|---|---|---|
| `primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (light palette, for the theme editor) |
| `tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for light mode (SSR CSS-var injection) |
| `dark_primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (dark palette, for the theme editor) |
| `dark_tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for dark mode (SSR CSS-var injection) |
| `thresholds` | [`Thresholds`](#thresholds) | No | Score thresholds resolved from the setting |

---

## `ThemePrimitives`

40 optional fields. The 17 essentials drive the rest; the other 23
are overrides for fine-tuning when derivation isn't what you want.

Empty primitive → empty token → client falls back to globals.css.

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `primary` | `string` | No | — |
| `accent` | `string` | No | — |
| `card` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `ring` | `string` | No | — |
| `border` | `string` | No | — |
| `destructive` | `string` | No | — |
| `success` | `string` | No | — |
| `warning` | `string` | No | — |
| `info` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `input` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `ThemeTokens`

40 fully-resolved CSS variable values (snake_case 1:1 with vars).

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `accent` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `border` | `string` | No | — |
| `input` | `string` | No | — |
| `ring` | `string` | No | — |
| `success` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `Thresholds`

Numeric score thresholds resolved from the active setting.

Server pre-buckets dashboard metrics into ``success | warning | danger |
neutral`` already, so most components don't need these values. Surface
them for chart reference lines, tooltips, and any client-side bucketing.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `integer` | Yes | Score >= this counts as success |
| `warning` | `integer` | Yes | Score >= this counts as warning |
| `danger` | `integer` | Yes | Score < success threshold but >= this counts as danger; below is neutral/no-data |

---

## `app__infra__invocation__types__DraftFormState`

Server-authoritative form state returned after draft save.

| Field | Type | Required | Description |
|---|---|---|---|
| `name_id` | `string` | No | Saved name identifier |
| `name` | `string` | No | Saved name value |
| `description_id` | `string` | No | Saved description identifier |
| `description` | `string` | No | Saved description value |
| `value_id` | `string` | No | Saved value identifier |
| `flag_ids` | `string`[] | No | Saved flag identifiers |
| `department_ids` | `string`[] | No | Saved department identifiers |
| `key_id` | `string` | No | Saved key identifier |
| `endpoint_id` | `string` | No | Saved endpoint identifier |
| `modality_ids` | `string`[] | No | Saved modality identifiers |
| `temperature_level_id` | `string` | No | Saved temperature level identifier |
| `pricing_id` | `string` | No | Saved pricing identifier |
| `reasoning_level_id` | `string` | No | Saved reasoning level identifier |
| `quality_ids` | `string`[] | No | Saved quality identifiers |
| `voice_ids` | `string`[] | No | Saved voice identifiers |
| `model_flag_ids` | `string`[] | No | Saved model flag junction-row identifiers |
| `model_flag_values` | [`InvocationModelFlagValue`](#invocationmodelflagvalue)[] | No | Denormalized (model_id, type, value) echo derived from model_flag_ids |
| `model_position_ids` | `string`[] | No | Saved model position identifiers |
| `model_rubric_ids` | `string`[] | No | Saved model rubric identifiers |
| `pending_ids` | `string`[] | No | Pending resource identifiers |

---

## `app__infra__invocation__types__SectionFilter`

Per-section filter options for GET requests.

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Filter options by search text |
| `limit` | `integer` | No | Max options to return |
| `selected` | `boolean` | No | Only return selected items |
| `suggested` | `boolean` | No | Only return suggested items |
| `include` | `boolean` | No | Include this section in response (default true) |
| `parameter_ids` | `string`[] | No | Reserved for compatibility with shared filter parsing |

---

---

# `POST` `/token`

Route: /api-reference/token

# `POST` `/token`

Token

Token endpoint — exchanges authorization codes for tokens.

Supports client_secret_post (form body) and client_secret_basic (Authorization header).

## Response

```
{
  "additionalProperties": true,
  "type": "object",
  "title": "Response Token Token Post"
}
```

---

# `GET` `/tool/watch`

Route: /api-reference/tool/get-tool-watch

# `GET` `/tool/watch`

Tool Watch

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `group_id` | query | No | — |
| `run_id` | query | No | Optional run filter. If provided, only events whose envelope run_id matches are streamed. Omit to receive every tool event in the group (the FE default). |

## Response

```
{}
```

---

# `POST` `/tool/call_download`

Route: /api-reference/tool/post-tool-call-download

# `POST` `/tool/call_download`

Download Call

Download a call file by call resource ID.

## Request Body (`CallDownloadToolApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `call_id` | `string` | Yes | UUID of the calls_resource to download |

## Response

```
{}
```

---

# `POST` `/tool/context`

Route: /api-reference/tool/post-tool-context

# `POST` `/tool/context`

Get Tool Context

Get page context for the tool artifact.

Returns docs + profile identity + evaluated permissions in a single call.
Superset of /docs — clients can migrate from /docs to /context incrementally.

## Request Body (`DocsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entity_id` | `string` | No | — |
| `snapshot_key` | `string` | No | — |
| `schema` | `boolean` | No | If true, include MCP/tooling schema metadata (artifact, entries, resources, permission_docs, api_operations). Defaults to false for lean page-bootstrap responses. |

## Response (`ComposedContextResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Artifact name |
| `type` | `string` | Yes | Artifact type identifier |
| `description` | `string` | Yes | Human-readable description |
| `artifact` | [`DocsResponse`](/api-reference/tool/types#docsresponse) | No | Artifact tool documentation (None unless schema=true) |
| `entries` | [`DocsResponse`](/api-reference/tool/types#docsresponse)[] | No | Entry documentation list (None unless schema=true) |
| `resources` | [`DocsResponse`](/api-reference/tool/types#docsresponse)[] | No | Resource documentation list (None unless schema=true) |
| `permission_docs` | [`OperationInfo`](/api-reference/tool/types#operationinfo)[] | No | Permission function signatures for MCP/dev tooling (None unless schema=true) |
| `api_operations` | [`OperationInfo`](/api-reference/tool/types#operationinfo)[] | No | API operation documentation (None unless schema=true) |
| `page_metadata` | [`DocsApiResponse`](/api-reference/tool/types#docsapiresponse) | No | Page-level metadata |
| `prompts` | [`OperationPrompts`](/api-reference/tool/types#operationprompts) | No | Starter prompts keyed by operation |
| `profile` | [`ProfileSummary`](/api-reference/tool/types#profilesummary) | Yes | Caller identity from JWT |
| `caller_permissions` | [`CallerPermissions`](/api-reference/tool/types#callerpermissions) | Yes | Evaluated permissions for this caller |

---

# `POST` `/tool/create`

Route: /api-reference/tool/post-tool-create

# `POST` `/tool/create`

Create Tool

Create tools using composable infra architecture.

## Request Body (`CreateToolApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `tools` | [`CreateToolItem`](/api-reference/tool/types#createtoolitem)[] | Yes | List of tools to create |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant create |
| `soft` | `boolean` | No | Stage the create dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`CreateToolApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`ToolResultItem`](/api-reference/tool/types#toolresultitem)[] | Yes | List of operation results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |
| `tools` | [`ListToolApiTool`](/api-reference/tool/types#listtoolapitool)[] | No | Hydrated rows for the created tools (same shape as `/tool/search` returns) |

---

# `POST` `/tool/csv`

Route: /api-reference/tool/post-tool-csv

# `POST` `/tool/csv`

Parse Tool Csv

Parse a CSV file and return mapped items for preview.

## Request Body

| Field | Type | Required | Description |
|---|---|---|---|
| `file` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `soft` | `boolean` | No | — |
| `accept` | `boolean` | No | — |

## Response (`ParseToolCsvApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `upload_id` | `string` | Yes | — |
| `items` | [`CreateToolItem`](/api-reference/tool/types#createtoolitem)[] | Yes | — |
| `mapped_fields` | `string`[] | Yes | — |
| `row_count` | `integer` | Yes | — |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with `accept` to promote/reject the staged raw-CSV upload. NOTE: ack returns no items (the preview is only on the propose). |

---

# `POST` `/tool/delete`

Route: /api-reference/tool/post-tool-delete

# `POST` `/tool/delete`

Delete Tool

Bulk delete tools — composable infra architecture.

## Request Body (`DeleteToolApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `tool_ids` | `string`[] | No | List of tool IDs to delete (required on first call when ``all`` is false) |
| `all` | `boolean` | No | When true, delete every tool matching the filter fields below (minus ``excluded_ids``) |
| `excluded_ids` | `string`[] | No | UUIDs to skip even when matched by ``all``-mode filters |
| `search` | `string` | No | Full-text search query |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `filter_creatable` | `string`[] | No | Filter by creatable flag (no-op for row filtering today; accepted for forward compatibility) |
| `filter_agent_ids` | `string`[] | No | Filter by agent UUIDs that reference these tools (no-op for row filtering today; accepted for forward compatibility) |
| `department_search` | `string` | No | Search text for department facet (no-op for row filtering) |
| `flag_search` | `string` | No | Search text for flag facet (no-op for row filtering) |
| `agent_search` | `string` | No | Search text for agent facet (no-op for row filtering) |
| `idempotency_key` | `string` | No | Operation key for ack — confirms or rejects a dormant delete |
| `soft` | `boolean` | No | Stage the delete dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (confirm) or reject dormant state. Only meaningful with idempotency_key |

## Response (`DeleteToolApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`DeleteToolResult`](/api-reference/tool/types#deletetoolresult)[] | Yes | List of deletion results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/tool/draft`

Route: /api-reference/tool/post-tool-draft

# `POST` `/tool/draft`

Patch Tool Draft

Patch tool draft — composable infra architecture.

## Request Body (`PatchToolDraftApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `draft_id` | `string` | No | Existing draft ID to update |
| `input_draft_id` | `string` | No | Existing draft ID to update |
| `name` | `string` | No | Display name value |
| `name_id` | `string` | No | Name resource identifier |
| `description` | `string` | No | Description text value |
| `description_id` | `string` | No | Description resource identifier |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs — canonical; server derives semantics by flag type/value |
| `active` | `boolean` | No | Denormalized tool_active flag state; resolved to a flag_ids entry server-side |
| `department_ids` | `string`[] | No | Department identifiers |
| `arg_ids` | `string`[] | No | Argument identifiers |
| `args` | [`CreateArgInput`](/api-reference/tool/types#createarginput)[] | No | Arguments to create inline |
| `arg_position_ids` | `string`[] | No | Argument position identifiers |
| `arg_positions` | [`CreateArgPositionInput`](/api-reference/tool/types#createargpositioninput)[] | No | Argument positions to create inline |
| `args_output_ids` | `string`[] | No | Argument output identifiers |
| `args_outputs_ids` | `string`[] | No | Legacy alias for argument output identifiers |
| `args_outputs` | [`CreateArgsOutputInput`](/api-reference/tool/types#createargsoutputinput)[] | No | Argument outputs to create inline |
| `args_drafts` | [`ToolArgDraftValue`](/api-reference/tool/types#toolargdraftvalue)[] | No | Unified per-arg drafts for the Arguments step card. When present, takes precedence over the flat arg_ids/arg_position_ids/args_output_ids triple. |
| `instruction_id` | `string` | No | Instruction resource identifier |
| `instruction_ids` | `string`[] | No | Instruction resource identifiers |
| `permission_ids` | `string`[] | No | Permission identifiers |
| `pending_ids` | `string`[] | No | Pending resource identifiers to preserve |
| `idempotency_key` | `string` | No | Operation key for ack semantics |
| `soft` | `boolean` | No | Stage the draft dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept or reject acknowledgement when idempotency_key is supplied |

## Response (`PatchToolDraftApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the draft save succeeded |
| `draft_id` | `string` | Yes | Draft unique identifier |
| `idempotency_key` | `string` | No | Operation key echoed back for client correlation |
| `message` | `string` | Yes | Result message |
| `form_state` | [`app__infra__tool__types__DraftFormState`](/api-reference/tool/types#app-infra-tool-types-draftformstate) | No | Server-authoritative form state |

---

# `POST` `/tool/drafts`

Route: /api-reference/tool/post-tool-drafts

# `POST` `/tool/drafts`

Get Tool Drafts

List tool drafts owned by the current profile.

## Request Body (`GetToolDraftsApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE substring) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GetToolDraftsApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `entries` | [`GetToolDraftResponse`](/api-reference/tool/types#gettooldraftresponse)[] | No | List of tool draft entries |

---

# `POST` `/tool/duplicate`

Route: /api-reference/tool/post-tool-duplicate

# `POST` `/tool/duplicate`

Duplicate Tool

Duplicate a tool — composable infra architecture.

## Request Body (`DuplicateToolApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `tool_id` | `string` | Yes | Tool identifier to duplicate |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant duplicate |
| `soft` | `boolean` | No | Stage the duplicate dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`DuplicateToolApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the duplication succeeded |
| `tool_id` | `string` | Yes | New duplicated tool identifier |
| `message` | `string` | Yes | Result message |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |
| `tools` | [`ListToolApiTool`](/api-reference/tool/types#listtoolapitool)[] | No | Hydrated row for the duplicated tool (same shape as `/tool/search` returns) |

---

# `POST` `/tool/export`

Route: /api-reference/tool/post-tool-export

# `POST` `/tool/export`

Export Tools

Export all tools as a clean, denormalized CSV.

## Request Body (`ExportToolApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `tool_id` | `string` | No | Tool identifier to export |
| `idempotency_key` | `string` | No | Idempotency key — replays the prior export instead of re-running |
| `soft` | `boolean` | No | Stage the export dormant (active=False); ack with accept activates it |
| `accept` | `boolean` | No | Ack: True promotes the staged export, False rejects. Only meaningful with idempotency_key |

## Response (`ExportToolApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource holding the export CSV |
| `file_name` | `string` | Yes | Suggested download file name |
| `row_count` | `integer` | Yes | Number of data rows in the export |
| `idempotency_key` | `string` | No | Server-minted soft-call key (audit call_id). On a soft propose, echo this back with `accept` to promote/reject the staged export. |

---

# `POST` `/tool/file_download`

Route: /api-reference/tool/post-tool-file-download

# `POST` `/tool/file_download`

Download File

Download a file by file resource ID.

## Request Body (`FileDownloadToolApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `file_id` | `string` | Yes | UUID of the files_resource to download |

## Response

```
{}
```

---

# `POST` `/tool/generate`

Route: /api-reference/tool/post-tool-generate

# `POST` `/tool/generate`

Generate Tool

Trigger tool generation. Returns immediately; progress via events.

## Request Body (`ArtifactGenerateRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `instructions` | `string`[] | No | — |
| `config` | [`GenerateConfig`](/api-reference/tool/types#generateconfig) | No | — |
| `modalities` | `string`[] | No | — |
| `audios_id` | `string` | No | — |
| `conversation_id` | `string` | No | — |
| `trace_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `accept` | `boolean` | No | — |
| `wait_for_complete` | `boolean` | No | — |

## Response (`ArtifactGenerateResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `run_id` | `string` | No | — |
| `idempotency_key` | `string` | No | — |
| `eval` | [`EvalSetup`](/api-reference/tool/types#evalsetup) | No | — |
| `produced_media` | [`ProducedMedia`](/api-reference/tool/types#producedmedia)[] | No | — |

---

# `POST` `/tool/generations`

Route: /api-reference/tool/post-tool-generations

# `POST` `/tool/generations`

Generations Tool

List tool generation groups — composable infra architecture.

## Request Body (`GenerationsToolApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Name search (ILIKE) |
| `date_from` | `string` | No | Start date filter |
| `date_to` | `string` | No | End date filter |
| `page_limit` | `integer` | No | Maximum items per page |
| `page_offset` | `integer` | No | Offset for pagination |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`GenerationsToolApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `items` | [`GenerationsToolListItem`](/api-reference/tool/types#generationstoollistitem)[] | No | Generation groups |
| `total_count` | `integer` | No | Total number of matching generations |

---

# `POST` `/tool/get`

Route: /api-reference/tool/post-tool-get

# `POST` `/tool/get`

Get Tool

Get tool information using the canonical shared tool operation.

## Request Body (`GetToolApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Tool unique identifier |
| `tool_id` | `string` | No | Legacy alias for tool unique identifier |
| `draft_id` | `string` | No | Draft unique identifier |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |
| `names` | [`app__infra__tool__types__SectionFilter`](/api-reference/tool/types#app-infra-tool-types-sectionfilter) | No | Filter options for names |
| `descriptions` | [`app__infra__tool__types__SectionFilter`](/api-reference/tool/types#app-infra-tool-types-sectionfilter) | No | Filter options for descriptions |
| `flags` | [`app__infra__tool__types__SectionFilter`](/api-reference/tool/types#app-infra-tool-types-sectionfilter) | No | Filter options for flags |
| `args` | [`app__infra__tool__types__SectionFilter`](/api-reference/tool/types#app-infra-tool-types-sectionfilter) | No | Filter options for args |
| `arg_positions` | [`app__infra__tool__types__SectionFilter`](/api-reference/tool/types#app-infra-tool-types-sectionfilter) | No | Filter options for arg positions |
| `args_outputs` | [`app__infra__tool__types__SectionFilter`](/api-reference/tool/types#app-infra-tool-types-sectionfilter) | No | Filter options for arg outputs |
| `permissions` | [`app__infra__tool__types__SectionFilter`](/api-reference/tool/types#app-infra-tool-types-sectionfilter) | No | Filter options for permissions |
| `instructions` | [`app__infra__tool__types__SectionFilter`](/api-reference/tool/types#app-infra-tool-types-sectionfilter) | No | Filter options for instructions |
| `departments` | [`app__infra__tool__types__SectionFilter`](/api-reference/tool/types#app-infra-tool-types-sectionfilter) | No | Filter options for departments |

## Response (`GetToolApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `tool_exists` | `boolean` | No | Whether the tool exists |
| `can_edit` | `boolean` | No | Whether the current user can edit |
| `disabled_reason` | `string` | No | Reason editing is disabled |
| `group_id` | `string` | No | Group identifier for the tool |
| `draft_name` | `string` | No | Immutable draft label from the active draft entry, when a ``draft_id`` was supplied. ``None`` for non-draft fetches. |
| `tool_id` | `string` | No | Tool identifier |
| `show_ai_generate` | `boolean` | No | Whether AI generation is available |
| `basic_show_ai_generate` | `boolean` | No | Show AI generate for basic step |
| `args_show_ai_generate` | `boolean` | No | Show AI generate for args step |
| `permissions_show_ai_generate` | `boolean` | No | Show AI generate for permissions step |
| `pending_ids` | `string`[] | No | Pending resource identifiers when available |
| `names` | [`ToolNameResource`](/api-reference/tool/types#toolnameresource)[] | No | Name resources |
| `descriptions` | [`ToolDescriptionResource`](/api-reference/tool/types#tooldescriptionresource)[] | No | Description resources |
| `flags` | [`ToolFlagResource`](/api-reference/tool/types#toolflagresource)[] | No | Flag resources (one per flags_resource row, value=true/false) |
| `args` | [`ToolArgResource`](/api-reference/tool/types#toolargresource)[] | No | Argument resources |
| `arg_positions` | [`ToolArgPositionResource`](/api-reference/tool/types#toolargpositionresource)[] | No | Argument position resources |
| `args_outputs` | [`ToolArgOutputResource`](/api-reference/tool/types#toolargoutputresource)[] | No | Argument output resources |
| `permissions` | [`ToolPermissionResource`](/api-reference/tool/types#toolpermissionresource)[] | No | Permission resources |
| `instructions` | [`ToolInstructionResource`](/api-reference/tool/types#toolinstructionresource)[] | No | Instruction resources (single-select) |
| `departments` | [`ToolDepartmentResource`](/api-reference/tool/types#tooldepartmentresource)[] | No | Department resources |

---

# `POST` `/tool/group`

Route: /api-reference/tool/post-tool-group

# `POST` `/tool/group`

Group Tool

Resolve or create a tool group with optional naming.

## Request Body (`GroupToolApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | No | Existing group UUID (omit to create or reuse via time window) |
| `snapshot_key` | `string` | No | Snapshot key for SETNX-race convergence on a single group across concurrent reads (e.g. parallel /context + /group + /search fan-out on page load). Echoed back in the response. |

## Response (`GroupToolApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Resolved or newly created group UUID |
| `name` | `string` | No | The group's current title (latest active group_names_entry, or 'New Chat' fallback for freshly minted groups) |
| `snapshot_key` | `string` | No | Snapshot key echoed back — the UUID concurrent fan-out reads converged on via SETNX. Mirrors the resolved group_id. |
| `runs` | [`GroupRun`](/api-reference/tool/types#grouprun)[] | No | Conversation history — populated when resolving an existing group for fetch |
| `group_exists` | `boolean` | No | (detail) Whether the group exists in storage — populated when ``include_resources=True`` |
| `actor_name` | `string` | No | (detail) Display name of the current actor (caller profile) |
| `total_message_count` | `integer` | No | (detail) Total number of messages in the group |
| `models` | [`GroupResource`](/api-reference/tool/types#groupresource)[] | No | (detail) Models used in the group |
| `agents` | [`GroupResource`](/api-reference/tool/types#groupresource)[] | No | (detail) Agents used in the group |
| `profiles` | [`GroupResource`](/api-reference/tool/types#groupresource)[] | No | (detail) Profiles that authored runs in this group |

---

# `POST` `/tool/preview`

Route: /api-reference/tool/post-tool-preview

# `POST` `/tool/preview`

Preview Tool

Render output templates against mock arg values.

## Request Body (`PreviewToolApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `args` | [`ToolPreviewArg`](/api-reference/tool/types#toolpreviewarg)[] | No | Args available as Jinja variables |
| `outputs` | [`ToolPreviewOutput`](/api-reference/tool/types#toolpreviewoutput)[] | No | Output templates to render |
| `mock` | `object` | No | Mock values keyed by arg name |

## Response (`PreviewToolApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `outputs` | [`ToolPreviewOutputResult`](/api-reference/tool/types#toolpreviewoutputresult)[] | No | Rendered output blocks |
| `type_hints` | [`ToolPreviewArgHint`](/api-reference/tool/types#toolpreviewarghint)[] | No | Per-arg usage/filter hints |
| `undeclared` | `string`[] | No | Variable names referenced by templates but not declared in args |

---

# `POST` `/tool/problem`

Route: /api-reference/tool/post-tool-problem

# `POST` `/tool/problem`

Problem Tool

Report a tool problem — composable infra architecture.

## Request Body (`ProblemToolApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | `string` | Yes | Problem type: feature, bug, question, other |
| `message` | `string` | Yes | Problem description (max 1000 chars) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant problem |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`ProblemToolApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `problem_id` | `string` | Yes | UUID of the created problem |
| `success` | `boolean` | No | Whether the problem was created |
| `message` | `string` | No | Status message |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/tool/refresh`

Route: /api-reference/tool/post-tool-refresh

# `POST` `/tool/refresh`

Tool Refresh

Refresh tool materialized views and invalidate caches.

## Request Body (`RefreshToolApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `targets` | `string`[] | No | MV targets to refresh (omit for all). Options: tool_drafts_mv |
| `idempotency_key` | `string` | No | Operation key for ack |
| `accept` | `boolean` | No | Accept or reject. Only meaningful with idempotency_key |
| `soft` | `boolean` | No | Stage the refresh as a pending (held) request — recorded but not enqueued; ack with accept releases/enqueues it |

## Response (`RefreshResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | — |
| `refreshed_views` | `string`[] | Yes | — |
| `invalidated_tags` | `string`[] | Yes | — |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |

---

# `POST` `/tool/search`

Route: /api-reference/tool/post-tool-search

# `POST` `/tool/search`

Search Tool

Search tools — composable infra architecture.

## Request Body (`SearchToolApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | — |
| `filter_department_ids` | `string`[] | No | — |
| `filter_creatable` | `string`[] | No | — |
| `department_search` | `string` | No | — |
| `page_size` | `integer` | No | — |
| `page_offset` | `integer` | No | — |
| `snapshot_key` | `string` | No | Cache snapshot key for consistent reads across related requests |

## Response (`ListToolApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `actor_name` | `string` | No | Display name of the current actor |
| `tools` | [`ListToolApiTool`](/api-reference/tool/types#listtoolapitool)[] | No | List of tool entries |
| `department_filter` | [`ListFilterSection`](/api-reference/tool/types#listfiltersection) | No | Department filter options |
| `creatable_filter` | [`ListFilterSection`](/api-reference/tool/types#listfiltersection) | No | Creatable filter options |
| `agent_filter` | [`ListFilterSection`](/api-reference/tool/types#listfiltersection) | No | Filter options for agents that reference these tools |
| `flag_filter` | [`ListFilterSection`](/api-reference/tool/types#listfiltersection) | No | Filter options for flags in list UI |
| `permissions_filter` | [`ListFilterSection`](/api-reference/tool/types#listfiltersection) | No | Filter options for permissions in list UI |
| `total_count` | `integer` | No | Total number of tools |
| `import_fields` | [`ImportField`](/api-reference/tool/types#importfield)[] | No | CSV import column schema for the bulk-import dialog |

---

# `POST` `/tool/text_download`

Route: /api-reference/tool/post-tool-text-download

# `POST` `/tool/text_download`

Download Text

Download a text file by text resource ID.

## Request Body (`TextDownloadToolApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `text_id` | `string` | Yes | UUID of the texts_resource to download |

## Response

```
{}
```

---

# `POST` `/tool/title`

Route: /api-reference/tool/post-tool-title

# `POST` `/tool/title`

Title Tool

Rename a tool's group (writes group_names_entry).

## Request Body (`TitleToolApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Group to rename |
| `title` | `string` | Yes | New title (display name) for the group |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant rename |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`TitleToolApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | The group that was renamed |
| `group_name_id` | `string` | Yes | UUID of the new group_names_entry row |
| `title` | `string` | Yes | The title that was set |
| `idempotency_key` | `string` | No | Operation key echoed back |

---

# `POST` `/tool/update`

Route: /api-reference/tool/post-tool-update

# `POST` `/tool/update`

Update Tool

Update tools using composable infra architecture.

## Request Body (`UpdateToolApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `tools` | [`UpdateToolItem`](/api-reference/tool/types#updatetoolitem)[] | No | List of tools to update (required on first call when ``all`` is false) |
| `all` | `boolean` | No | When true, apply ``patch`` to every tool matching the filter fields below (minus ``excluded_ids``) |
| `excluded_ids` | `string`[] | No | UUIDs to skip even when matched by ``all``-mode filters |
| `patch` | [`UpdateToolPatch`](/api-reference/tool/types#updatetoolpatch) | No | Shared change set applied to every matched row when ``all=true`` (sparse — only set fields are updated; ``patch.id`` ignored) |
| `search` | `string` | No | Full-text search query |
| `filter_department_ids` | `string`[] | No | Filter by department UUIDs |
| `filter_creatable` | `string`[] | No | Filter by creatable flag (no-op for row filtering today; accepted for forward compatibility) |
| `filter_agent_ids` | `string`[] | No | Filter by agent UUIDs that reference these tools (no-op for row filtering today; accepted for forward compatibility) |
| `department_search` | `string` | No | Search text for department facet (no-op for row filtering) |
| `flag_search` | `string` | No | Search text for flag facet (no-op for row filtering) |
| `agent_search` | `string` | No | Search text for agent facet (no-op for row filtering) |
| `idempotency_key` | `string` | No | Operation key for ack — promotes or rejects a dormant update |
| `soft` | `boolean` | No | Stage the update dormant (active=False) — propose; the ack (\{idempotency_key, accept\}) promotes/rejects it |
| `accept` | `boolean` | No | Accept (promote) or reject dormant state. Only meaningful with idempotency_key |

## Response (`UpdateToolApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | [`ToolResultItem`](/api-reference/tool/types#toolresultitem)[] | Yes | List of operation results |
| `idempotency_key` | `string` | No | Idempotency key echoed back for client correlation |
| `tools` | [`ListToolApiTool`](/api-reference/tool/types#listtoolapitool)[] | No | Hydrated rows for the updated tools (same shape as `/tool/search` returns) |

---

# `POST` `/tool/watch`

Route: /api-reference/tool/post-tool-watch

# `POST` `/tool/watch`

Tool Watch Once

One-shot snapshot of run state, snapshot-replayable via ``snapshot_key``.

## Request Body (`WatchApiRequest`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | Chat group whose events we watch |
| `run_id` | `string` | No | Specific run to watch (e.g. the ``run_id`` returned by a prior ``X_Generate`` call). If None, watches every active run in the group at call time. |
| `wait_for_complete` | `boolean` | No | If True, block until the watched run reaches a terminal (complete/failed) event or timeout fires. If False, return current state and exit immediately. |
| `timeout_seconds` | `integer` | No | Max wait time when ``wait_for_complete=True``. |
| `snapshot_key` | `string` | No | Read snapshot key — on the one-shot POST /watch, the audit wrapper records this watch's point-in-time view (latest run state at call time) keyed by it and replays the same view on any later call with the same key. Ignored by the SSE GET stream. |

## Response (`WatchApiResponse`)

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | — |
| `runs` | [`RunStatus`](/api-reference/tool/types#runstatus)[] | Yes | — |
| `timed_out` | `boolean` | No | — |
| `waited_seconds` | `number` | No | — |

---

# Tool Types

Route: /api-reference/tool/types

# Tool Types

## `CallerPermissions`

Evaluated permissions for the current caller on this artifact type.

| Field | Type | Required | Description |
|---|---|---|---|
| `can_create` | `boolean` | Yes | Whether the caller can create new artifacts |
| `can_draft` | `boolean` | Yes | Whether the caller can create/update drafts |
| `can_duplicate` | `boolean` | Yes | Whether the caller can duplicate artifacts |
| `has_access` | `boolean` | No | Whether the caller can view this entity |
| `can_edit` | `boolean` | No | Whether the caller can edit this entity |
| `can_delete` | `boolean` | No | Whether the caller can delete this entity |
| `disabled_reason` | `string` | No | Human-readable reason if editing is disabled |

---

## `ColumnInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Column name |
| `type` | `string` | Yes | Column data type |
| `nullable` | `boolean` | Yes | Whether the column is nullable |

---

## `CreateArgInput`

Inline arg creation input.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Argument name |
| `field_type` | `string` | Yes | Argument type (string, number, boolean, array) |
| `description` | `string` | No | Argument description |
| `required` | `boolean` | No | Whether the argument is required |
| `default_value` | `string` | No | Default value |

---

## `CreateArgPositionInput`

Inline arg position creation input.

| Field | Type | Required | Description |
|---|---|---|---|
| `args_id` | `string` | Yes | Argument resource ID this position belongs to |
| `value` | `integer` | Yes | Position value |

---

## `CreateArgsOutputInput`

Inline args output creation input.

| Field | Type | Required | Description |
|---|---|---|---|
| `args_id` | `string` | Yes | Argument resource ID this output belongs to |
| `name` | `string` | Yes | Output name |
| `template` | `string` | No | Output template |

---

## `CreateToolItem`

Single tool item for create — no tool_id.

Required fields (name): provide ID or value.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Optional pre-assigned identifier |
| `resource_id` | `string` | No | Optional preset UUID for the resource snapshot |
| `name_id` | `string` | No | REQUIRED FOR CREATE (or pass `name`): UUID of an existing name resource |
| `name` | `string` | No | REQUIRED FOR CREATE (or pass `name_id`): display name text (creates new resource) |
| `description_id` | `string` | No | UUID of an existing description resource |
| `description` | `string` | No | Description text value (creates new resource if description_id not provided) |
| `department_ids` | `string`[] | No | Department identifiers |
| `flag_ids` | `string`[] | No | Flag option identifiers |
| `arg_positions_ids` | `string`[] | No | Argument position identifiers |
| `args_ids` | `string`[] | No | Argument identifiers |
| `args_outputs_ids` | `string`[] | No | Argument output identifiers |
| `permission_ids` | `string`[] | No | Permission identifiers |
| `instruction_id` | `string` | No | Response template instruction resource UUID |
| `tool_ids` | `string`[] | No | Related tool identifiers |

---

## `DeleteToolResult`

Per-item result within a bulk delete response.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the deletion succeeded |
| `tool_id` | `string` | No | Deleted tool identifier (None when soft-skipped without resolution) |
| `message` | `string` | Yes | Result message |

---

## `DocsApiResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `list` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `detail` | [`PageMetaItem`](#pagemetaitem) | Yes | — |
| `new` | [`PageMetaItem`](#pagemetaitem) | Yes | — |

---

## `DocsResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Resource or entry name |
| `type` | `string` | Yes | Resource or entry type identifier |
| `description` | `string` | Yes | Human-readable description |
| `materialized_view` | [`MvInfo`](#mvinfo) | No | Materialized view metadata |
| `tables` | [`TableInfo`](#tableinfo)[] | Yes | Related database tables |
| `operations` | [`OperationInfo`](#operationinfo)[] | Yes | Available operations |

---

## `EvalSetup`

Run-level eval scaffold — first-class on the generate response.

Audit's ``**output`` spread carries this onto
``<artifact>.generate.completed``. Null when no rubric-bearing
agent participated.

| Field | Type | Required | Description |
|---|---|---|---|
| `test_id` | `string` | Yes | — |
| `invocations` | [`InvocationSlot`](#invocationslot)[] | Yes | — |

---

## `GenerateConfig`

Developer configuration — all optional with sensible defaults.

| Field | Type | Required | Description |
|---|---|---|---|
| `operations` | `string`[] | No | — |
| `dangerous` | `boolean` | No | — |
| `params` | `object` | No | — |
| `group_id` | `string` | No | — |

---

## `GenerationsToolListItem`

Single generation group in the tool generations response.

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | UUID of the generation group |
| `session_id` | `string` | No | UUID of the parent session |
| `group_name` | `string` | No | Name of the generation group |
| `created_at` | `string` | No | Timestamp of the generation |

---

## `GetToolDraftResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | UUID of the draft |
| `created_at` | `string` | Yes | Creation timestamp |
| `generated` | `boolean` | Yes | Whether this was AI-generated |
| `mcp` | `boolean` | Yes | Whether MCP tooling was used |
| `active` | `boolean` | Yes | Whether this draft is active |
| `session_id` | `string` | Yes | Associated session UUID |
| `name` | `string` | No | Immutable draft label set at create time |
| `arg_position_ids` | `string`[] | Yes | Associated arg position UUIDs |
| `arg_ids` | `string`[] | Yes | Associated arg UUIDs |
| `args_output_ids` | `string`[] | Yes | Associated args output UUIDs |
| `department_ids` | `string`[] | Yes | Associated department UUIDs |
| `description_ids` | `string`[] | Yes | Associated description UUIDs |
| `flag_ids` | `string`[] | Yes | Associated flag UUIDs |
| `name_ids` | `string`[] | Yes | Associated name UUIDs |
| `instruction_ids` | `string`[] | No | Associated instruction UUIDs |
| `permission_ids` | `string`[] | Yes | Associated permission UUIDs |
| `profile_ids` | `string`[] | Yes | Associated profile UUIDs |
| `agent_ids` | `string`[] | No | Associated agent UUIDs |
| `pending_arg_position_ids` | `string`[] | No | Pending arg position UUIDs |
| `pending_arg_ids` | `string`[] | No | Pending arg UUIDs |
| `pending_args_output_ids` | `string`[] | No | Pending args output UUIDs |
| `pending_department_ids` | `string`[] | No | Pending department UUIDs |
| `pending_description_ids` | `string`[] | No | Pending description UUIDs |
| `pending_flag_ids` | `string`[] | No | Pending flag UUIDs |
| `pending_name_ids` | `string`[] | No | Pending name UUIDs |
| `pending_instruction_ids` | `string`[] | No | Pending instruction UUIDs |
| `pending_permission_ids` | `string`[] | No | Pending permission UUIDs |
| `pending_agent_ids` | `string`[] | No | Pending agent UUIDs |

---

## `GroupCall`

Tool call referenced by a message.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `tool_name` | `string` | No | — |
| `template_name` | `string` | No | — |
| `tool` | `object` | No | — |
| `ledger_status` | `string` | No | — |
| `ledger_operation` | `string` | No | — |
| `ledger_artifact` | `string` | No | — |
| `ledger_artifact_id` | `string` | No | — |

---

## `GroupMessage`

Message within a run.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `role` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `text_ids` | `string`[] | No | — |
| `audio_ids` | `string`[] | No | — |
| `image_ids` | `string`[] | No | — |
| `video_ids` | `string`[] | No | — |
| `file_ids` | `string`[] | No | — |
| `call_ids` | `string`[] | No | — |
| `calls` | [`GroupCall`](#groupcall)[] | No | — |
| `reasoning` | `boolean` | No | True when this row is a chain-of-thought trace persisted alongside the assistant answer (rendered as a collapsed accordion). |
| `in_context` | `boolean` | No | Whether this message is included in the LLM context for the next generation. Mirrors the dedup pass that builds chat history (see in_context_reason). |
| `in_context_reason` | `string` | No | Why this message is in/out of LLM context. 'kept' = included; 'deduped_read' = older read-only call to a tool that has a fresher result later in the group; future values may include 'trimmed_top_n'. |

---

## `GroupResource`

Lightweight `\{id, name\}` for cross-referencing run-level ids
(``model_id`` / ``agent_id`` / ``profile_id``) against human-readable
names on the analytics panel. Names come from the canonical
``get_models`` / ``get_agents`` / ``get_profiles`` black boxes.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `name` | `string` | No | — |

---

## `GroupRun`

Run within a group, with its messages.

Carries token / cost / model / agent / profile attribution so the
analytics view can render per-run cost + actor info without a
parallel detail shape. ``profile_id`` is the authoring profile
(human user), ``agent_id`` is the LLM-side actor, ``model_id`` is
the model used by that agent. All optional — runs predating these
columns or with unresolved attributions surface ``None``.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | — |
| `created_at` | `string` | No | — |
| `input_tokens` | `integer` | No | — |
| `output_tokens` | `integer` | No | — |
| `cached_input_tokens` | `integer` | No | — |
| `cost` | `number` | No | — |
| `model_id` | `string` | No | — |
| `agent_id` | `string` | No | — |
| `profile_id` | `string` | No | — |
| `previous_context_start_index` | `integer` | No | Index in ``messages`` where the current run's own messages begin; earlier rows are previous-context replay. ``None`` when the run has no previous context attached. |
| `messages` | [`GroupMessage`](#groupmessage)[] | No | — |

---

## `ImportField`

Field descriptor for CSV import column mapping.

| Field | Type | Required | Description |
|---|---|---|---|
| `key` | `string` | Yes | — |
| `label` | `string` | Yes | — |
| `required` | `boolean` | No | — |
| `multi` | `boolean` | No | — |
| `type` | `string` | No | — |
| `example` | `string` | No | — |
| `description` | `string` | No | — |

---

## `InvocationSlot`

One agent's slot in a multi-agent generation pool.

Populated by ``setup_generation_test`` when an agent carries a
rubric. The client uses these IDs to drive the eval workflow:
review the candidate's output, optionally fire a grader against
its ``invocation_id``, and promote/reject by call_id via the
existing ``idempotency_key + accept`` pattern.

| Field | Type | Required | Description |
|---|---|---|---|
| `invocation_id` | `string` | Yes | — |
| `agent_id` | `string` | Yes | — |
| `rubric_id` | `string` | No | — |

---

## `ListFilterOption`

Standardized option for list endpoint filter sections.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Unique identifier for this filter option |
| `name` | `string` | No | Display name |
| `count` | `integer` | No | Number of matching records |
| `hex_code` | `string` | No | Hex color code for display |
| `value` | `string` | No | Internal value |
| `type` | `string` | No | Option type discriminator |

---

## `ListFilterSection`

Filter section with options and echoed request state.

| Field | Type | Required | Description |
|---|---|---|---|
| `options` | [`ListFilterOption`](#listfilteroption)[] | No | Available filter options |
| `selected_ids` | `string`[] | No | Currently selected filter option IDs |
| `search` | `string` | No | Active search text for filtering |

---

## `ListToolApiTool`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Tool artifact UUID (canonical id; mirrors tool_id) |
| `tool_id` | `string` | No | Tool unique identifier |
| `name` | `string` | No | Display name of the tool |
| `description` | `string` | No | Tool description text |
| `active` | `boolean` | No | Whether this tool is currently active |
| `is_inactive` | `boolean` | No | Whether this tool is inactive (derived from tool_active flag) |
| `flag_ids` | `string`[] | No | Currently selected flag option UUIDs |
| `permission_ids` | `string`[] | No | Permission resource UUIDs assigned to this tool |
| `agent_ids` | `string`[] | No | Agent artifact UUIDs that reference this tool |
| `department_ids` | `string`[] | No | Department resource UUIDs assigned to this tool |
| `updated_at` | `string` | No | Timestamp of last update |
| `can_edit` | `boolean` | No | Whether the current user can edit |
| `can_duplicate` | `boolean` | No | Whether the current user can duplicate |
| `can_delete` | `boolean` | No | Whether the current user can delete |
| `pending_status` | `string` | No | Latest soft_calls_mv status: 'pending' / 'accepted' / 'rejected' |
| `pending_operation` | `string` | No | Operation type ('create'|'update'|'delete'|'duplicate') of the pending op |
| `pending_call_id` | `string` | No | call_id (idempotency key for ack) of the pending op |

---

## `MvInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Materialized view name |
| `definition` | `string` | Yes | SQL definition of the view |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the view |

---

## `OperationInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Operation name |
| `description` | `string` | Yes | Human-readable description of the operation |
| `params` | [`ParamInfo`](#paraminfo)[] | Yes | List of operation parameters |
| `returns` | `object` | No | Return type schema |

---

## `OperationPrompts`

Starter prompts keyed by operation name.

Each key is an operation (e.g. "create", "search", "draft", "export")
and the value is a list of starter prompts for that operation.
The client picks from the operations the caller has permission for
and rotates through them.

| Field | Type | Required | Description |
|---|---|---|---|
| `prompts` | `object` | No | Map of operation name to starter prompts |

---

## `PageMetaItem`

| Field | Type | Required | Description |
|---|---|---|---|
| `title` | `string` | Yes | — |
| `description` | `string` | Yes | — |

---

## `ParamInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Parameter name |
| `type` | `string` | Yes | Parameter data type |
| `required` | `boolean` | Yes | Whether the parameter is required |
| `default` | `any` | No | Default value if not required |

---

## `ProducedMedia`

One asset produced by a generation run.

``resource_id`` is the canonical id the per-artifact download tools
accept (e.g. ``Scenario_Image_Download(image_id=resource_id)`` for
``modality="image"``). It maps to ``images_resource.id`` /
``videos_resource.id`` / ``audios_resource.id`` depending on the
modality.

| Field | Type | Required | Description |
|---|---|---|---|
| `modality` | `"image"` \| `"video"` \| `"audio"` | Yes | — |
| `resource_id` | `string` | Yes | — |
| `upload_id` | `string` | Yes | — |
| `mime_type` | `string` | No | — |
| `file_size` | `integer` | No | — |

---

## `ProfileSummary`

Caller identity derived from JWT — who you are on this page.

Superset of the old six-field version: now carries everything the client
needs so that ``/\{artifact\}/context`` fully replaces ``/profiles/context``
and the extra ``getLayoutContextData`` round-trip can be dropped.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Display name of the authenticated user |
| `role` | `string` | Yes | Role name (e.g. 'Super Administrator') |
| `role_level` | `integer` | Yes | Role hierarchy level (0 = highest privilege) |
| `department_ids` | `string`[] | Yes | Departments the user belongs to |
| `artifact_access` | `string`[] | Yes | Artifact types this role can access (sidebar visibility) |
| `role_permissions` | `any`[][] | Yes | Full (artifact, operation) permission tuples for granular page gating |
| `is_active` | `boolean` | Yes | Whether the user's profile is active |
| `id` | `string` | Yes | Profile UUID (SocketProvider, ProfileProvider) |
| `theme` | [`ThemeBundle`](#themebundle) | No | Resolved theme: hex primitives + derived oklch tokens + score thresholds |
| `session_id` | `string` | No | Current session UUID |
| `is_emulation` | `boolean` | No | Whether user is in emulation mode (ProfileProvider) |
| `role_resources` | [`QGetProfileContextV4RoleResource`](#qgetprofilecontextv4roleresource)[] | No | All role resources for emulation display (ProfileProvider) |
| `scoped_roles` | `string`[] | No | Roles the user can emulate (ProfileProvider) |
| `active` | `boolean` | No | Alias for is_active (ProfileProvider uses this name) |

---

## `QGetProfileContextV4RoleResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `role` | `string` | No | — |
| `name` | `string` | No | — |
| `description` | `string` | No | — |
| `icon_value` | `string` | No | — |
| `color_hex` | `string` | No | — |

---

## `RunStatus`

Outcome of one watched run.

| Field | Type | Required | Description |
|---|---|---|---|
| `run_id` | `string` | Yes | — |
| `status` | `"pending"` \| `"completed"` \| `"failed"` | Yes | — |
| `modality` | `string` | No | Modality of generated output (image, video, text…) |
| `resource_ids` | `string`[] | No | Resource UUIDs produced by this run (e.g. images_resource ids) |
| `error` | `string` | No | — |

---

## `TableInfo`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Table name |
| `columns` | [`ColumnInfo`](#columninfo)[] | Yes | List of columns in the table |

---

## `ThemeBundle`

Full theme payload for a page bootstrap.

Riding along on every ``/\{artifact\}/context`` response via
``ProfileSummary.theme``. Layers:
  - ``primitives`` / ``dark_primitives`` — hex inputs the settings
    editor reads/writes (light + dark palettes).
  - ``tokens`` / ``dark_tokens`` — oklch tokens the client paints with.
    ``ThemeStyle`` emits two ``<style>`` blocks: one scoped to
    ``:root:not(.dark)`` (light) and one to ``:root.dark`` (dark).
  - ``thresholds`` — numeric score thresholds for analytics components.
Empty-in → empty-out per token: missing values fall through to the
matching ``globals.css`` default.

| Field | Type | Required | Description |
|---|---|---|---|
| `primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (light palette, for the theme editor) |
| `tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for light mode (SSR CSS-var injection) |
| `dark_primitives` | [`ThemePrimitives`](#themeprimitives) | No | Hex inputs from the setting (dark palette, for the theme editor) |
| `dark_tokens` | [`ThemeTokens`](#themetokens) | No | Derived oklch tokens for dark mode (SSR CSS-var injection) |
| `thresholds` | [`Thresholds`](#thresholds) | No | Score thresholds resolved from the setting |

---

## `ThemePrimitives`

40 optional fields. The 17 essentials drive the rest; the other 23
are overrides for fine-tuning when derivation isn't what you want.

Empty primitive → empty token → client falls back to globals.css.

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `primary` | `string` | No | — |
| `accent` | `string` | No | — |
| `card` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `ring` | `string` | No | — |
| `border` | `string` | No | — |
| `destructive` | `string` | No | — |
| `success` | `string` | No | — |
| `warning` | `string` | No | — |
| `info` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `input` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `ThemeTokens`

40 fully-resolved CSS variable values (snake_case 1:1 with vars).

| Field | Type | Required | Description |
|---|---|---|---|
| `background` | `string` | No | — |
| `foreground` | `string` | No | — |
| `card` | `string` | No | — |
| `card_foreground` | `string` | No | — |
| `popover` | `string` | No | — |
| `popover_foreground` | `string` | No | — |
| `primary` | `string` | No | — |
| `primary_foreground` | `string` | No | — |
| `secondary` | `string` | No | — |
| `secondary_foreground` | `string` | No | — |
| `muted` | `string` | No | — |
| `muted_foreground` | `string` | No | — |
| `accent` | `string` | No | — |
| `accent_foreground` | `string` | No | — |
| `destructive` | `string` | No | — |
| `destructive_foreground` | `string` | No | — |
| `danger` | `string` | No | — |
| `danger_foreground` | `string` | No | — |
| `border` | `string` | No | — |
| `input` | `string` | No | — |
| `ring` | `string` | No | — |
| `success` | `string` | No | — |
| `success_foreground` | `string` | No | — |
| `warning` | `string` | No | — |
| `warning_foreground` | `string` | No | — |
| `info` | `string` | No | — |
| `info_foreground` | `string` | No | — |
| `chart1` | `string` | No | — |
| `chart2` | `string` | No | — |
| `chart3` | `string` | No | — |
| `chart4` | `string` | No | — |
| `chart5` | `string` | No | — |
| `sidebar` | `string` | No | — |
| `sidebar_foreground` | `string` | No | — |
| `sidebar_primary` | `string` | No | — |
| `sidebar_primary_foreground` | `string` | No | — |
| `sidebar_accent` | `string` | No | — |
| `sidebar_accent_foreground` | `string` | No | — |
| `sidebar_border` | `string` | No | — |
| `sidebar_ring` | `string` | No | — |

---

## `Thresholds`

Numeric score thresholds resolved from the active setting.

Server pre-buckets dashboard metrics into ``success | warning | danger |
neutral`` already, so most components don't need these values. Surface
them for chart reference lines, tooltips, and any client-side bucketing.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `integer` | Yes | Score >= this counts as success |
| `warning` | `integer` | Yes | Score >= this counts as warning |
| `danger` | `integer` | Yes | Score < success threshold but >= this counts as danger; below is neutral/no-data |

---

## `ToolArgDraftValue`

Unified per-arg draft value for the Arguments step card.

Each entry maps 1:1 to one row of the Arguments list. Position is the
*index* of the entry — the resolver creates/finds an arg_positions_resource
row matching (args_id, value=index). Outputs nest under their owning arg.
Saved rows (id set) stay immutable; the client surfaces them as chips and
cloning into a fresh draft to edit (Roles pattern).

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Existing args_resource id when re-linking |
| `name` | `string` | Yes | Argument name |
| `field_type` | `string` | No | Argument type (string, number, boolean, array) |
| `description` | `string` | No | Argument description |
| `required` | `boolean` | No | Whether the argument is required |
| `default_value` | `string` | No | Default value |
| `outputs` | [`ToolArgOutputDraftValue`](#toolargoutputdraftvalue)[] | No | Per-arg jinja output templates |

---

## `ToolArgOutputDraftValue`

Output-template draft value for an inline-creatable args_outputs row.

id null → server creates an args_outputs_resource row scoped to the
enclosing arg's resolved id. id set → row is re-linked unchanged
(saved rows are immutable on this surface).

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Existing args_outputs_resource id when re-linking |
| `name` | `string` | Yes | Output name |
| `template` | `string` | No | Jinja template — variables drawn from the arg's name and any other selected args |

---

## `ToolArgOutputResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Argument output resource identifier |
| `args_id` | `string` | No | Associated argument identifier |
| `name` | `string` | No | Output template name |
| `template` | `string` | No | Output template body |
| `generated` | `boolean` | No | Whether the output template was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `ToolArgPositionResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Argument position resource identifier |
| `args_id` | `string` | No | Associated argument identifier |
| `value` | `integer` | No | Position value |
| `generated` | `boolean` | No | Whether the argument position was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `ToolArgResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Argument resource identifier |
| `name` | `string` | No | Argument name |
| `description` | `string` | No | Argument description |
| `field_type` | `string` | No | Argument field type |
| `required` | `boolean` | No | Whether the argument is required |
| `default_value` | `string` | No | Argument default value |
| `generated` | `boolean` | No | Whether the argument was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `ToolDepartmentResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `department_id` | `string` | No | Department identifier |
| `name` | `string` | No | Department name |
| `description` | `string` | No | Department description |
| `generated` | `boolean` | No | Whether the department was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `ToolDescriptionResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Description resource identifier |
| `description` | `string` | No | Tool description |
| `generated` | `boolean` | No | Whether the description was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `ToolFieldError`

Per-field error from value resolution.

| Field | Type | Required | Description |
|---|---|---|---|
| `field` | `string` | Yes | Field name that caused the error |
| `message` | `string` | Yes | Error message describing the issue |

---

## `ToolFlagResource`

Flag option row — one per (name, type, value) entry in flags_resource.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Flag resource identifier |
| `name` | `string` | No | Flag display name |
| `type` | `string` | No | Flag type (e.g. 'tool_active') |
| `value` | `boolean` | No | Underlying bool value of this option |
| `description` | `string` | No | Flag description |
| `icon_id` | `string` | No | Icon identifier for the flag |
| `icon` | `string` | No | Resolved SVG markup for the icon |
| `generated` | `boolean` | No | Whether this flag was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `ToolInstructionResource`

Instruction resource for a tool.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Instruction resource identifier |
| `template` | `string` | No | Instruction template body |
| `name` | `string` | No | Instruction display name (when present) |
| `generated` | `boolean` | No | Whether the instruction was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `ToolNameResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Name resource identifier |
| `name` | `string` | No | Tool display name |
| `generated` | `boolean` | No | Whether the name was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `ToolPermissionResource`

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Permission resource identifier |
| `artifact` | `string` | No | Permission artifact type |
| `operation` | `string` | No | Permission operation |
| `name` | `string` | No | Permission display name |
| `description` | `string` | No | Permission description |
| `generated` | `boolean` | No | Whether the permission was AI-generated |
| `suggested` | `boolean` | No | Whether this item is suggested |
| `selected` | `boolean` | No | Whether this item is selected |
| `pending` | `boolean` | No | Whether this item is pending acceptance |

---

## `ToolPreviewArg`

Per-arg shape for preview rendering.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Argument name (used as the Jinja variable) |
| `field_type` | `string` | No | Argument type — drives mock-value coercion |
| `default_value` | `string` | No | Fallback if mock value isn't provided |

---

## `ToolPreviewArgHint`

Per-arg type/usage hint inferred from the templates.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Argument name |
| `used` | `boolean` | No | Whether any template references this arg |
| `filters` | `string`[] | No | Jinja filters applied to this arg across templates |

---

## `ToolPreviewOutput`

Per-output shape for preview rendering.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Output name (echoed in the response) |
| `template` | `string` | No | Jinja template body |

---

## `ToolPreviewOutputResult`

Per-output preview result.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Output name (echoes the request) |
| `compiled` | `string` | No | Rendered template string when successful |
| `error` | `string` | No | Jinja error message when rendering or parsing failed |

---

## `ToolResultItem`

Per-item result within a bulk create/update response.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `boolean` | Yes | Whether the operation succeeded |
| `tool_id` | `string` | No | Tool unique identifier |
| `message` | `string` | Yes | Result message |
| `errors` | [`ToolFieldError`](#toolfielderror)[] | No | List of field-level errors |

---

## `UpdateToolItem`

Single tool item for update — tool_id required, all fields optional.

Only provided fields are updated (partial update).

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | Target tool identifier to update |
| `name_id` | `string` | No | Name resource identifier |
| `name` | `string` | No | Display name value |
| `description_id` | `string` | No | Description resource identifier |
| `description` | `string` | No | Description text value |
| `department_ids` | `string`[] | No | Department identifiers |
| `flag_ids` | `string`[] | No | Flag option identifiers |
| `arg_positions_ids` | `string`[] | No | Argument position identifiers |
| `args_ids` | `string`[] | No | Argument identifiers |
| `args_outputs_ids` | `string`[] | No | Argument output identifiers |
| `permission_ids` | `string`[] | No | Permission identifiers |
| `instruction_id` | `string` | No | Response template instruction resource UUID |
| `tool_ids` | `string`[] | No | Related tool identifiers |

---

## `UpdateToolPatch`

Shared patch for bulk-update-all-matching mode.

Inherits every field from ``UpdateToolItem`` and just relaxes
``id`` to optional — the bulk impl stamps the resolved id onto a
clone of the patch per matched row, so any client-supplied id is
ignored. Sparse semantics: only fields the client sets are written.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | No | Ignored — bulk impl stamps the resolved tool id per matched row |
| `name_id` | `string` | No | Name resource identifier |
| `name` | `string` | No | Display name value |
| `description_id` | `string` | No | Description resource identifier |
| `description` | `string` | No | Description text value |
| `department_ids` | `string`[] | No | Department identifiers |
| `flag_ids` | `string`[] | No | Flag option identifiers |
| `arg_positions_ids` | `string`[] | No | Argument position identifiers |
| `args_ids` | `string`[] | No | Argument identifiers |
| `args_outputs_ids` | `string`[] | No | Argument output identifiers |
| `permission_ids` | `string`[] | No | Permission identifiers |
| `instruction_id` | `string` | No | Response template instruction resource UUID |
| `tool_ids` | `string`[] | No | Related tool identifiers |

---

## `app__infra__tool__types__DraftFormState`

Server-authoritative form state returned after draft save.

| Field | Type | Required | Description |
|---|---|---|---|
| `name_id` | `string` | No | Resolved name resource identifier |
| `name` | `string` | No | Resolved name value |
| `description_id` | `string` | No | Resolved description resource identifier |
| `description` | `string` | No | Resolved description value |
| `flag_ids` | `string`[] | No | Selected flag option UUIDs |
| `active` | `boolean` | No | Echoed tool_active flag state |
| `department_ids` | `string`[] | No | Department identifiers |
| `arg_ids` | `string`[] | Yes | Argument identifiers |
| `arg_position_ids` | `string`[] | Yes | Argument position identifiers |
| `args_output_ids` | `string`[] | Yes | Argument output identifiers |
| `args_outputs_ids` | `string`[] | Yes | Legacy alias for argument output identifiers |
| `args_drafts` | [`ToolArgDraftValue`](#toolargdraftvalue)[] | No | Echoed unified per-arg drafts after resolution (ids filled in, outputs nested) |
| `instruction_id` | `string` | No | Instruction resource identifier |
| `instruction_ids` | `string`[] | No | Instruction resource identifiers |
| `permission_ids` | `string`[] | Yes | Permission identifiers |
| `pending_ids` | `string`[] | No | Pending resource identifiers |

---

## `app__infra__tool__types__SectionFilter`

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | `string` | No | Filter options by search text |
| `limit` | `integer` | No | Max options to return |
| `selected` | `boolean` | No | Only return selected items |
| `suggested` | `boolean` | No | Only return suggested items |
| `include` | `boolean` | No | Include this section in response (default true) |

---

---

# `GET` `/userinfo`

Route: /api-reference/userinfo

# `GET` `/userinfo`

Userinfo

UserInfo endpoint — returns user claims from access token.

## Response

```
{
  "type": "object",
  "additionalProperties": true,
  "title": "Response Userinfo Userinfo Get"
}
```

---

# `GET` `/.well-known/oauth-authorization-server`

Route: /api-reference/well-known-oauth-authorization-server

# `GET` `/.well-known/oauth-authorization-server`

Oauth Authorization Server Metadata

RFC 8414 OAuth Authorization Server Metadata — same as OIDC discovery.

## Response

```
{}
```

---

# `GET` `/.well-known/openid-configuration`

Route: /api-reference/well-known-openid-configuration

# `GET` `/.well-known/openid-configuration`

Openid Configuration

OIDC discovery endpoint.

## Response

```
{
  "additionalProperties": true,
  "type": "object",
  "title": "Response Openid Configuration  Well Known Openid Configuration Get"
}
```

---

# Attempts

Route: /attempts

# Attempts

An **attempt** is the parent container for a single learner's run
through a simulation. It owns the chats, the grading, the artifacts,
and the lifecycle state. If a learner is *doing* something in Glow,
they're inside an attempt.

## What is an attempt?

An attempt is created when a learner starts a simulation. It holds:

- **One chat per scenario** in the simulation — each scenario becomes
  a sibling conversation under the same attempt
- **Grading state** — when the attempt completes, rubric scoring
  rolls up across the chats
- **Lifecycle metadata** — start time, completion time, archive flag,
  practice vs. graded mode
- **Group membership** — attempts can be bound to an
  [attempt group](#groups) for batch coordination

The conversation surface itself — messages, audio, hints, grading —
lives in the [chat](/chat) sub-namespace. The analytics view on top
of an attempt lives in [dashboard](/dashboard). This page covers the
**root attempt artifact**: the lifecycle and management ops that act
on an attempt as a whole.

---

## The lifecycle

Every attempt moves through a small state machine:

| Step | Endpoint | What happens |
|------|----------|--------------|
| **1. Start** | `POST /attempt/start` | Create the attempt, fan out one chat per scenario |
| **2. Run** | `POST /chat/*` | Learner converses with each persona — see [chat](/chat) |
| **3. Stop (optional)** | `POST /attempt/stop` | Halt an in-flight AI generation mid-stream |
| **4. Complete** | `POST /attempt/complete` | Finalize the attempt and trigger rubric grading |
| **5. Archive (optional)** | `POST /attempt/archive` | Hide from default lists without deleting |

Steps 1, 3, 4, and 5 are the focus of this page. Step 2 is the
chat surface — covered in full on [/chat](/chat).

---

## Starting an attempt

`POST /attempt/start` takes either a `home_id` or a `practice_id`
(the entry the learner clicked from the [home](/home) or
[practice](/practice) page) and resolves it into the underlying
simulation. One chat is created per scenario in that simulation, all
parented under the new `attempt_id`.

```bash
# Start from a home entry
glow attempts start --body '{"home_id": "00000000-0000-0000-0000-000000000001"}'

# Start from a practice entry
glow attempts start --body '{"practice_id": "00000000-0000-0000-0000-000000000002"}'
```

The response carries the new `attempt_id` plus the list of
`chat_id`s that were spawned. From there the client typically calls
`POST /chat/message` (or the audio variants) to drive the first
conversation.

---

## Stopping in-flight generation

`POST /attempt/stop` halts a running AI response. It targets the
attempt's `group_id` (the streaming hub key — see
[Streaming Foundations](/streaming)) and cancels the in-flight
generation without tearing down the attempt itself.

```bash
glow attempts stop --body '{"group_id": "00000000-0000-0000-0000-000000000003"}'
```

This is the safe way to interrupt a long-running response (e.g.
the learner wants to retry, or the persona is going off the rails).
The attempt and chat rows are unaffected — only the generation is
cancelled.

---

## Completing and archiving

Two different operations, two different intents.

### Complete

`POST /attempt/complete` finalizes the attempt. It freezes the
chats, runs the rubric grader across them, and produces the
`completion_id` that downstream views (dashboard, reports) hang off
of.

```bash
glow attempts complete --body '{
  "attempt_id": "00000000-0000-0000-0000-000000000010",
  "message": "Completed by learner"
}'
```

Completion is irreversible in the sense that the grading rollup
happens at this point — subsequent chat edits won't retroactively
re-grade. To re-grade, regenerate via the chat-level grade endpoint
(see [/chat](/chat)).

### Archive

`POST /attempt/archive` hides attempts from default list views
without deleting them. Use it when a learner's run was a mistake,
a test, or otherwise shouldn't show up in dashboards.

Archive uses the canonical **bulk-write shape** — pass either
explicit IDs, or `all: true` with flat filter fields plus
`excluded_ids`. See [Patterns: bulk operations](/patterns) for the
full pattern.

```bash
# Archive specific attempts
glow attempts archive --body '{
  "attempt_ids": ["00000000-0000-0000-0000-000000000010"],
  "archived": true
}'

# Bulk-archive everything matching a filter, except a few keepers
glow attempts archive --body '{
  "all": true,
  "filter_cohort_ids": ["00000000-0000-0000-0000-000000000020"],
  "excluded_ids": ["00000000-0000-0000-0000-000000000011"],
  "archived": true
}'
```

To unarchive, pass `archived: false` with the same selector. Default
search hides archived attempts; pass `show_archived: true` to
include them.

---

## Listing and searching

`POST /attempt/search` is the canonical paginated history endpoint.
The previous per-view `/attempt/{home,practice,dashboard}/search`
routes were collapsed into this one — view intent is now expressed
through filter parameters (`practice`, `target_profile_id`,
`profile_ids`, …).

```bash
glow attempts search --body '{
  "cohort_ids": ["00000000-0000-0000-0000-000000000020"],
  "simulation_search": "tutoring",
  "practice": false,
  "page": 0,
  "page_size": 25
}'
```

The response is a `HistoryResponse` with hydrated display aggregates
(score %, persona, time, etc.) plus filter facets so the UI can
render dropdowns without a second round-trip. For the full facet
recipe and filter-field conventions, see
[Patterns: search facets](/patterns#recipe-3-search-facets-search--filter)
and the [Attempt API reference](/api-reference/attempt) for the
complete filter schema.

---

## Exporting

`POST /attempt/export` returns a `{file_id, file_name, row_count}`
descriptor. The client then downloads the actual ZIP via the
canonical media path (`/attempt/file/download`) — see
[Media Foundations](/media) for the universal download flow.

```bash
glow attempts export --body '{
  "view": "dashboard",
  "attempt_id": "00000000-0000-0000-0000-000000000010"
}'
```

The export bundles chat transcripts, audio, rubric scoring, and any
generated artifacts. View-aware: `view: "record"` exports a single
learner's history, `view: "dashboard"` exports the cohort-level
slice, etc.

---

## Groups

`POST /attempt/group` resolves (or mints) the `group_id` that ties
an attempt to the streaming hub. Most clients don't call this
directly — `attempt/start` mints the group for you — but it's
exposed for advanced flows that need to coordinate cross-attempt
batches or re-attach to an existing group.

---

## Universal ops

The attempt artifact also exposes the universal cross-cutting
operations every artifact in Glow gets for free. These are
documented once in Foundations rather than re-explained here:

- `POST /attempt/context`, `POST /attempt/problem`,
  `POST /attempt/refresh`, `POST /attempt/title` — generic artifact
  helpers (context loading, error surfacing, cache-bust, retitle).
- `POST /attempt/generate` and `POST /attempt/generations` — the
  generation request / history pair. See [Generation](/generation).
- `POST /attempt/watch` — the SSE subscription for live updates.
  See [Streaming Foundations](/streaming).
- `POST /attempt/audio_upload`, `POST /attempt/audio_download`,
  `POST /attempt/file_download`, `POST /attempt/file_preview`,
  `POST /attempt/image_download`, `POST /attempt/text_download`,
  `POST /attempt/video_download` — universal media operations.
  See [Media](/media).
- `POST /attempt/get`, `POST /attempt/draft`, `POST /attempt/drafts`
  — single-row fetch and the draft cycle. The draft cycle follows
  the same optimistic-concurrency pattern as [personas](/personas).

---

## Common operations reference

| Task | CLI | API |
|------|-----|-----|
| Start an attempt | `glow attempts start --body '{...}'` | `POST /attempt/start` |
| Stop in-flight generation | `glow attempts stop --body '{...}'` | `POST /attempt/stop` |
| Complete an attempt | `glow attempts complete --body '{...}'` | `POST /attempt/complete` |
| Archive attempts | `glow attempts archive --body '{...}'` | `POST /attempt/archive` |
| Search attempts | `glow attempts search --body '{...}'` | `POST /attempt/search` |
| Export an attempt | `glow attempts export --body '{...}'` | `POST /attempt/export` |
| Resolve attempt group | `glow attempts group --body '{...}'` | `POST /attempt/group` |
| Get one attempt | `glow attempts get --body '{...}'` | `POST /attempt/get` |
| Save a draft | `glow attempts draft --body '{...}'` | `POST /attempt/draft` |
| List drafts | `glow attempts drafts` | `POST /attempt/drafts` |

## Related

- [Chat](/chat) — the conversation surface that lives inside attempts
- [Dashboard](/dashboard) — the analytics view over completed attempts
- [Home](/home) — learner landing page, where attempts are started
- [Practice](/practice) — the practice-mode entry surface
- [Leaderboard](/leaderboard) — cross-attempt ranking view
- [Reports](/reports) — long-form reporting over attempt history
- [Attempt API Reference](/api-reference/attempt) — full endpoint schemas
- [Attempt CLI Reference](/cli-reference/attempts) — all CLI commands and flags

---

# Audit & Lineage

Route: /audit

# Audit & Lineage

```mermaid
flowchart TD
    A[Learner action] --> B[soft_calls_entry row]
    B -->|group_id| C[Session timeline]
    B -->|group_id| D[Per-group runs view]
```

*One learner action becomes a `soft_calls_entry` row, stitched back through `group_id` into the session timeline and the per-group runs view.*

Glow records every mutation that crosses the wire as an append-only
ledger row, then stitches those rows back through `group_id` into
the [Session](/session) timeline and the [Group](/group) detail tree.
This is the write-side discipline that powers post-hoc
"what actually happened" inspection, FERPA review, and replay of
failed invocations.

Audit is not a public endpoint — it is a framework wrapper that every
mutation route runs through. Drilling the trail is done via the
existing system endpoints documented on
[Activity](/activity), [Session](/session), and [Group](/group).

## What gets audited

Every artifact mutation routed through
`run_artifact_operation_with_audit` participates in audit. The wrapper
does three things in order, regardless of whether the operation has a
registered tool:

1. Emits a `{artifact}.{operation}.started` event onto the internal
   socket bus (forwarded to clients by `ws/output/`).
2. Invokes the runner — the actual mutation closure.
3. Emits `{artifact}.{operation}.completed` on success, or
   `{artifact}.{operation}.failed` on error, with the same `call_id`
   as the `.started` event.

When the tool graph resolves a tool for the `(artifact, operation)`
pair, the wrapper additionally writes a tool-call audit row and may
append a `soft_calls_entry` ledger row from inside the runner.

Reads are **not** audited. Cache hits, websocket replays, and the
SSE relay path do not produce ledger rows.

## The soft_calls_entry shape

```mermaid
stateDiagram-v2
    [*] --> pending
    pending --> accepted
    pending --> rejected
```

*Each `soft_calls_entry` carries the wire-level `call_id` plus an `artifact`/`operation` pair; its `status` moves pending → accepted | rejected.*

The ledger lives in `public.soft_calls_entry` and is **insert-only** —
state transitions are recorded as new rows, never updates. A companion
materialized view `soft_calls_mv` collapses to the latest row per
`call_id` for fast lookups.

| Column | Type | Notes |
|---|---|---|
| `id` | `uuid` | Primary key, defaulted to `uuidv7()` so rows sort by insertion time. |
| `call_id` | `uuid` | The wire-level identity carried on `.started` / `.completed` / `.failed`. |
| `artifact` | `text` | Mirrors `permissions_resource.artifact` (e.g. `persona`, `agent`). |
| `operation` | `text` | The operation key (e.g. `create`, `update`, `delete`). |
| `status` | `text` | One of `pending`, `accepted`, `rejected` (enforced by check constraint). |
| `artifact_id` | `uuid` | The row this call mutates / proposes to mutate. |
| `patch` | `jsonb` | Proposed change payload (nullable). |
| `active` | `boolean` | `false` hides the row from `soft_calls_mv` without deleting it. |
| `mcp` | `boolean` | `true` when the call originated from an MCP tool surface. |
| `generated` | `boolean` | `true` when written by the framework, `false` for hand-seeded rows. |
| `created_at` | `timestamptz` | Defaulted to `now()`. |

Vocabulary mirrors `permissions_resource`: the `(artifact, operation)`
pair is the canonical identifier across the tool graph, the audit
ledger, and the permissions table.

### Append-only state transitions

A soft tool call lifecycle looks like:

```
INSERT … status='pending'   ← LLM proposes a change
INSERT … status='accepted'  ← user confirms (or the runner auto-accepts)
```

or:

```
INSERT … status='pending'
INSERT … status='rejected'  ← user declines, no further writes
```

`soft_calls_mv` returns only the latest row per `call_id`, so
consumers see one logical state. Historic transitions are recoverable
by reading the base table directly.

## group_id stitches audit, session, and group

```mermaid
flowchart LR
    G([group_id]) --> T["Session timeline: group_created"]
    G --> R["Group detail: runs + messages"]
    G --> L["Audit ledger: call_id family"]
```

*A single `group_id` resolves three ways — a timeline event, the group-detail tree, and the call_id family in the ledger.*

Every audit row, every run, and every timeline event carries a
`group_id`. That single id is the join key across the three views:

```
                       session_id
                           │
                           ▼
                ┌─────────────────────┐
                │  Session (timeline) │
                └──────────┬──────────┘
                           │  groups[]
                           ▼
                   group_id ──────────────┐
                       │                  │
        ┌──────────────┴───────────┐      │
        ▼                          ▼      ▼
  ┌──────────┐              ┌──────────────────────┐
  │  Group   │              │  soft_calls_entry    │
  │  (runs + │              │  (one row per        │
  │ messages)│              │   mutation call_id)  │
  └──────────┘              └──────────────────────┘
```

The framework guarantees stitching by:

- **Minting `group_id` early** — routes that create-the-group set
  `mint_group_id_if_missing=True`, which consults the active-group
  Redis cache (so `/context`, `/group`, `/search` firing in parallel
  converge on the same id via `SET NX EX`) and materializes the
  `groups_entry` row before the first event fires. Without this the
  `.started` event would carry `group_id=None` and SSE would drop it.
- **Reusing `call_id` across `.started` / `.completed` / `.failed`** —
  one wire-level id per invocation, threaded through both the event
  payloads and the audit row's primary key via `pre_minted_call_id`.
- **Carrying `operation_key`** — a stable per-step identifier (see
  [Idempotency + replay safety](#idempotency--replay-safety) below).

## Reading the audit trail

The audit trail is not exposed as its own endpoint — the existing
system endpoints already surface the relevant slices. The canonical
drill chain is:

| Step | Surface | Endpoint | Carries |
|---|---|---|---|
| 1. Engagement | [Activity](/activity) | `POST /system/activity` | `sessions_count`, per-profile breakdown |
| 2. Session pick | [Activity](/activity) | `POST /system/sessions` | `session_id` per row |
| 3. Session detail | [Session](/session) | `POST /system/session` | `groups[]` + `timeline[]` |
| 4. Group detail | [Group](/group) | `POST /system/group` (`include_detail: true`) | `runs[]` + `messages[]` with `calls[]` |
| 5. Receipt | filesystem | call JSON receipt (`call_upload_id`) | full `started` / `completed` / `failed` event log |

Each step narrows the time window and the entity set. The Group
endpoint's lean mode (`include_detail: false`) is the cheap path used
by the audit-linking middleware — it returns identity only, enough to
hyperlink a `group_id` back to its session without paying for the full
runs + messages tree.

The Group page already documents the runs and messages shape; see
[Group → Understanding the detail response](/group#understanding-the-detail-response).

## Idempotency + replay safety

Two ids work together to make audited calls safe to re-fire:

- **`call_id`** — minted per invocation. Identifies one specific
  attempt. Different attempts of the same logical operation get
  different `call_id`s.
- **`operation_key`** — stable across attempts of the same logical
  step. Carried on the wire alongside `call_id`, and persisted on the
  audit row.

`calls_entry.operation_key` is the canonical replay key. When a
runner fails partway (network drop, model timeout, a downstream 500),
re-firing the *same* `operation_key` lets the framework detect the
duplicate, short-circuit any already-written soft-call rows, and
resume from the failure point without producing a second ledger
entry. The test picker fan-out uses this mechanism to safely retry
individual calls inside a larger replay without re-running the calls
that already succeeded.

`idempotency_key` is the wider deduplication contract — passed in by
callers that need exactly-once semantics across long retry windows.
The framework's earlier brittle assumption that `idempotency_key ==
artifact_id` is gone; the soft_calls ledger is now the source of
truth.

## What audit does NOT cover

The audit wrapper is the canonical entry point, but it is not the
only path that emits events. Be precise about its limits:

- **Direct `internal_sio.emit(...)` calls** — handlers that bypass
  `run_artifact_operation_with_audit` and emit events themselves
  produce wire traffic without a ledger row. The catch-all forwarder
  in `ws/output.py` still relays them to clients, but no
  `soft_calls_entry` is written.
- **Read endpoints** — `POST /<artifact>/get`, `/<artifact>/search`,
  and the various `*_download` routes never participate in audit.
  There is no "who read this" trail.
- **Cache hits** — when `bypass_cache=False` and the resolver returns
  a cached result, no runner runs, so no events fire and no ledger
  row is written. The original ledger row from the call that
  populated the cache is the only audit trail.
- **MV reads** — querying `soft_calls_mv` (e.g. through the search
  endpoint) is itself a read, not an audited write.
- **Failed pre-flight** — when `run_artifact_operation_with_audit`
  raises in `resolve_common_context` (profile not found, permission
  denied), the wrapper exits before any event fires. The failure is
  observable in application logs but not in the ledger.

If a write needs auditing, the answer is always to route it through
`run_artifact_operation_with_audit` — adding ad-hoc ledger inserts
elsewhere fragments the source of truth.

## Related

- [Activity](/activity) — aggregate engagement counts, the entry point for the drill chain.
- [Session](/session) — per-session timeline and groups list.
- [Group](/group) — per-group runs, messages, and `calls[]` references.
- [API Reference](/api-reference) — full system endpoint schemas.

---

# Authentication

Route: /authentication

# Authentication

Every Glow request needs a caller identity. Authentication is a single
scheme — a bearer token attached as an HTTP header:

| Scheme | Header | Issued by | Resolves to |
|---|---|---|---|
| **BearerAuth** | `Authorization: Bearer <jwt>` | Keycloak (interactive) or service-account exchange | profile + session |

The CLI handles this automatically: `glow login` writes the bearer to
`~/.config/glow/tokens.json`, and every subsequent call attaches the
`Authorization` header for you.

```mermaid
sequenceDiagram
    participant C as Client
    participant M as API middleware
    participant K as Keycloak JWKS
    C->>M: Request + Authorization Bearer jwt
    M->>K: verify signature
    M->>M: resolve_identity to profile + session
    M-->>C: handler runs as the resolved caller
```

*The bearer JWT is verified and resolved to a profile + session before the route handler runs.*

## Interactive flow (`glow login`)

```bash
glow login --instance-url https://my-school.example.com
```

What happens:

1. The CLI hits `GET /.well-known/openid-configuration` on the
   instance to discover Keycloak endpoints.
2. It spawns a localhost listener and opens your browser to the
   `authorize_endpoint` with a generated `state` + `code_verifier`
   (PKCE — no client secret needed for the public CLI client).
3. Keycloak logs you in (or returns to your existing SSO session) and
   redirects to `http://127.0.0.1:<port>/callback?code=…&state=…`.
4. The CLI exchanges the code at `token_endpoint` for an access token
   + refresh token and writes both to `~/.config/glow/tokens.json`,
   keyed by instance URL.

After login, every subsequent CLI call attaches `Authorization: Bearer
<access_token>` automatically. The refresh token is used silently when
the access token expires.

## Service-account flow (`--token`)

For CI / scripted use, mint a service-account JWT once and pass it
explicitly:

```bash
glow login --instance-url https://my-school.example.com \
  --token "$SERVICE_ACCOUNT_JWT"
```

This skips the browser dance and stores the token directly. The JWT
must be signed by the same Keycloak realm and carry a
`profile.is_service_account = true` claim.

## Server-side logout

```bash
glow logout
```

Fires `GET /logout` on the instance (which writes a `logouts_entry`
row so the next request mints a fresh session) and then clears the
local `tokens.json`. The server-side call is best-effort — the local
clear always runs even if the server is unreachable.

## Raw HTTP

The curl examples throughout these docs read two environment variables —
your instance URL and your bearer token — so you can **export them once
and every example is copy-paste-ready**:

```bash
export GLOW_INSTANCE_URL=https://your-school.example.edu
export GLOW_TOKEN=$(cat ~/.config/glow/tokens.json | jq -r '.[].access_token' | head -1)
# …or paste a token directly: export GLOW_TOKEN=eyJhbG...
```

`GLOW_INSTANCE_URL` is the same variable the CLI reads; `GLOW_TOKEN` is the
JWT `glow login` already stored under `~/.config/glow/`. With both set, the
canonical request shape is:

```bash
curl -X POST $GLOW_INSTANCE_URL/persona/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -d '{}'
```

That single `Authorization: Bearer` header authenticates every
endpoint — read and mutation paths alike.

### Discovery endpoints

| Endpoint | Purpose |
|---|---|
| `GET /.well-known/openid-configuration` | OIDC discovery doc (issuer, endpoints) |
| `GET /jwks` | public signing keys for verifying issued JWTs |
| `GET /authorize` | OAuth authorization endpoint (browser redirect) |
| `GET /oidc_callback` | OAuth callback (used by browser flows) |
| `POST /token` | code → access token / refresh exchange |
| `GET /userinfo` | introspect the bearer's profile claims |
| `GET /login` / `GET /logout` | bare browser-flow entry points |

These mirror the standard OIDC surface — most clients only need
`/.well-known/...` to bootstrap.

## Multiple instances

```bash
glow login --instance-url https://school-a.example.com
glow login --instance-url https://school-b.example.com

# tokens.json now has both; the --instance-url flag (or GLOW_INSTANCE_URL
# env var) selects which one a given command uses.
GLOW_INSTANCE_URL=https://school-b.example.com glow personas search
```

Sessions are listed in the CLI via the `instance` config under
`~/.config/glow/`. There's no first-class `glow sessions list` command
today — read the file directly if needed.

## Service accounts

Service accounts are the non-interactive flavour of bearer auth: a
long-lived JWT that a CI pipeline, cron job, or programmatic client
attaches without ever opening a browser. Same `Authorization: Bearer
<jwt>` shape as a human session — only the issuance path differs.

The recap (covered in [Service-account flow](#service-account-flow---token)
above):

```bash
glow login --instance-url https://my-school.example.com \
  --token "$SERVICE_ACCOUNT_JWT"
```

The CLI's `--token` branch (`save_token` in
[`src/auth.rs`](https://github.com/glow-academic/cli/blob/main/src/auth.rs))
writes the JWT straight into `~/.config/glow/tokens.json` with no
`refresh_token` and no `expires_in` — the server enforces lifetime via
the JWT's own `exp` claim.

### Minting a service-account JWT

Today this is an operator-side step, done directly against Keycloak:

1. In the realm's Keycloak admin console, create (or pick) a user that
   represents the service identity (e.g. `ci-runner@yourdomain`).
2. Add a `profile.is_service_account = true` claim via a user attribute
   + a protocol mapper, so it lands in the issued token. Server-side
   resolution in
   [`resolve_identity.py`](https://github.com/glow-academic/api/blob/main/core/app/infra/identity/resolve_identity.py)
   accepts the JWT the same way as a human bearer; the claim is what
   downstream policy uses to distinguish "machine" from "person" when
   it matters (e.g. skipping interactive consent prompts).
3. Mint a token for that user — admin REST API
   (`POST /auth/realms/<realm>/protocol/openid-connect/token`) with the
   service account's credentials, or via the admin console's "Get
   access token" helper.

**Honest gap:** there is no first-class CLI helper for minting
service-account JWTs today (no `glow service-accounts create`). The
operator does it via Keycloak admin or a custom script. The CLI's job
ends at *consuming* an already-minted token via `--token`.

### Scope, rotation, storage

- **TTL.** Driven by the Keycloak client / user token lifespan
  setting. Default Keycloak access-token lifespan is 5 minutes;
  service-account tokens are typically configured for hours-to-days so
  the CI run completes without a refresh dance.
- **Rotation.** Re-mint in Keycloak, update the CI secret, re-run
  `glow login --token "$NEW_JWT"`. No refresh token is stored, so
  expiry is hard-stop — plan rotation cadence to match TTL.
- **Storage in CI.** Treat the JWT as a bearer credential. Standard
  pattern:

  ```yaml
  # GitHub Actions
  env:
    SERVICE_ACCOUNT_JWT: ${{ secrets.GLOW_SERVICE_ACCOUNT_JWT }}
  run: |
    glow login --instance-url "$GLOW_INSTANCE_URL" \
      --token "$SERVICE_ACCOUNT_JWT"
    glow personas search
  ```

  Never check the token into the repo; never echo it in logs.

## Related

- [Start](/start) — install + first-boot
- [CLI Reference: login](/cli-reference/login/) · [logout](/cli-reference/logout/)
- API Reference: [`POST /profile/context`](/api-reference/profile/post-profile-context/) returns the authenticated profile
- [Permissions](/permissions/) — roles, role_artifacts, and per-route policy

---

# Auths

Route: /auths

# Auths

Auths manages authentication providers for your Glow instance -- the SSO configurations, login methods, and access controls that determine how TAs and administrators sign in. It supports full CRUD operations with a draft system for safe, staged edits.

> Auth artifacts configure the SSO/IdP providers. For the runtime auth flow (login, tokens, sessions), see [Authentication](/authentication).

## What auth artifacts configure

An auth row is an **identity-provider (IdP) configuration record** — not a runtime session. Each row tells the Glow instance how to wire one external SSO provider (university Shibboleth, Google Workspace, Azure AD, generic OIDC, ...) into the embedded Keycloak.

- **Provider shape.** Each auth carries display fields (`name`, `description`), a `flag` (enabled/disabled), one or more `protocol_ids` (OIDC, SAML, ...), and a `slug` that becomes the login-button path. The `department_ids` set scopes which orgs see the button.
- **Encrypted item keys.** Sensitive provider config (`client_secret`, signing keys, redirect-URI overrides) lives in `items`, and each item points at one or more `auth_item_key_ids` — encrypted-at-rest key resources. List and get responses **never return the plaintext**; values round-trip through `app.infra.identity.decrypt.resolve_decrypt`, which composes the canonical `get_keys` + `decrypt_api_key` path and requires the actor's `profile_id`.
- **Keycloak sync.** Creating or saving an auth invalidates the `auths` cache tag and triggers `app.infra.identity.keycloak_sync` on the next sync pass. `sync_identity_provider_for_realm_level` and `sync_identity_provider_for_org` walk the auth rows for each realm/department, decrypt the item keys, and upsert matching Keycloak `IdentityProvider` records — so the auth artifact is the source of truth and Keycloak is the projection.
- **Runtime handoff.** Once synced, the actual login dance (PKCE, token exchange, session minting) is handled by the flow documented in [Authentication](/authentication). Auths configure *which* providers exist; `/authentication` covers *how* a request authenticates against them.

## What is an Auth?

An auth provider defines a login method for your Glow instance. This could be a university SSO integration, an email-based login, or another authentication protocol. Each auth provider is composed of sections:

- **Names** and **Descriptions** -- Display identity for the provider
- **Flags** -- Feature toggles (e.g., enabled/disabled)
- **Protocols** -- Authentication protocol configuration
- **Slugs** -- URL-friendly identifiers for login routes
- **Items** -- Individual auth items (e.g., client IDs, secrets, redirect URIs)

Auths uses a composable architecture with full CRUD, duplication, and a draft system with optimistic locking -- the same pattern as Settings.

---

## Create an auth provider

### Via the CLI

> Calls below use `$GLOW_INSTANCE_URL` + `$GLOW_TOKEN` — see [Authentication](/authentication) to export them once.

```bash
glow auths create --body '{"auths": [{"name": "University SSO", "description": "SAML SSO for university login"}]}'
```

### Via the API

```bash
curl -X POST $GLOW_INSTANCE_URL/auth/create \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "auths": [{
      "name": "University SSO",
      "description": "SAML-based single sign-on for university TA login"
    }]
  }'
```

Returns per-item results in `results`, each carrying the new `auth_id` and a `draft_id` ready for protocol wiring.

---

## OIDC / protocol wiring

The `protocols` section captures which authentication protocol (OIDC, SAML, ...) this provider speaks; `items` carry the encrypted client IDs, secrets, and redirect URIs. Item values are never returned in plaintext from list or get -- pull them on demand through the dedicated edit drawer.

```bash
glow auths draft --body '{
  "input_draft_id": "auth-draft-uuid",
  "expected_version": 1,
  "protocol_ids": ["protocol-oidc"],
  "slug_ids": ["slug-university"],
  "item_ids": ["item-client-id", "item-client-secret", "item-redirect-uri"]
}'
```

---

## Adding a new IdP

End-to-end recipe for wiring a fresh SSO provider into Keycloak. The four moves are: create the auth shell, seed the encrypted item keys, attach them in a draft, then let `keycloak_sync` project the row into the realm.

**1. Create the auth shell** (returns `auth_id` + a fresh `draft_id`):

```bash
curl -X POST $GLOW_INSTANCE_URL/auth/create \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "auths": [{
      "name": "Acme University SSO",
      "description": "OIDC login for Acme faculty + TAs",
      "protocol": "oidc",
      "slug": "acme-sso",
      "department_ids": ["dept-acme"]
    }]
  }'
```

`protocol`/`slug` are resolve-or-create — pass a string and the server will reuse an existing resource or mint one. See [POST /auth/create](/api-reference/auth/post-auth-create) for the full request schema, including the `items` array and per-item `auth_item_key_ids` for seeding encrypted values up front.

**2. Save the draft** with the wired items (client ID, secret, redirect URI). Plaintext values you submit go through the encrypted-key pipeline before they land in `items`; subsequent `get`/`search` calls return only the key IDs.

```bash
glow auths draft --body '{
  "input_draft_id": "<draft-id-from-step-1>",
  "expected_version": 1,
  "item_ids": ["item-client-id", "item-client-secret", "item-redirect-uri"]
}'
```

**3. Promote the draft** via `POST /auth/update` (or the UI's *Save* button). The route emits `X-Invalidate-Tags: auths` and the next `keycloak_sync` pass picks up the new row, decrypts the item keys, and upserts the matching Keycloak `IdentityProvider` for each realm the auth's departments map to.

**4. Verify** the login button shows up under `/login/<slug>` and that the round-trip lands a session — that path is covered in [Authentication](/authentication).

---

## The draft cycle

Auths uses a draft system with optimistic locking -- the same pattern as Settings. Saving via `PATCH /auth/draft` returns the new `version`; pass it as `expected_version` on the next save so concurrent edits surface a conflict instead of clobbering.

```bash
curl -X PATCH $GLOW_INSTANCE_URL/auth/draft \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input_draft_id": "existing-draft-uuid",
    "expected_version": 2,
    "name": "Updated University SSO",
    "description": "Updated SAML configuration",
    "protocol_ids": ["protocol-saml"],
    "slug_ids": ["slug-university"],
    "department_ids": ["dept-cs"],
    "item_ids": ["item-client-id", "item-secret"]
  }'
```

Key fields:
- `input_draft_id` -- UUID of existing draft (omit for new)
- `expected_version` -- Optimistic lock version
- `name`, `name_id` -- Name value or resource UUID
- `description`, `description_id` -- Description value or resource UUID
- `flag_id` -- Feature flag option UUID
- `protocol_ids`, `slug_ids`, `item_ids`, `department_ids` -- Resource assignments

Response: `success`, `draft_id`, `new_version`, `message`, and `form_state`.

**List your drafts:**

```bash
curl -X POST $GLOW_INSTANCE_URL/auth/drafts \
  -H "Authorization: Bearer $GLOW_TOKEN"
```

**Loading a draft:**

```bash
glow auths get --body '{"auth_id": "auth-uuid", "draft_id": "draft-uuid"}'
```

---

## Search & filter

`POST /auth/search` returns a paginated list of auth providers:

- `actor_name` -- Current user's display name
- `auths` -- Array of `ListAuthApiAuth` items
- `department_filter` -- Department filter options
- `total_count` -- Total number of auth providers

Optional filters:

| Filter | Field | Description |
|---|---|---|
| Text search | `search` | Search across auth provider names |
| Departments | `filter_department_ids` | Filter by department |
| Department search | `department_search` | Text search for departments |
| Pagination | `page_size`, `page_offset` | Control page size |

```bash
curl -X POST $GLOW_INSTANCE_URL/auth/search \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"search": "sso", "filter_department_ids": ["dept-cs"], "page_size": 25}'
```

---

## Bulk operations

Bulk delete and update follow the canonical *all-matching* shape -- explicit IDs, or `all: true` with flat filter fields plus optional `excluded_ids` and a `patch` body. The persona surface is the prove-out; auths follows the same shape.

**Delete by explicit IDs:**

```bash
curl -X POST $GLOW_INSTANCE_URL/auth/delete \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"auth_ids": ["auth-uuid-1", "auth-uuid-2"]}'
```

**Delete all matching a filter (with exclusions):**

```bash
glow auths delete --body '{
  "all": true,
  "filter_department_ids": ["dept-retired"],
  "excluded_ids": ["auth-shared-sso"]
}'
```

**Duplicate an auth provider:**

```bash
curl -X POST $GLOW_INSTANCE_URL/auth/duplicate \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"auth_id": "auth-uuid"}'
```

Returns `success`, `auth_id` (new UUID), and `message`.

## Common Operations

| Task | CLI | API Endpoint |
|---|---|---|
| List auth providers | `glow auths search` | `POST /auth/search` |
| Get auth provider | `glow auths get` | `POST /auth/get` |
| Create auth provider | `glow auths create` | `POST /auth/create` |
| Update auth provider | `glow auths update` | `POST /auth/update` |
| Duplicate auth | -- | `POST /auth/duplicate` |
| Delete auths | `glow auths delete` | `POST /auth/delete` |
| Bulk delete (filter) | `glow auths delete --body '{"all": true, "filter_…": "…"}'` | `POST /auth/delete` |
| Save draft | `glow auths draft` | `PATCH /auth/draft` |
| List drafts | -- | `POST /auth/drafts` |
| Export | `glow auths export` | `POST /auth/export` |
| View docs | -- | `POST /auth/docs` |

## Related

- [Auths API Reference](/api-reference/auth)
- [Auths CLI Reference](/cli-reference/auth)
- [Settings Guide](/setting) -- instance configuration (links auth providers)

---

# Backup & restore

Route: /backup-restore

# Backup & restore

Glow's local backup story is deliberately small: every instance keeps
a directory of gzipped `pg_dump` snapshots on disk, and the canonical
restore path piggybacks on the blue/green redeploy flow so a recovery
swap looks exactly like a normal rollout.

## What's backed up

A backup is a `pg_dump` of the postgres container's primary database,
piped through `gzip`, with the `keycloak` schema excluded:

```
pg_dump --exclude-schema=keycloak -U $POSTGRES_USER $POSTGRES_DB | gzip
```

That covers the application data — personas, scenarios, simulations,
attempts, drafts, audit rows, etc. It does **not** cover:

- The Keycloak schema (intentionally excluded; treat identity as
  provisioned, not data).
- Uploaded media that lives on disk outside Postgres.
- `.env`, `glow-deploy.yaml`, or any other config under
  `~/.glow/instances/<name>/` — those are operator-managed source.
- Remote storage. Backups are local files; nothing is pushed offsite
  by default.

If you need an off-box copy, rsync the `backups/` directory yourself.

---

## Where backups live

Every instance has its own `backups/` directory:

```
~/.glow/instances/<name>/
  glow-deploy.yaml
  .env
  docker-compose.yml
  .deploy-state.json
  backups/
    manual-<label>-<timestamp>.sql.gz       # from `glow backup create`
    backup-deploy-<timestamp>.sql.gz        # auto pre-deploy snapshots
```

File naming follows two conventions:

| Source | Filename pattern |
|--------|------------------|
| `glow backup create --label foo` | `manual-foo-<unix-seconds>.sql.gz` |
| Auto pre-deploy snapshot | `backup-deploy-<YYYYMMDDTHHMMSSZ>.sql.gz` |

The directory is preserved across `glow destroy` — only containers and
volumes are wiped. Your snapshots stay put.

---

## Creating a backup

```bash
glow backup create [--name <instance>] [--label <label>]
```

What it does:

1. Asserts Docker is reachable.
2. Execs `pg_dump | gzip` inside the running `database` container.
3. Writes the gzipped stream to
   `~/.glow/instances/<name>/backups/manual-<label>-<ts>.sql.gz`.

The instance must be running (the database container has to be up to
serve `pg_dump`). `--label` defaults to `manual`; slashes, spaces, and
colons in the label are normalised to `-`.

---

## Listing backups

```bash
glow backup list [--name <instance>]
# alias: glow backup ls
```

Output is sorted newest-first and prints filename, size, and full
path. Only files ending in `.sql.gz` are returned — anything else in
the directory is ignored.

---

## Restoring

The **canonical** restore path is to roll the restore in through a
redeploy:

```bash
glow redeploy --name <instance> --from-backup <filename>
```

This routes through the normal deploy pipeline, which means you still
get:

- A fresh pre-deploy snapshot of the current DB *before* the restore
  touches anything (see [Auto pre-backup](#auto-pre-backup-on-redeploy)).
- Blue/green orchestration — the new color comes up against the
  restored DB.
- Healthcheck monitoring during the grace window, with auto-rollback
  if the new color flaps.

There's also a standalone restore command for emergencies where you
just want to drop the DB and stream a dump back in without rolling a
new image:

```bash
glow backup restore --name <instance> <filename>
```

This is **destructive** — it drops + recreates `$POSTGRES_DB`,
streams the gzipped dump in via `psql`, then restarts both
`server-blue` and `server-green` so the asyncpg pools are fresh. The
CLI requires you to type `restore` to confirm (unless `--yes`).

Prefer `glow redeploy --from-backup` for anything resembling a planned
rollback. Reserve `glow backup restore` for "the DB is gone, get it
back" moments.

---

## Auto pre-backup on redeploy

Every `glow redeploy` (as opposed to a first `glow deploy`) takes a
snapshot **before** doing anything destructive. From the deploy
pipeline:

```
1. Resolve config + versions
2. Compatibility checks
3. Ensure shared docker network
4. → Pre-deploy backup (best-effort)
5. Plan blue/green swap
6. Render .env, pull images, bring up next color
…
12. Monitor grace period — rollback if it flaps.
```

The pre-deploy snapshot lands in the same `backups/` dir with the
`backup-deploy-` prefix. If `pg_dump` fails (e.g. the DB is wedged),
the deploy still continues — the failure is logged but non-fatal, on
the principle that a missing snapshot shouldn't block you from
deploying a fix.

The blue/green monitor watches the new color's healthchecks during
the configured grace window (`--grace-minutes`, default 2). If the
new color flaps, the orchestrator rolls traffic back to the previous
color automatically — at which point the pre-deploy snapshot is your
safety net for any DB changes the new color might have made on the
way down.

---

## Retention

There are two retention regimes, and both are intentionally light:

- **Manual backups (`manual-*.sql.gz`):** operator-managed. Nothing
  prunes them; delete with `glow backup delete` when you're done.
- **Auto pre-deploy snapshots (`backup-deploy-*.sql.gz`):** rolling
  window of the **7 most recent** per instance. Older ones are
  removed best-effort after each successful snapshot.

```bash
glow backup delete --name <instance> <filename>
```

No encryption, no offsite upload, no scheduling — the v1.0.0 model is
that you own the files on disk and can rsync, encrypt, or rotate them
to suit your environment.

---

## Disaster recovery flow

A pragmatic checklist when something goes sideways:

1. **Stop accepting new writes.** Take the client offline or
   firewall the API so the blast radius stops growing.
2. **Snapshot the current state**, even if it's broken — it's the
   only evidence you have of *what* went wrong:

   ```bash
   glow backup create --name <instance> --label disaster-snapshot
   ```

3. **Investigate.** Pull logs (`glow logs`), inspect the DB, decide
   whether the corruption is recoverable in place or needs a rollback.
4. **Roll back to a known-good snapshot** via redeploy so you still
   get blue/green safety:

   ```bash
   glow backup list --name <instance>
   glow redeploy --name <instance> --from-backup <known-good-filename>
   ```

5. **Verify** with `glow status` and a smoke test, then re-enable
   traffic.

---

## Related

- [`glow backup create`](/cli-reference/backup-create) — manual snapshot command
- [`glow backup list`](/cli-reference/backup-list) — list snapshots for an instance
- [`glow backup restore`](/cli-reference/backup-restore) — standalone destructive restore
- [`glow backup delete`](/cli-reference/backup-delete) — remove a snapshot file
- [`glow redeploy`](/cli-reference/redeploy) — canonical restore path via `--from-backup`
- [`glow deploy`](/cli-reference/deploy) — initial deployment (no pre-backup since the DB is fresh)

---

# Benchmark

Route: /benchmark

# Benchmark

The Benchmark resource provides test performance analytics across your Glow instance. Use it to review eval scores, track test history, and export data for reporting. Benchmark is an API-only resource with no CLI commands.

![Benchmark dashboard showing test results across models with scores per evaluation criterion](/screenshots/benchmark/dashboard.png)

## What is Benchmark?

Benchmark aggregates test and eval performance data into a single analytics surface. It collects scores, pass rates, invocation counts, and test history across departments and date ranges. Administrators and instructors can use benchmark data to compare eval performance over time, identify trends, and export results for institutional reporting.

Each benchmark response includes eval cards (high-level performance summaries), paginated test history, department filters, and inline analytics facets for client-side rendering.

## Quick Start

### API

![Benchmark test configuration showing model selection, scenario selection, and test parameters](/screenshots/benchmark/create.png)

**Fetch benchmark data** for the current semester:

> Calls below use `$GLOW_INSTANCE_URL` + `$GLOW_TOKEN` — see [Authentication](/authentication) to export them once.

```bash
curl -X POST $GLOW_INSTANCE_URL/test/benchmark \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2026-01-15",
    "end_date": "2026-05-15"
  }'
```

The response includes `evals` (eval performance cards), `departments`, `history` (paginated test runs), and `analytics` (filter facets).

**Filter by department:**

```bash
curl -X POST $GLOW_INSTANCE_URL/test/benchmark \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2026-01-15",
    "end_date": "2026-05-15",
    "department_ids": ["dept-nursing-101"]
  }'
```

![Benchmark results showing side-by-side model comparison with per-criterion scores](/screenshots/benchmark/results.png)

## Run execution

## Searching Test History

Use `POST /test/search` to paginate and filter test history independently of the full benchmark payload:

```bash
curl -X POST $GLOW_INSTANCE_URL/test/search \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "history_page": 1,
    "history_page_size": 25,
    "history_search": "midterm",
    "history_sort_by": "created_at",
    "history_sort_order": "desc"
  }'
```

The response returns `data` (an array of `BenchmarkHistoryItem` objects), `total_count`, pagination fields, and `eval_options` for dropdown filters.

### Filtering by Eval and Archive Status

```bash
curl -X POST $GLOW_INSTANCE_URL/test/search \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "history_eval_ids": ["eval-abc-123"],
    "history_archived": false,
    "history_page": 1,
    "history_page_size": 50
  }'
```

## Refreshing and Exporting

**Refresh materialized views** to ensure benchmark data is up to date. This invalidates caches and rebuilds aggregated views:

```bash
curl -X POST $GLOW_INSTANCE_URL/test/refresh \
  -H "Authorization: Bearer $GLOW_TOKEN"
```

Returns `success`, `refreshed_views`, and `invalidated_tags`.

**Export benchmark data** as a denormalized ZIP file for offline analysis or institutional reporting:

```bash
curl -X POST $GLOW_INSTANCE_URL/test/export \
  -H "Authorization: Bearer $GLOW_TOKEN"
```

The response contains `content` (base64-encoded ZIP), `file_name`, `mime_type`, and `row_count`.

## Common Operations

| Operation | Method | Endpoint |
|---|---|---|
| Get benchmark data | `POST` | `POST /test/benchmark` |
| Search test history | `POST` | `POST /test/search` |
| Refresh views | `POST` | `POST /test/refresh` |
| Export data (ZIP) | `POST` | `POST /test/export` |
| Get documentation | `POST` | `/benchmark/docs` |

## Related

- [Benchmark API](/api-reference/test)
- [Health Guide](/health) -- service-level monitoring

---

# Chat

Route: /chat

# Chat

Chats are the individual conversations within an attempt — each chat
corresponds to one scenario and holds the full message history between
the learner and the AI persona.

Chat is a **sub-namespace on the attempt artifact**. Every operation
is named `chat_<op>` and lives at `POST /attempt/chat_<op>`:
`chat_get`, `chat_message`, `chat_grade`, `chat_draft`, etc. The CLI
exposes them as `glow attempts chat <op>` for ergonomics; the wire
path concatenates them under `/attempt/`.

## What is a Chat?

A chat is a single conversational session between a learner and an AI persona within an [Attempt](/api-reference/attempt). When a learner starts a simulation with three scenarios, three chats are created — one per scenario. Each chat holds the message thread, the persona configuration, attached documents, and any customization applied at runtime.

A chat contains:

- **Chat Entry ID** — unique identifier for this conversation
- **Attempt ID** — the parent attempt this chat belongs to
- **Names / Descriptions** — display copy
- **Personas** — the AI character(s) active in this chat (inherited from the scenario)
- **Documents** — reference materials available during the conversation
- **Parameter Fields** — resolved parameter values injected into persona instructions
- **Scenarios** — the scenario this chat is running
- **Objectives** — learning goals the chat is targeting
- **Questions & Options** — structured prompts for quiz-style interactions
- **Images & Videos** — media assets shown as context
- **Problem Statements** — the situation being addressed
- **Flags** — configuration flags for the chat session
- **Departments** — organizational groupings

Chats also support a draft system for customizing chat configurations before or during a session.

![Chat interface showing message thread with AI persona, with voice mode toggle and input area](/screenshots/chat/interface.png)

## Sending a message

## Quick Start

### Get Chat Details via CLI

> Calls below use `$GLOW_INSTANCE_URL` + `$GLOW_TOKEN` — see [Authentication](/authentication) to export them once.

```bash
glow attempts chat get --body '{"chat_entry_id": "your-chat-entry-uuid"}'
```

### Get Chat Details via API

```bash
curl -X POST $GLOW_INSTANCE_URL/attempt/chat_get \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -d '{
    "chat_entry_id": "your-chat-entry-uuid",
    "attempt_id": "parent-attempt-uuid"
  }'
```

The response includes all hydrated resources: personas, documents, parameter fields, questions, options, and more.

### Export a Chat

```bash
# CLI
glow attempts chat export --body '{"chat_entry_id": "..."}'

# API
curl -X POST $GLOW_INSTANCE_URL/attempt/chat_export \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -d '{
    "chat_entry_id": "your-chat-entry-uuid",
    "attempt_id": "parent-attempt-uuid"
  }'
```

## How Chats Connect to the Workflow

Chats are created automatically as part of **step 5** when a learner starts an attempt:

| Step | Resource | Description |
|------|----------|-------------|
| 1. Create Personas | [Personas](/personas) | Define AI characters with instructions and parameter fields |
| 2. Assign to Scenarios | [Scenarios](/scenarios) | Build training situations and attach personas, documents, and objectives |
| 3. Add Scenarios to Simulations | [Simulations](/simulations) | Bundle scenarios into a complete training session with rubrics and time limits |
| 4. Add Simulations to Cohorts | [Cohorts](/cohorts) | Assign simulations to groups of learners |
| **5. Run Attempts** | [Attempts](/api-reference/attempt) | Learners start attempts; **Glow creates one Chat per scenario** |

You do not create chats directly via `chat_create` in normal flows —
the attempt's `POST /attempt/start` does it. `chat_create` is exposed
for tooling that needs to seed chats outside the normal flow.

## The chat sub-op surface

Every chat operation is a separate endpoint under `/attempt/chat_<op>`:

| Sub-op | Endpoint | Purpose |
|---|---|---|
| `chat_get` | `POST /attempt/chat_get` | hydrate a single chat by id |
| `chat_create` | `POST /attempt/chat_create` | create a new chat (rare) |
| `chat_message` | `POST /attempt/chat_message` | send a user message |
| `chat_response` | `POST /attempt/chat_response` | submit a structured question response |
| `chat_grade` | `POST /attempt/chat_grade` | request grading |
| `chat_complete` | `POST /attempt/chat_complete` | mark a chat completed |
| `chat_hints` | `POST /attempt/chat_hints` | fetch hints |
| `chat_feedback` | `POST /attempt/chat_feedback` | per-standard feedback |
| `chat_strengths` / `chat_improvements` | `POST /attempt/chat_strengths` / `_improvements` | per-message strength/improvement breakdown |
| `chat_analyses` | `POST /attempt/chat_analyses` | overall analyses |
| `chat_audio` | `POST /attempt/chat_audio` | attach an audio resource to a message |
| `chat_speak` / `chat_silence` / `chat_voice` | `POST /attempt/chat_speak` / `_silence` / `_voice` | live voice session control (see WS surface below) |
| `chat_draft` / `chat_drafts` | `POST /attempt/chat_draft` (PATCH-like) / `chat_drafts` | edit draft / list drafts |
| `chat_refresh` / `chat_export` | `POST /attempt/chat_refresh` / `chat_export` | invalidate cache / export transcript |

CLI dispatch is symmetric — `glow attempts chat <op>` (e.g.
`glow attempts chat message <chat_id> "..."`) maps 1:1 to
`POST /attempt/chat_<op>`.

## Grading a chat

## Hints, feedback, and analyses

## Live REPL (WS)

The same chat surface is also exposed over socket.io for live message
flow. The CLI has an interactive REPL at:

```bash
# Open a socket.io REPL — type a line + Enter to send a chat_message
glow attempts chat live <chat_id>
```

Voice is handled separately by the `chat_voice` / `chat_speak` /
`chat_silence` session ops (`glow attempts chat voice|speak|silence`,
each a plain call to its `POST /attempt/chat_*` endpoint) — see the
[Voice pipeline](/voice) for the full STT → LLM → TTS loop.

## Searching and filtering chat resources

`POST /attempt/chat_get` supports search filters to narrow down the resources shown for a chat:

```bash
curl -X POST $GLOW_INSTANCE_URL/attempt/chat_get \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -d '{
    "chat_entry_id": "your-chat-entry-uuid",
    "persona_search": "confused",
    "document_search": "FERPA",
    "persona_show_selected": true,
    "document_show_selected": false
  }'
```

Available search filters:

| Filter | Description |
|--------|-------------|
| `description_search` | Filter descriptions by text |
| `persona_search` | Filter personas by text |
| `document_search` | Filter documents by text |
| `problem_statement_search` | Filter problem statements by text |
| `image_search` | Filter images by text |
| `video_search` | Filter videos by text |
| `question_search` | Filter questions by text |
| `option_search` | Filter options by text |
| `persona_show_selected` | Show only currently selected personas |
| `document_show_selected` | Show only currently selected documents |

## Working with drafts

Chat drafts let you customize a chat's configuration — changing which personas, documents, parameters, and other resources are active.

```bash
# CLI
glow attempts chat draft --body '{
  "name": "Custom FERPA Chat",
  "description": "Modified chat with additional documents",
  "persona_ids": ["concerned-student-uuid"],
  "document_ids": ["ferpa-policy-uuid", "supplemental-guide-uuid"],
  "parameter_field_ids": ["location-param-uuid"]
}'

# API
curl -X POST $GLOW_INSTANCE_URL/attempt/chat_draft \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -d '{
    "name": "Custom FERPA Chat",
    "description": "Modified chat with additional documents",
    "persona_ids": ["concerned-student-uuid"],
    "document_ids": ["ferpa-policy-uuid", "supplemental-guide-uuid"]
  }'
```

The draft endpoint supports optimistic concurrency through `expected_version` and returns the `form_state` with all selected resource IDs after save.

**List your chat drafts:**

```bash
# CLI
glow attempts chat drafts

# API
curl -X POST $GLOW_INSTANCE_URL/attempt/chat_drafts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GLOW_TOKEN"
```

## Exporting a transcript

## Common Operations

| Task | CLI | API |
|------|-----|-----|
| Get chat details | `glow attempts chat get --body '{"chat_entry_id": "..."}'` | `POST /attempt/chat_get` |
| Send a message | `glow attempts chat message <chat_id> "..."` | `POST /attempt/chat_message` |
| Grade a chat | `glow attempts chat grade <chat_id>` | `POST /attempt/chat_grade` |
| Live REPL (socket.io) | `glow attempts chat live <chat_id>` | (WebSocket — see CLI source) |
| Export chat transcript | `glow attempts chat export` | `POST /attempt/chat_export` |
| Save a chat draft | `glow attempts chat draft --body '{...}'` | `POST /attempt/chat_draft` |
| List chat drafts | `glow attempts chat drafts` | `POST /attempt/chat_drafts` |
| Refresh views | `glow attempts chat refresh` | `POST /attempt/chat_refresh` |

## Related

- [Attempt API Reference](/api-reference/attempt) — every chat_* endpoint with full schemas
- [Attempts CLI Reference](/cli-reference/attempts) — every `glow attempts ...` command
- [Scenarios](/scenarios) — the training situations that each chat runs
- [Personas](/personas) — the AI characters active in each chat
- [Simulations](/simulations) — the training sessions that define which scenarios (and chats) are created

---

# `glow agents call download`

Route: /cli-reference/agents/call/download

# `glow agents call download`

Download call on AI agents.

## Usage

```bash
glow agents call download --id <id>
```

> Wire call: `POST /agent/call_download`. Run `glow agents call download --help` for the full flag list.

---

# `glow agents context`

Route: /cli-reference/agents/context

# `glow agents context`

Context AI agents.

## Usage

```bash
glow agents context --id <id>
```

> Wire call: `POST /agent/context`. Run `glow agents context --help` for the full flag list.

---

# `glow agents create`

Route: /cli-reference/agents/create

# `glow agents create`

Create AI agents.

## Usage

```bash
glow agents create --body '\{...\}'
```

> Wire call: `POST /agent/create`. Run `glow agents create --help` for the full flag list.

---

# `glow agents csv`

Route: /cli-reference/agents/csv

# `glow agents csv`

Csv AI agents.

## Usage

```bash
glow agents csv --id <id>
```

> Wire call: `POST /agent/csv`. Run `glow agents csv --help` for the full flag list.

---

# `glow agents delete`

Route: /cli-reference/agents/delete

# `glow agents delete`

Delete AI agents.

## Usage

```bash
glow agents delete --id <id>
```

> Wire call: `POST /agent/delete`. Run `glow agents delete --help` for the full flag list.

---

# `glow agents draft`

Route: /cli-reference/agents/draft

# `glow agents draft`

Draft AI agents.

## Usage

```bash
glow agents draft --id <id>
```

> Wire call: `POST /agent/draft`. Run `glow agents draft --help` for the full flag list.

---

# `glow agents drafts`

Route: /cli-reference/agents/drafts

# `glow agents drafts`

Drafts AI agents.

## Usage

```bash
glow agents drafts --id <id>
```

> Wire call: `POST /agent/drafts`. Run `glow agents drafts --help` for the full flag list.

---

# `glow agents duplicate`

Route: /cli-reference/agents/duplicate

# `glow agents duplicate`

Duplicate AI agents.

## Usage

```bash
glow agents duplicate --id <id>
```

> Wire call: `POST /agent/duplicate`. Run `glow agents duplicate --help` for the full flag list.

---

# `glow agents export`

Route: /cli-reference/agents/export

# `glow agents export`

Export AI agents.

## Usage

```bash
glow agents export --id <id>
```

> Wire call: `POST /agent/export`. Run `glow agents export --help` for the full flag list.

---

# `glow agents file download`

Route: /cli-reference/agents/file/download

# `glow agents file download`

Download file on AI agents.

## Usage

```bash
glow agents file download --id <id>
```

> Wire call: `POST /agent/file_download`. Run `glow agents file download --help` for the full flag list.

---

# `glow agents generate`

Route: /cli-reference/agents/generate

# `glow agents generate`

Generate AI agents.

## Usage

```bash
glow agents generate --body '\{...\}'
```

> Wire call: `POST /agent/generate`. Run `glow agents generate --help` for the full flag list.

---

# `glow agents generations`

Route: /cli-reference/agents/generations

# `glow agents generations`

Generations AI agents.

## Usage

```bash
glow agents generations --id <id>
```

> Wire call: `POST /agent/generations`. Run `glow agents generations --help` for the full flag list.

---

# `glow agents get`

Route: /cli-reference/agents/get

# `glow agents get`

Get AI agents.

## Usage

```bash
glow agents get --id <id>
```

> Wire call: `POST /agent/get`. Run `glow agents get --help` for the full flag list.

---

# `glow agents group`

Route: /cli-reference/agents/group

# `glow agents group`

Group AI agents.

## Usage

```bash
glow agents group --id <id>
```

> Wire call: `POST /agent/group`. Run `glow agents group --help` for the full flag list.

---

# `glow agents problem`

Route: /cli-reference/agents/problem

# `glow agents problem`

Problem AI agents.

## Usage

```bash
glow agents problem --id <id>
```

> Wire call: `POST /agent/problem`. Run `glow agents problem --help` for the full flag list.

---

# `glow agents refresh`

Route: /cli-reference/agents/refresh

# `glow agents refresh`

Refresh AI agents.

## Usage

```bash
glow agents refresh --id <id>
```

> Wire call: `POST /agent/refresh`. Run `glow agents refresh --help` for the full flag list.

---

# `glow agents search`

Route: /cli-reference/agents/search

# `glow agents search`

Search AI agents.

## Usage

```bash
glow agents search
```

> Wire call: `POST /agent/search`. Run `glow agents search --help` for the full flag list.

---

# `glow agents text download`

Route: /cli-reference/agents/text/download

# `glow agents text download`

Download text on AI agents.

## Usage

```bash
glow agents text download --id <id>
```

> Wire call: `POST /agent/text_download`. Run `glow agents text download --help` for the full flag list.

---

# `glow agents title`

Route: /cli-reference/agents/title

# `glow agents title`

Title AI agents.

## Usage

```bash
glow agents title --id <id>
```

> Wire call: `POST /agent/title`. Run `glow agents title --help` for the full flag list.

---

# `glow agents update`

Route: /cli-reference/agents/update

# `glow agents update`

Update AI agents.

## Usage

```bash
glow agents update --id <id>
```

> Wire call: `POST /agent/update`. Run `glow agents update --help` for the full flag list.

---

# `glow agents watch`

Route: /cli-reference/agents/watch

# `glow agents watch`

Watch AI agents.

## Usage

```bash
glow agents watch --id <id>
```

> Wire call: `POST /agent/watch`. Run `glow agents watch --help` for the full flag list.

---

# `glow attempts archive`

Route: /cli-reference/attempts/archive

# `glow attempts archive`

Archive on attempts.

## Usage

```bash
glow attempts archive --id <id>
```

> Wire call: `POST /attempt/archive`. Run `glow attempts archive --help` for the full flag list.

---

# `glow attempts audio download`

Route: /cli-reference/attempts/audio/download

# `glow attempts audio download`

Download audio on attempts.

## Usage

```bash
glow attempts audio download --id <id>
```

> Wire call: `POST /attempt/audio_download`. Run `glow attempts audio download --help` for the full flag list.

---

# `glow attempts audio upload`

Route: /cli-reference/attempts/audio/upload

# `glow attempts audio upload`

Upload audio on attempts.

## Usage

```bash
glow attempts audio upload --body '\{...\}'
```

> Wire call: `POST /attempt/audio_upload`. Run `glow attempts audio upload --help` for the full flag list.

---

# `glow attempts call download`

Route: /cli-reference/attempts/call/download

# `glow attempts call download`

Download call on attempts.

## Usage

```bash
glow attempts call download --id <id>
```

> Wire call: `POST /attempt/call_download`. Run `glow attempts call download --help` for the full flag list.

---

# `glow attempts chat analyses`

Route: /cli-reference/attempts/chat/analyses

# `glow attempts chat analyses`

Analyses on chat (under attempts).

## Usage

```bash
glow attempts chat analyses --id <id>
```

> Wire call: `POST /attempt/chat_analyses`. Run `glow attempts chat analyses --help` for the full flag list.

---

# `glow attempts chat audio`

Route: /cli-reference/attempts/chat/audio

# `glow attempts chat audio`

Audio on chat (under attempts).

## Usage

```bash
glow attempts chat audio --id <id>
```

> Wire call: `POST /attempt/chat_audio`. Run `glow attempts chat audio --help` for the full flag list.

---

# `glow attempts chat complete`

Route: /cli-reference/attempts/chat/complete

# `glow attempts chat complete`

Complete on chat (under attempts).

## Usage

```bash
glow attempts chat complete --id <id>
```

> Wire call: `POST /attempt/chat_complete`. Run `glow attempts chat complete --help` for the full flag list.

---

# `glow attempts chat create`

Route: /cli-reference/attempts/chat/create

# `glow attempts chat create`

Create on chat (under attempts).

## Usage

```bash
glow attempts chat create --body '\{...\}'
```

> Wire call: `POST /attempt/chat_create`. Run `glow attempts chat create --help` for the full flag list.

---

# `glow attempts chat export`

Route: /cli-reference/attempts/chat/export

# `glow attempts chat export`

Export on chat (under attempts).

## Usage

```bash
glow attempts chat export --id <id>
```

> Wire call: `POST /attempt/chat_export`. Run `glow attempts chat export --help` for the full flag list.

---

# `glow attempts chat feedback`

Route: /cli-reference/attempts/chat/feedback

# `glow attempts chat feedback`

Feedback on chat (under attempts).

## Usage

```bash
glow attempts chat feedback --id <id>
```

> Wire call: `POST /attempt/chat_feedback`. Run `glow attempts chat feedback --help` for the full flag list.

---

# `glow attempts chat get`

Route: /cli-reference/attempts/chat/get

# `glow attempts chat get`

Get on chat (under attempts).

## Usage

```bash
glow attempts chat get --id <id>
```

> Wire call: `POST /attempt/chat_get`. Run `glow attempts chat get --help` for the full flag list.

---

# `glow attempts chat grade`

Route: /cli-reference/attempts/chat/grade

# `glow attempts chat grade`

Grade on chat (under attempts).

## Usage

```bash
glow attempts chat grade --id <id>
```

> Wire call: `POST /attempt/chat_grade`. Run `glow attempts chat grade --help` for the full flag list.

---

# `glow attempts chat hints`

Route: /cli-reference/attempts/chat/hints

# `glow attempts chat hints`

Hints on chat (under attempts).

## Usage

```bash
glow attempts chat hints --id <id>
```

> Wire call: `POST /attempt/chat_hints`. Run `glow attempts chat hints --help` for the full flag list.

---

# `glow attempts chat improvements`

Route: /cli-reference/attempts/chat/improvements

# `glow attempts chat improvements`

Improvements on chat (under attempts).

## Usage

```bash
glow attempts chat improvements --id <id>
```

> Wire call: `POST /attempt/chat_improvements`. Run `glow attempts chat improvements --help` for the full flag list.

---

# `glow attempts chat message`

Route: /cli-reference/attempts/chat/message

# `glow attempts chat message`

Message on chat (under attempts).

## Usage

```bash
glow attempts chat message --id <id>
```

> Wire call: `POST /attempt/chat_message`. Run `glow attempts chat message --help` for the full flag list.

---

# `glow attempts chat response`

Route: /cli-reference/attempts/chat/response

# `glow attempts chat response`

Response on chat (under attempts).

## Usage

```bash
glow attempts chat response --id <id>
```

> Wire call: `POST /attempt/chat_response`. Run `glow attempts chat response --help` for the full flag list.

---

# `glow attempts chat silence`

Route: /cli-reference/attempts/chat/silence

# `glow attempts chat silence`

Silence on chat (under attempts).

## Usage

```bash
glow attempts chat silence --id <id>
```

> Wire call: `POST /attempt/chat_silence`. Run `glow attempts chat silence --help` for the full flag list.

---

# `glow attempts chat speak`

Route: /cli-reference/attempts/chat/speak

# `glow attempts chat speak`

Speak on chat (under attempts).

## Usage

```bash
glow attempts chat speak --id <id>
```

> Wire call: `POST /attempt/chat_speak`. Run `glow attempts chat speak --help` for the full flag list.

---

# `glow attempts chat strengths`

Route: /cli-reference/attempts/chat/strengths

# `glow attempts chat strengths`

Strengths on chat (under attempts).

## Usage

```bash
glow attempts chat strengths --id <id>
```

> Wire call: `POST /attempt/chat_strengths`. Run `glow attempts chat strengths --help` for the full flag list.

---

# `glow attempts chat voice`

Route: /cli-reference/attempts/chat/voice

# `glow attempts chat voice`

Voice on chat (under attempts).

## Usage

```bash
glow attempts chat voice --id <id>
```

> Wire call: `POST /attempt/chat_voice`. Run `glow attempts chat voice --help` for the full flag list.

---

# `glow attempts complete`

Route: /cli-reference/attempts/complete

# `glow attempts complete`

Complete on attempts.

## Usage

```bash
glow attempts complete --id <id>
```

> Wire call: `POST /attempt/complete`. Run `glow attempts complete --help` for the full flag list.

---

# `glow attempts context`

Route: /cli-reference/attempts/context

# `glow attempts context`

Context on attempts.

## Usage

```bash
glow attempts context --id <id>
```

> Wire call: `POST /attempt/context`. Run `glow attempts context --help` for the full flag list.

---

# `glow attempts dashboard get`

Route: /cli-reference/attempts/dashboard/get

# `glow attempts dashboard get`

Get on dashboard (under attempts).

## Usage

```bash
glow attempts dashboard get --id <id>
```

> Wire call: `POST /attempt/dashboard`. Run `glow attempts dashboard get --help` for the full flag list.

---

# `glow attempts draft`

Route: /cli-reference/attempts/draft

# `glow attempts draft`

Draft on attempts.

## Usage

```bash
glow attempts draft --id <id>
```

> Wire call: `POST /attempt/draft`. Run `glow attempts draft --help` for the full flag list.

---

# `glow attempts drafts`

Route: /cli-reference/attempts/drafts

# `glow attempts drafts`

Drafts on attempts.

## Usage

```bash
glow attempts drafts --id <id>
```

> Wire call: `POST /attempt/drafts`. Run `glow attempts drafts --help` for the full flag list.

---

# `glow attempts export`

Route: /cli-reference/attempts/export

# `glow attempts export`

Export on attempts.

## Usage

```bash
glow attempts export --id <id>
```

> Wire call: `POST /attempt/export`. Run `glow attempts export --help` for the full flag list.

---

# `glow attempts file download`

Route: /cli-reference/attempts/file/download

# `glow attempts file download`

Download file on attempts.

## Usage

```bash
glow attempts file download --id <id>
```

> Wire call: `POST /attempt/file_download`. Run `glow attempts file download --help` for the full flag list.

---

# `glow attempts file preview`

Route: /cli-reference/attempts/file/preview

# `glow attempts file preview`

Preview file on attempts.

## Usage

```bash
glow attempts file preview --id <id>
```

> Wire call: `POST /attempt/file_preview`. Run `glow attempts file preview --help` for the full flag list.

---

# `glow attempts generate`

Route: /cli-reference/attempts/generate

# `glow attempts generate`

Generate on attempts.

## Usage

```bash
glow attempts generate --body '\{...\}'
```

> Wire call: `POST /attempt/generate`. Run `glow attempts generate --help` for the full flag list.

---

# `glow attempts generations`

Route: /cli-reference/attempts/generations

# `glow attempts generations`

Generations on attempts.

## Usage

```bash
glow attempts generations --id <id>
```

> Wire call: `POST /attempt/generations`. Run `glow attempts generations --help` for the full flag list.

---

# `glow attempts get`

Route: /cli-reference/attempts/get

# `glow attempts get`

Get on attempts.

## Usage

```bash
glow attempts get --id <id>
```

> Wire call: `POST /attempt/get`. Run `glow attempts get --help` for the full flag list.

---

# `glow attempts group`

Route: /cli-reference/attempts/group

# `glow attempts group`

Group on attempts.

## Usage

```bash
glow attempts group --id <id>
```

> Wire call: `POST /attempt/group`. Run `glow attempts group --help` for the full flag list.

---

# `glow attempts home get`

Route: /cli-reference/attempts/home/get

# `glow attempts home get`

Get on home (under attempts).

## Usage

```bash
glow attempts home get --id <id>
```

> Wire call: `POST /attempt/home`. Run `glow attempts home get --help` for the full flag list.

---

# `glow attempts image download`

Route: /cli-reference/attempts/image/download

# `glow attempts image download`

Download image on attempts.

## Usage

```bash
glow attempts image download --id <id>
```

> Wire call: `POST /attempt/image_download`. Run `glow attempts image download --help` for the full flag list.

---

# `glow attempts leaderboard get`

Route: /cli-reference/attempts/leaderboard/get

# `glow attempts leaderboard get`

Get on leaderboard (under attempts).

## Usage

```bash
glow attempts leaderboard get --id <id>
```

> Wire call: `POST /attempt/leaderboard`. Run `glow attempts leaderboard get --help` for the full flag list.

---

# `glow attempts practice get`

Route: /cli-reference/attempts/practice/get

# `glow attempts practice get`

Get on practice (under attempts).

## Usage

```bash
glow attempts practice get --id <id>
```

> Wire call: `POST /attempt/practice`. Run `glow attempts practice get --help` for the full flag list.

---

# `glow attempts problem`

Route: /cli-reference/attempts/problem

# `glow attempts problem`

Problem on attempts.

## Usage

```bash
glow attempts problem --id <id>
```

> Wire call: `POST /attempt/problem`. Run `glow attempts problem --help` for the full flag list.

---

# `glow attempts refresh`

Route: /cli-reference/attempts/refresh

# `glow attempts refresh`

Refresh on attempts.

## Usage

```bash
glow attempts refresh --id <id>
```

> Wire call: `POST /attempt/refresh`. Run `glow attempts refresh --help` for the full flag list.

---

# `glow attempts search`

Route: /cli-reference/attempts/search

# `glow attempts search`

Search on attempts.

## Usage

```bash
glow attempts search
```

> Wire call: `POST /attempt/search`. Run `glow attempts search --help` for the full flag list.

---

# `glow attempts start`

Route: /cli-reference/attempts/start

# `glow attempts start`

Start on attempts.

## Usage

```bash
glow attempts start --id <id>
```

> Wire call: `POST /attempt/start`. Run `glow attempts start --help` for the full flag list.

---

# `glow attempts stop`

Route: /cli-reference/attempts/stop

# `glow attempts stop`

Stop on attempts.

## Usage

```bash
glow attempts stop --id <id>
```

> Wire call: `POST /attempt/stop`. Run `glow attempts stop --help` for the full flag list.

---

# `glow attempts text download`

Route: /cli-reference/attempts/text/download

# `glow attempts text download`

Download text on attempts.

## Usage

```bash
glow attempts text download --id <id>
```

> Wire call: `POST /attempt/text_download`. Run `glow attempts text download --help` for the full flag list.

---

# `glow attempts title`

Route: /cli-reference/attempts/title

# `glow attempts title`

Title on attempts.

## Usage

```bash
glow attempts title --id <id>
```

> Wire call: `POST /attempt/title`. Run `glow attempts title --help` for the full flag list.

---

# `glow attempts video download`

Route: /cli-reference/attempts/video/download

# `glow attempts video download`

Download video on attempts.

## Usage

```bash
glow attempts video download --id <id>
```

> Wire call: `POST /attempt/video_download`. Run `glow attempts video download --help` for the full flag list.

---

# `glow attempts watch`

Route: /cli-reference/attempts/watch

# `glow attempts watch`

Watch on attempts.

## Usage

```bash
glow attempts watch --id <id>
```

> Wire call: `POST /attempt/watch`. Run `glow attempts watch --help` for the full flag list.

---

# `glow auths call download`

Route: /cli-reference/auths/call/download

# `glow auths call download`

Download call on Authentication records.

## Usage

```bash
glow auths call download --id <id>
```

> Wire call: `POST /auth/call_download`. Run `glow auths call download --help` for the full flag list.

---

# `glow auths client-config`

Route: /cli-reference/auths/client-config

# `glow auths client-config`

Client Config Authentication records.

## Usage

```bash
glow auths client-config --id <id>
```

> Wire call: `POST /auth/client-config`. Run `glow auths client-config --help` for the full flag list.

---

# `glow auths context`

Route: /cli-reference/auths/context

# `glow auths context`

Context Authentication records.

## Usage

```bash
glow auths context --id <id>
```

> Wire call: `POST /auth/context`. Run `glow auths context --help` for the full flag list.

---

# `glow auths create`

Route: /cli-reference/auths/create

# `glow auths create`

Create Authentication records.

## Usage

```bash
glow auths create --body '\{...\}'
```

> Wire call: `POST /auth/create`. Run `glow auths create --help` for the full flag list.

---

# `glow auths csv`

Route: /cli-reference/auths/csv

# `glow auths csv`

Csv Authentication records.

## Usage

```bash
glow auths csv --id <id>
```

> Wire call: `POST /auth/csv`. Run `glow auths csv --help` for the full flag list.

---

# `glow auths delete`

Route: /cli-reference/auths/delete

# `glow auths delete`

Delete Authentication records.

## Usage

```bash
glow auths delete --id <id>
```

> Wire call: `POST /auth/delete`. Run `glow auths delete --help` for the full flag list.

---

# `glow auths draft`

Route: /cli-reference/auths/draft

# `glow auths draft`

Draft Authentication records.

## Usage

```bash
glow auths draft --id <id>
```

> Wire call: `POST /auth/draft`. Run `glow auths draft --help` for the full flag list.

---

# `glow auths drafts`

Route: /cli-reference/auths/drafts

# `glow auths drafts`

Drafts Authentication records.

## Usage

```bash
glow auths drafts --id <id>
```

> Wire call: `POST /auth/drafts`. Run `glow auths drafts --help` for the full flag list.

---

# `glow auths duplicate`

Route: /cli-reference/auths/duplicate

# `glow auths duplicate`

Duplicate Authentication records.

## Usage

```bash
glow auths duplicate --id <id>
```

> Wire call: `POST /auth/duplicate`. Run `glow auths duplicate --help` for the full flag list.

---

# `glow auths export`

Route: /cli-reference/auths/export

# `glow auths export`

Export Authentication records.

## Usage

```bash
glow auths export --id <id>
```

> Wire call: `POST /auth/export`. Run `glow auths export --help` for the full flag list.

---

# `glow auths file download`

Route: /cli-reference/auths/file/download

# `glow auths file download`

Download file on Authentication records.

## Usage

```bash
glow auths file download --id <id>
```

> Wire call: `POST /auth/file_download`. Run `glow auths file download --help` for the full flag list.

---

# `glow auths generate`

Route: /cli-reference/auths/generate

# `glow auths generate`

Generate Authentication records.

## Usage

```bash
glow auths generate --body '\{...\}'
```

> Wire call: `POST /auth/generate`. Run `glow auths generate --help` for the full flag list.

---

# `glow auths generations`

Route: /cli-reference/auths/generations

# `glow auths generations`

Generations Authentication records.

## Usage

```bash
glow auths generations --id <id>
```

> Wire call: `POST /auth/generations`. Run `glow auths generations --help` for the full flag list.

---

# `glow auths get`

Route: /cli-reference/auths/get

# `glow auths get`

Get Authentication records.

## Usage

```bash
glow auths get --id <id>
```

> Wire call: `POST /auth/get`. Run `glow auths get --help` for the full flag list.

---

# `glow auths group`

Route: /cli-reference/auths/group

# `glow auths group`

Group Authentication records.

## Usage

```bash
glow auths group --id <id>
```

> Wire call: `POST /auth/group`. Run `glow auths group --help` for the full flag list.

---

# `glow auths problem`

Route: /cli-reference/auths/problem

# `glow auths problem`

Problem Authentication records.

## Usage

```bash
glow auths problem --id <id>
```

> Wire call: `POST /auth/problem`. Run `glow auths problem --help` for the full flag list.

---

# `glow auths refresh`

Route: /cli-reference/auths/refresh

# `glow auths refresh`

Refresh Authentication records.

## Usage

```bash
glow auths refresh --id <id>
```

> Wire call: `POST /auth/refresh`. Run `glow auths refresh --help` for the full flag list.

---

# `glow auths search`

Route: /cli-reference/auths/search

# `glow auths search`

Search Authentication records.

## Usage

```bash
glow auths search
```

> Wire call: `POST /auth/search`. Run `glow auths search --help` for the full flag list.

---

# `glow auths text download`

Route: /cli-reference/auths/text/download

# `glow auths text download`

Download text on Authentication records.

## Usage

```bash
glow auths text download --id <id>
```

> Wire call: `POST /auth/text_download`. Run `glow auths text download --help` for the full flag list.

---

# `glow auths title`

Route: /cli-reference/auths/title

# `glow auths title`

Title Authentication records.

## Usage

```bash
glow auths title --id <id>
```

> Wire call: `POST /auth/title`. Run `glow auths title --help` for the full flag list.

---

# `glow auths update`

Route: /cli-reference/auths/update

# `glow auths update`

Update Authentication records.

## Usage

```bash
glow auths update --id <id>
```

> Wire call: `POST /auth/update`. Run `glow auths update --help` for the full flag list.

---

# `glow auths watch`

Route: /cli-reference/auths/watch

# `glow auths watch`

Watch Authentication records.

## Usage

```bash
glow auths watch --id <id>
```

> Wire call: `POST /auth/watch`. Run `glow auths watch --help` for the full flag list.

---

# `glow backup create`

Route: /cli-reference/backup-create

# `glow backup create`

Create a new pg_dump backup

## Usage

```bash
glow backup create [--name] [--label]
```

## Options

| Flag | Required | Description |
|---|---|---|
| `--name` | No | — |
| `--label` | No | Optional label tag; filename becomes `manual-<label>-<ts>.sql.gz` |

---

# `glow backup delete`

Route: /cli-reference/backup-delete

# `glow backup delete`

Delete a backup file

## Usage

```bash
glow backup delete [--name] file <file>
```

## Options

| Flag | Required | Description |
|---|---|---|
| `--name` | No | — |
| `file` | Yes | — |

---

# `glow backup list`

Route: /cli-reference/backup-list

# `glow backup list`

List local backups for an instance

## Usage

```bash
glow backup list [--name]
```

## Options

| Flag | Required | Description |
|---|---|---|
| `--name` | No | — |

---

# `glow backup restore`

Route: /cli-reference/backup-restore

# `glow backup restore`

Restore an existing backup (destructive — drops + recreates DB)

## Usage

```bash
glow backup restore [--name] file <file>
```

## Options

| Flag | Required | Description |
|---|---|---|
| `--name` | No | — |
| `file` | Yes | Backup filename inside the instance's `backups/` dir |

---

# `glow cohorts call download`

Route: /cli-reference/cohorts/call/download

# `glow cohorts call download`

Download call on User cohorts.

## Usage

```bash
glow cohorts call download --id <id>
```

> Wire call: `POST /cohort/call_download`. Run `glow cohorts call download --help` for the full flag list.

---

# `glow cohorts context`

Route: /cli-reference/cohorts/context

# `glow cohorts context`

Context User cohorts.

## Usage

```bash
glow cohorts context --id <id>
```

> Wire call: `POST /cohort/context`. Run `glow cohorts context --help` for the full flag list.

---

# `glow cohorts create`

Route: /cli-reference/cohorts/create

# `glow cohorts create`

Create User cohorts.

## Usage

```bash
glow cohorts create --body '\{...\}'
```

> Wire call: `POST /cohort/create`. Run `glow cohorts create --help` for the full flag list.

---

# `glow cohorts csv`

Route: /cli-reference/cohorts/csv

# `glow cohorts csv`

Csv User cohorts.

## Usage

```bash
glow cohorts csv --id <id>
```

> Wire call: `POST /cohort/csv`. Run `glow cohorts csv --help` for the full flag list.

---

# `glow cohorts delete`

Route: /cli-reference/cohorts/delete

# `glow cohorts delete`

Delete User cohorts.

## Usage

```bash
glow cohorts delete --id <id>
```

> Wire call: `POST /cohort/delete`. Run `glow cohorts delete --help` for the full flag list.

---

# `glow cohorts draft`

Route: /cli-reference/cohorts/draft

# `glow cohorts draft`

Draft User cohorts.

## Usage

```bash
glow cohorts draft --id <id>
```

> Wire call: `POST /cohort/draft`. Run `glow cohorts draft --help` for the full flag list.

---

# `glow cohorts drafts`

Route: /cli-reference/cohorts/drafts

# `glow cohorts drafts`

Drafts User cohorts.

## Usage

```bash
glow cohorts drafts --id <id>
```

> Wire call: `POST /cohort/drafts`. Run `glow cohorts drafts --help` for the full flag list.

---

# `glow cohorts duplicate`

Route: /cli-reference/cohorts/duplicate

# `glow cohorts duplicate`

Duplicate User cohorts.

## Usage

```bash
glow cohorts duplicate --id <id>
```

> Wire call: `POST /cohort/duplicate`. Run `glow cohorts duplicate --help` for the full flag list.

---

# `glow cohorts export`

Route: /cli-reference/cohorts/export

# `glow cohorts export`

Export User cohorts.

## Usage

```bash
glow cohorts export --id <id>
```

> Wire call: `POST /cohort/export`. Run `glow cohorts export --help` for the full flag list.

---

# `glow cohorts file download`

Route: /cli-reference/cohorts/file/download

# `glow cohorts file download`

Download file on User cohorts.

## Usage

```bash
glow cohorts file download --id <id>
```

> Wire call: `POST /cohort/file_download`. Run `glow cohorts file download --help` for the full flag list.

---

# `glow cohorts generate`

Route: /cli-reference/cohorts/generate

# `glow cohorts generate`

Generate User cohorts.

## Usage

```bash
glow cohorts generate --body '\{...\}'
```

> Wire call: `POST /cohort/generate`. Run `glow cohorts generate --help` for the full flag list.

---

# `glow cohorts generations`

Route: /cli-reference/cohorts/generations

# `glow cohorts generations`

Generations User cohorts.

## Usage

```bash
glow cohorts generations --id <id>
```

> Wire call: `POST /cohort/generations`. Run `glow cohorts generations --help` for the full flag list.

---

# `glow cohorts get`

Route: /cli-reference/cohorts/get

# `glow cohorts get`

Get User cohorts.

## Usage

```bash
glow cohorts get --id <id>
```

> Wire call: `POST /cohort/get`. Run `glow cohorts get --help` for the full flag list.

---

# `glow cohorts group`

Route: /cli-reference/cohorts/group

# `glow cohorts group`

Group User cohorts.

## Usage

```bash
glow cohorts group --id <id>
```

> Wire call: `POST /cohort/group`. Run `glow cohorts group --help` for the full flag list.

---

# `glow cohorts problem`

Route: /cli-reference/cohorts/problem

# `glow cohorts problem`

Problem User cohorts.

## Usage

```bash
glow cohorts problem --id <id>
```

> Wire call: `POST /cohort/problem`. Run `glow cohorts problem --help` for the full flag list.

---

# `glow cohorts refresh`

Route: /cli-reference/cohorts/refresh

# `glow cohorts refresh`

Refresh User cohorts.

## Usage

```bash
glow cohorts refresh --id <id>
```

> Wire call: `POST /cohort/refresh`. Run `glow cohorts refresh --help` for the full flag list.

---

# `glow cohorts search`

Route: /cli-reference/cohorts/search

# `glow cohorts search`

Search User cohorts.

## Usage

```bash
glow cohorts search
```

> Wire call: `POST /cohort/search`. Run `glow cohorts search --help` for the full flag list.

---

# `glow cohorts text download`

Route: /cli-reference/cohorts/text/download

# `glow cohorts text download`

Download text on User cohorts.

## Usage

```bash
glow cohorts text download --id <id>
```

> Wire call: `POST /cohort/text_download`. Run `glow cohorts text download --help` for the full flag list.

---

# `glow cohorts title`

Route: /cli-reference/cohorts/title

# `glow cohorts title`

Title User cohorts.

## Usage

```bash
glow cohorts title --id <id>
```

> Wire call: `POST /cohort/title`. Run `glow cohorts title --help` for the full flag list.

---

# `glow cohorts update`

Route: /cli-reference/cohorts/update

# `glow cohorts update`

Update User cohorts.

## Usage

```bash
glow cohorts update --id <id>
```

> Wire call: `POST /cohort/update`. Run `glow cohorts update --help` for the full flag list.

---

# `glow cohorts watch`

Route: /cli-reference/cohorts/watch

# `glow cohorts watch`

Watch User cohorts.

## Usage

```bash
glow cohorts watch --id <id>
```

> Wire call: `POST /cohort/watch`. Run `glow cohorts watch --help` for the full flag list.

---

# `glow departments call download`

Route: /cli-reference/departments/call/download

# `glow departments call download`

Download call on Organizational departments.

## Usage

```bash
glow departments call download --id <id>
```

> Wire call: `POST /department/call_download`. Run `glow departments call download --help` for the full flag list.

---

# `glow departments context`

Route: /cli-reference/departments/context

# `glow departments context`

Context Organizational departments.

## Usage

```bash
glow departments context --id <id>
```

> Wire call: `POST /department/context`. Run `glow departments context --help` for the full flag list.

---

# `glow departments create`

Route: /cli-reference/departments/create

# `glow departments create`

Create Organizational departments.

## Usage

```bash
glow departments create --body '\{...\}'
```

> Wire call: `POST /department/create`. Run `glow departments create --help` for the full flag list.

---

# `glow departments csv`

Route: /cli-reference/departments/csv

# `glow departments csv`

Csv Organizational departments.

## Usage

```bash
glow departments csv --id <id>
```

> Wire call: `POST /department/csv`. Run `glow departments csv --help` for the full flag list.

---

# `glow departments delete`

Route: /cli-reference/departments/delete

# `glow departments delete`

Delete Organizational departments.

## Usage

```bash
glow departments delete --id <id>
```

> Wire call: `POST /department/delete`. Run `glow departments delete --help` for the full flag list.

---

# `glow departments draft`

Route: /cli-reference/departments/draft

# `glow departments draft`

Draft Organizational departments.

## Usage

```bash
glow departments draft --id <id>
```

> Wire call: `POST /department/draft`. Run `glow departments draft --help` for the full flag list.

---

# `glow departments drafts`

Route: /cli-reference/departments/drafts

# `glow departments drafts`

Drafts Organizational departments.

## Usage

```bash
glow departments drafts --id <id>
```

> Wire call: `POST /department/drafts`. Run `glow departments drafts --help` for the full flag list.

---

# `glow departments duplicate`

Route: /cli-reference/departments/duplicate

# `glow departments duplicate`

Duplicate Organizational departments.

## Usage

```bash
glow departments duplicate --id <id>
```

> Wire call: `POST /department/duplicate`. Run `glow departments duplicate --help` for the full flag list.

---

# `glow departments export`

Route: /cli-reference/departments/export

# `glow departments export`

Export Organizational departments.

## Usage

```bash
glow departments export --id <id>
```

> Wire call: `POST /department/export`. Run `glow departments export --help` for the full flag list.

---

# `glow departments file download`

Route: /cli-reference/departments/file/download

# `glow departments file download`

Download file on Organizational departments.

## Usage

```bash
glow departments file download --id <id>
```

> Wire call: `POST /department/file_download`. Run `glow departments file download --help` for the full flag list.

---

# `glow departments generate`

Route: /cli-reference/departments/generate

# `glow departments generate`

Generate Organizational departments.

## Usage

```bash
glow departments generate --body '\{...\}'
```

> Wire call: `POST /department/generate`. Run `glow departments generate --help` for the full flag list.

---

# `glow departments generations`

Route: /cli-reference/departments/generations

# `glow departments generations`

Generations Organizational departments.

## Usage

```bash
glow departments generations --id <id>
```

> Wire call: `POST /department/generations`. Run `glow departments generations --help` for the full flag list.

---

# `glow departments get`

Route: /cli-reference/departments/get

# `glow departments get`

Get Organizational departments.

## Usage

```bash
glow departments get --id <id>
```

> Wire call: `POST /department/get`. Run `glow departments get --help` for the full flag list.

---

# `glow departments group`

Route: /cli-reference/departments/group

# `glow departments group`

Group Organizational departments.

## Usage

```bash
glow departments group --id <id>
```

> Wire call: `POST /department/group`. Run `glow departments group --help` for the full flag list.

---

# `glow departments problem`

Route: /cli-reference/departments/problem

# `glow departments problem`

Problem Organizational departments.

## Usage

```bash
glow departments problem --id <id>
```

> Wire call: `POST /department/problem`. Run `glow departments problem --help` for the full flag list.

---

# `glow departments refresh`

Route: /cli-reference/departments/refresh

# `glow departments refresh`

Refresh Organizational departments.

## Usage

```bash
glow departments refresh --id <id>
```

> Wire call: `POST /department/refresh`. Run `glow departments refresh --help` for the full flag list.

---

# `glow departments search`

Route: /cli-reference/departments/search

# `glow departments search`

Search Organizational departments.

## Usage

```bash
glow departments search
```

> Wire call: `POST /department/search`. Run `glow departments search --help` for the full flag list.

---

# `glow departments text download`

Route: /cli-reference/departments/text/download

# `glow departments text download`

Download text on Organizational departments.

## Usage

```bash
glow departments text download --id <id>
```

> Wire call: `POST /department/text_download`. Run `glow departments text download --help` for the full flag list.

---

# `glow departments title`

Route: /cli-reference/departments/title

# `glow departments title`

Title Organizational departments.

## Usage

```bash
glow departments title --id <id>
```

> Wire call: `POST /department/title`. Run `glow departments title --help` for the full flag list.

---

# `glow departments update`

Route: /cli-reference/departments/update

# `glow departments update`

Update Organizational departments.

## Usage

```bash
glow departments update --id <id>
```

> Wire call: `POST /department/update`. Run `glow departments update --help` for the full flag list.

---

# `glow departments watch`

Route: /cli-reference/departments/watch

# `glow departments watch`

Watch Organizational departments.

## Usage

```bash
glow departments watch --id <id>
```

> Wire call: `POST /department/watch`. Run `glow departments watch --help` for the full flag list.

---

# `glow deploy`

Route: /cli-reference/deploy

# `glow deploy`

Deploy a Glow instance to the local machine (first-time setup). Reads `~/.glow/instances/<name>/glow-deploy.yaml`. Run `glow init` first to scaffold one interactively

## Usage

```bash
glow deploy [--name] [--api-version] [--client-version] [--seed-setup] [--grace-minutes]
```

## Options

| Flag | Required | Description |
|---|---|---|
| `--name` | No | Instance name (defaults to "default") |
| `--api-version` | No | API image version, e.g. `v1.0.0` |
| `--client-version` | No | Client image version (required unless topology=api_only) |
| `--seed-setup` | No | Seed template for first deploy: fresh | university | organization |
| `--grace-minutes` | No | Grace period (minutes) to watch the new color after traffic swap |

---

# `glow destroy`

Route: /cli-reference/destroy

# `glow destroy`

Tear down containers + volumes (DESTROYS DATA — confirm twice). Config + backups under `~/.glow/instances/<name>/` are preserved

## Usage

```bash
glow destroy [--name]
```

## Options

| Flag | Required | Description |
|---|---|---|
| `--name` | No | — |

---

# `glow documents call download`

Route: /cli-reference/documents/call/download

# `glow documents call download`

Download call on Document management.

## Usage

```bash
glow documents call download --id <id>
```

> Wire call: `POST /document/call_download`. Run `glow documents call download --help` for the full flag list.

---

# `glow documents context`

Route: /cli-reference/documents/context

# `glow documents context`

Context Document management.

## Usage

```bash
glow documents context --id <id>
```

> Wire call: `POST /document/context`. Run `glow documents context --help` for the full flag list.

---

# `glow documents create`

Route: /cli-reference/documents/create

# `glow documents create`

Create Document management.

## Usage

```bash
glow documents create --body '\{...\}'
```

> Wire call: `POST /document/create`. Run `glow documents create --help` for the full flag list.

---

# `glow documents csv`

Route: /cli-reference/documents/csv

# `glow documents csv`

Csv Document management.

## Usage

```bash
glow documents csv --id <id>
```

> Wire call: `POST /document/csv`. Run `glow documents csv --help` for the full flag list.

---

# `glow documents delete`

Route: /cli-reference/documents/delete

# `glow documents delete`

Delete Document management.

## Usage

```bash
glow documents delete --id <id>
```

> Wire call: `POST /document/delete`. Run `glow documents delete --help` for the full flag list.

---

# `glow documents draft`

Route: /cli-reference/documents/draft

# `glow documents draft`

Draft Document management.

## Usage

```bash
glow documents draft --id <id>
```

> Wire call: `POST /document/draft`. Run `glow documents draft --help` for the full flag list.

---

# `glow documents drafts`

Route: /cli-reference/documents/drafts

# `glow documents drafts`

Drafts Document management.

## Usage

```bash
glow documents drafts --id <id>
```

> Wire call: `POST /document/drafts`. Run `glow documents drafts --help` for the full flag list.

---

# `glow documents duplicate`

Route: /cli-reference/documents/duplicate

# `glow documents duplicate`

Duplicate Document management.

## Usage

```bash
glow documents duplicate --id <id>
```

> Wire call: `POST /document/duplicate`. Run `glow documents duplicate --help` for the full flag list.

---

# `glow documents export`

Route: /cli-reference/documents/export

# `glow documents export`

Export Document management.

## Usage

```bash
glow documents export --id <id>
```

> Wire call: `POST /document/export`. Run `glow documents export --help` for the full flag list.

---

# `glow documents file download`

Route: /cli-reference/documents/file/download

# `glow documents file download`

Download file on Document management.

## Usage

```bash
glow documents file download --id <id>
```

> Wire call: `POST /document/file_download`. Run `glow documents file download --help` for the full flag list.

---

# `glow documents file preview`

Route: /cli-reference/documents/file/preview

# `glow documents file preview`

Preview file on Document management.

## Usage

```bash
glow documents file preview --id <id>
```

> Wire call: `POST /document/file_preview`. Run `glow documents file preview --help` for the full flag list.

---

# `glow documents file upload`

Route: /cli-reference/documents/file/upload

# `glow documents file upload`

Upload file on Document management.

## Usage

```bash
glow documents file upload --body '\{...\}'
```

> Wire call: `POST /document/file_upload`. Run `glow documents file upload --help` for the full flag list.

---

# `glow documents generate`

Route: /cli-reference/documents/generate

# `glow documents generate`

Generate Document management.

## Usage

```bash
glow documents generate --body '\{...\}'
```

> Wire call: `POST /document/generate`. Run `glow documents generate --help` for the full flag list.

---

# `glow documents generations`

Route: /cli-reference/documents/generations

# `glow documents generations`

Generations Document management.

## Usage

```bash
glow documents generations --id <id>
```

> Wire call: `POST /document/generations`. Run `glow documents generations --help` for the full flag list.

---

# `glow documents get`

Route: /cli-reference/documents/get

# `glow documents get`

Get Document management.

## Usage

```bash
glow documents get --id <id>
```

> Wire call: `POST /document/get`. Run `glow documents get --help` for the full flag list.

---

# `glow documents group`

Route: /cli-reference/documents/group

# `glow documents group`

Group Document management.

## Usage

```bash
glow documents group --id <id>
```

> Wire call: `POST /document/group`. Run `glow documents group --help` for the full flag list.

---

# `glow documents image download`

Route: /cli-reference/documents/image/download

# `glow documents image download`

Download image on Document management.

## Usage

```bash
glow documents image download --id <id>
```

> Wire call: `POST /document/image_download`. Run `glow documents image download --help` for the full flag list.

---

# `glow documents image upload`

Route: /cli-reference/documents/image/upload

# `glow documents image upload`

Upload image on Document management.

## Usage

```bash
glow documents image upload --body '\{...\}'
```

> Wire call: `POST /document/image_upload`. Run `glow documents image upload --help` for the full flag list.

---

# `glow documents problem`

Route: /cli-reference/documents/problem

# `glow documents problem`

Problem Document management.

## Usage

```bash
glow documents problem --id <id>
```

> Wire call: `POST /document/problem`. Run `glow documents problem --help` for the full flag list.

---

# `glow documents refresh`

Route: /cli-reference/documents/refresh

# `glow documents refresh`

Refresh Document management.

## Usage

```bash
glow documents refresh --id <id>
```

> Wire call: `POST /document/refresh`. Run `glow documents refresh --help` for the full flag list.

---

# `glow documents search`

Route: /cli-reference/documents/search

# `glow documents search`

Search Document management.

## Usage

```bash
glow documents search
```

> Wire call: `POST /document/search`. Run `glow documents search --help` for the full flag list.

---

# `glow documents text download`

Route: /cli-reference/documents/text/download

# `glow documents text download`

Download text on Document management.

## Usage

```bash
glow documents text download --id <id>
```

> Wire call: `POST /document/text_download`. Run `glow documents text download --help` for the full flag list.

---

# `glow documents text upload`

Route: /cli-reference/documents/text/upload

# `glow documents text upload`

Upload text on Document management.

## Usage

```bash
glow documents text upload --body '\{...\}'
```

> Wire call: `POST /document/text_upload`. Run `glow documents text upload --help` for the full flag list.

---

# `glow documents title`

Route: /cli-reference/documents/title

# `glow documents title`

Title Document management.

## Usage

```bash
glow documents title --id <id>
```

> Wire call: `POST /document/title`. Run `glow documents title --help` for the full flag list.

---

# `glow documents update`

Route: /cli-reference/documents/update

# `glow documents update`

Update Document management.

## Usage

```bash
glow documents update --id <id>
```

> Wire call: `POST /document/update`. Run `glow documents update --help` for the full flag list.

---

# `glow documents watch`

Route: /cli-reference/documents/watch

# `glow documents watch`

Watch Document management.

## Usage

```bash
glow documents watch --id <id>
```

> Wire call: `POST /document/watch`. Run `glow documents watch --help` for the full flag list.

---

# `glow evals call download`

Route: /cli-reference/evals/call/download

# `glow evals call download`

Download call on Evaluation configurations.

## Usage

```bash
glow evals call download --id <id>
```

> Wire call: `POST /eval/call_download`. Run `glow evals call download --help` for the full flag list.

---

# `glow evals context`

Route: /cli-reference/evals/context

# `glow evals context`

Context Evaluation configurations.

## Usage

```bash
glow evals context --id <id>
```

> Wire call: `POST /eval/context`. Run `glow evals context --help` for the full flag list.

---

# `glow evals create`

Route: /cli-reference/evals/create

# `glow evals create`

Create Evaluation configurations.

## Usage

```bash
glow evals create --body '\{...\}'
```

> Wire call: `POST /eval/create`. Run `glow evals create --help` for the full flag list.

---

# `glow evals csv`

Route: /cli-reference/evals/csv

# `glow evals csv`

Csv Evaluation configurations.

## Usage

```bash
glow evals csv --id <id>
```

> Wire call: `POST /eval/csv`. Run `glow evals csv --help` for the full flag list.

---

# `glow evals delete`

Route: /cli-reference/evals/delete

# `glow evals delete`

Delete Evaluation configurations.

## Usage

```bash
glow evals delete --id <id>
```

> Wire call: `POST /eval/delete`. Run `glow evals delete --help` for the full flag list.

---

# `glow evals draft`

Route: /cli-reference/evals/draft

# `glow evals draft`

Draft Evaluation configurations.

## Usage

```bash
glow evals draft --id <id>
```

> Wire call: `POST /eval/draft`. Run `glow evals draft --help` for the full flag list.

---

# `glow evals drafts`

Route: /cli-reference/evals/drafts

# `glow evals drafts`

Drafts Evaluation configurations.

## Usage

```bash
glow evals drafts --id <id>
```

> Wire call: `POST /eval/drafts`. Run `glow evals drafts --help` for the full flag list.

---

# `glow evals duplicate`

Route: /cli-reference/evals/duplicate

# `glow evals duplicate`

Duplicate Evaluation configurations.

## Usage

```bash
glow evals duplicate --id <id>
```

> Wire call: `POST /eval/duplicate`. Run `glow evals duplicate --help` for the full flag list.

---

# `glow evals export`

Route: /cli-reference/evals/export

# `glow evals export`

Export Evaluation configurations.

## Usage

```bash
glow evals export --id <id>
```

> Wire call: `POST /eval/export`. Run `glow evals export --help` for the full flag list.

---

# `glow evals file download`

Route: /cli-reference/evals/file/download

# `glow evals file download`

Download file on Evaluation configurations.

## Usage

```bash
glow evals file download --id <id>
```

> Wire call: `POST /eval/file_download`. Run `glow evals file download --help` for the full flag list.

---

# `glow evals generate`

Route: /cli-reference/evals/generate

# `glow evals generate`

Generate Evaluation configurations.

## Usage

```bash
glow evals generate --body '\{...\}'
```

> Wire call: `POST /eval/generate`. Run `glow evals generate --help` for the full flag list.

---

# `glow evals generations`

Route: /cli-reference/evals/generations

# `glow evals generations`

Generations Evaluation configurations.

## Usage

```bash
glow evals generations --id <id>
```

> Wire call: `POST /eval/generations`. Run `glow evals generations --help` for the full flag list.

---

# `glow evals get`

Route: /cli-reference/evals/get

# `glow evals get`

Get Evaluation configurations.

## Usage

```bash
glow evals get --id <id>
```

> Wire call: `POST /eval/get`. Run `glow evals get --help` for the full flag list.

---

# `glow evals group`

Route: /cli-reference/evals/group

# `glow evals group`

Group Evaluation configurations.

## Usage

```bash
glow evals group --id <id>
```

> Wire call: `POST /eval/group`. Run `glow evals group --help` for the full flag list.

---

# `glow evals problem`

Route: /cli-reference/evals/problem

# `glow evals problem`

Problem Evaluation configurations.

## Usage

```bash
glow evals problem --id <id>
```

> Wire call: `POST /eval/problem`. Run `glow evals problem --help` for the full flag list.

---

# `glow evals refresh`

Route: /cli-reference/evals/refresh

# `glow evals refresh`

Refresh Evaluation configurations.

## Usage

```bash
glow evals refresh --id <id>
```

> Wire call: `POST /eval/refresh`. Run `glow evals refresh --help` for the full flag list.

---

# `glow evals search`

Route: /cli-reference/evals/search

# `glow evals search`

Search Evaluation configurations.

## Usage

```bash
glow evals search
```

> Wire call: `POST /eval/search`. Run `glow evals search --help` for the full flag list.

---

# `glow evals text download`

Route: /cli-reference/evals/text/download

# `glow evals text download`

Download text on Evaluation configurations.

## Usage

```bash
glow evals text download --id <id>
```

> Wire call: `POST /eval/text_download`. Run `glow evals text download --help` for the full flag list.

---

# `glow evals title`

Route: /cli-reference/evals/title

# `glow evals title`

Title Evaluation configurations.

## Usage

```bash
glow evals title --id <id>
```

> Wire call: `POST /eval/title`. Run `glow evals title --help` for the full flag list.

---

# `glow evals update`

Route: /cli-reference/evals/update

# `glow evals update`

Update Evaluation configurations.

## Usage

```bash
glow evals update --id <id>
```

> Wire call: `POST /eval/update`. Run `glow evals update --help` for the full flag list.

---

# `glow evals watch`

Route: /cli-reference/evals/watch

# `glow evals watch`

Watch Evaluation configurations.

## Usage

```bash
glow evals watch --id <id>
```

> Wire call: `POST /eval/watch`. Run `glow evals watch --help` for the full flag list.

---

# `glow fields call download`

Route: /cli-reference/fields/call/download

# `glow fields call download`

Download call on Custom fields.

## Usage

```bash
glow fields call download --id <id>
```

> Wire call: `POST /field/call_download`. Run `glow fields call download --help` for the full flag list.

---

# `glow fields context`

Route: /cli-reference/fields/context

# `glow fields context`

Context Custom fields.

## Usage

```bash
glow fields context --id <id>
```

> Wire call: `POST /field/context`. Run `glow fields context --help` for the full flag list.

---

# `glow fields create`

Route: /cli-reference/fields/create

# `glow fields create`

Create Custom fields.

## Usage

```bash
glow fields create --body '\{...\}'
```

> Wire call: `POST /field/create`. Run `glow fields create --help` for the full flag list.

---

# `glow fields csv`

Route: /cli-reference/fields/csv

# `glow fields csv`

Csv Custom fields.

## Usage

```bash
glow fields csv --id <id>
```

> Wire call: `POST /field/csv`. Run `glow fields csv --help` for the full flag list.

---

# `glow fields delete`

Route: /cli-reference/fields/delete

# `glow fields delete`

Delete Custom fields.

## Usage

```bash
glow fields delete --id <id>
```

> Wire call: `POST /field/delete`. Run `glow fields delete --help` for the full flag list.

---

# `glow fields draft`

Route: /cli-reference/fields/draft

# `glow fields draft`

Draft Custom fields.

## Usage

```bash
glow fields draft --id <id>
```

> Wire call: `POST /field/draft`. Run `glow fields draft --help` for the full flag list.

---

# `glow fields drafts`

Route: /cli-reference/fields/drafts

# `glow fields drafts`

Drafts Custom fields.

## Usage

```bash
glow fields drafts --id <id>
```

> Wire call: `POST /field/drafts`. Run `glow fields drafts --help` for the full flag list.

---

# `glow fields duplicate`

Route: /cli-reference/fields/duplicate

# `glow fields duplicate`

Duplicate Custom fields.

## Usage

```bash
glow fields duplicate --id <id>
```

> Wire call: `POST /field/duplicate`. Run `glow fields duplicate --help` for the full flag list.

---

# `glow fields export`

Route: /cli-reference/fields/export

# `glow fields export`

Export Custom fields.

## Usage

```bash
glow fields export --id <id>
```

> Wire call: `POST /field/export`. Run `glow fields export --help` for the full flag list.

---

# `glow fields file download`

Route: /cli-reference/fields/file/download

# `glow fields file download`

Download file on Custom fields.

## Usage

```bash
glow fields file download --id <id>
```

> Wire call: `POST /field/file_download`. Run `glow fields file download --help` for the full flag list.

---

# `glow fields generate`

Route: /cli-reference/fields/generate

# `glow fields generate`

Generate Custom fields.

## Usage

```bash
glow fields generate --body '\{...\}'
```

> Wire call: `POST /field/generate`. Run `glow fields generate --help` for the full flag list.

---

# `glow fields generations`

Route: /cli-reference/fields/generations

# `glow fields generations`

Generations Custom fields.

## Usage

```bash
glow fields generations --id <id>
```

> Wire call: `POST /field/generations`. Run `glow fields generations --help` for the full flag list.

---

# `glow fields get`

Route: /cli-reference/fields/get

# `glow fields get`

Get Custom fields.

## Usage

```bash
glow fields get --id <id>
```

> Wire call: `POST /field/get`. Run `glow fields get --help` for the full flag list.

---

# `glow fields group`

Route: /cli-reference/fields/group

# `glow fields group`

Group Custom fields.

## Usage

```bash
glow fields group --id <id>
```

> Wire call: `POST /field/group`. Run `glow fields group --help` for the full flag list.

---

# `glow fields problem`

Route: /cli-reference/fields/problem

# `glow fields problem`

Problem Custom fields.

## Usage

```bash
glow fields problem --id <id>
```

> Wire call: `POST /field/problem`. Run `glow fields problem --help` for the full flag list.

---

# `glow fields refresh`

Route: /cli-reference/fields/refresh

# `glow fields refresh`

Refresh Custom fields.

## Usage

```bash
glow fields refresh --id <id>
```

> Wire call: `POST /field/refresh`. Run `glow fields refresh --help` for the full flag list.

---

# `glow fields search`

Route: /cli-reference/fields/search

# `glow fields search`

Search Custom fields.

## Usage

```bash
glow fields search
```

> Wire call: `POST /field/search`. Run `glow fields search --help` for the full flag list.

---

# `glow fields text download`

Route: /cli-reference/fields/text/download

# `glow fields text download`

Download text on Custom fields.

## Usage

```bash
glow fields text download --id <id>
```

> Wire call: `POST /field/text_download`. Run `glow fields text download --help` for the full flag list.

---

# `glow fields title`

Route: /cli-reference/fields/title

# `glow fields title`

Title Custom fields.

## Usage

```bash
glow fields title --id <id>
```

> Wire call: `POST /field/title`. Run `glow fields title --help` for the full flag list.

---

# `glow fields update`

Route: /cli-reference/fields/update

# `glow fields update`

Update Custom fields.

## Usage

```bash
glow fields update --id <id>
```

> Wire call: `POST /field/update`. Run `glow fields update --help` for the full flag list.

---

# `glow fields watch`

Route: /cli-reference/fields/watch

# `glow fields watch`

Watch Custom fields.

## Usage

```bash
glow fields watch --id <id>
```

> Wire call: `POST /field/watch`. Run `glow fields watch --help` for the full flag list.

---

# `glow init`

Route: /cli-reference/init

# `glow init`

Interactive wizard: scaffold a `glow-deploy.yaml` under `~/.glow/instances/<name>/`. Walks you through origin URL, AI provider + key, seed template, and optional OIDC. Idempotent — re-running overwrites the yaml

## Usage

```bash
glow init [--name]
```

## Options

| Flag | Required | Description |
|---|---|---|
| `--name` | No | — |

---

# `glow login`

Route: /cli-reference/login

# `glow login`

Authenticate with Glow instance

## Usage

```bash
glow login [--token] [--client-id]
```

## Options

| Flag | Required | Description |
|---|---|---|
| `--token` | No | Pre-issued JWT to store as the access token. When set, the OAuth redirect flow is skipped and the token is persisted keyed on the instance URL. No refresh_token is recorded — the server enforces expiry via the token's own ``exp`` claim |
| `--client-id` | No | OAuth client ID. Defaults to the value from ``--client-id`` / ``$GLOW_CLIENT_ID`` / config / "glow-cli". Ignored when ``--token`` is set |

---

# `glow logout`

Route: /cli-reference/logout

# `glow logout`

Sign out: fire ``GET /logout`` server-side (writes a ``logouts_entry`` row so the next request mints a fresh session) and then clear the local stored token. The server-side call is best-effort — local clear always runs

## Usage

```bash
glow logout
```

---

# `glow logs`

Route: /cli-reference/logs

# `glow logs`

Tail container logs (`docker compose logs [-f]`)

## Usage

```bash
glow logs [--name] [--follow] [service]
```

## Options

| Flag | Required | Description |
|---|---|---|
| `--name` | No | — |
| `--follow, -f` | No | Follow log output |
| `service` | No | Optional service name (e.g. `server-blue`, `database`) |

---

# `glow mcp call`

Route: /cli-reference/mcp-call

# `glow mcp call`

Call an MCP tool by name with a JSON arguments object. → POST /mcp/ with JSON-RPC ``tools/call``

## Usage

```bash
glow mcp call tool_name <tool_name> [--args]
```

## Options

| Flag | Required | Description |
|---|---|---|
| `tool_name` | Yes | Tool name (as it appears in ``list-tools`` output) |
| `--args` | No | JSON arguments object (defaults to ``\{\}``) |

---

# `glow mcp list-tools`

Route: /cli-reference/mcp-list-tools

# `glow mcp list-tools`

List the MCP tools the Glow instance exposes. → POST /mcp/ with JSON-RPC ``tools/list``

## Usage

```bash
glow mcp list-tools
```

---

# `glow models call download`

Route: /cli-reference/models/call/download

# `glow models call download`

Download call on AI model configurations.

## Usage

```bash
glow models call download --id <id>
```

> Wire call: `POST /model/call_download`. Run `glow models call download --help` for the full flag list.

---

# `glow models context`

Route: /cli-reference/models/context

# `glow models context`

Context AI model configurations.

## Usage

```bash
glow models context --id <id>
```

> Wire call: `POST /model/context`. Run `glow models context --help` for the full flag list.

---

# `glow models create`

Route: /cli-reference/models/create

# `glow models create`

Create AI model configurations.

## Usage

```bash
glow models create --body '\{...\}'
```

> Wire call: `POST /model/create`. Run `glow models create --help` for the full flag list.

---

# `glow models csv`

Route: /cli-reference/models/csv

# `glow models csv`

Csv AI model configurations.

## Usage

```bash
glow models csv --id <id>
```

> Wire call: `POST /model/csv`. Run `glow models csv --help` for the full flag list.

---

# `glow models delete`

Route: /cli-reference/models/delete

# `glow models delete`

Delete AI model configurations.

## Usage

```bash
glow models delete --id <id>
```

> Wire call: `POST /model/delete`. Run `glow models delete --help` for the full flag list.

---

# `glow models draft`

Route: /cli-reference/models/draft

# `glow models draft`

Draft AI model configurations.

## Usage

```bash
glow models draft --id <id>
```

> Wire call: `POST /model/draft`. Run `glow models draft --help` for the full flag list.

---

# `glow models drafts`

Route: /cli-reference/models/drafts

# `glow models drafts`

Drafts AI model configurations.

## Usage

```bash
glow models drafts --id <id>
```

> Wire call: `POST /model/drafts`. Run `glow models drafts --help` for the full flag list.

---

# `glow models duplicate`

Route: /cli-reference/models/duplicate

# `glow models duplicate`

Duplicate AI model configurations.

## Usage

```bash
glow models duplicate --id <id>
```

> Wire call: `POST /model/duplicate`. Run `glow models duplicate --help` for the full flag list.

---

# `glow models export`

Route: /cli-reference/models/export

# `glow models export`

Export AI model configurations.

## Usage

```bash
glow models export --id <id>
```

> Wire call: `POST /model/export`. Run `glow models export --help` for the full flag list.

---

# `glow models file download`

Route: /cli-reference/models/file/download

# `glow models file download`

Download file on AI model configurations.

## Usage

```bash
glow models file download --id <id>
```

> Wire call: `POST /model/file_download`. Run `glow models file download --help` for the full flag list.

---

# `glow models generate`

Route: /cli-reference/models/generate

# `glow models generate`

Generate AI model configurations.

## Usage

```bash
glow models generate --body '\{...\}'
```

> Wire call: `POST /model/generate`. Run `glow models generate --help` for the full flag list.

---

# `glow models generations`

Route: /cli-reference/models/generations

# `glow models generations`

Generations AI model configurations.

## Usage

```bash
glow models generations --id <id>
```

> Wire call: `POST /model/generations`. Run `glow models generations --help` for the full flag list.

---

# `glow models get`

Route: /cli-reference/models/get

# `glow models get`

Get AI model configurations.

## Usage

```bash
glow models get --id <id>
```

> Wire call: `POST /model/get`. Run `glow models get --help` for the full flag list.

---

# `glow models group`

Route: /cli-reference/models/group

# `glow models group`

Group AI model configurations.

## Usage

```bash
glow models group --id <id>
```

> Wire call: `POST /model/group`. Run `glow models group --help` for the full flag list.

---

# `glow models problem`

Route: /cli-reference/models/problem

# `glow models problem`

Problem AI model configurations.

## Usage

```bash
glow models problem --id <id>
```

> Wire call: `POST /model/problem`. Run `glow models problem --help` for the full flag list.

---

# `glow models refresh`

Route: /cli-reference/models/refresh

# `glow models refresh`

Refresh AI model configurations.

## Usage

```bash
glow models refresh --id <id>
```

> Wire call: `POST /model/refresh`. Run `glow models refresh --help` for the full flag list.

---

# `glow models search`

Route: /cli-reference/models/search

# `glow models search`

Search AI model configurations.

## Usage

```bash
glow models search
```

> Wire call: `POST /model/search`. Run `glow models search --help` for the full flag list.

---

# `glow models text download`

Route: /cli-reference/models/text/download

# `glow models text download`

Download text on AI model configurations.

## Usage

```bash
glow models text download --id <id>
```

> Wire call: `POST /model/text_download`. Run `glow models text download --help` for the full flag list.

---

# `glow models title`

Route: /cli-reference/models/title

# `glow models title`

Title AI model configurations.

## Usage

```bash
glow models title --id <id>
```

> Wire call: `POST /model/title`. Run `glow models title --help` for the full flag list.

---

# `glow models update`

Route: /cli-reference/models/update

# `glow models update`

Update AI model configurations.

## Usage

```bash
glow models update --id <id>
```

> Wire call: `POST /model/update`. Run `glow models update --help` for the full flag list.

---

# `glow models watch`

Route: /cli-reference/models/watch

# `glow models watch`

Watch AI model configurations.

## Usage

```bash
glow models watch --id <id>
```

> Wire call: `POST /model/watch`. Run `glow models watch --help` for the full flag list.

---

# CLI Reference

Route: /cli-reference

# CLI Reference

Every `glow` command, auto-generated from the CLI spec — so these pages
track the released CLI version (see
[`api-versions.json`](https://github.com/glow-academic/docs/blob/main/api-versions.json)).

Commands are grouped in the sidebar on the left: lifecycle commands like
`glow login`, `glow deploy`, and `glow status`, alongside per-resource
groups (`glow personas …`, `glow scenarios …`, and so on). Press
<kbd>⌘ K</kbd> to jump straight to a command.

See [Start](/start) for install and first-boot, and
[Authentication](/authentication) for how `glow login` stores its token.

---

# `glow parameters call download`

Route: /cli-reference/parameters/call/download

# `glow parameters call download`

Download call on Configuration parameters.

## Usage

```bash
glow parameters call download --id <id>
```

> Wire call: `POST /parameter/call_download`. Run `glow parameters call download --help` for the full flag list.

---

# `glow parameters context`

Route: /cli-reference/parameters/context

# `glow parameters context`

Context Configuration parameters.

## Usage

```bash
glow parameters context --id <id>
```

> Wire call: `POST /parameter/context`. Run `glow parameters context --help` for the full flag list.

---

# `glow parameters create`

Route: /cli-reference/parameters/create

# `glow parameters create`

Create Configuration parameters.

## Usage

```bash
glow parameters create --body '\{...\}'
```

> Wire call: `POST /parameter/create`. Run `glow parameters create --help` for the full flag list.

---

# `glow parameters csv`

Route: /cli-reference/parameters/csv

# `glow parameters csv`

Csv Configuration parameters.

## Usage

```bash
glow parameters csv --id <id>
```

> Wire call: `POST /parameter/csv`. Run `glow parameters csv --help` for the full flag list.

---

# `glow parameters delete`

Route: /cli-reference/parameters/delete

# `glow parameters delete`

Delete Configuration parameters.

## Usage

```bash
glow parameters delete --id <id>
```

> Wire call: `POST /parameter/delete`. Run `glow parameters delete --help` for the full flag list.

---

# `glow parameters draft`

Route: /cli-reference/parameters/draft

# `glow parameters draft`

Draft Configuration parameters.

## Usage

```bash
glow parameters draft --id <id>
```

> Wire call: `POST /parameter/draft`. Run `glow parameters draft --help` for the full flag list.

---

# `glow parameters drafts`

Route: /cli-reference/parameters/drafts

# `glow parameters drafts`

Drafts Configuration parameters.

## Usage

```bash
glow parameters drafts --id <id>
```

> Wire call: `POST /parameter/drafts`. Run `glow parameters drafts --help` for the full flag list.

---

# `glow parameters duplicate`

Route: /cli-reference/parameters/duplicate

# `glow parameters duplicate`

Duplicate Configuration parameters.

## Usage

```bash
glow parameters duplicate --id <id>
```

> Wire call: `POST /parameter/duplicate`. Run `glow parameters duplicate --help` for the full flag list.

---

# `glow parameters export`

Route: /cli-reference/parameters/export

# `glow parameters export`

Export Configuration parameters.

## Usage

```bash
glow parameters export --id <id>
```

> Wire call: `POST /parameter/export`. Run `glow parameters export --help` for the full flag list.

---

# `glow parameters file download`

Route: /cli-reference/parameters/file/download

# `glow parameters file download`

Download file on Configuration parameters.

## Usage

```bash
glow parameters file download --id <id>
```

> Wire call: `POST /parameter/file_download`. Run `glow parameters file download --help` for the full flag list.

---

# `glow parameters generate`

Route: /cli-reference/parameters/generate

# `glow parameters generate`

Generate Configuration parameters.

## Usage

```bash
glow parameters generate --body '\{...\}'
```

> Wire call: `POST /parameter/generate`. Run `glow parameters generate --help` for the full flag list.

---

# `glow parameters generations`

Route: /cli-reference/parameters/generations

# `glow parameters generations`

Generations Configuration parameters.

## Usage

```bash
glow parameters generations --id <id>
```

> Wire call: `POST /parameter/generations`. Run `glow parameters generations --help` for the full flag list.

---

# `glow parameters get`

Route: /cli-reference/parameters/get

# `glow parameters get`

Get Configuration parameters.

## Usage

```bash
glow parameters get --id <id>
```

> Wire call: `POST /parameter/get`. Run `glow parameters get --help` for the full flag list.

---

# `glow parameters group`

Route: /cli-reference/parameters/group

# `glow parameters group`

Group Configuration parameters.

## Usage

```bash
glow parameters group --id <id>
```

> Wire call: `POST /parameter/group`. Run `glow parameters group --help` for the full flag list.

---

# `glow parameters problem`

Route: /cli-reference/parameters/problem

# `glow parameters problem`

Problem Configuration parameters.

## Usage

```bash
glow parameters problem --id <id>
```

> Wire call: `POST /parameter/problem`. Run `glow parameters problem --help` for the full flag list.

---

# `glow parameters refresh`

Route: /cli-reference/parameters/refresh

# `glow parameters refresh`

Refresh Configuration parameters.

## Usage

```bash
glow parameters refresh --id <id>
```

> Wire call: `POST /parameter/refresh`. Run `glow parameters refresh --help` for the full flag list.

---

# `glow parameters search`

Route: /cli-reference/parameters/search

# `glow parameters search`

Search Configuration parameters.

## Usage

```bash
glow parameters search
```

> Wire call: `POST /parameter/search`. Run `glow parameters search --help` for the full flag list.

---

# `glow parameters text download`

Route: /cli-reference/parameters/text/download

# `glow parameters text download`

Download text on Configuration parameters.

## Usage

```bash
glow parameters text download --id <id>
```

> Wire call: `POST /parameter/text_download`. Run `glow parameters text download --help` for the full flag list.

---

# `glow parameters title`

Route: /cli-reference/parameters/title

# `glow parameters title`

Title Configuration parameters.

## Usage

```bash
glow parameters title --id <id>
```

> Wire call: `POST /parameter/title`. Run `glow parameters title --help` for the full flag list.

---

# `glow parameters update`

Route: /cli-reference/parameters/update

# `glow parameters update`

Update Configuration parameters.

## Usage

```bash
glow parameters update --id <id>
```

> Wire call: `POST /parameter/update`. Run `glow parameters update --help` for the full flag list.

---

# `glow parameters watch`

Route: /cli-reference/parameters/watch

# `glow parameters watch`

Watch Configuration parameters.

## Usage

```bash
glow parameters watch --id <id>
```

> Wire call: `POST /parameter/watch`. Run `glow parameters watch --help` for the full flag list.

---

# `glow personas call download`

Route: /cli-reference/personas/call/download

# `glow personas call download`

Download call on AI personas for simulation.

## Usage

```bash
glow personas call download --id <id>
```

> Wire call: `POST /persona/call_download`. Run `glow personas call download --help` for the full flag list.

---

# `glow personas context`

Route: /cli-reference/personas/context

# `glow personas context`

Context AI personas for simulation.

## Usage

```bash
glow personas context --id <id>
```

> Wire call: `POST /persona/context`. Run `glow personas context --help` for the full flag list.

---

# `glow personas create`

Route: /cli-reference/personas/create

# `glow personas create`

Create AI personas for simulation.

## Usage

```bash
glow personas create --body '\{...\}'
```

> Wire call: `POST /persona/create`. Run `glow personas create --help` for the full flag list.

---

# `glow personas csv`

Route: /cli-reference/personas/csv

# `glow personas csv`

Csv AI personas for simulation.

## Usage

```bash
glow personas csv --id <id>
```

> Wire call: `POST /persona/csv`. Run `glow personas csv --help` for the full flag list.

---

# `glow personas delete`

Route: /cli-reference/personas/delete

# `glow personas delete`

Delete AI personas for simulation.

## Usage

```bash
glow personas delete --id <id>
```

> Wire call: `POST /persona/delete`. Run `glow personas delete --help` for the full flag list.

---

# `glow personas draft`

Route: /cli-reference/personas/draft

# `glow personas draft`

Draft AI personas for simulation.

## Usage

```bash
glow personas draft --id <id>
```

> Wire call: `POST /persona/draft`. Run `glow personas draft --help` for the full flag list.

---

# `glow personas drafts`

Route: /cli-reference/personas/drafts

# `glow personas drafts`

Drafts AI personas for simulation.

## Usage

```bash
glow personas drafts --id <id>
```

> Wire call: `POST /persona/drafts`. Run `glow personas drafts --help` for the full flag list.

---

# `glow personas duplicate`

Route: /cli-reference/personas/duplicate

# `glow personas duplicate`

Duplicate AI personas for simulation.

## Usage

```bash
glow personas duplicate --id <id>
```

> Wire call: `POST /persona/duplicate`. Run `glow personas duplicate --help` for the full flag list.

---

# `glow personas export`

Route: /cli-reference/personas/export

# `glow personas export`

Export AI personas for simulation.

## Usage

```bash
glow personas export --id <id>
```

> Wire call: `POST /persona/export`. Run `glow personas export --help` for the full flag list.

---

# `glow personas file download`

Route: /cli-reference/personas/file/download

# `glow personas file download`

Download file on AI personas for simulation.

## Usage

```bash
glow personas file download --id <id>
```

> Wire call: `POST /persona/file_download`. Run `glow personas file download --help` for the full flag list.

---

# `glow personas generate`

Route: /cli-reference/personas/generate

# `glow personas generate`

Generate AI personas for simulation.

## Usage

```bash
glow personas generate --body '\{...\}'
```

> Wire call: `POST /persona/generate`. Run `glow personas generate --help` for the full flag list.

---

# `glow personas generations`

Route: /cli-reference/personas/generations

# `glow personas generations`

Generations AI personas for simulation.

## Usage

```bash
glow personas generations --id <id>
```

> Wire call: `POST /persona/generations`. Run `glow personas generations --help` for the full flag list.

---

# `glow personas get`

Route: /cli-reference/personas/get

# `glow personas get`

Get AI personas for simulation.

## Usage

```bash
glow personas get --id <id>
```

> Wire call: `POST /persona/get`. Run `glow personas get --help` for the full flag list.

---

# `glow personas group`

Route: /cli-reference/personas/group

# `glow personas group`

Group AI personas for simulation.

## Usage

```bash
glow personas group --id <id>
```

> Wire call: `POST /persona/group`. Run `glow personas group --help` for the full flag list.

---

# `glow personas problem`

Route: /cli-reference/personas/problem

# `glow personas problem`

Problem AI personas for simulation.

## Usage

```bash
glow personas problem --id <id>
```

> Wire call: `POST /persona/problem`. Run `glow personas problem --help` for the full flag list.

---

# `glow personas refresh`

Route: /cli-reference/personas/refresh

# `glow personas refresh`

Refresh AI personas for simulation.

## Usage

```bash
glow personas refresh --id <id>
```

> Wire call: `POST /persona/refresh`. Run `glow personas refresh --help` for the full flag list.

---

# `glow personas search`

Route: /cli-reference/personas/search

# `glow personas search`

Search AI personas for simulation.

## Usage

```bash
glow personas search
```

> Wire call: `POST /persona/search`. Run `glow personas search --help` for the full flag list.

---

# `glow personas text download`

Route: /cli-reference/personas/text/download

# `glow personas text download`

Download text on AI personas for simulation.

## Usage

```bash
glow personas text download --id <id>
```

> Wire call: `POST /persona/text_download`. Run `glow personas text download --help` for the full flag list.

---

# `glow personas title`

Route: /cli-reference/personas/title

# `glow personas title`

Title AI personas for simulation.

## Usage

```bash
glow personas title --id <id>
```

> Wire call: `POST /persona/title`. Run `glow personas title --help` for the full flag list.

---

# `glow personas update`

Route: /cli-reference/personas/update

# `glow personas update`

Update AI personas for simulation.

## Usage

```bash
glow personas update --id <id>
```

> Wire call: `POST /persona/update`. Run `glow personas update --help` for the full flag list.

---

# `glow personas watch`

Route: /cli-reference/personas/watch

# `glow personas watch`

Watch AI personas for simulation.

## Usage

```bash
glow personas watch --id <id>
```

> Wire call: `POST /persona/watch`. Run `glow personas watch --help` for the full flag list.

---

# `glow profiles call download`

Route: /cli-reference/profiles/call/download

# `glow profiles call download`

Download call on User profiles.

## Usage

```bash
glow profiles call download --id <id>
```

> Wire call: `POST /profile/call_download`. Run `glow profiles call download --help` for the full flag list.

---

# `glow profiles context`

Route: /cli-reference/profiles/context

# `glow profiles context`

Context User profiles.

## Usage

```bash
glow profiles context --id <id>
```

> Wire call: `POST /profile/context`. Run `glow profiles context --help` for the full flag list.

---

# `glow profiles create`

Route: /cli-reference/profiles/create

# `glow profiles create`

Create User profiles.

## Usage

```bash
glow profiles create --body '\{...\}'
```

> Wire call: `POST /profile/create`. Run `glow profiles create --help` for the full flag list.

---

# `glow profiles csv`

Route: /cli-reference/profiles/csv

# `glow profiles csv`

Csv User profiles.

## Usage

```bash
glow profiles csv --id <id>
```

> Wire call: `POST /profile/csv`. Run `glow profiles csv --help` for the full flag list.

---

# `glow profiles delete`

Route: /cli-reference/profiles/delete

# `glow profiles delete`

Delete User profiles.

## Usage

```bash
glow profiles delete --id <id>
```

> Wire call: `POST /profile/delete`. Run `glow profiles delete --help` for the full flag list.

---

# `glow profiles draft`

Route: /cli-reference/profiles/draft

# `glow profiles draft`

Draft User profiles.

## Usage

```bash
glow profiles draft --id <id>
```

> Wire call: `POST /profile/draft`. Run `glow profiles draft --help` for the full flag list.

---

# `glow profiles drafts`

Route: /cli-reference/profiles/drafts

# `glow profiles drafts`

Drafts User profiles.

## Usage

```bash
glow profiles drafts --id <id>
```

> Wire call: `POST /profile/drafts`. Run `glow profiles drafts --help` for the full flag list.

---

# `glow profiles duplicate`

Route: /cli-reference/profiles/duplicate

# `glow profiles duplicate`

Duplicate User profiles.

## Usage

```bash
glow profiles duplicate --id <id>
```

> Wire call: `POST /profile/duplicate`. Run `glow profiles duplicate --help` for the full flag list.

---

# `glow profiles emulate`

Route: /cli-reference/profiles/emulate

# `glow profiles emulate`

Emulate User profiles.

## Usage

```bash
glow profiles emulate --id <id>
```

> Wire call: `POST /profile/emulate`. Run `glow profiles emulate --help` for the full flag list.

---

# `glow profiles export`

Route: /cli-reference/profiles/export

# `glow profiles export`

Export User profiles.

## Usage

```bash
glow profiles export --id <id>
```

> Wire call: `POST /profile/export`. Run `glow profiles export --help` for the full flag list.

---

# `glow profiles file download`

Route: /cli-reference/profiles/file/download

# `glow profiles file download`

Download file on User profiles.

## Usage

```bash
glow profiles file download --id <id>
```

> Wire call: `POST /profile/file_download`. Run `glow profiles file download --help` for the full flag list.

---

# `glow profiles generate`

Route: /cli-reference/profiles/generate

# `glow profiles generate`

Generate User profiles.

## Usage

```bash
glow profiles generate --body '\{...\}'
```

> Wire call: `POST /profile/generate`. Run `glow profiles generate --help` for the full flag list.

---

# `glow profiles generations`

Route: /cli-reference/profiles/generations

# `glow profiles generations`

Generations User profiles.

## Usage

```bash
glow profiles generations --id <id>
```

> Wire call: `POST /profile/generations`. Run `glow profiles generations --help` for the full flag list.

---

# `glow profiles get`

Route: /cli-reference/profiles/get

# `glow profiles get`

Get User profiles.

## Usage

```bash
glow profiles get --id <id>
```

> Wire call: `POST /profile/get`. Run `glow profiles get --help` for the full flag list.

---

# `glow profiles group`

Route: /cli-reference/profiles/group

# `glow profiles group`

Group User profiles.

## Usage

```bash
glow profiles group --id <id>
```

> Wire call: `POST /profile/group`. Run `glow profiles group --help` for the full flag list.

---

# `glow profiles problem`

Route: /cli-reference/profiles/problem

# `glow profiles problem`

Problem User profiles.

## Usage

```bash
glow profiles problem --id <id>
```

> Wire call: `POST /profile/problem`. Run `glow profiles problem --help` for the full flag list.

---

# `glow profiles refresh`

Route: /cli-reference/profiles/refresh

# `glow profiles refresh`

Refresh User profiles.

## Usage

```bash
glow profiles refresh --id <id>
```

> Wire call: `POST /profile/refresh`. Run `glow profiles refresh --help` for the full flag list.

---

# `glow profiles search`

Route: /cli-reference/profiles/search

# `glow profiles search`

Search User profiles.

## Usage

```bash
glow profiles search
```

> Wire call: `POST /profile/search`. Run `glow profiles search --help` for the full flag list.

---

# `glow profiles text download`

Route: /cli-reference/profiles/text/download

# `glow profiles text download`

Download text on User profiles.

## Usage

```bash
glow profiles text download --id <id>
```

> Wire call: `POST /profile/text_download`. Run `glow profiles text download --help` for the full flag list.

---

# `glow profiles title`

Route: /cli-reference/profiles/title

# `glow profiles title`

Title User profiles.

## Usage

```bash
glow profiles title --id <id>
```

> Wire call: `POST /profile/title`. Run `glow profiles title --help` for the full flag list.

---

# `glow profiles unemulate`

Route: /cli-reference/profiles/unemulate

# `glow profiles unemulate`

Unemulate User profiles.

## Usage

```bash
glow profiles unemulate --id <id>
```

> Wire call: `POST /profile/unemulate`. Run `glow profiles unemulate --help` for the full flag list.

---

# `glow profiles update`

Route: /cli-reference/profiles/update

# `glow profiles update`

Update User profiles.

## Usage

```bash
glow profiles update --id <id>
```

> Wire call: `POST /profile/update`. Run `glow profiles update --help` for the full flag list.

---

# `glow profiles watch`

Route: /cli-reference/profiles/watch

# `glow profiles watch`

Watch User profiles.

## Usage

```bash
glow profiles watch --id <id>
```

> Wire call: `POST /profile/watch`. Run `glow profiles watch --help` for the full flag list.

---

# `glow providers call download`

Route: /cli-reference/providers/call/download

# `glow providers call download`

Download call on AI provider integrations.

## Usage

```bash
glow providers call download --id <id>
```

> Wire call: `POST /provider/call_download`. Run `glow providers call download --help` for the full flag list.

---

# `glow providers context`

Route: /cli-reference/providers/context

# `glow providers context`

Context AI provider integrations.

## Usage

```bash
glow providers context --id <id>
```

> Wire call: `POST /provider/context`. Run `glow providers context --help` for the full flag list.

---

# `glow providers create`

Route: /cli-reference/providers/create

# `glow providers create`

Create AI provider integrations.

## Usage

```bash
glow providers create --body '\{...\}'
```

> Wire call: `POST /provider/create`. Run `glow providers create --help` for the full flag list.

---

# `glow providers csv`

Route: /cli-reference/providers/csv

# `glow providers csv`

Csv AI provider integrations.

## Usage

```bash
glow providers csv --id <id>
```

> Wire call: `POST /provider/csv`. Run `glow providers csv --help` for the full flag list.

---

# `glow providers decrypt`

Route: /cli-reference/providers/decrypt

# `glow providers decrypt`

Decrypt AI provider integrations.

## Usage

```bash
glow providers decrypt --id <id>
```

> Wire call: `POST /provider/decrypt`. Run `glow providers decrypt --help` for the full flag list.

---

# `glow providers delete`

Route: /cli-reference/providers/delete

# `glow providers delete`

Delete AI provider integrations.

## Usage

```bash
glow providers delete --id <id>
```

> Wire call: `POST /provider/delete`. Run `glow providers delete --help` for the full flag list.

---

# `glow providers draft`

Route: /cli-reference/providers/draft

# `glow providers draft`

Draft AI provider integrations.

## Usage

```bash
glow providers draft --id <id>
```

> Wire call: `POST /provider/draft`. Run `glow providers draft --help` for the full flag list.

---

# `glow providers drafts`

Route: /cli-reference/providers/drafts

# `glow providers drafts`

Drafts AI provider integrations.

## Usage

```bash
glow providers drafts --id <id>
```

> Wire call: `POST /provider/drafts`. Run `glow providers drafts --help` for the full flag list.

---

# `glow providers duplicate`

Route: /cli-reference/providers/duplicate

# `glow providers duplicate`

Duplicate AI provider integrations.

## Usage

```bash
glow providers duplicate --id <id>
```

> Wire call: `POST /provider/duplicate`. Run `glow providers duplicate --help` for the full flag list.

---

# `glow providers export`

Route: /cli-reference/providers/export

# `glow providers export`

Export AI provider integrations.

## Usage

```bash
glow providers export --id <id>
```

> Wire call: `POST /provider/export`. Run `glow providers export --help` for the full flag list.

---

# `glow providers file download`

Route: /cli-reference/providers/file/download

# `glow providers file download`

Download file on AI provider integrations.

## Usage

```bash
glow providers file download --id <id>
```

> Wire call: `POST /provider/file_download`. Run `glow providers file download --help` for the full flag list.

---

# `glow providers generate`

Route: /cli-reference/providers/generate

# `glow providers generate`

Generate AI provider integrations.

## Usage

```bash
glow providers generate --body '\{...\}'
```

> Wire call: `POST /provider/generate`. Run `glow providers generate --help` for the full flag list.

---

# `glow providers generations`

Route: /cli-reference/providers/generations

# `glow providers generations`

Generations AI provider integrations.

## Usage

```bash
glow providers generations --id <id>
```

> Wire call: `POST /provider/generations`. Run `glow providers generations --help` for the full flag list.

---

# `glow providers get`

Route: /cli-reference/providers/get

# `glow providers get`

Get AI provider integrations.

## Usage

```bash
glow providers get --id <id>
```

> Wire call: `POST /provider/get`. Run `glow providers get --help` for the full flag list.

---

# `glow providers group`

Route: /cli-reference/providers/group

# `glow providers group`

Group AI provider integrations.

## Usage

```bash
glow providers group --id <id>
```

> Wire call: `POST /provider/group`. Run `glow providers group --help` for the full flag list.

---

# `glow providers problem`

Route: /cli-reference/providers/problem

# `glow providers problem`

Problem AI provider integrations.

## Usage

```bash
glow providers problem --id <id>
```

> Wire call: `POST /provider/problem`. Run `glow providers problem --help` for the full flag list.

---

# `glow providers refresh`

Route: /cli-reference/providers/refresh

# `glow providers refresh`

Refresh AI provider integrations.

## Usage

```bash
glow providers refresh --id <id>
```

> Wire call: `POST /provider/refresh`. Run `glow providers refresh --help` for the full flag list.

---

# `glow providers search`

Route: /cli-reference/providers/search

# `glow providers search`

Search AI provider integrations.

## Usage

```bash
glow providers search
```

> Wire call: `POST /provider/search`. Run `glow providers search --help` for the full flag list.

---

# `glow providers text download`

Route: /cli-reference/providers/text/download

# `glow providers text download`

Download text on AI provider integrations.

## Usage

```bash
glow providers text download --id <id>
```

> Wire call: `POST /provider/text_download`. Run `glow providers text download --help` for the full flag list.

---

# `glow providers title`

Route: /cli-reference/providers/title

# `glow providers title`

Title AI provider integrations.

## Usage

```bash
glow providers title --id <id>
```

> Wire call: `POST /provider/title`. Run `glow providers title --help` for the full flag list.

---

# `glow providers update`

Route: /cli-reference/providers/update

# `glow providers update`

Update AI provider integrations.

## Usage

```bash
glow providers update --id <id>
```

> Wire call: `POST /provider/update`. Run `glow providers update --help` for the full flag list.

---

# `glow providers watch`

Route: /cli-reference/providers/watch

# `glow providers watch`

Watch AI provider integrations.

## Usage

```bash
glow providers watch --id <id>
```

> Wire call: `POST /provider/watch`. Run `glow providers watch --help` for the full flag list.

---

# `glow redeploy`

Route: /cli-reference/redeploy

# `glow redeploy`

Roll out a new version while keeping the database. Auto-pre-backs up before doing anything destructive, blue/green swaps with healthcheck monitoring + auto-rollback if the new color flaps

## Usage

```bash
glow redeploy [--name] [--api-version] [--client-version] [--from-backup] [--reseed] [--grace-minutes]
```

## Options

| Flag | Required | Description |
|---|---|---|
| `--name` | No | — |
| `--api-version` | No | — |
| `--client-version` | No | Client image tag — falls back to the last-deployed version recorded in state when omitted |
| `--from-backup` | No | Restore from a named backup as part of the redeploy |
| `--reseed` | No | DESTRUCTIVE: re-run seed-gen and wipe the DB. Use with care |
| `--grace-minutes` | No | — |

---

# `glow rubrics call download`

Route: /cli-reference/rubrics/call/download

# `glow rubrics call download`

Download call on Grading rubrics.

## Usage

```bash
glow rubrics call download --id <id>
```

> Wire call: `POST /rubric/call_download`. Run `glow rubrics call download --help` for the full flag list.

---

# `glow rubrics context`

Route: /cli-reference/rubrics/context

# `glow rubrics context`

Context Grading rubrics.

## Usage

```bash
glow rubrics context --id <id>
```

> Wire call: `POST /rubric/context`. Run `glow rubrics context --help` for the full flag list.

---

# `glow rubrics create`

Route: /cli-reference/rubrics/create

# `glow rubrics create`

Create Grading rubrics.

## Usage

```bash
glow rubrics create --body '\{...\}'
```

> Wire call: `POST /rubric/create`. Run `glow rubrics create --help` for the full flag list.

---

# `glow rubrics csv`

Route: /cli-reference/rubrics/csv

# `glow rubrics csv`

Csv Grading rubrics.

## Usage

```bash
glow rubrics csv --id <id>
```

> Wire call: `POST /rubric/csv`. Run `glow rubrics csv --help` for the full flag list.

---

# `glow rubrics delete`

Route: /cli-reference/rubrics/delete

# `glow rubrics delete`

Delete Grading rubrics.

## Usage

```bash
glow rubrics delete --id <id>
```

> Wire call: `POST /rubric/delete`. Run `glow rubrics delete --help` for the full flag list.

---

# `glow rubrics draft`

Route: /cli-reference/rubrics/draft

# `glow rubrics draft`

Draft Grading rubrics.

## Usage

```bash
glow rubrics draft --id <id>
```

> Wire call: `POST /rubric/draft`. Run `glow rubrics draft --help` for the full flag list.

---

# `glow rubrics drafts`

Route: /cli-reference/rubrics/drafts

# `glow rubrics drafts`

Drafts Grading rubrics.

## Usage

```bash
glow rubrics drafts --id <id>
```

> Wire call: `POST /rubric/drafts`. Run `glow rubrics drafts --help` for the full flag list.

---

# `glow rubrics duplicate`

Route: /cli-reference/rubrics/duplicate

# `glow rubrics duplicate`

Duplicate Grading rubrics.

## Usage

```bash
glow rubrics duplicate --id <id>
```

> Wire call: `POST /rubric/duplicate`. Run `glow rubrics duplicate --help` for the full flag list.

---

# `glow rubrics export`

Route: /cli-reference/rubrics/export

# `glow rubrics export`

Export Grading rubrics.

## Usage

```bash
glow rubrics export --id <id>
```

> Wire call: `POST /rubric/export`. Run `glow rubrics export --help` for the full flag list.

---

# `glow rubrics file download`

Route: /cli-reference/rubrics/file/download

# `glow rubrics file download`

Download file on Grading rubrics.

## Usage

```bash
glow rubrics file download --id <id>
```

> Wire call: `POST /rubric/file_download`. Run `glow rubrics file download --help` for the full flag list.

---

# `glow rubrics generate`

Route: /cli-reference/rubrics/generate

# `glow rubrics generate`

Generate Grading rubrics.

## Usage

```bash
glow rubrics generate --body '\{...\}'
```

> Wire call: `POST /rubric/generate`. Run `glow rubrics generate --help` for the full flag list.

---

# `glow rubrics generations`

Route: /cli-reference/rubrics/generations

# `glow rubrics generations`

Generations Grading rubrics.

## Usage

```bash
glow rubrics generations --id <id>
```

> Wire call: `POST /rubric/generations`. Run `glow rubrics generations --help` for the full flag list.

---

# `glow rubrics get`

Route: /cli-reference/rubrics/get

# `glow rubrics get`

Get Grading rubrics.

## Usage

```bash
glow rubrics get --id <id>
```

> Wire call: `POST /rubric/get`. Run `glow rubrics get --help` for the full flag list.

---

# `glow rubrics group`

Route: /cli-reference/rubrics/group

# `glow rubrics group`

Group Grading rubrics.

## Usage

```bash
glow rubrics group --id <id>
```

> Wire call: `POST /rubric/group`. Run `glow rubrics group --help` for the full flag list.

---

# `glow rubrics problem`

Route: /cli-reference/rubrics/problem

# `glow rubrics problem`

Problem Grading rubrics.

## Usage

```bash
glow rubrics problem --id <id>
```

> Wire call: `POST /rubric/problem`. Run `glow rubrics problem --help` for the full flag list.

---

# `glow rubrics refresh`

Route: /cli-reference/rubrics/refresh

# `glow rubrics refresh`

Refresh Grading rubrics.

## Usage

```bash
glow rubrics refresh --id <id>
```

> Wire call: `POST /rubric/refresh`. Run `glow rubrics refresh --help` for the full flag list.

---

# `glow rubrics search`

Route: /cli-reference/rubrics/search

# `glow rubrics search`

Search Grading rubrics.

## Usage

```bash
glow rubrics search
```

> Wire call: `POST /rubric/search`. Run `glow rubrics search --help` for the full flag list.

---

# `glow rubrics text download`

Route: /cli-reference/rubrics/text/download

# `glow rubrics text download`

Download text on Grading rubrics.

## Usage

```bash
glow rubrics text download --id <id>
```

> Wire call: `POST /rubric/text_download`. Run `glow rubrics text download --help` for the full flag list.

---

# `glow rubrics title`

Route: /cli-reference/rubrics/title

# `glow rubrics title`

Title Grading rubrics.

## Usage

```bash
glow rubrics title --id <id>
```

> Wire call: `POST /rubric/title`. Run `glow rubrics title --help` for the full flag list.

---

# `glow rubrics update`

Route: /cli-reference/rubrics/update

# `glow rubrics update`

Update Grading rubrics.

## Usage

```bash
glow rubrics update --id <id>
```

> Wire call: `POST /rubric/update`. Run `glow rubrics update --help` for the full flag list.

---

# `glow rubrics watch`

Route: /cli-reference/rubrics/watch

# `glow rubrics watch`

Watch Grading rubrics.

## Usage

```bash
glow rubrics watch --id <id>
```

> Wire call: `POST /rubric/watch`. Run `glow rubrics watch --help` for the full flag list.

---

# `glow scenarios call download`

Route: /cli-reference/scenarios/call/download

# `glow scenarios call download`

Download call on Simulation scenarios.

## Usage

```bash
glow scenarios call download --id <id>
```

> Wire call: `POST /scenario/call_download`. Run `glow scenarios call download --help` for the full flag list.

---

# `glow scenarios context`

Route: /cli-reference/scenarios/context

# `glow scenarios context`

Context Simulation scenarios.

## Usage

```bash
glow scenarios context --id <id>
```

> Wire call: `POST /scenario/context`. Run `glow scenarios context --help` for the full flag list.

---

# `glow scenarios create`

Route: /cli-reference/scenarios/create

# `glow scenarios create`

Create Simulation scenarios.

## Usage

```bash
glow scenarios create --body '\{...\}'
```

> Wire call: `POST /scenario/create`. Run `glow scenarios create --help` for the full flag list.

---

# `glow scenarios csv`

Route: /cli-reference/scenarios/csv

# `glow scenarios csv`

Csv Simulation scenarios.

## Usage

```bash
glow scenarios csv --id <id>
```

> Wire call: `POST /scenario/csv`. Run `glow scenarios csv --help` for the full flag list.

---

# `glow scenarios delete`

Route: /cli-reference/scenarios/delete

# `glow scenarios delete`

Delete Simulation scenarios.

## Usage

```bash
glow scenarios delete --id <id>
```

> Wire call: `POST /scenario/delete`. Run `glow scenarios delete --help` for the full flag list.

---

# `glow scenarios draft`

Route: /cli-reference/scenarios/draft

# `glow scenarios draft`

Draft Simulation scenarios.

## Usage

```bash
glow scenarios draft --id <id>
```

> Wire call: `POST /scenario/draft`. Run `glow scenarios draft --help` for the full flag list.

---

# `glow scenarios drafts`

Route: /cli-reference/scenarios/drafts

# `glow scenarios drafts`

Drafts Simulation scenarios.

## Usage

```bash
glow scenarios drafts --id <id>
```

> Wire call: `POST /scenario/drafts`. Run `glow scenarios drafts --help` for the full flag list.

---

# `glow scenarios duplicate`

Route: /cli-reference/scenarios/duplicate

# `glow scenarios duplicate`

Duplicate Simulation scenarios.

## Usage

```bash
glow scenarios duplicate --id <id>
```

> Wire call: `POST /scenario/duplicate`. Run `glow scenarios duplicate --help` for the full flag list.

---

# `glow scenarios export`

Route: /cli-reference/scenarios/export

# `glow scenarios export`

Export Simulation scenarios.

## Usage

```bash
glow scenarios export --id <id>
```

> Wire call: `POST /scenario/export`. Run `glow scenarios export --help` for the full flag list.

---

# `glow scenarios file download`

Route: /cli-reference/scenarios/file/download

# `glow scenarios file download`

Download file on Simulation scenarios.

## Usage

```bash
glow scenarios file download --id <id>
```

> Wire call: `POST /scenario/file_download`. Run `glow scenarios file download --help` for the full flag list.

---

# `glow scenarios file preview`

Route: /cli-reference/scenarios/file/preview

# `glow scenarios file preview`

Preview file on Simulation scenarios.

## Usage

```bash
glow scenarios file preview --id <id>
```

> Wire call: `POST /scenario/file_preview`. Run `glow scenarios file preview --help` for the full flag list.

---

# `glow scenarios generate`

Route: /cli-reference/scenarios/generate

# `glow scenarios generate`

Generate Simulation scenarios.

## Usage

```bash
glow scenarios generate --body '\{...\}'
```

> Wire call: `POST /scenario/generate`. Run `glow scenarios generate --help` for the full flag list.

---

# `glow scenarios generations`

Route: /cli-reference/scenarios/generations

# `glow scenarios generations`

Generations Simulation scenarios.

## Usage

```bash
glow scenarios generations --id <id>
```

> Wire call: `POST /scenario/generations`. Run `glow scenarios generations --help` for the full flag list.

---

# `glow scenarios get`

Route: /cli-reference/scenarios/get

# `glow scenarios get`

Get Simulation scenarios.

## Usage

```bash
glow scenarios get --id <id>
```

> Wire call: `POST /scenario/get`. Run `glow scenarios get --help` for the full flag list.

---

# `glow scenarios group`

Route: /cli-reference/scenarios/group

# `glow scenarios group`

Group Simulation scenarios.

## Usage

```bash
glow scenarios group --id <id>
```

> Wire call: `POST /scenario/group`. Run `glow scenarios group --help` for the full flag list.

---

# `glow scenarios image download`

Route: /cli-reference/scenarios/image/download

# `glow scenarios image download`

Download image on Simulation scenarios.

## Usage

```bash
glow scenarios image download --id <id>
```

> Wire call: `POST /scenario/image_download`. Run `glow scenarios image download --help` for the full flag list.

---

# `glow scenarios image upload`

Route: /cli-reference/scenarios/image/upload

# `glow scenarios image upload`

Upload image on Simulation scenarios.

## Usage

```bash
glow scenarios image upload --body '\{...\}'
```

> Wire call: `POST /scenario/image_upload`. Run `glow scenarios image upload --help` for the full flag list.

---

# `glow scenarios problem`

Route: /cli-reference/scenarios/problem

# `glow scenarios problem`

Problem Simulation scenarios.

## Usage

```bash
glow scenarios problem --id <id>
```

> Wire call: `POST /scenario/problem`. Run `glow scenarios problem --help` for the full flag list.

---

# `glow scenarios refresh`

Route: /cli-reference/scenarios/refresh

# `glow scenarios refresh`

Refresh Simulation scenarios.

## Usage

```bash
glow scenarios refresh --id <id>
```

> Wire call: `POST /scenario/refresh`. Run `glow scenarios refresh --help` for the full flag list.

---

# `glow scenarios search`

Route: /cli-reference/scenarios/search

# `glow scenarios search`

Search Simulation scenarios.

## Usage

```bash
glow scenarios search
```

> Wire call: `POST /scenario/search`. Run `glow scenarios search --help` for the full flag list.

---

# `glow scenarios text download`

Route: /cli-reference/scenarios/text/download

# `glow scenarios text download`

Download text on Simulation scenarios.

## Usage

```bash
glow scenarios text download --id <id>
```

> Wire call: `POST /scenario/text_download`. Run `glow scenarios text download --help` for the full flag list.

---

# `glow scenarios title`

Route: /cli-reference/scenarios/title

# `glow scenarios title`

Title Simulation scenarios.

## Usage

```bash
glow scenarios title --id <id>
```

> Wire call: `POST /scenario/title`. Run `glow scenarios title --help` for the full flag list.

---

# `glow scenarios update`

Route: /cli-reference/scenarios/update

# `glow scenarios update`

Update Simulation scenarios.

## Usage

```bash
glow scenarios update --id <id>
```

> Wire call: `POST /scenario/update`. Run `glow scenarios update --help` for the full flag list.

---

# `glow scenarios video download`

Route: /cli-reference/scenarios/video/download

# `glow scenarios video download`

Download video on Simulation scenarios.

## Usage

```bash
glow scenarios video download --id <id>
```

> Wire call: `POST /scenario/video_download`. Run `glow scenarios video download --help` for the full flag list.

---

# `glow scenarios video upload`

Route: /cli-reference/scenarios/video/upload

# `glow scenarios video upload`

Upload video on Simulation scenarios.

## Usage

```bash
glow scenarios video upload --body '\{...\}'
```

> Wire call: `POST /scenario/video_upload`. Run `glow scenarios video upload --help` for the full flag list.

---

# `glow scenarios watch`

Route: /cli-reference/scenarios/watch

# `glow scenarios watch`

Watch Simulation scenarios.

## Usage

```bash
glow scenarios watch --id <id>
```

> Wire call: `POST /scenario/watch`. Run `glow scenarios watch --help` for the full flag list.

---

# `glow settings call download`

Route: /cli-reference/settings/call/download

# `glow settings call download`

Download call on Instance settings.

## Usage

```bash
glow settings call download --id <id>
```

> Wire call: `POST /setting/call_download`. Run `glow settings call download --help` for the full flag list.

---

# `glow settings context`

Route: /cli-reference/settings/context

# `glow settings context`

Context Instance settings.

## Usage

```bash
glow settings context --id <id>
```

> Wire call: `POST /setting/context`. Run `glow settings context --help` for the full flag list.

---

# `glow settings create`

Route: /cli-reference/settings/create

# `glow settings create`

Create Instance settings.

## Usage

```bash
glow settings create --body '\{...\}'
```

> Wire call: `POST /setting/create`. Run `glow settings create --help` for the full flag list.

---

# `glow settings csv`

Route: /cli-reference/settings/csv

# `glow settings csv`

Csv Instance settings.

## Usage

```bash
glow settings csv --id <id>
```

> Wire call: `POST /setting/csv`. Run `glow settings csv --help` for the full flag list.

---

# `glow settings decrypt`

Route: /cli-reference/settings/decrypt

# `glow settings decrypt`

Decrypt Instance settings.

## Usage

```bash
glow settings decrypt --id <id>
```

> Wire call: `POST /setting/decrypt`. Run `glow settings decrypt --help` for the full flag list.

---

# `glow settings delete`

Route: /cli-reference/settings/delete

# `glow settings delete`

Delete Instance settings.

## Usage

```bash
glow settings delete --id <id>
```

> Wire call: `POST /setting/delete`. Run `glow settings delete --help` for the full flag list.

---

# `glow settings draft`

Route: /cli-reference/settings/draft

# `glow settings draft`

Draft Instance settings.

## Usage

```bash
glow settings draft --id <id>
```

> Wire call: `POST /setting/draft`. Run `glow settings draft --help` for the full flag list.

---

# `glow settings drafts`

Route: /cli-reference/settings/drafts

# `glow settings drafts`

Drafts Instance settings.

## Usage

```bash
glow settings drafts --id <id>
```

> Wire call: `POST /setting/drafts`. Run `glow settings drafts --help` for the full flag list.

---

# `glow settings duplicate`

Route: /cli-reference/settings/duplicate

# `glow settings duplicate`

Duplicate Instance settings.

## Usage

```bash
glow settings duplicate --id <id>
```

> Wire call: `POST /setting/duplicate`. Run `glow settings duplicate --help` for the full flag list.

---

# `glow settings export`

Route: /cli-reference/settings/export

# `glow settings export`

Export Instance settings.

## Usage

```bash
glow settings export --id <id>
```

> Wire call: `POST /setting/export`. Run `glow settings export --help` for the full flag list.

---

# `glow settings file download`

Route: /cli-reference/settings/file/download

# `glow settings file download`

Download file on Instance settings.

## Usage

```bash
glow settings file download --id <id>
```

> Wire call: `POST /setting/file_download`. Run `glow settings file download --help` for the full flag list.

---

# `glow settings generate`

Route: /cli-reference/settings/generate

# `glow settings generate`

Generate Instance settings.

## Usage

```bash
glow settings generate --body '\{...\}'
```

> Wire call: `POST /setting/generate`. Run `glow settings generate --help` for the full flag list.

---

# `glow settings generations`

Route: /cli-reference/settings/generations

# `glow settings generations`

Generations Instance settings.

## Usage

```bash
glow settings generations --id <id>
```

> Wire call: `POST /setting/generations`. Run `glow settings generations --help` for the full flag list.

---

# `glow settings get`

Route: /cli-reference/settings/get

# `glow settings get`

Get Instance settings.

## Usage

```bash
glow settings get --id <id>
```

> Wire call: `POST /setting/get`. Run `glow settings get --help` for the full flag list.

---

# `glow settings group`

Route: /cli-reference/settings/group

# `glow settings group`

Group Instance settings.

## Usage

```bash
glow settings group --id <id>
```

> Wire call: `POST /setting/group`. Run `glow settings group --help` for the full flag list.

---

# `glow settings problem`

Route: /cli-reference/settings/problem

# `glow settings problem`

Problem Instance settings.

## Usage

```bash
glow settings problem --id <id>
```

> Wire call: `POST /setting/problem`. Run `glow settings problem --help` for the full flag list.

---

# `glow settings refresh`

Route: /cli-reference/settings/refresh

# `glow settings refresh`

Refresh Instance settings.

## Usage

```bash
glow settings refresh --id <id>
```

> Wire call: `POST /setting/refresh`. Run `glow settings refresh --help` for the full flag list.

---

# `glow settings search`

Route: /cli-reference/settings/search

# `glow settings search`

Search Instance settings.

## Usage

```bash
glow settings search
```

> Wire call: `POST /setting/search`. Run `glow settings search --help` for the full flag list.

---

# `glow settings text download`

Route: /cli-reference/settings/text/download

# `glow settings text download`

Download text on Instance settings.

## Usage

```bash
glow settings text download --id <id>
```

> Wire call: `POST /setting/text_download`. Run `glow settings text download --help` for the full flag list.

---

# `glow settings title`

Route: /cli-reference/settings/title

# `glow settings title`

Title Instance settings.

## Usage

```bash
glow settings title --id <id>
```

> Wire call: `POST /setting/title`. Run `glow settings title --help` for the full flag list.

---

# `glow settings update`

Route: /cli-reference/settings/update

# `glow settings update`

Update Instance settings.

## Usage

```bash
glow settings update --id <id>
```

> Wire call: `POST /setting/update`. Run `glow settings update --help` for the full flag list.

---

# `glow settings watch`

Route: /cli-reference/settings/watch

# `glow settings watch`

Watch Instance settings.

## Usage

```bash
glow settings watch --id <id>
```

> Wire call: `POST /setting/watch`. Run `glow settings watch --help` for the full flag list.

---

# `glow simulations call download`

Route: /cli-reference/simulations/call/download

# `glow simulations call download`

Download call on Simulation configurations.

## Usage

```bash
glow simulations call download --id <id>
```

> Wire call: `POST /simulation/call_download`. Run `glow simulations call download --help` for the full flag list.

---

# `glow simulations context`

Route: /cli-reference/simulations/context

# `glow simulations context`

Context Simulation configurations.

## Usage

```bash
glow simulations context --id <id>
```

> Wire call: `POST /simulation/context`. Run `glow simulations context --help` for the full flag list.

---

# `glow simulations create`

Route: /cli-reference/simulations/create

# `glow simulations create`

Create Simulation configurations.

## Usage

```bash
glow simulations create --body '\{...\}'
```

> Wire call: `POST /simulation/create`. Run `glow simulations create --help` for the full flag list.

---

# `glow simulations csv`

Route: /cli-reference/simulations/csv

# `glow simulations csv`

Csv Simulation configurations.

## Usage

```bash
glow simulations csv --id <id>
```

> Wire call: `POST /simulation/csv`. Run `glow simulations csv --help` for the full flag list.

---

# `glow simulations delete`

Route: /cli-reference/simulations/delete

# `glow simulations delete`

Delete Simulation configurations.

## Usage

```bash
glow simulations delete --id <id>
```

> Wire call: `POST /simulation/delete`. Run `glow simulations delete --help` for the full flag list.

---

# `glow simulations draft`

Route: /cli-reference/simulations/draft

# `glow simulations draft`

Draft Simulation configurations.

## Usage

```bash
glow simulations draft --id <id>
```

> Wire call: `POST /simulation/draft`. Run `glow simulations draft --help` for the full flag list.

---

# `glow simulations drafts`

Route: /cli-reference/simulations/drafts

# `glow simulations drafts`

Drafts Simulation configurations.

## Usage

```bash
glow simulations drafts --id <id>
```

> Wire call: `POST /simulation/drafts`. Run `glow simulations drafts --help` for the full flag list.

---

# `glow simulations duplicate`

Route: /cli-reference/simulations/duplicate

# `glow simulations duplicate`

Duplicate Simulation configurations.

## Usage

```bash
glow simulations duplicate --id <id>
```

> Wire call: `POST /simulation/duplicate`. Run `glow simulations duplicate --help` for the full flag list.

---

# `glow simulations export`

Route: /cli-reference/simulations/export

# `glow simulations export`

Export Simulation configurations.

## Usage

```bash
glow simulations export --id <id>
```

> Wire call: `POST /simulation/export`. Run `glow simulations export --help` for the full flag list.

---

# `glow simulations file download`

Route: /cli-reference/simulations/file/download

# `glow simulations file download`

Download file on Simulation configurations.

## Usage

```bash
glow simulations file download --id <id>
```

> Wire call: `POST /simulation/file_download`. Run `glow simulations file download --help` for the full flag list.

---

# `glow simulations generate`

Route: /cli-reference/simulations/generate

# `glow simulations generate`

Generate Simulation configurations.

## Usage

```bash
glow simulations generate --body '\{...\}'
```

> Wire call: `POST /simulation/generate`. Run `glow simulations generate --help` for the full flag list.

---

# `glow simulations generations`

Route: /cli-reference/simulations/generations

# `glow simulations generations`

Generations Simulation configurations.

## Usage

```bash
glow simulations generations --id <id>
```

> Wire call: `POST /simulation/generations`. Run `glow simulations generations --help` for the full flag list.

---

# `glow simulations get`

Route: /cli-reference/simulations/get

# `glow simulations get`

Get Simulation configurations.

## Usage

```bash
glow simulations get --id <id>
```

> Wire call: `POST /simulation/get`. Run `glow simulations get --help` for the full flag list.

---

# `glow simulations group`

Route: /cli-reference/simulations/group

# `glow simulations group`

Group Simulation configurations.

## Usage

```bash
glow simulations group --id <id>
```

> Wire call: `POST /simulation/group`. Run `glow simulations group --help` for the full flag list.

---

# `glow simulations problem`

Route: /cli-reference/simulations/problem

# `glow simulations problem`

Problem Simulation configurations.

## Usage

```bash
glow simulations problem --id <id>
```

> Wire call: `POST /simulation/problem`. Run `glow simulations problem --help` for the full flag list.

---

# `glow simulations refresh`

Route: /cli-reference/simulations/refresh

# `glow simulations refresh`

Refresh Simulation configurations.

## Usage

```bash
glow simulations refresh --id <id>
```

> Wire call: `POST /simulation/refresh`. Run `glow simulations refresh --help` for the full flag list.

---

# `glow simulations search`

Route: /cli-reference/simulations/search

# `glow simulations search`

Search Simulation configurations.

## Usage

```bash
glow simulations search
```

> Wire call: `POST /simulation/search`. Run `glow simulations search --help` for the full flag list.

---

# `glow simulations text download`

Route: /cli-reference/simulations/text/download

# `glow simulations text download`

Download text on Simulation configurations.

## Usage

```bash
glow simulations text download --id <id>
```

> Wire call: `POST /simulation/text_download`. Run `glow simulations text download --help` for the full flag list.

---

# `glow simulations title`

Route: /cli-reference/simulations/title

# `glow simulations title`

Title Simulation configurations.

## Usage

```bash
glow simulations title --id <id>
```

> Wire call: `POST /simulation/title`. Run `glow simulations title --help` for the full flag list.

---

# `glow simulations update`

Route: /cli-reference/simulations/update

# `glow simulations update`

Update Simulation configurations.

## Usage

```bash
glow simulations update --id <id>
```

> Wire call: `POST /simulation/update`. Run `glow simulations update --help` for the full flag list.

---

# `glow simulations watch`

Route: /cli-reference/simulations/watch

# `glow simulations watch`

Watch Simulation configurations.

## Usage

```bash
glow simulations watch --id <id>
```

> Wire call: `POST /simulation/watch`. Run `glow simulations watch --help` for the full flag list.

---

# `glow start`

Route: /cli-reference/start

# `glow start`

Resume previously-stopped containers

## Usage

```bash
glow start [--name]
```

## Options

| Flag | Required | Description |
|---|---|---|
| `--name` | No | — |

---

# `glow status`

Route: /cli-reference/status

# `glow status`

Show instance state + per-container health

## Usage

```bash
glow status [--name]
```

## Options

| Flag | Required | Description |
|---|---|---|
| `--name` | No | — |

---

# `glow stop`

Route: /cli-reference/stop

# `glow stop`

Stop containers; volumes + network intact. `glow start` resumes

## Usage

```bash
glow stop [--name]
```

## Options

| Flag | Required | Description |
|---|---|---|
| `--name` | No | — |

---

# `glow system activity get`

Route: /cli-reference/system/activity/get

# `glow system activity get`

Get on activity (under system).

## Usage

```bash
glow system activity get --id <id>
```

> Wire call: `POST /system/activity`. Run `glow system activity get --help` for the full flag list.

---

# `glow system audio download`

Route: /cli-reference/system/audio/download

# `glow system audio download`

Download audio on system.

## Usage

```bash
glow system audio download --id <id>
```

> Wire call: `POST /system/audio_download`. Run `glow system audio download --help` for the full flag list.

---

# `glow system call download`

Route: /cli-reference/system/call/download

# `glow system call download`

Download call on system.

## Usage

```bash
glow system call download --id <id>
```

> Wire call: `POST /system/call_download`. Run `glow system call download --help` for the full flag list.

---

# `glow system context`

Route: /cli-reference/system/context

# `glow system context`

Context on system.

## Usage

```bash
glow system context --id <id>
```

> Wire call: `POST /system/context`. Run `glow system context --help` for the full flag list.

---

# `glow system export`

Route: /cli-reference/system/export

# `glow system export`

Export on system.

## Usage

```bash
glow system export --id <id>
```

> Wire call: `POST /system/export`. Run `glow system export --help` for the full flag list.

---

# `glow system file download`

Route: /cli-reference/system/file/download

# `glow system file download`

Download file on system.

## Usage

```bash
glow system file download --id <id>
```

> Wire call: `POST /system/file_download`. Run `glow system file download --help` for the full flag list.

---

# `glow system file preview`

Route: /cli-reference/system/file/preview

# `glow system file preview`

Preview file on system.

## Usage

```bash
glow system file preview --id <id>
```

> Wire call: `POST /system/file_preview`. Run `glow system file preview --help` for the full flag list.

---

# `glow system generate`

Route: /cli-reference/system/generate

# `glow system generate`

Generate on system.

## Usage

```bash
glow system generate --body '\{...\}'
```

> Wire call: `POST /system/generate`. Run `glow system generate --help` for the full flag list.

---

# `glow system generations`

Route: /cli-reference/system/generations

# `glow system generations`

Generations on system.

## Usage

```bash
glow system generations --id <id>
```

> Wire call: `POST /system/generations`. Run `glow system generations --help` for the full flag list.

---

# `glow system group get`

Route: /cli-reference/system/group/get

# `glow system group get`

Get on group (under system).

## Usage

```bash
glow system group get --id <id>
```

> Wire call: `POST /system/group`. Run `glow system group get --help` for the full flag list.

---

# `glow system group`

Route: /cli-reference/system/group

# `glow system group`

Group on system.

## Usage

```bash
glow system group --id <id>
```

> Wire call: `POST /system/group`. Run `glow system group --help` for the full flag list.

---

# `glow system health get`

Route: /cli-reference/system/health/get

# `glow system health get`

Get on health (under system).

## Usage

```bash
glow system health get --id <id>
```

> Wire call: `POST /system/health`. Run `glow system health get --help` for the full flag list.

---

# `glow system image download`

Route: /cli-reference/system/image/download

# `glow system image download`

Download image on system.

## Usage

```bash
glow system image download --id <id>
```

> Wire call: `POST /system/image_download`. Run `glow system image download --help` for the full flag list.

---

# `glow system pricing get`

Route: /cli-reference/system/pricing/get

# `glow system pricing get`

Get on pricing (under system).

## Usage

```bash
glow system pricing get --id <id>
```

> Wire call: `POST /system/pricing`. Run `glow system pricing get --help` for the full flag list.

---

# `glow system problem`

Route: /cli-reference/system/problem

# `glow system problem`

Problem on system.

## Usage

```bash
glow system problem --id <id>
```

> Wire call: `POST /system/problem`. Run `glow system problem --help` for the full flag list.

---

# `glow system refresh`

Route: /cli-reference/system/refresh

# `glow system refresh`

Refresh on system.

## Usage

```bash
glow system refresh --id <id>
```

> Wire call: `POST /system/refresh`. Run `glow system refresh --help` for the full flag list.

---

# `glow system resolve`

Route: /cli-reference/system/resolve

# `glow system resolve`

Resolve on system.

## Usage

```bash
glow system resolve --id <id>
```

> Wire call: `POST /system/resolve`. Run `glow system resolve --help` for the full flag list.

---

# `glow system session get`

Route: /cli-reference/system/session/get

# `glow system session get`

Get on session (under system).

## Usage

```bash
glow system session get --id <id>
```

> Wire call: `POST /system/session`. Run `glow system session get --help` for the full flag list.

---

# `glow system text download`

Route: /cli-reference/system/text/download

# `glow system text download`

Download text on system.

## Usage

```bash
glow system text download --id <id>
```

> Wire call: `POST /system/text_download`. Run `glow system text download --help` for the full flag list.

---

# `glow system title`

Route: /cli-reference/system/title

# `glow system title`

Title on system.

## Usage

```bash
glow system title --id <id>
```

> Wire call: `POST /system/title`. Run `glow system title --help` for the full flag list.

---

# `glow system video download`

Route: /cli-reference/system/video/download

# `glow system video download`

Download video on system.

## Usage

```bash
glow system video download --id <id>
```

> Wire call: `POST /system/video_download`. Run `glow system video download --help` for the full flag list.

---

# `glow system watch`

Route: /cli-reference/system/watch

# `glow system watch`

Watch on system.

## Usage

```bash
glow system watch --id <id>
```

> Wire call: `POST /system/watch`. Run `glow system watch --help` for the full flag list.

---

# `glow tests archive`

Route: /cli-reference/tests/archive

# `glow tests archive`

Archive on tests.

## Usage

```bash
glow tests archive --id <id>
```

> Wire call: `POST /test/archive`. Run `glow tests archive --help` for the full flag list.

---

# `glow tests benchmark get`

Route: /cli-reference/tests/benchmark/get

# `glow tests benchmark get`

Get on benchmark (under tests).

## Usage

```bash
glow tests benchmark get --id <id>
```

> Wire call: `POST /test/benchmark`. Run `glow tests benchmark get --help` for the full flag list.

---

# `glow tests call download`

Route: /cli-reference/tests/call/download

# `glow tests call download`

Download call on tests.

## Usage

```bash
glow tests call download --id <id>
```

> Wire call: `POST /test/call_download`. Run `glow tests call download --help` for the full flag list.

---

# `glow tests complete`

Route: /cli-reference/tests/complete

# `glow tests complete`

Complete on tests.

## Usage

```bash
glow tests complete --id <id>
```

> Wire call: `POST /test/complete`. Run `glow tests complete --help` for the full flag list.

---

# `glow tests context`

Route: /cli-reference/tests/context

# `glow tests context`

Context on tests.

## Usage

```bash
glow tests context --id <id>
```

> Wire call: `POST /test/context`. Run `glow tests context --help` for the full flag list.

---

# `glow tests draft`

Route: /cli-reference/tests/draft

# `glow tests draft`

Draft on tests.

## Usage

```bash
glow tests draft --id <id>
```

> Wire call: `POST /test/draft`. Run `glow tests draft --help` for the full flag list.

---

# `glow tests drafts`

Route: /cli-reference/tests/drafts

# `glow tests drafts`

Drafts on tests.

## Usage

```bash
glow tests drafts --id <id>
```

> Wire call: `POST /test/drafts`. Run `glow tests drafts --help` for the full flag list.

---

# `glow tests export`

Route: /cli-reference/tests/export

# `glow tests export`

Export on tests.

## Usage

```bash
glow tests export --id <id>
```

> Wire call: `POST /test/export`. Run `glow tests export --help` for the full flag list.

---

# `glow tests feedback`

Route: /cli-reference/tests/feedback

# `glow tests feedback`

Feedback on tests.

## Usage

```bash
glow tests feedback --id <id>
```

> Wire call: `POST /test/feedback`. Run `glow tests feedback --help` for the full flag list.

---

# `glow tests file download`

Route: /cli-reference/tests/file/download

# `glow tests file download`

Download file on tests.

## Usage

```bash
glow tests file download --id <id>
```

> Wire call: `POST /test/file_download`. Run `glow tests file download --help` for the full flag list.

---

# `glow tests generate`

Route: /cli-reference/tests/generate

# `glow tests generate`

Generate on tests.

## Usage

```bash
glow tests generate --body '\{...\}'
```

> Wire call: `POST /test/generate`. Run `glow tests generate --help` for the full flag list.

---

# `glow tests generations`

Route: /cli-reference/tests/generations

# `glow tests generations`

Generations on tests.

## Usage

```bash
glow tests generations --id <id>
```

> Wire call: `POST /test/generations`. Run `glow tests generations --help` for the full flag list.

---

# `glow tests get`

Route: /cli-reference/tests/get

# `glow tests get`

Get on tests.

## Usage

```bash
glow tests get --id <id>
```

> Wire call: `POST /test/get`. Run `glow tests get --help` for the full flag list.

---

# `glow tests grade`

Route: /cli-reference/tests/grade

# `glow tests grade`

Grade on tests.

## Usage

```bash
glow tests grade --id <id>
```

> Wire call: `POST /test/grade`. Run `glow tests grade --help` for the full flag list.

---

# `glow tests group`

Route: /cli-reference/tests/group

# `glow tests group`

Group on tests.

## Usage

```bash
glow tests group --id <id>
```

> Wire call: `POST /test/group`. Run `glow tests group --help` for the full flag list.

---

# `glow tests invocation complete`

Route: /cli-reference/tests/invocation/complete

# `glow tests invocation complete`

Complete on invocation (under tests).

## Usage

```bash
glow tests invocation complete --id <id>
```

> Wire call: `POST /test/invocation_complete`. Run `glow tests invocation complete --help` for the full flag list.

---

# `glow tests invocation create`

Route: /cli-reference/tests/invocation/create

# `glow tests invocation create`

Create on invocation (under tests).

## Usage

```bash
glow tests invocation create --body '\{...\}'
```

> Wire call: `POST /test/invocation_create`. Run `glow tests invocation create --help` for the full flag list.

---

# `glow tests invocation get`

Route: /cli-reference/tests/invocation/get

# `glow tests invocation get`

Get on invocation (under tests).

## Usage

```bash
glow tests invocation get --id <id>
```

> Wire call: `POST /test/invocation_get`. Run `glow tests invocation get --help` for the full flag list.

---

# `glow tests invocation run`

Route: /cli-reference/tests/invocation/run

# `glow tests invocation run`

Run on invocation (under tests).

## Usage

```bash
glow tests invocation run --id <id>
```

> Wire call: `POST /test/invocation_run`. Run `glow tests invocation run --help` for the full flag list.

---

# `glow tests invocation terminate`

Route: /cli-reference/tests/invocation/terminate

# `glow tests invocation terminate`

Terminate on invocation (under tests).

## Usage

```bash
glow tests invocation terminate --id <id>
```

> Wire call: `POST /test/invocation_terminate`. Run `glow tests invocation terminate --help` for the full flag list.

---

# `glow tests invocation trace`

Route: /cli-reference/tests/invocation/trace

# `glow tests invocation trace`

Trace on invocation (under tests).

## Usage

```bash
glow tests invocation trace --id <id>
```

> Wire call: `POST /test/invocation_trace`. Run `glow tests invocation trace --help` for the full flag list.

---

# `glow tests problem`

Route: /cli-reference/tests/problem

# `glow tests problem`

Problem on tests.

## Usage

```bash
glow tests problem --id <id>
```

> Wire call: `POST /test/problem`. Run `glow tests problem --help` for the full flag list.

---

# `glow tests refresh`

Route: /cli-reference/tests/refresh

# `glow tests refresh`

Refresh on tests.

## Usage

```bash
glow tests refresh --id <id>
```

> Wire call: `POST /test/refresh`. Run `glow tests refresh --help` for the full flag list.

---

# `glow tests search`

Route: /cli-reference/tests/search

# `glow tests search`

Search on tests.

## Usage

```bash
glow tests search
```

> Wire call: `POST /test/search`. Run `glow tests search --help` for the full flag list.

---

# `glow tests start`

Route: /cli-reference/tests/start

# `glow tests start`

Start on tests.

## Usage

```bash
glow tests start --id <id>
```

> Wire call: `POST /test/start`. Run `glow tests start --help` for the full flag list.

---

# `glow tests stop`

Route: /cli-reference/tests/stop

# `glow tests stop`

Stop on tests.

## Usage

```bash
glow tests stop --id <id>
```

> Wire call: `POST /test/stop`. Run `glow tests stop --help` for the full flag list.

---

# `glow tests text download`

Route: /cli-reference/tests/text/download

# `glow tests text download`

Download text on tests.

## Usage

```bash
glow tests text download --id <id>
```

> Wire call: `POST /test/text_download`. Run `glow tests text download --help` for the full flag list.

---

# `glow tests title`

Route: /cli-reference/tests/title

# `glow tests title`

Title on tests.

## Usage

```bash
glow tests title --id <id>
```

> Wire call: `POST /test/title`. Run `glow tests title --help` for the full flag list.

---

# `glow tests watch`

Route: /cli-reference/tests/watch

# `glow tests watch`

Watch on tests.

## Usage

```bash
glow tests watch --id <id>
```

> Wire call: `POST /test/watch`. Run `glow tests watch --help` for the full flag list.

---

# `glow tools call download`

Route: /cli-reference/tools/call/download

# `glow tools call download`

Download call on Tool integrations.

## Usage

```bash
glow tools call download --id <id>
```

> Wire call: `POST /tool/call_download`. Run `glow tools call download --help` for the full flag list.

---

# `glow tools context`

Route: /cli-reference/tools/context

# `glow tools context`

Context Tool integrations.

## Usage

```bash
glow tools context --id <id>
```

> Wire call: `POST /tool/context`. Run `glow tools context --help` for the full flag list.

---

# `glow tools create`

Route: /cli-reference/tools/create

# `glow tools create`

Create Tool integrations.

## Usage

```bash
glow tools create --body '\{...\}'
```

> Wire call: `POST /tool/create`. Run `glow tools create --help` for the full flag list.

---

# `glow tools csv`

Route: /cli-reference/tools/csv

# `glow tools csv`

Csv Tool integrations.

## Usage

```bash
glow tools csv --id <id>
```

> Wire call: `POST /tool/csv`. Run `glow tools csv --help` for the full flag list.

---

# `glow tools delete`

Route: /cli-reference/tools/delete

# `glow tools delete`

Delete Tool integrations.

## Usage

```bash
glow tools delete --id <id>
```

> Wire call: `POST /tool/delete`. Run `glow tools delete --help` for the full flag list.

---

# `glow tools draft`

Route: /cli-reference/tools/draft

# `glow tools draft`

Draft Tool integrations.

## Usage

```bash
glow tools draft --id <id>
```

> Wire call: `POST /tool/draft`. Run `glow tools draft --help` for the full flag list.

---

# `glow tools drafts`

Route: /cli-reference/tools/drafts

# `glow tools drafts`

Drafts Tool integrations.

## Usage

```bash
glow tools drafts --id <id>
```

> Wire call: `POST /tool/drafts`. Run `glow tools drafts --help` for the full flag list.

---

# `glow tools duplicate`

Route: /cli-reference/tools/duplicate

# `glow tools duplicate`

Duplicate Tool integrations.

## Usage

```bash
glow tools duplicate --id <id>
```

> Wire call: `POST /tool/duplicate`. Run `glow tools duplicate --help` for the full flag list.

---

# `glow tools export`

Route: /cli-reference/tools/export

# `glow tools export`

Export Tool integrations.

## Usage

```bash
glow tools export --id <id>
```

> Wire call: `POST /tool/export`. Run `glow tools export --help` for the full flag list.

---

# `glow tools file download`

Route: /cli-reference/tools/file/download

# `glow tools file download`

Download file on Tool integrations.

## Usage

```bash
glow tools file download --id <id>
```

> Wire call: `POST /tool/file_download`. Run `glow tools file download --help` for the full flag list.

---

# `glow tools generate`

Route: /cli-reference/tools/generate

# `glow tools generate`

Generate Tool integrations.

## Usage

```bash
glow tools generate --body '\{...\}'
```

> Wire call: `POST /tool/generate`. Run `glow tools generate --help` for the full flag list.

---

# `glow tools generations`

Route: /cli-reference/tools/generations

# `glow tools generations`

Generations Tool integrations.

## Usage

```bash
glow tools generations --id <id>
```

> Wire call: `POST /tool/generations`. Run `glow tools generations --help` for the full flag list.

---

# `glow tools get`

Route: /cli-reference/tools/get

# `glow tools get`

Get Tool integrations.

## Usage

```bash
glow tools get --id <id>
```

> Wire call: `POST /tool/get`. Run `glow tools get --help` for the full flag list.

---

# `glow tools group`

Route: /cli-reference/tools/group

# `glow tools group`

Group Tool integrations.

## Usage

```bash
glow tools group --id <id>
```

> Wire call: `POST /tool/group`. Run `glow tools group --help` for the full flag list.

---

# `glow tools preview`

Route: /cli-reference/tools/preview

# `glow tools preview`

Preview Tool integrations.

## Usage

```bash
glow tools preview --id <id>
```

> Wire call: `POST /tool/preview`. Run `glow tools preview --help` for the full flag list.

---

# `glow tools problem`

Route: /cli-reference/tools/problem

# `glow tools problem`

Problem Tool integrations.

## Usage

```bash
glow tools problem --id <id>
```

> Wire call: `POST /tool/problem`. Run `glow tools problem --help` for the full flag list.

---

# `glow tools refresh`

Route: /cli-reference/tools/refresh

# `glow tools refresh`

Refresh Tool integrations.

## Usage

```bash
glow tools refresh --id <id>
```

> Wire call: `POST /tool/refresh`. Run `glow tools refresh --help` for the full flag list.

---

# `glow tools search`

Route: /cli-reference/tools/search

# `glow tools search`

Search Tool integrations.

## Usage

```bash
glow tools search
```

> Wire call: `POST /tool/search`. Run `glow tools search --help` for the full flag list.

---

# `glow tools text download`

Route: /cli-reference/tools/text/download

# `glow tools text download`

Download text on Tool integrations.

## Usage

```bash
glow tools text download --id <id>
```

> Wire call: `POST /tool/text_download`. Run `glow tools text download --help` for the full flag list.

---

# `glow tools title`

Route: /cli-reference/tools/title

# `glow tools title`

Title Tool integrations.

## Usage

```bash
glow tools title --id <id>
```

> Wire call: `POST /tool/title`. Run `glow tools title --help` for the full flag list.

---

# `glow tools update`

Route: /cli-reference/tools/update

# `glow tools update`

Update Tool integrations.

## Usage

```bash
glow tools update --id <id>
```

> Wire call: `POST /tool/update`. Run `glow tools update --help` for the full flag list.

---

# `glow tools watch`

Route: /cli-reference/tools/watch

# `glow tools watch`

Watch Tool integrations.

## Usage

```bash
glow tools watch --id <id>
```

> Wire call: `POST /tool/watch`. Run `glow tools watch --help` for the full flag list.

---

# Cohorts

Route: /cohorts

# Cohorts

Cohorts bring everything together. A cohort is a group of profiles (learners) assigned to a set of simulations. It is the final assembly step before learners can run simulation attempts.

## What is a Cohort?

A cohort is a named group that links profiles to simulations. When a learner logs in, they see the simulations available in their assigned cohorts. Cohorts also carry profile personas, which tell the AI who each learner is so the AI student character can adapt its behavior.

**University example:** A "Practice Cohort" might include Professor Smith and TA Johnson with access to practice simulations for rehearsing classroom scenarios. A "Training Cohort" might include the University Admin, Professor Smith, and TA Johnson with access to training simulations for onboarding.

![Cohorts list showing cohort cards with name, member count, and simulation count](/screenshots/cohorts/list.png)

## How It Connects: The 5-Step Workflow

Cohorts are step 4 -- the final assembly before learners can run attempts:

1. **Create Personas** -- Define AI student characters with temperaments and behaviors.
2. **Assign to Scenarios** -- Attach personas and documents to scenarios.
3. **Add to Simulations** -- Group scenarios into simulations.
4. **Add to Cohorts** -- Assign *profiles* and *simulations* to a cohort. Configure profile personas to tell the AI who each learner is.
5. **Run Attempts** -- Learners launch simulations from their cohort.

A cohort requires at least one profile and one simulation. Once both are assigned, the profiles in that cohort can begin running simulation attempts.

---

## Create a cohort

### Via the CLI

> Calls below use `$GLOW_INSTANCE_URL` + `$GLOW_TOKEN` — see [Authentication](/authentication) to export them once.

```bash
glow cohorts create --body '{
  "cohorts": [
    {
      "name": "Practice Cohort",
      "description": "Practice simulations for CS instructional staff"
    }
  ]
}'
```

### Via the API

All endpoints use `POST` and require an `Authorization: Bearer` header.

```bash
curl -X POST $GLOW_INSTANCE_URL/cohort/create \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cohorts": [
      {
        "name": "Training Cohort",
        "description": "Training simulations for new CS department staff"
      }
    ]
  }'
```

---

## Cohort composition

A cohort contains several key sections that you configure together on the detail page.

![Cohort detail showing member list, assigned simulations, and persona override configuration](/screenshots/cohorts/detail.png)

### Profiles

The profiles assigned to a cohort determine who can access its simulations. You can search and filter profiles when adding them.

**Example:** The Practice Cohort includes Professor Smith and TA Johnson. Both can access the practice simulations assigned to this cohort.

### Simulations

The simulations assigned to a cohort determine what learners can practice. A simulation can belong to multiple cohorts.

**Example:** The Practice Cohort has practice simulations for office-hours scenarios, while the Training Cohort has training simulations for onboarding new instructors.

### Simulation positions and availability

Cohorts support simulation positions (ordering how simulations appear) and simulation availability (controlling when simulations are accessible). These are managed through `simulation_position_ids` / `simulation_positions` and `simulation_availability_ids` / `simulation_availability` on the draft endpoint.

## Profile personas

Profile personas tell the AI *who the learner is*, so the AI student character can adapt its behavior accordingly. For example, a Confused student persona might use more technical language when speaking to a graduate-level TA and simpler language when speaking to an introductory TA -- because the profile persona gives the AI context about the learner's background.

Profile personas are configured at the cohort level. Each profile in a cohort can have a persona assigned that describes the learner's role, experience level, and background. This is not about changing which AI character the learner faces -- it is about giving the AI enough context to interact realistically with different types of learners.

**Example:** In the Training Cohort:
- TA Johnson has a profile persona describing them as a first-year graduate TA for CS-180 with limited teaching experience. The AI student character might use simpler questions and be more patient.
- Professor Smith has a profile persona describing them as a tenured professor with 15 years of teaching experience. The AI student character might ask more challenging questions and push back more.

The persona affects the AI's behavior, not the learner's identity. The same "Confused" student character adapts how it expresses confusion based on whether it is speaking with a new TA or a seasoned professor.

Profile personas are managed through `profile_persona_ids` (existing personas) and `profile_personas` (new persona values) on the cohort draft endpoint.

---

## Drafts

Cohorts support the draft workflow. Changes are saved as a draft before being published, with optimistic concurrency via `expected_version` so two editors don't silently clobber each other.

```bash
# Save a cohort draft
glow cohorts draft --body '{
  "name": "Practice Cohort",
  "description": "Practice simulations for CS instructional staff"
}'
```

Via the API, use `PATCH /cohort/draft` with fields like `input_draft_id`, `expected_version`, `name`, `description`, `flag_id`, `department_ids`, `simulation_ids`, `profile_ids`, `simulation_position_ids`, `simulation_positions`, `simulation_availability_ids`, `simulation_availability`, `profile_persona_ids`, and `profile_personas`.

---

## Filtering and search

Cohorts support rich search and filtering.

- **Profile** -- Find cohorts containing specific profiles (`filter_profile_ids`, `profile_search`)
- **Simulation** -- Find cohorts containing specific simulations (`filter_simulation_ids`, `simulation_search`)
- **Department** -- Scope to a department (`filter_department_ids`, `department_search`)
- **Flag** -- Filter by cohort flags (`flag_search`)

```bash
# Search cohorts by profile
curl -X POST $GLOW_INSTANCE_URL/cohort/search \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_search": "Johnson",
    "page_size": 20
  }'
```

---

## Bulk operations

Bulk delete and update follow the canonical *all-matching* shape: pass either explicit IDs, or `all: true` with flat filter fields + optional `excluded_ids` + a `patch` for updates.

**Delete by explicit IDs:**

```bash
glow cohorts delete --body '{
  "cohort_ids": ["cohort-1", "cohort-2", "cohort-3"]
}'
```

**Delete all matching a filter (with exclusions):**

```bash
glow cohorts delete --body '{
  "all": true,
  "filter_department_ids": ["dept-sunset"],
  "excluded_ids": ["cohort-keep-this-one"]
}'
```

**Bulk update via `patch`:**

```bash
glow cohorts update --body '{
  "all": true,
  "filter_department_ids": ["dept-archive"],
  "patch": { "archived": true }
}'
```

See the [Personas guide](/personas) for the canonical write-up of this pattern -- it applies the same way across artifacts that have adopted it.

## Common Operations

| Task | CLI | API Endpoint |
|---|---|---|
| List all cohorts | `glow cohorts list` | `POST /cohort/search` |
| Get a cohort | `glow cohorts get --body '{...}'` | `POST /cohort/get` |
| Create cohorts | `glow cohorts create --body '{...}'` | `POST /cohort/create` |
| Update cohorts | `glow cohorts update --body '{...}'` | `POST /cohort/update` |
| Duplicate a cohort | -- | `POST /cohort/duplicate` |
| Delete cohorts | `glow cohorts delete --body '{...}'` | `POST /cohort/delete` |
| Bulk delete (filter) | `glow cohorts delete --body '{"all": true, "filter_…": "…"}'` | `POST /cohort/delete` |
| Export to CSV | `glow cohorts export` | `POST /cohort/export` |
| Save a draft | `glow cohorts draft --body '{...}'` | `PATCH /cohort/draft` |
| List drafts | -- | `POST /cohort/drafts` |

## Related

- [Cohorts API](/api-reference/cohort)
- [Cohorts CLI](/cli-reference/cohort)
- [Profiles Guide](/profile) -- the people assigned to cohorts
- [Departments Guide](/department) -- cohorts are scoped to departments

---

# Dashboard

Route: /dashboard

# Dashboard

The Dashboard is the admin analytics hub for TA training programs.
It returns a single bundled response — header summaries, primary and
secondary metric panels, rubric breakdowns, simulation overviews, and
inline attempt history — so program coordinators can evaluate how
TAs are performing in office-hours simulations.

Dashboard is a **view on the attempt artifact** — one endpoint
(`POST /attempt/dashboard`) that takes a filter body and returns a
`DashboardBundleResponse`. It is not its own artifact, so there is no
`/dashboard/...` URL space; sibling operations (attempt search,
export, refresh) live at the attempt root.

![Dashboard overview showing aggregate scores by rubric standard across all cohorts](/screenshots/dashboard/overview.png)

## What is Dashboard?

Dashboard aggregates training data across all TAs, cohorts, and simulations into a single analytics surface. It answers questions like:

- How are TAs scoring on Communication Skills and De-escalation rubrics this semester?
- Which simulations (e.g., Confused Student, Aggressive Student) have the lowest pass rates?
- What is the overall completion percentage across departments?
- How has average score trended over the past 30 days?

![Dashboard chart showing score trends over time for each rubric standard group](/screenshots/dashboard/trends.png)

Dashboard returns `header_metrics` (total attempts, average score, completion percentage, first-attempt pass rate), `primary_metrics` and `secondary_metrics` panels, rubric/parameter/scenario breakdowns, score `thresholds`, AI-generated `insights`, and inline `history` with pagination.

## Header metrics at a glance

## Quick Start

### CLI

> Calls below use `$GLOW_INSTANCE_URL` + `$GLOW_TOKEN` — see [Authentication](/authentication) to export them once.

```bash
# Fetch the full dashboard bundle (all metrics, rubrics, simulations)
glow attempts dashboard

# Scope to a specific cohort and date range (body merges into the request)
glow attempts dashboard --body '{"cohort_ids": ["cohort-abc"], "start_date": "2025-01-01", "end_date": "2025-06-30"}'

# Sibling operations on the attempt artifact (NOT under /dashboard)
glow attempts search --body '{"page_size": 25, "sort_by": "score", "sort_order": "desc"}'
glow attempts export
glow attempts refresh
```

### API

```bash
# Get dashboard bundle — single endpoint, filters in the body
curl -X POST $GLOW_INSTANCE_URL/attempt/dashboard \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "department_ids": ["dept-cs"],
    "start_date": "2025-01-01",
    "end_date": "2025-06-30"
  }'

# Search attempt history (separate endpoint on the attempt artifact)
curl -X POST $GLOW_INSTANCE_URL/attempt/search \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "page_size": 20,
    "sort_order": "desc"
  }'
```

## Filtering and Scoping

Dashboard supports composable filters in the body so you can drill down to exactly the data you need:

| Filter | Field | Example |
|---|---|---|
| Date range | `start_date`, `end_date` | `"start_date": "2025-01-01"` |
| Cohorts | `cohort_ids` | `["fall-2025-cs101"]` |
| Departments | `department_ids` | `["dept-cs", "dept-math"]` |
| Simulations | `simulation_ids` | `["sim-confused-student"]` |
| Roles | `roles` | `["ta", "lead-ta"]` |
| Rubric picker | `rubric_ids`, `rubric_search` | `"rubric_search": "de-escalation"` |
| Scenario picker | `scenario_ids`, `scenario_search` | `"scenario_search": "passive"` |
| Parameter picker | `parameter_ids`, `parameter_search` | `"parameter_search": "policy"` |
| Single TA | `target_profile_id` | UUID of the TA profile |

When `target_profile_id` is provided, the response includes `profile_name`, `profile_emails`, `profile_primary_email`, and `profile_role` for the scoped TA.

## Rubric breakdown

## Understanding the Response

The `DashboardBundleResponse` is organized into sections:

- **`header_metrics`** -- Top-line summary cards: total attempts, average score, completion percentage, first-attempt pass rate.
- **`primary_metrics`** / **`secondary_metrics`** / **`footer_metrics`** -- Detailed metric panels with trend data, hover tooltips, and breakdowns.
- **`simulations`** -- Metadata for each simulation (name, scenario count, rubric mappings).
- **`scenarios`** -- Per-scenario metadata for drill-down.
- **`rubrics`** / **`parameters`** / **`fields`** -- Rubric and parameter breakdowns (e.g., Communication Skills, Policy Knowledge, De-escalation).
- **`thresholds`** -- Score threshold configuration for pass/fail determination.
- **`insights`** -- AI-generated insights per section, highlighting patterns and anomalies.
- **`history`** -- Inline paginated attempt history with `HistoryItem` rows.
- **`analytics`** -- Filter facets (department options, cohort options, role options, date range boundaries) for rendering dropdowns.

## Sibling: Attempt History Search

For larger paginated history tables, use the attempt search endpoint
directly — it returns the same `HistoryItem` shape with full pagination:

```bash
curl -X POST $GLOW_INSTANCE_URL/attempt/search \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "target_profile_id": "ta-profile-uuid",
    "scenario_ids": ["scenario-confused-student"],
    "sort_by": "date",
    "sort_order": "desc",
    "page_size": 10
  }'
```

Each `HistoryItem` includes `attempt_id`, `simulation_name`, `score`, `score_status` (pass/fail), `persona_names_junction`, `num_scenarios_completed`, and action flags like `show_view` and `show_continue`.

## Exporting

```bash
# Export attempts as a denormalized ZIP (sibling endpoint, not under dashboard)
glow attempts export
```

The export endpoint returns a base64-encoded ZIP with `content`, `file_name`, `mime_type`, and `row_count`.

## Common Operations

| Task | CLI | API Endpoint |
|---|---|---|
| Dashboard metric bundle | `glow attempts dashboard` | `POST /attempt/dashboard` |
| Attempt history search | `glow attempts search` | `POST /attempt/search` |
| Export attempts | `glow attempts export` | `POST /attempt/export` |
| Refresh MV caches | `glow attempts refresh` | `POST /attempt/refresh` |

## Related

- [Attempt API Reference](/api-reference/attempt) — every endpoint on the attempt artifact
- [Attempts CLI Reference](/cli-reference/attempts) — every `glow attempts ...` command
- [Reports](/reports) — aggregate training reports (sibling view, `POST /attempt/report`)
- [Leaderboard](/leaderboard) — score rankings (sibling view, `POST /attempt/leaderboard`)
- [Practice](/practice) — practice-mode view (sibling view, `POST /attempt/practice`)

---

# Data layer

Route: /data-layer

# Data layer

Glow's read path has two cooperating layers. **Materialized views**
(`<artifact>_mv` tables in Postgres) precompute the hydrated rows that
search and list endpoints return, refreshed in the background on a
cadence per artifact. A **route-level cache** sits in front of those
reads in Redis, keyed by the request and busted by tag. Together they
turn most list/get reads into sub-50ms responses without coupling
mutation paths to read freshness.

```mermaid
sequenceDiagram
    participant C as Client
    participant R as Route cache
    participant MV as Materialized view
    C->>MV: 1st search cold, response cached
    C->>R: 2nd search route-cache hit
    Note over C,R: mutation elsewhere fires X-Invalidate-Tags
    C->>MV: 3rd search clean miss, re-warms
```

*Cold search warms the materialized view; the next hits the route cache; a mutation elsewhere fires `X-Invalidate-Tags` so the following request misses cleanly and re-warms.*

## Two layers

The split is deliberate:

| Layer | Storage | Keyed by | Busted by |
|------|---------|----------|-----------|
| Materialized views | Postgres (`<artifact>_mv`) | Underlying entry tables | Background refresh on a cadence + `POST /<artifact>/refresh` |
| Route-level cache | Redis (`http:cache:*`) | Path + body hash | TTL + `X-Invalidate-Tags` from mutation responses |

A list read first checks the route cache; on miss it queries the MV
and writes the response back into Redis with a tag set. A mutation in
the same artifact enqueues an MV refresh **and** returns
`X-Invalidate-Tags`, which clients are expected to surface so that the
next read bypasses the now-stale cache entry. Reads from MVs are not
audited — the [Audit](/audit) ledger only captures mutations.

---

## Materialized views

Almost every artifact in Glow has a paired `<artifact>_mv` materialized
view that joins the canonical entry table with its drafts, junctions,
and lookup rows in a single SELECT. Search, list, and most
hydration-heavy GET endpoints read **only** from the MV — never from
the raw entry table — so per-request hydration stays O(1) regardless
of how many junctions the artifact has accumulated.

The full registry of MV targets lives in
`core/app/infra/refresh/config.py:MV_REGISTRY`. A small sample:

| MV | Backs | Refresh tier |
|----|-------|--------------|
| `personas_mv`, `persona_drafts_mv` | `POST /persona/search`, `/persona/get`, `/persona/drafts` | Cool |
| `tests_mv`, `test_invocation_mv` | `POST /test/search`, `/test/invocations` | Cool |
| `runs_mv`, `messages_mv`, `calls_mv` | Live attempt + agent surfaces | Hot |
| `groups_mv`, `group_names_mv` | Session timeline + every artifact's `/title` resolver | Hot |
| `grants_mv`, `health_mv`, `sessions_mv` | Permission gates + admin dashboards | Glacial |

### Auto-refresh cadence

Every MV target is assigned a hotness tier — `Hot` (~2s), `Warm` (~5s),
`Cool` (~10s), `Glacial` (~30s) — defined alongside the registry. A
per-MV background worker (`MVRefresher` in
`core/app/infra/refresh/scheduler.py`) debounces enqueues into one
`REFRESH MATERIALIZED VIEW CONCURRENTLY` per interval and serializes
across replicas via a Redis lock. The exact interval per MV is
configurable in `MV_REGISTRY` — don't read the constants here as a
contract.

Mutations don't run the refresh inline. Instead, every create / update
/ delete primitive calls `enqueue_refreshes(...)` with the MV targets
that depend on it, which just flips an O(1) Redis flag. The worker
picks it up on its next tick. This means **read freshness lags writes
by up to one refresh interval** for the artifact's tier.

### Manual refresh: `POST /<artifact>/refresh`

Every artifact exposes a refresh endpoint that re-enqueues all of its
MV targets *and* invalidates the route-level cache tags for that
artifact. Example for personas:

```bash
glow personas refresh
```

```bash
curl -X POST $GLOW_INSTANCE_URL/persona/refresh \
  -H "Authorization: Bearer $GLOW_TOKEN"
```

The response carries the list of invalidated tags and the per-target
enqueue receipts, and the HTTP `X-Invalidate-Tags` header echoes the
same tag set so client caches react too. The actual MV recompute still
happens in the background worker — `refresh` is **not** a synchronous
"give me a fresh row" call.

---

## Route-level cache

The route cache is a thin Redis-backed wrapper any list / search /
hydrated-GET endpoint can opt into. The primitives live in
`core/app/utils/cache/`:

- `cache_key(path, body, user_ctx)` — SHA-1 over a stable JSON encoding
  of `{path, body, user_ctx}`. The prefix is `http:cache:`. The
  `user_ctx` arg is optional; routes that scope per-profile pass the
  profile_id, routes that don't (license-wide list reads) leave it
  empty.
- `get_cached(key, redis=...)` — returns the cached envelope or `None`.
- `set_cached(key, data, ttl, tags, redis=...)` — writes the envelope
  with a TTL and adds the key to each tag's Redis set so
  `invalidate_tags` can sweep them later.
- `invalidate_tags(tags, redis=...)` — drops every cached key
  registered against any of the tags in one pipeline.

### Wiring example

`core/app/routes/system/groups.py` is the prototypical shape:

```python
tags = ["artifacts", "groups", "list"]
bypass_cache = http_request.headers.get("X-Bypass-Cache") == "1"
cache_key_val = cache_key(http_request.url.path, request.model_dump(mode="json"))

if not bypass_cache:
    cached = await get_cached(cache_key_val, redis=get_redis_client())
    if cached:
        response.headers["X-Cache-Tags"] = ",".join(tags)
        response.headers["X-Cache-Hit"] = "1"
        return ListPricingResponse.model_validate(cached["data"])

api_response = await groups_system_impl(...)

await set_cached(
    cache_key_val,
    {"data": api_response.model_dump(mode="json")},
    ttl=300,
    tags=tags,
    redis=redis,
)
response.headers["X-Cache-Tags"] = ",".join(tags)
response.headers["X-Cache-Hit"] = "0"
return api_response
```

TTLs are per-route — the groups list uses 300s in the snippet above;
the "big" page-context cache (`core/app/utils/cache/big.py`) defaults
to 30s. Don't read either as a global contract; check the call site.

Every cached response carries two headers so clients can self-report:

- `X-Cache-Tags` — the tag set this response was stored under, so a
  client can mirror the server's invalidation scheme.
- `X-Cache-Hit` — `1` if the response came from Redis, `0` if it was
  computed and just written.

---

## `X-Bypass-Cache`

Send `X-Bypass-Cache: 1` on any cached read to skip the route cache
entirely. The route still runs against the MV (which may itself be
stale by up to one refresh interval — see above), but Redis is
neither consulted on the way in nor written on the way out.

Use it when:

- You just performed a mutation in the same client and need a
  consistent-read for the next render.
- You're debugging a "why is this stale" report and want to rule out
  Redis as the source.
- You're running a test that asserts on freshly written rows.

Do not use it as a default — it negates the whole point of the cache
layer.

## `X-Invalidate-Tags`

Mutation responses (and the `/refresh` endpoint of every artifact)
return an `X-Invalidate-Tags` header listing the tag families that
the write touched. Examples observed in the routes:

- `POST /persona/update` → `personas`
- `POST /persona/refresh` → `personas,artifacts`
- `POST /test/grade` → `test,tests,grades`
- `POST /document/file_upload` → `uploads,resources,files`

Clients that maintain their own caches (the Glow UI does, via
`useArtifactGeneration` and the shared generation listener) read this
header on every response and drop their local entries for the listed
tags. The server-side equivalent is `invalidate_tags(...)` from
`core/app/utils/cache/invalidate_tags.py`, which the same mutation
paths call inline before returning.

## When to call `/<artifact>/refresh` manually

| Scenario | Manual `/refresh`? | Why |
|----------|--------------------|-----|
| Routine mutate-then-read through the SDK | No | Auto-enqueue + tag invalidate already cover this within one tick |
| Just finished a bulk import / CSV load | Yes | One refresh collapses N enqueues; UI tables can re-fetch immediately |
| Background MV drift suspected during incident triage | Yes | Forces an enqueue regardless of the next-run-at gate |
| About to snapshot a list view in a test or report | Yes | Pairs naturally with `X-Bypass-Cache: 1` on the follow-up read |
| Recovery after a worker crash | No | The Redis pending flag survives — the next worker tick drains it |

The refresh endpoint is cheap (it just flips a Redis flag and writes
an audit row); the actual `REFRESH MATERIALIZED VIEW` cost is paid
once per debounce window regardless of how many times you call it.

## Related

- [POST /persona/refresh](/api-reference/persona/post-persona-refresh) — the canonical refresh endpoint, one per artifact
- [Streaming](/streaming) — refresh emits a `.completed` event on the artifact watch channel when the MV recompute finishes
- [Audit](/audit) — cache hits and MV refresh ticks are intentionally not audited; only the mutations that trigger invalidation land in the ledger
- [Activity](/activity) — backs onto `activity_mv`, the same refresh + cache contract as every other list surface

---

# Departments

Route: /departments

# Departments

Departments are the organizational boundary in Glow. They scope nearly every resource -- profiles, documents, parameters, fields, scenarios, simulations, and cohorts -- so that different groups within your institution can work independently.

## What is a Department?

A department is a top-level organizational unit that controls visibility and access across Glow. Every resource is scoped to one or more departments, and profiles can only see and manage resources within their assigned departments.

**University example:** The "University" department might be described as an "Innovative base of knowledge in the emerging field of computing." All CS-related resources -- profiles for Professor Smith and TA Johnson, parameters like Temperament and Class, documents like the Academic Integrity Policy -- are scoped to this department.

## How It Connects: The 5-Step Workflow

Departments underpin every step of the Glow workflow by scoping resources:

1. **Create Personas** -- Personas are scoped to a department.
2. **Assign to Scenarios** -- Scenarios, documents, and their parameters/fields are all scoped to a department.
3. **Add to Simulations** -- Simulations are scoped to a department.
4. **Add to Cohorts** -- Cohorts are scoped to a department. Only profiles belonging to the same department can be added.
5. **Run Attempts** -- Learners only see simulations within cohorts from their department.

Departments connect to nearly everything. They are the first resource you should set up when configuring a new Glow instance.

---

## Create a department

### Via the CLI

> Calls below use `$GLOW_INSTANCE_URL` + `$GLOW_TOKEN` — see [Authentication](/authentication) to export them once.

```bash
glow departments create --body '{
  "departments": [
    {
      "name": "University",
      "description": "Innovative base of knowledge in the emerging field of computing"
    }
  ]
}'
```

### Via the API

All endpoints use `POST` and require an `Authorization: Bearer` header.

```bash
curl -X POST $GLOW_INSTANCE_URL/department/create \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "departments": [
      {
        "name": "University",
        "description": "Innovative base of knowledge in the emerging field of computing"
      }
    ]
  }'
```

---

## Member assignment

Profiles belong to one or more departments and can only manage resources within those departments. Assignment happens by updating each profile's `department_ids`, but the department detail surface is the natural place to audit who currently sits inside a scope.

## What Departments Scope

| Resource | How departments apply |
|---|---|
| **Profiles** | A profile belongs to one or more departments and can only manage resources within those departments |
| **Documents** | Each document is scoped to a department |
| **Parameters** | Each parameter is scoped to a department |
| **Fields** | Each field is scoped to a department |
| **Scenarios** | Scenarios inherit department scope |
| **Simulations** | Simulations are scoped to a department |
| **Cohorts** | Cohorts are scoped to a department; only same-department profiles can be members |

---

## Settings and flags

Departments have a settings section that controls department-level configuration. Settings are managed through the `settings` field on the department get response and the `setting_ids` field on the draft endpoint. Flags toggle department-level feature behavior.

---

## The draft cycle

Departments support the draft workflow. Changes are saved as a draft before being published, with `expected_version` providing optimistic concurrency.

```bash
glow departments draft --body '{
  "input_draft_id": "dept-draft-uuid",
  "expected_version": 2,
  "name": "University",
  "description": "Innovative base of knowledge in the emerging field of computing"
}'
```

Via the API, use `PATCH /department/draft` with fields like `input_draft_id`, `expected_version`, `name`, `description`, `flag_id`, and `setting_ids`.

---

## Search & filter

```bash
curl -X POST $GLOW_INSTANCE_URL/department/search \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "search": "University",
    "page_size": 10
  }'
```

---

## Bulk operations

Bulk delete and update follow the canonical *all-matching* shape -- explicit IDs, or `all: true` with flat filter fields plus optional `excluded_ids` and a `patch` body. The persona surface is the prove-out; departments follow the same shape.

**Delete by explicit IDs:**

```bash
glow departments delete --body '{"department_ids": ["dept-1", "dept-2"]}'
```

**Delete all matching a filter (with exclusions):**

```bash
glow departments delete --body '{
  "all": true,
  "search": "deprecated",
  "excluded_ids": ["dept-keep-this-one"]
}'
```

**Bulk update via `patch`:**

```bash
glow departments update --body '{
  "all": true,
  "search": "archived-",
  "patch": { "archived": true }
}'
```

## Common Operations

| Task | CLI | API Endpoint |
|---|---|---|
| List all departments | `glow departments list` | `POST /department/search` |
| Get a department | `glow departments get --body '{...}'` | `POST /department/get` |
| Create departments | `glow departments create --body '{...}'` | `POST /department/create` |
| Update departments | `glow departments update --body '{...}'` | `POST /department/update` |
| Duplicate a department | -- | `POST /department/duplicate` |
| Delete departments | `glow departments delete --body '{...}'` | `POST /department/delete` |
| Bulk delete (filter) | `glow departments delete --body '{"all": true, "filter_…": "…"}'` | `POST /department/delete` |
| Export to CSV | `glow departments export` | `POST /department/export` |
| Save a draft | `glow departments draft --body '{...}'` | `PATCH /department/draft` |
| List drafts | -- | `POST /department/drafts` |

## Related

- [Departments API](/api-reference/department)
- [Departments CLI](/cli-reference/department)
- [Profiles Guide](/profile) -- profiles belong to departments
- [Documents Guide](/document) -- documents are scoped to departments
- [Parameters Guide](/parameter) -- parameters are scoped to departments
- [Cohorts Guide](/cohort) -- cohorts are scoped to departments

---

# Documents

Route: /documents

# Documents

Documents provide reference material that grounds AI-driven simulations in real institutional content. They attach to scenarios so the AI character can draw on policies, syllabi, and other materials during a conversation.

![Documents list showing uploaded documents with name, type, and associated scenario count](/screenshots/documents/list.png)

## What is a Document?

A document is a piece of content -- such as a policy, syllabus, lab template, or homework assignment -- that gets attached to a scenario. When a learner runs a simulation, the AI character uses the document as context to stay accurate and on-topic.

**University example:** An "Academic Integrity Policy" document ensures that when a student character asks about cheating consequences, the AI responds with the actual university policy rather than generic information. A "FERPA Policy" document gives the AI grounding in privacy regulations for scenarios involving student records.

## How It Connects: The 5-Step Workflow

Documents participate in step 2 of the Glow workflow:

1. **Create Personas** -- Define AI student characters with temperaments and behaviors.
2. **Assign to Scenarios** -- Attach personas and *documents* to scenarios. Documents give the AI factual grounding.
3. **Add to Simulations** -- Group scenarios into simulations.
4. **Add to Cohorts** -- Assign profiles and simulations to a cohort.
5. **Run Attempts** -- Learners launch simulations; the AI uses document content during the conversation.

Documents connect to **scenarios**, not agents. A single document can be shared across multiple scenarios. For example, the Academic Integrity Policy might be referenced in both a "Student Caught Cheating" scenario and a "Grade Appeal" scenario.

---

## Create a document

### Via the CLI

> Calls below use `$GLOW_INSTANCE_URL` + `$GLOW_TOKEN` — see [Authentication](/authentication) to export them once.

```bash
glow documents create --body '{
  "documents": [
    {
      "name": "Academic Integrity Policy",
      "description": "University policy on academic honesty, plagiarism, and cheating"
    }
  ]
}'
```

### Via the API

All endpoints use `POST` and require an `Authorization: Bearer` header.

```bash
curl -X POST $GLOW_INSTANCE_URL/document/create \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {
        "name": "FERPA Policy",
        "description": "Family Educational Rights and Privacy Act guidelines for the university"
      }
    ]
  }'
```

![Document upload form showing name field, file upload area, and department selection](/screenshots/documents/create.png)

## Document Types and Templates

Documents can represent many types of institutional content:

| Template | Example Use |
|---|---|
| **Syllabus** | Course policies, grading criteria, schedule |
| **Homework** | Assignment descriptions, rubrics, due dates |
| **Lab** | Lab procedures, safety protocols, equipment guides |
| **Policy** | Academic integrity, FERPA, code of conduct |

**Example:** The CS-180 syllabus document contains the course schedule, grading breakdown, and late policy. When attached to a scenario about a student requesting a deadline extension, the AI character can reference the actual late policy from the syllabus.

![Document detail showing document preview with content and linked scenarios](/screenshots/documents/detail.png)

## Content Sections

A document in Glow can include several types of content:

- **Name and description** -- The document title and a summary of what it contains.
- **Text content** -- The main body of the document, such as policy text or syllabus content.
- **File uploads** -- Attached files like PDFs or Word documents that supplement the text content.
- **Images** -- Visual content such as diagrams or charts.
- **Parameters and fields** -- Link the document to specific parameter categories and field values for filtering and organization.
- **Department** -- Scope the document to a department so it appears only for relevant users.

---

## Uploading files

Documents support file uploads for rich content. The upload endpoint is binary-body (no JSON wrapper) and returns an `upload_id` that you then reference when saving the document draft.

```bash
# Upload a file
curl -X POST $GLOW_INSTANCE_URL/document/upload \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/pdf" \
  -H "X-Filename: academic_integrity_policy.pdf" \
  --data-binary @academic_integrity_policy.pdf
```

The upload returns an `upload_id`. Reference it when saving the document draft:

```bash
glow documents draft --body '{
  "input_draft_id": "doc-draft-uuid",
  "expected_version": 1,
  "name": "Academic Integrity Policy",
  "file_ids": ["upload-id-returned-above"]
}'
```

---

## Drafts

Documents support the draft workflow. Changes are saved as a draft before being published, with optimistic concurrency via `expected_version`.

```bash
# Save a document draft
glow documents draft --body '{
  "name": "Academic Integrity Policy",
  "description": "Updated policy for the 2026 academic year"
}'
```

Via the API, use `PATCH /document/draft` with fields like `input_draft_id`, `expected_version`, `name`, `description`, `file_ids`, `text_ids`, `department_ids`, `parameter_ids`, and `parameter_field_ids`.

---

## Search and filter

Document search supports full-text plus facet filters across department, parameter, and field.

```bash
curl -X POST $GLOW_INSTANCE_URL/document/search \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "search": "FERPA",
    "page_size": 10
  }'
```

---

## Bulk operations

Bulk delete and update follow the canonical *all-matching* shape -- pass either explicit IDs, or `all: true` with flat filter fields + optional `excluded_ids` + a `patch` for updates.

```bash
# Delete every document in a deprecated department, except the canonical references
glow documents delete --body '{
  "all": true,
  "filter_department_ids": ["dept-deprecated"],
  "excluded_ids": ["doc-keep-canonical-policy"]
}'

# Bulk update via patch
glow documents update --body '{
  "all": true,
  "filter_department_ids": ["dept-archive"],
  "patch": { "archived": true }
}'
```

See the [Personas guide](/personas#bulk-operations) for the canonical write-up of this pattern.

## Common Operations

| Task | CLI | API Endpoint |
|---|---|---|
| List all documents | `glow documents list` | `POST /document/search` |
| Get a document | `glow documents get --body '{...}'` | `POST /document/get` |
| Create documents | `glow documents create --body '{...}'` | `POST /document/create` |
| Update documents | `glow documents update --body '{...}'` | `POST /document/update` |
| Duplicate a document | -- | `POST /document/duplicate` |
| Delete documents | `glow documents delete --body '{...}'` | `POST /document/delete` |
| Bulk delete (filter) | `glow documents delete --body '{"all": true, "filter_…": "…"}'` | `POST /document/delete` |
| Upload a file | -- | `POST /document/upload` |
| Export to CSV | `glow documents export` | `POST /document/export` |
| Save a draft | `glow documents draft --body '{...}'` | `PATCH /document/draft` |
| List drafts | -- | `POST /document/drafts` |

## Related

- [Documents API](/api-reference/document)
- [Documents CLI](/cli-reference/document)
- [Parameters Guide](/parameter) -- parameters and fields that organize documents
- [Fields Guide](/field) -- field values attached to documents
- [Departments Guide](/department) -- scope documents to departments

---

# Evals

Route: /evals

# Evals

Evals assess how well TAs handled student interactions during office hour simulations. An eval brings together models, rubrics, and configuration flags to run automated scoring across simulation transcripts, producing actionable feedback on TA performance.

---

## What is an Eval?

An eval in Glow is an automated assessment pipeline that scores simulation conversations. Each eval combines:

- **Models** -- the LLM configurations used as evaluator judges (via `model_ids`)
- **Model Rubrics** -- the scoring criteria applied during evaluation (via `model_rubric_ids`)
- **Model Flags** -- behavioral flags that tag specific patterns in conversations (via `model_flag_ids`)
- **Model Positions** -- ordering of models in multi-judge setups (via `model_position_ids`)
- **Configuration Flags** -- control whether the eval is active, dynamic, or uses groups

For example, a university might run an eval called "Fall 2025 TA Assessment" that uses GPT-4o as the evaluator model, applies the "Communication Skills" and "Policy Knowledge" rubrics, and flags instances of "Incorrect Information" or "Inappropriate Tone".

## How it Connects

```
Eval
  |
  +-- Models (evaluator LLMs via model_ids)
  +-- Model Rubrics (scoring criteria via model_rubric_ids)
  +-- Model Flags (behavioral tags via model_flag_ids)
  +-- Model Positions (judge ordering via model_position_ids)
  +-- Departments (scoping via department_ids)
```

- **Models** serve as the evaluator judges. The eval uses these models to read simulation transcripts and produce scores. These are separate from the models that *powered* the simulation -- they are the models that *grade* it.
- **Rubrics** connect through `model_rubric_ids` (the `eval_model_rubrics_junction`). Each rubric's standard groups and standards define what the evaluator model scores.
- **Model Flags** tag specific patterns in conversations (e.g., "Gave Incorrect Deadline", "Used Empathetic Language"). These are distinct from the eval-level configuration flags.
- **Departments** scope the eval to specific organizational units, enabling department-level reporting.

---

## Create an eval

### Via the CLI

> Calls below use `$GLOW_INSTANCE_URL` + `$GLOW_TOKEN` — see [Authentication](/authentication) to export them once.

```bash
glow evals create --body '{
  "evals": [{
    "name": "Fall 2025 TA Assessment",
    "description": "Automated scoring of TA office hour simulations for the fall semester",
    "model_ids": ["GPT4O_MODEL_UUID"],
    "model_rubric_ids": ["COMM_SKILLS_RUBRIC_UUID", "POLICY_KNOWLEDGE_RUBRIC_UUID"]
  }]
}'
```

### Via the API

```bash
curl -X POST $GLOW_INSTANCE_URL/eval/create \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "evals": [{
      "name": "Spring 2026 CS Department Eval",
      "description": "Evaluate TA performance across all CS course simulations",
      "department_ids": ["CS_DEPT_UUID"],
      "model_ids": ["EVALUATOR_MODEL_UUID"],
      "model_rubric_ids": ["DE_ESCALATION_RUBRIC_UUID"]
    }]
  }'
```

---

## Wiring models, rubrics, and flags

### Attaching Evaluator Models

Evals reference models through `model_ids`. These models act as judges -- they read simulation transcripts and score TA performance against the attached rubrics. You can attach multiple models to compare scoring consistency across different LLMs.

```bash
glow evals update --body '{
  "evals": [{
    "eval_id": "EVAL_UUID",
    "model_ids": ["GPT4O_MODEL_UUID", "CLAUDE_MODEL_UUID"]
  }]
}'
```

### Attaching Rubrics

Use `model_rubric_ids` to attach rubrics that define the scoring criteria. Each rubric's standard groups and standards become the dimensions on which the evaluator model scores the conversation.

For example, attaching both "Communication Skills" and "De-escalation" rubrics means every simulation transcript will be scored on active listening, empathy, clarity, conflict resolution, and other standards defined in those rubrics.

### Behavioral Flags

Use `model_flag_ids` to define specific behaviors the evaluator should tag. Unlike rubric standards (which are scored on a point scale), flags are binary markers that call out notable patterns:

- "Provided Incorrect Information"
- "Successfully De-escalated Conflict"
- "Referred Student to Appropriate Resource"

---

## Running an eval

Evals support several configuration flags that control how runs behave -- whether the eval is active, dynamic (on-the-fly scoring as attempts complete), and whether results are bucketed into groups.

| Flag Section | Purpose |
|---|---|
| `active_flags` | Whether the eval is currently active and running |
| `dynamic_flags` | Whether the eval uses dynamic mode for on-the-fly scoring |
| `groups_flags` | Whether the eval organizes results into groups |

These flags appear as sections in the GET response, each containing the current flag config and available options. The list response also surfaces these as boolean fields:

| Field | Description |
|---|---|
| `is_inactive` | Whether the eval is currently inactive |
| `is_dynamic` | Whether the eval uses dynamic mode |
| `use_groups` | Whether the eval uses groups |
| `num_runs` | Total number of eval runs completed |
| `num_groups` | Number of eval groups |

---

## The draft cycle

Evals support a draft workflow for staging changes before they affect scoring pipelines. This is important because modifying an active eval can change how future simulation runs are scored.

```bash
# Create or update an eval draft
glow evals draft --body '{
  "name": "Fall 2025 TA Assessment v2",
  "description": "Added de-escalation rubric and behavioral flags",
  "model_ids": ["EVALUATOR_MODEL_UUID"],
  "rubric_ids": ["COMM_SKILLS_UUID", "DE_ESCALATION_UUID"]
}'

# List your drafts
glow evals list
```

The draft endpoint uses `PATCH` semantics with `expected_version` for optimistic concurrency. The draft request supports `model_ids`, `rubric_ids`, `flag_ids`, and `department_ids`. The response includes `draft_id`, `new_version`, and a `form_state` with the resolved state of all fields.

---

## Search & filter

```bash
glow evals search --body '{"search": "fall"}'

glow evals search --body '{
  "filter_department_ids": ["CS_DEPT_UUID"],
  "page_size": 25
}'
```

---

## Bulk operations

Bulk delete and update follow the canonical *all-matching* shape -- explicit IDs, or `all: true` with flat filter fields plus optional `excluded_ids` and a `patch` body. The persona surface is the prove-out; evals follow the same shape.

**Delete by explicit IDs:**

```bash
glow evals delete --body '{"eval_ids": ["eval-1", "eval-2"]}'
```

**Delete all matching a filter (with exclusions):**

```bash
glow evals delete --body '{
  "all": true,
  "filter_department_ids": ["dept-finished-semester"],
  "excluded_ids": ["eval-still-running-reports"]
}'
```

**Bulk update via `patch`:**

```bash
glow evals update --body '{
  "all": true,
  "filter_department_ids": ["dept-finished-semester"],
  "patch": { "is_inactive": true }
}'
```

## Common Operations

| Task | CLI | API Endpoint |
|---|---|---|
| List all evals | `glow evals search` | `POST /eval/search` |
| Get eval details | `glow evals get --body '{"eval_id": "..."}'` | `POST /eval/get` |
| Create eval | `glow evals create --body '{...}'` | `POST /eval/create` |
| Update eval | `glow evals update --body '{"eval_id": "...", ...}'` | `POST /eval/update` |
| Duplicate eval | -- | `POST /eval/duplicate` |
| Delete eval(s) | `glow evals delete --body '{"eval_id": "..."}'` | `POST /eval/delete` |
| Bulk delete (filter) | `glow evals delete --body '{"all": true, "filter_…": "…"}'` | `POST /eval/delete` |
| Export to CSV | `glow evals export` | `POST /eval/export` |
| Stage a draft | `glow evals draft --body '{...}'` | `PATCH /eval/draft` |
| List drafts | `glow evals list` | `POST /eval/drafts` |

---

## Related

- [Evals API Reference](/api-reference/eval) -- full endpoint and type documentation
- [Evals CLI Reference](/cli-reference/eval) -- all CLI commands
- [Rubrics Guide](/rubric) -- define scoring criteria used by evals
- [Models Guide](/model) -- configure the evaluator models that power evals
- [Providers Guide](/provider) -- set up LLM backends for evaluator models

---

# Fields

Route: /fields

# Fields

Fields are the specific values within a parameter. While parameters define categories like "Temperament" or "Class", fields define the individual options within those categories -- "Confused", "Happy", "CS-180", and so on.

![Fields list showing field entries with name, value, and parent parameter](/screenshots/fields/list.png)

## What is a Field?

A field is a single value that belongs to a parameter. Fields are the building blocks that get attached to documents and scenarios, letting you tag simulation content with precise characteristics.

**University example:** The "Temperament" parameter has four fields:

| Field | Description |
|---|---|
| **Confused** | The AI student character is uncertain, asks clarifying questions, and struggles to follow along |
| **Happy** | The AI student character is positive, engaged, and receptive to instruction |
| **Passive** | The AI student character is quiet, requires prompting, and gives minimal responses |
| **Aggressive** | The AI student character is confrontational, challenges authority, and pushes back |

Other examples include "CS-180" and "CS-251" as fields under the "Class" parameter, or "Almost Empty (1)" through "Hectic (10)" as fields under the "Crowdedness" parameter.

## How It Connects: The 5-Step Workflow

Fields contribute to step 2 of the Glow workflow through their role in organizing documents:

1. **Create Personas** -- Define AI student characters with temperaments and behaviors.
2. **Assign to Scenarios** -- Attach personas and documents to scenarios. Documents are tagged with *fields* to indicate their specific characteristics.
3. **Add to Simulations** -- Group scenarios into simulations.
4. **Add to Cohorts** -- Assign profiles and simulations to a cohort.
5. **Run Attempts** -- Learners launch simulations; the AI uses field-tagged content during the conversation.

Fields connect to **parameters** (each field belongs to a parameter) and to **documents** (documents are tagged with fields for categorization and filtering).

---

## Create a field

### Via the CLI

> Calls below use `$GLOW_INSTANCE_URL` + `$GLOW_TOKEN` — see [Authentication](/authentication) to export them once.

```bash
glow fields create --body '{
  "fields": [
    {
      "name": "Confused",
      "description": "The AI student character is uncertain and struggles to follow along"
    }
  ]
}'
```

### Via the API

All endpoints use `POST` and require an `Authorization: Bearer` header.

```bash
curl -X POST $GLOW_INSTANCE_URL/field/create \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": [
      {
        "name": "CS-180",
        "description": "Introduction to Computer Science course field"
      }
    ]
  }'
```

---

## Conditional parameters and multiple descriptions

![Field detail showing name, description, value, and linked parameter](/screenshots/fields/detail.png)

### Conditional Parameters

Fields can have conditional parameters. This means a field can specify that when it is selected, certain additional parameters become relevant. This enables dynamic scenario configuration where selecting one field value unlocks further options.

**Example:** Selecting the "CS-180" field under the "Class" parameter might conditionally require the "Location" parameter, since CS-180 has specific classroom and lab locations.

The API exposes this through `conditional_parameter_ids` on the field draft, and the get endpoint returns a `conditional_parameters` section.

### Descriptions

Fields support multiple descriptions. This is useful when a field needs different levels of detail for different contexts -- a short label for list views and a longer description for the AI to use during simulation.

The get endpoint accepts a `descriptions_search` parameter, letting you search through a field's descriptions when it has many.

---

## Drafts

Fields support the draft workflow. Changes are saved as a draft before being published, with optimistic concurrency via `expected_version`.

```bash
# Save a field draft
glow fields draft --body '{
  "name": "Happy",
  "description": "The AI student character is positive, engaged, and receptive to instruction"
}'
```

Via the API, use `PATCH /field/draft` with fields like `input_draft_id`, `expected_version`, `name`, `description`, `flag_id`, `department_ids`, and `conditional_parameter_ids`.

---

## Filtering and search

Fields support rich search and filtering:

- **Parameter** -- Find fields belonging to specific parameters (`parameter_ids`, `parameter_search`)
- **Persona** -- Find fields used by specific personas (`persona_ids`, `persona_search`)
- **Department** -- Scope to a department (`filter_department_ids`, `department_search`)

```bash
# Search fields by parameter
curl -X POST $GLOW_INSTANCE_URL/field/search \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parameter_search": "Temperament",
    "page_size": 20
  }'
```

---

## Bulk operations

Bulk delete and update follow the canonical *all-matching* shape -- pass either explicit IDs, or `all: true` with flat filter fields + optional `excluded_ids` + a `patch` for updates.

```bash
# Delete every field under a retired parameter, except a manual keeplist
glow fields delete --body '{
  "all": true,
  "parameter_ids": ["retired-parameter-uuid"],
  "excluded_ids": ["field-keep-canonical"]
}'

# Bulk update via patch
glow fields update --body '{
  "all": true,
  "filter_department_ids": ["dept-archive"],
  "patch": { "archived": true }
}'
```

See the [Personas guide](/personas#bulk-operations) for the canonical write-up of this pattern.

## Common Operations

| Task | CLI | API Endpoint |
|---|---|---|
| List all fields | `glow fields list` | `POST /field/search` |
| Get a field | `glow fields get --body '{...}'` | `POST /field/get` |
| Create fields | `glow fields create --body '{...}'` | `POST /field/create` |
| Update fields | `glow fields update --body '{...}'` | `POST /field/update` |
| Duplicate a field | -- | `POST /field/duplicate` |
| Delete fields | `glow fields delete --body '{...}'` | `POST /field/delete` |
| Bulk delete (filter) | `glow fields delete --body '{"all": true, "filter_…": "…"}'` | `POST /field/delete` |
| Export to CSV | `glow fields export` | `POST /field/export` |
| Save a draft | `glow fields draft --body '{...}'` | `PATCH /field/draft` |
| List drafts | -- | `POST /field/drafts` |

## Related

- [Fields API](/api-reference/field)
- [Fields CLI](/cli-reference/field)
- [Parameters Guide](/parameter) -- the categories that contain fields
- [Documents Guide](/document) -- documents reference fields
- [Departments Guide](/department) -- scope fields to departments

---

# Generation

Route: /generation

# Generation

Most artifacts in Glow can be authored two ways: hand-written through
the standard CRUD surface (`create` / `draft` / `update`) or generated
by an LLM. The generated path is uniform across the 20 artifact
families and is the subject of this page.

## The generate pattern in two beats

Every artifact that supports generation exposes the same two-step
contract:

1. **Trigger.** `POST /<artifact>/generate` accepts an
   `ArtifactGenerateRequest` and returns immediately with
   `{ group_id, run_id, ... }`. The run is fire-and-return: the
   server kicks off the model calls in the background and the HTTP
   call hands you back the handles you need to follow it.
2. **Follow.** `GET /<artifact>/watch?run_id=<run_id>` is a long-lived
   Server-Sent Events stream that emits typed lifecycle events for
   that run until the terminal `*.complete` or `*.error` event lands.

The pair is the canonical fan-out: the trigger response is *the
ticket* you exchange for a stream of progress on
[/streaming](/streaming).

| Handle | Lifetime | What it scopes |
|--------|----------|----------------|
| `group_id` | The conversation / session window | Every run the actor performs in this window — re-used across many triggers, surfaced on the [Group](/group) detail view, and how `glow <art> generations` paginates history |
| `run_id` | One trigger | Exactly one generate call — the filter you pass to `/watch` so the stream is scoped to this run instead of every run in the group |

`group_id` is resolved server-side from the actor's session if you
don't pass one; `run_id` is minted by the trigger (or by the client up
front via `client_run_id` on the request if you want to subscribe
before the run exists).

---

## Triggering generation

The request body is `ArtifactGenerateRequest` — `instructions` (what
you want), an optional `config` block (operations, params,
`dangerous`), and optional modality / audio handles for media and
voice flows. Artifact type is implicit from the URL path.

**Raw HTTP:**

```bash
curl -X POST $GLOW_INSTANCE_URL/persona/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -d '{
    "instructions": ["A passive student who starts every reply with Uh..."],
    "config": { "dangerous": false }
  }'
```

Response:

```json
{
  "group_id": "9c8d…",
  "run_id":   "1f2e…",
  "produced_media": []
}
```

**glow CLI:**

```bash
# Fire-and-return — same as the curl call above
glow personas generate --body '{
  "instructions": ["A passive student who starts every reply with Uh..."]
}'
```

The trigger returns within a few hundred milliseconds regardless of
how long the underlying model work takes. Plug the returned `run_id`
into `/watch` (or use `--wait`, below) to block on completion.

---

## The `--wait` shortcut

`glow <artifact> generate --wait` rolls the trigger + watch loop into
one blocking call. The CLI fires the `POST /<artifact>/generate`,
captures the `run_id` and `group_id`, and immediately attaches to
`GET /<artifact>/watch?run_id=<run_id>`, printing each SSE frame and
exiting on the first terminal event (`*.complete` → exit 0,
`*.error`/`*.failed` → exit 1).

```bash
glow personas generate --wait --body '{
  "instructions": ["Aggressive student in CS-180, intensity 7"]
}'
```

Useful in scripts and CI: the `--wait` shortcut means a generate is
just one command and the process exit code tells you whether the
artifact was actually saved. Stream-closed without a terminal event
exits 0 (the API may end the stream when its dedup/age window
expires).

Without `--wait`, `glow <artifact> generate` is fire-and-return — the
same shape the FE uses when it has its own SSE subscription open
already.

---

## Event types you'll see

Six client-facing event types ride the watch stream. The text
lifecycle and the media lifecycle are independent — a text-only
generate emits only the first four; an image/video generate also
emits the two `Media*` variants in parallel.

| Event | Fires when | Carries |
|-------|-----------|---------|
| **`GenerationProgressEvent`** | Each resource in the run completes | `completed_resources`, `total_resources`, `percentage`, `last_completed_resource` |
| **`GenerationSavedEvent`** | The artifact row is persisted to Postgres | `artifact_id` |
| **`GenerationCompleteEvent`** | All work for the run is done (terminal) | `success`, `message`, `artifact_id` |
| **`GenerationErrorEvent`** | Any resource or the run as a whole fails (terminal) | `resource_type`, `resource_id`, `message` |
| **`GenerationMediaProgressEvent`** | Image/video generation crosses a status boundary | `modality`, `status` (`started` / `in_progress`), `message` |
| **`GenerationMediaCompleteEvent`** | An image/video asset finishes uploading | `modality`, `upload_id`, `file_size`, `mime_type` |

**Ordering you can rely on:**

- `Progress*` frames are monotonic on `completed_resources` and
  arrive before `Complete` / `Saved`.
- `Saved` always arrives before `Complete` for runs that persist an
  artifact (some media-only runs go `MediaComplete` → `Complete`
  with no `Saved`).
- `MediaProgress` with `status: "started"` precedes any
  `MediaComplete` for the same `resource_id`.
- `Error` is terminal but may arrive *with* prior `Progress` frames —
  partial failures still report what made it through.

Every event carries the `group_id` and `run_id` envelope so a single
SSE connection scoped to a `group_id` (omit `run_id` on `/watch`) can
multiplex many concurrent runs. The auto-generated schemas live under
[`/api-reference`](/api-reference) — see
[`/api-reference/persona/get-persona-watch`](/api-reference/persona/get-persona-watch)
for the persona variant, and the equivalent `get-<artifact>-watch`
page under every other artifact.

---

## Artifact-specific signatures

Most artifacts (`persona`, `agent`, `rubric`, `eval`, `tool`,
`field`, `parameter`, `document`, …) take the standard
`ArtifactGenerateRequest` body — pass `instructions` and let the
server pick operations.

A handful have an ergonomic shape on top of that contract. The most
common deviation is **scenarios**, which the CLI exposes positionally:

```bash
# glow scenarios generate <modality> <title> [--instructions <text>]
glow scenarios generate image "University Office" \
  --instructions "Wide-angle shot, late afternoon light, books on the desk"
```

The CLI translates that into the same `POST /scenario/generate` call
with `{ modality, title, instructions }` in the body. For the full
per-artifact request schema, jump to the relevant artifact page:

- [Personas](/personas) — text generation only
- [Scenarios](/scenarios) — image / video / text, `title` is the asset's display name
- [Agents](/agents) — text generation, optional `params` for graph-mode
- [Rubrics](/rubrics), [Evals](/evals), [Tools](/tools), [Fields](/fields), [Parameters](/parameters), [Documents](/documents) — standard text shape

Or read the auto-generated request body on
[`/api-reference/<artifact>/post-<artifact>-generate`](/api-reference).

---

## `glow <art> generations` — listing prior runs

Every artifact that supports generation also exposes a `generations`
endpoint that lists the `group_id`s an actor has produced for that
artifact, paginated and date-windowed.

```bash
# List the 20 most recent persona-generation groups for this actor
glow personas generations --body '{
  "page_limit": 20,
  "page_offset": 0
}'
```

Each row is a `{ group_id, group_name, session_id, created_at }` — use
`group_id` to open the full [Group](/group) detail view (every run +
every message) or to pull the audit trail. The endpoint is scoped to
the calling profile by default; admins see all generations in their
org.

Raw HTTP:

```bash
curl -X POST $GLOW_INSTANCE_URL/persona/generations \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -d '{ "search": "confused", "page_limit": 50 }'
```

The response carries an `items` list of
`{ group_id, session_id, group_name, created_at }` rows plus a
`total_count` for the matching window. Combine with `date_from` /
`date_to` to scope a sweep.

---

## Common operations reference

| Task | CLI | API |
|------|-----|-----|
| Trigger a generate (fire-and-return) | `glow <art> generate --body '{...}'` | `POST /<art>/generate` |
| Trigger + block on completion | `glow <art> generate --wait --body '{...}'` | `POST /<art>/generate` then `GET /<art>/watch?run_id=...` |
| Stream events for one run | `glow <art> watch <run_id>` | `GET /<art>/watch?run_id=<run_id>` |
| Stream every event in a group | `glow <art> watch --group <group_id>` | `GET /<art>/watch?group_id=<group_id>` |
| List prior generations | `glow <art> generations --body '{...}'` | `POST /<art>/generations` |
| Inspect one group's full tree | `glow system group --body '{"group_id":"...","include_detail":true}'` | `POST /system/group` |

## Related

- [Streaming](/streaming) — SSE plumbing details, reconnect semantics, and the `/watch` event envelope
- [Media](/media) — image, video, and audio generation modalities and the produced-media handoff
- [Group](/group) — the audit view of every run inside a single `group_id`
- [Personas](/personas), [Scenarios](/scenarios), [Agents](/agents) — per-artifact pages with concrete generate request bodies
- [API Reference](/api-reference) — auto-generated request / response schemas for every `<art>/generate`, `<art>/generations`, and `<art>/watch` endpoint

---

# Group

Route: /group

# Group

Group provides detailed information about an AI generation group —
the collection of model calls (runs) and messages produced during a
training interaction. This is the deepest level of inspection for
understanding exactly what the AI generated and how it was used.

Group is a **view on the system artifact**, exposed via two endpoints:

* `POST /system/group` — single group detail (lean resolve or full
  detail tree depending on `include_detail` in the body).
* `POST /system/groups` — paginated list of all groups (also surfaces
  cost / pricing data; this is what powers the [Pricing](/pricing)
  page's group-history table).

The CLI surfaces these as `glow system group` and `glow system groups`.

## What is Group?

When a TA interacts with a student persona simulation, Glow creates a **group** that tracks all AI model runs and messages in that interaction. A group contains:

- Multiple **runs**, each representing a single AI model invocation with input/output token counts and cost
- **Messages** within each run, organized by role (system, user, assistant) with support for text, audio, image, video, and file uploads
- **Tool calls** made during the interaction
- Metadata about which **models**, **agents**, and **profiles** participated

Groups are essential for debugging AI behavior, auditing training interactions for academic integrity, reviewing FERPA-sensitive conversations, and understanding token consumption patterns.

## Quick Start

### CLI

> Calls below use `$GLOW_INSTANCE_URL` + `$GLOW_TOKEN` — see [Authentication](/authentication) to export them once.

```bash
# Lean resolve — group identity only (cheap path used by audit linking)
glow system group --body '{"group_id": "group-uuid"}'

# Full detail tree with all runs + messages
glow system group --body '{"group_id": "group-uuid", "include_detail": true, "message_limit": 50}'

# Paginate all groups (used by Pricing's group-history table)
glow system groups --body '{"page_size": 25}'

# Export group data as a ZIP
glow system export --body '{"target_group_id": "group-uuid"}'
```

### API

```bash
# Get one group (set include_detail for the full tree)
curl -X POST $GLOW_INSTANCE_URL/system/group \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "group-uuid",
    "include_detail": true,
    "message_limit": 100,
    "message_offset": 0
  }'

# List groups (pricing / cost view)
curl -X POST $GLOW_INSTANCE_URL/system/groups \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"page_size": 20}'
```

## Lean vs. detail

## Request fields

| Field | Type | Required | Description |
|---|---|---|---|
| `group_id` | `string` | Yes | UUID of the group to fetch |
| `include_detail` | `boolean` | No | `true` returns the full detail tree (runs + messages). Default `false` returns lean identity for audit linking. |
| `message_limit` | `integer` | No | Maximum number of messages to return (when `include_detail=true`) |
| `message_offset` | `integer` | No | Offset for message pagination |

## Understanding the detail response

The full-detail response (`include_detail=true`) includes:

- **`group_exists`** -- Whether the group was found.
- **`actor_name`** -- Display name of the current user.
- **`group_name`** -- Display name of the group.
- **`total_message_count`** -- Total messages in the group (for pagination).

### Runs

The **`runs`** array contains `GroupDetailRunWithMessages` objects:

Each run has:
- **`run`** -- Run metadata:
  - `id` -- UUID of the run
  - `created_at` -- Timestamp
  - `input_tokens`, `output_tokens`, `cached_input_tokens` -- Token counts
  - `cost` -- Dollar cost of this run
  - `model_id` -- Which AI model was used
  - `agent_id` -- Which agent processed the run
  - `profile_id` -- Which user triggered the run
- **`messages`** -- Array of `GroupDetailMessageItem` objects:
  - `id` -- UUID
  - `role` -- Message role (system, user, assistant)
  - `text_upload_ids` -- UUIDs for text content
  - `audio_upload_ids`, `image_upload_ids`, `video_upload_ids`, `file_upload_ids` -- Media upload UUIDs
  - `calls` -- Tool/function calls made, each with `id`, `template_name`, `file_path`, `created_at`
- **`previous_context_start_index`** -- Where previous context starts in the message array (for understanding context windows)

### Resources

- **`models`** -- Models used, each with `model_id` and `name`.
- **`agents`** -- Agents used, each with `agent_id` and `name`.
- **`profiles`** -- Profiles involved, each with `profile_id` and `name`.

## Downloading media

Messages reference uploaded media via their `*_upload_ids` fields. The
canonical download path is the system artifact's media endpoints:

| Media kind | Endpoint |
|---|---|
| audio | `POST /system/audio_download` |
| image | `POST /system/image_download` |
| video | `POST /system/video_download` |
| file | `POST /system/file_download` |
| text | `POST /system/text_download` |

Each takes the relevant `<kind>_upload_id` in the body and supports
range requests for large files.

## Listing groups

## AI generation flow

Groups are created as part of the AI generation flow, which produces
stream events (delivered over SSE via `POST /<artifact>/watch`):

1. **`GenerationProgressEvent`** -- Reports `completed_resources` / `total_resources` and `percentage`.
2. **`GenerationCompleteEvent`** -- Indicates success or failure for an `artifact_type`.
3. **`GenerationSavedEvent`** -- Confirms the artifact was saved.
4. **`GenerationErrorEvent`** -- Reports errors with `message` details.
5. **`GenerationMediaProgressEvent`** / **`GenerationMediaCompleteEvent`** -- Track image/video generation.

Each event references the `group_id` and `run_id`.

## Common Operations

| Task | CLI | API Endpoint |
|---|---|---|
| Get one group (lean) | `glow system group` | `POST /system/group` |
| Get one group (full detail) | `glow system group --body '{"include_detail":true}'` | `POST /system/group` |
| List groups (pricing) | `glow system groups` | `POST /system/groups` |
| Export group data | `glow system export` | `POST /system/export` |
| Refresh caches | `glow system refresh` | `POST /system/refresh` |

## Related

- [System API Reference](/api-reference/system) — every system/* endpoint
- [System CLI Reference](/cli-reference/system) — every `glow system ...` command
- [Session](/session) — session-level view that lists groups
- [Pricing](/pricing) — aggregated cost view across all groups
- [Invocation](/invocation) — AI model call tracking inside tests

---

# Health

Route: /health

# Health

The Health resource provides service health monitoring and system metrics for your Glow instance. Use it to track uptime, latency, CPU, memory, and error rates over time. Health is an API-only resource with no CLI commands.

![Health page showing system status indicators for database, AI providers, and services](/screenshots/health/status.png)

## What is Health?

Health aggregates hourly service check results and system metrics into time-series views. It answers questions like: Is the instance healthy? What was the uptime last week? Are latency or error rates trending up? Administrators use health data to monitor their university's Glow deployment and diagnose performance issues before they affect users.

The health response includes two materialized views:

- **`service_hourly`** -- per-hour uptime, check counts, latency, and error status for each monitored service.
- **`metrics_hourly`** -- per-hour CPU, memory, request counts, and error totals.

## Quick Start

### API

**Fetch health data** for the last 7 days:

> Calls below use `$GLOW_INSTANCE_URL` + `$GLOW_TOKEN` — see [Authentication](/authentication) to export them once.

```bash
curl -X POST $GLOW_INSTANCE_URL/system/health \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "date_from": "2026-03-21",
    "date_to": "2026-03-28",
    "page_limit": 100,
    "page_offset": 0
  }'
```

**Filter by service:**

```bash
curl -X POST $GLOW_INSTANCE_URL/system/health \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service": "glow-api",
    "date_from": "2026-03-21",
    "date_to": "2026-03-28"
  }'
```

## Understanding the Response

### Service Hourly View

Each `service_hourly` entry contains:

| Field | Description |
|---|---|
| `date_hour` | Hour bucket (e.g., `"2026-03-28T14:00:00Z"`) |
| `service` | Service name (e.g., `"glow-api"`) |
| `check_count` | Total health checks in this hour |
| `ok_count` | Successful checks |
| `fail_count` | Failed checks |
| `uptime_percent` | Uptime as a percentage (0--100) |
| `avg_latency_ms` | Average response latency in milliseconds |
| `min_latency_ms` | Minimum latency observed |
| `max_latency_ms` | Maximum latency observed |
| `latest_ok` | Whether the most recent check passed |
| `latest_error` | Error message from the most recent failure (empty if healthy) |

### Metrics Hourly View

Each `metrics_hourly` entry contains:

| Field | Description |
|---|---|
| `date_hour` | Hour bucket |
| `sample_count` | Number of metric samples collected |
| `avg_cpu_percent` / `min` / `max` | CPU utilization |
| `avg_latency_ms` / `min` / `max` | Request latency |
| `avg_memory_bytes` / `min` / `max` | Memory usage |
| `max_requests_total` | Peak total request count |
| `max_errors_total` | Peak total error count |

## Refreshing and Exporting

**Refresh materialized views** to ensure health data is current:

```bash
curl -X POST $GLOW_INSTANCE_URL/system/refresh \
  -H "Authorization: Bearer $GLOW_TOKEN"
```

Returns `success`, `refreshed_views`, and `invalidated_tags`.

**Export health data** as a denormalized ZIP for offline analysis:

```bash
curl -X POST $GLOW_INSTANCE_URL/system/export \
  -H "Authorization: Bearer $GLOW_TOKEN"
```

Returns `content` (base64-encoded), `file_name`, `mime_type`, and `row_count`.

## Common Operations

| Operation | Method | Endpoint |
|---|---|---|
| Get health data | `POST` | `POST /system/health` |
| Refresh views | `POST` | `POST /system/refresh` |
| Export data (ZIP) | `POST` | `POST /system/export` |
| Get documentation | `POST` | `/health/docs` |

## Related

- [Health API](/api-reference/system)
- [Info Guide](/info) -- quick server status check

---

# Home

Route: /home

# Home

Home is the TA landing page in Glow. It displays the training simulations assigned to the current TA, along with their progress status and attempt history. This is where TAs go to start, continue, or review their office-hours practice sessions.

![Home dashboard showing assigned simulations and recent attempt history with scores](/screenshots/home/dashboard.png)

## What is Home?

Home provides two views for TAs:

1. **Simulation cards** (`POST /attempt/home`) -- A list of assigned simulations showing the TA's name, each simulation's persona (Confused, Aggressive, Passive, or Happy student), progress status (not-started, in-progress, passed), highest score, and pass threshold.
2. **Attempt history** (`POST /attempt/search`) -- A paginated table of the TA's past attempts, with scores, scenario details, and actions (view, continue).

Home also returns rubric and standard mappings so the UI can display which Communication Skills, Policy Knowledge, and De-escalation standards are being assessed for each simulation.

## Quick Start

### CLI

> Calls below use `$GLOW_INSTANCE_URL` + `$GLOW_TOKEN` — see [Authentication](/authentication) to export them once.

```bash
# Get assigned simulations for the current TA
glow attempts home

# Search the TA's attempt history
glow attempts search --body '{"page": 1, "page_size": 20, "sort_order": "desc"}'

# Export home data with certificate
glow attempts export
```

### API

```bash
# Get simulation cards
curl -X POST $GLOW_INSTANCE_URL/attempt/home \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

# Search attempt history
curl -X POST $GLOW_INSTANCE_URL/attempt/search \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "page_size": 10,
    "sort_by": "date",
    "sort_order": "desc"
  }'
```

## Understanding the Simulation Cards

The `POST /attempt/home` response includes:

- **`actor_name`** -- Display name of the currently logged-in TA.
- **`items`** -- Array of `ChatSimulationOperational` objects, one per assigned simulation:
  - `simulation_id`, `simulation_name`, `simulation_description` -- Simulation identity
  - `color`, `icon` -- Persona display properties (e.g., red for Aggressive, blue for Confused)
  - `status` -- One of `"passed"`, `"in-progress"`, or `"not-started"`
  - `highest_score` -- Best score achieved (percentage)
  - `pass_pct` -- Pass threshold percentage
  - `has_passed` -- Whether the TA has passed this simulation
  - `num_sessions` -- Number of attempt sessions
  - `time_limit` -- Time limit in seconds for each attempt
  - `scenario_ids` -- Ordered list of scenario UUIDs
  - `cohort_ids`, `cohort_names_junction` -- Cohort membership
  - `view_mode` -- `"member"` for standard TA view, `"instructional"` for lead TA/admin view
  - `standard_groups` -- Standard group IDs for rubric display
  - For instructional view: `completion_pct`, `passed_count`, `in_progress_count`, `not_started_count`
- **`rubrics`** -- Rubric mappings with `rubric_id`, `name`, and `standard_group_ids`.
- **`standard_groups`** -- Standard group metadata: `name`, `description`, `points`, `pass_points`.
- **`standards`** -- Individual standards: `name`, `description`, `points`, grouped by `standard_group_id`.

## Understanding the Attempt History

![Home attempt history showing individual scores per scenario with pass/fail indicators](/screenshots/home/attempt-history.png)

The `POST /attempt/search` response returns paginated `HistoryItem` rows:

- `attempt_id`, `date` -- Attempt identity and formatted date
- `simulation_id`, `simulation_name` -- Which simulation was attempted
- `score`, `score_status` -- Score percentage and pass/fail label
- `pass_pct` -- Pass threshold
- `num_scenarios`, `num_scenarios_completed` -- Progress through scenarios
- `persona_names_junction`, `persona_colors_junction` -- Persona details
- `scenario_ids`, `scenario_titles` -- Scenario breakdown
- `show_view`, `show_continue` -- Available actions
- `infinite_mode` -- Whether the attempt used infinite mode
- `is_archived` -- Whether the attempt is archived

### Filtering History

| Filter | Field | Description |
|---|---|---|
| Simulation search | `simulation_search` | Text search across simulation names |
| Scenario search | `scenario_search` | Text search across scenario titles |
| Scenario filter | `scenario_ids` | Filter by specific scenarios |
| Infinite mode | `infinite_mode` | Filter by infinite mode status |
| Sorting | `sort_by`, `sort_order` | Sort by any column |
| Pagination | `page`, `page_size` | Control page size |

## Exporting

The export endpoint generates a denormalized ZIP that includes a certificate of completion:

```bash
glow attempts export
```

The response includes `content` (base64-encoded), `file_name`, `mime_type`, and `row_count`.

## Common Operations

| Task | CLI | API Endpoint |
|---|---|---|
| Get assigned simulations | `glow attempts home` | `POST /attempt/home` |
| Search attempt history | `glow attempts search` | `POST /attempt/search` |
| Export with certificate | `glow attempts export` | `POST /attempt/export` |
| Refresh caches | -- | `POST /attempt/refresh` |

## Related

- [Home API Reference](/api-reference/attempt)
- [Home CLI Reference](/cli-reference/attempts)
- [Practice Guide](/practice) -- open practice with student personas
- [Record Guide](/record) -- individual TA training history (admin view)

---

# How AI Simulation Training Works

Route: /how-it-works

# How AI Simulation Training Works

This page explains the ideas behind simulation-based training — why it works, what the building blocks are, and how to think about designing effective simulations. You don't need any technical background to follow along.

## Why Simulation Training Works

Most training is passive. People watch videos, read policies, or sit through lectures. Then they're expected to perform under pressure with real people. The gap between "knowing" and "doing" is where most failures happen.

Simulation training closes that gap by letting people **practice before the stakes are real**.

There are four reasons it works:

**Practice beats passive learning.** Research consistently shows that active recall — actually doing the thing, not just reading about it — produces dramatically better retention. A teaching assistant who practices handling a frustrated student five times will outperform one who watched a training video about it.

**Safe failure is the best teacher.** In a simulation, getting it wrong has no consequences. There's no real student who leaves upset, no customer who churns, no patient who gets the wrong advice. Glow supports this with backtracking (undo a message and try a different approach) and practice mode (retry freely without scores counting), so learners can experiment without fear.

**Immediate, structured feedback accelerates learning.** In traditional training, feedback comes days or weeks later — if it comes at all. In simulation training, every conversation gets graded in seconds against specific criteria with named levels. Instead of "you did okay," learners see: *"Active Listening: Acceptable (3/5) — Occasionally guided the student with questions but sometimes provided direct answers."* They know exactly what to work on.

**Repetition with variation builds intuition.** Glow generates scenarios by combining personas, course material, and environmental parameters (time of day, deadline pressure, room crowdedness, emotional intensity). The same rubric criteria get tested across meaningfully different situations, building the kind of adaptable skill that a single role-play session can't.

## The Building Blocks

Before thinking about any specific tool or platform, every simulation training program needs the same core ingredients:

### A character with personality and rules (Persona)

The person your learner talks to. Not a generic chatbot — a character with a name, a backstory, a mood, and specific behavioral rules that create realistic challenge.

The most important design principle, learned through extensive testing: **the AI character must not be able to solve the problem on its own.** In Glow, personas are designed so they can only make progress when the learner provides specific, relevant guidance using course terminology. If the learner asks a vague question like "What do you think?", the persona pushes back, gets more confused, or shuts down — just like a real person would.

This single rule is what makes the simulation *training* rather than just *conversation*. It forces the learner to actually teach.

A well-designed persona has:
- A **role and emotional state** — not "a student" but "a frustrated senior who believes their grade was unfair and has been waiting 20 minutes"
- **Behavioral rules** — how they react to good vs. bad teaching. An aggressive persona de-escalates when the learner acknowledges their frustration; a passive persona opens up only to specific, targeted questions
- **Knowledge boundaries** — what they know and don't know, and crucially, what misconceptions they hold
- **"Show, don't tell" design** — the persona's traits are demonstrated through behavior, never labeled. Instead of "a passive student," the scenario reads: "A student stands quietly at the edge of the room, clutching their notes, hesitating before approaching"

### A situation with context (Scenario)

The context that puts the learner in a position where they need to use their skills. A good scenario has:
- A **problem statement** — what's happening, written to *show* the persona's emotional state rather than *tell* it
- **Documents** — real course material (assignments, syllabi, problem sets) that ground the scenario in specifics
- **Objectives** — what the learner is trying to achieve
- **Environmental parameters** — time, location, crowdedness, deadline pressure, and intensity that shape the atmosphere

Scenarios work best when they're generated from real situations. In Glow's university deployment, every scenario is grounded in actual course documents (CS 180 homework on loops, EAPS 106 project on plate boundaries, MA 261 quiz on multivariable calculus). This specificity is what makes practice feel real and transfers to actual performance.

### Criteria for what "good" looks like (Rubric)

The scoring framework that defines what a successful interaction looks like. Without this, you're just having conversations — not training.

Glow uses rubrics with **named performance levels** rather than just numbers. Each criterion has five levels (Poor, Marginal, Acceptable, Good, Excellent) with specific behavioral descriptions:

| Level | Score | Active Listening Example |
|---|---|---|
| Poor | 1 | Directly provided the answer |
| Marginal | 2 | Rarely uses questioning techniques, often resorting to hints or partial solutions |
| Acceptable | 3 | Occasionally guides students with questions but sometimes provides direct answers |
| Good | 4 | Regularly uses guided questioning, encouraging student reasoning with occasional prompts |
| Excellent | 5 | Consistently employs open-ended questions that empower students to discover solutions independently |

This specificity serves two purposes: it gives the AI grader clear criteria to evaluate against, and it gives the learner a concrete roadmap for improvement. A score of 3 isn't just "average" — it means something specific and actionable.

### Real-time support (Hints)

Because simulation training can be challenging — especially the first time — Glow provides optional hints during the conversation. Each hint covers a different aspect of the interaction: emotional support strategies, content clarification techniques, and pedagogical approaches. Hints help learners who are stuck without giving away the answer.

### A way to measure and report performance

The system that turns rubric scores into actionable insights — both for the individual learner ("here's what to work on") and for the training designer ("here's where the cohort is struggling"). Glow provides dashboards, reports, leaderboards, and LMS-compatible exports.

## The Design Loop

Great simulations aren't designed in one pass. They're iterated into existence through a cycle that Glow's deployment at Purdue refined over a year of real-world use:

### 1. Start with the skill, not the tool

Before you open any editor, answer: **what specific skill are you trying to develop?** Not "customer service" — that's too broad. Something like "de-escalating a frustrated customer who has already been transferred twice."

The specificity of your skill definition determines the quality of everything that follows.

### 2. Design the rubric first

This is counterintuitive — most people want to build the persona and scenario first because that's the fun part. But starting with the rubric forces you to define what "good" actually looks like before you build the training.

Ask yourself: if a learner does this perfectly, what specifically would I observe? Those observations become your rubric standards. Write the behavioral descriptions for each level — what does a 1 look like? A 3? A 5?

### 3. Build personas that test those rubric criteria

Now design characters that create the right level of challenge for the skills you're measuring. If your rubric measures de-escalation, you need a persona who escalates. If it measures guided questioning, you need a persona who won't progress unless guided well.

The hardest part of persona design — and the area that required the most iteration in practice — is getting the AI to convincingly stay in character. Key lessons:
- Be explicit about what the persona is NOT allowed to do (solve problems independently, break character, offer help)
- Provide example conversations showing the expected interaction style
- Define escalation and de-escalation triggers tied to the learner's behavior
- Keep the persona's language natural and age-appropriate

### 4. Test it yourself

This is the step most people skip, and it's the most important one. Before giving the simulation to anyone else, **practice it yourself**. Talk to the AI character. See if the conversation feels realistic. See if the rubric scores match your intuition about how the conversation went.

If you played the scenario perfectly and got a mediocre rubric score, your rubric needs work. If the persona agreed too easily, it needs more resistance. If the persona broke character and started teaching instead of asking for help, the instructions need tightening.

### 5. Run with a small group

Deploy to 3-5 people. Watch the scores. Read the conversations. Look for patterns:
- Are scores clustered? The rubric might not differentiate well.
- Are learners confused about what to do? The scenario briefing needs more context — consider enabling hints.
- Do conversations end too quickly? The persona needs more depth.
- Is the grading consistent? Review a few transcripts yourself and compare your evaluation to the AI's.

### 6. Iterate and expand

Adjust based on what you learned. Then scale: add more scenarios to test different facets of the skill, add more challenging personas, create a progression from easy to hard. Use parameters to generate scenario variations without starting from scratch each time.

## Common Pitfalls

### Personas that solve problems on their own

The most damaging mistake. If the AI character reasons through the problem, offers suggestions, or makes progress without the learner's input, the simulation teaches nothing — the learner just watches the AI work.

**Fix:** Be explicit in the persona instructions: "You are NOT allowed to solve the question independently, even partially. You may ONLY make progress if the user's response directly uses relevant terminology and logically builds on what you just said." This single rule transforms the simulation from a conversation into actual training.

### Personas that break character

AI models are trained to be helpful assistants. When asked to play a confused student, they may slip into explaining concepts, asking guiding questions, or managing the conversation — behaviors that belong to the *teacher*, not the student.

**Fix:** Add explicit boundaries: "Never explain concepts from a position of authority. Never ask the user to 'calm down' or manage the conversation's flow. Never offer to 'look at the problem together.' You are the student — you need help, not the other way around." Also provide example conversations showing exactly the expected back-and-forth.

### Rubrics that are too vague

Criteria like "communicates well" or "handles the situation appropriately" are nearly useless for grading. The AI doesn't know what you mean, and neither will the learner reviewing their feedback.

**Fix:** Make every standard observable and specific. Instead of "shows empathy," write "acknowledges the other person's emotional state before transitioning to problem-solving." Give each score level a concrete behavioral description, not just a number.

### Not accounting for cheating

In real deployments, learners will copy AI character messages into ChatGPT and paste back generated responses. This is especially common in text-based simulations.

**Fix:** Glow provides multiple mitigations: disable copy-paste in the simulation, use audio-only mode for higher-stakes assessments, and enable input guardrails that detect unnaturally long or formatted responses. Design your assessment approach with these options in mind.

### Punishing failure instead of encouraging exploration

If learners lose all progress when they fail one scenario, or can't undo a bad message, they'll play it safe instead of experimenting. This undermines the entire point of simulation training.

**Fix:** Use practice mode for skill development, enable hints for support, and allow message backtracking so learners can try different approaches to the same conversation moment. Save formal assessment mode for when scores actually count.

## Beyond University TAs

Glow was built and validated training TAs, but the same framework generalizes to any domain where people practice interpersonal skills. The building blocks stay the same — only the personas, rubrics, scenarios, and parameters change.

### How the Framework Translates

| University | Enterprise | What changes |
|---|---|---|
| **Personas:** Confused, Aggressive, Passive, Happy students | **Personas:** Frustrated employee, Anxious report, Defensive team member, Enthusiastic new hire, Manager | Different emotional profiles, same behavioral rules (can't solve independently, show-don't-tell, escalation/de-escalation paths) |
| **Parameters:** Class, Location, Crowdedness, Deadline, Intensity, Time | **Parameters:** Employee Level (Junior → Executive), Years with Company, Job Position (Engineer, Designer, Analyst, Manager) | Different context dimensions, same parameterization system |
| **Rubric:** Adaptability, Content Mastery, Active Listening, Communication, Time Management | **Rubric:** Empathy, Policy Knowledge, Conflict Resolution, Professional Tone, Follow-through | Different criteria, same 5-level structure with behavioral descriptions |
| **Scenarios:** Office hours help sessions, grade disputes, confused students | **Scenarios:** One-on-ones, performance reviews, delivering difficult feedback, handling termination conversations | Different situations, same design principles (show-don't-tell, objectives, documents) |

### What Stays the Same Across Domains

The core design principles that make simulations effective don't change:

- **The persona can't solve independently** — whether it's a student who can't figure out loops or an employee who can't accept negative feedback, the AI character should only progress when the learner demonstrates the right skills
- **The rubric defines what "good" looks like** — with named performance levels and behavioral descriptions, not just numbers
- **Scenarios are grounded in real situations** — use actual company policies, performance review templates, or HR guidelines as documents, just like university courses use real homework assignments
- **Progressive difficulty applies everywhere** — start with an enthusiastic new hire (easy), work up to a defensive senior employee (hard)

### Multi-Discipline in Education

Even within education, the framework extends beyond CS. Glow has been used with course material spanning computer science, earth science, biology, chemistry, physics, mathematics, and statistics. The personas and rubric stay the same — a confused student is a confused student whether they're stuck on pointers or plate tectonics. The scenarios and documents change to match the discipline.

## Next Steps

- [Design Your First Simulation](/tutorial) — a hands-on tutorial that walks through building a complete simulation from scratch
- [Annotated Example](/annotated-example) — see what excellent and poor conversations actually look like, with rubric scores and commentary
- [Patterns & Best Practices](/patterns) — quick recipes for common design challenges
- [Start](/start) — set up your Glow instance and start building

---

# Invocation

Route: /invocation

# Invocation

Invocations are the per-row units inside a test — each one represents
a single AI model call made during a benchmark or batch run, with its
own configuration, status, trace, and grading.

Invocation is a **sub-namespace on the test artifact**. Every operation
is named `invocation_<op>` and lives at `POST /test/invocation_<op>`:
`invocation_get`, `invocation_run`, `invocation_complete`, etc. The
CLI surfaces them as `glow tests invocation <op>`.

## What is an Invocation?

An invocation captures everything needed to make and grade one AI
model call inside a test:

- **`invocation_id`** — unique identifier
- **`test_id`** — the parent test
- **`model` / `agent` / `provider`** — what's being called
- **`modalities`** — text / audio / image / video supported
- **`status`** — queued / running / completed / failed / terminated
- **`trace`** — full execution trace (prompts, intermediate calls, responses)
- **`scores`** — per-rubric-standard scores when graded

Invocations are created when a test fans out (e.g., one invocation per
scenario × model combination). They run independently and report back
into the parent test for aggregation in the [Benchmark](/benchmark)
view.

## The invocation sub-op surface

| Sub-op | Endpoint | Purpose |
|---|---|---|
| `invocation_get` | `POST /test/invocation_get` | hydrate one invocation by id |
| `invocation_create` | `POST /test/invocation_create` | seed a new invocation (rare; tests fan out automatically) |
| `invocation_run` | `POST /test/invocation_run` | start / re-fire an invocation |
| `invocation_complete` | `POST /test/invocation_complete` | mark complete |
| `invocation_terminate` | `POST /test/invocation_terminate` | terminate an in-flight invocation |
| `invocation_trace` | `POST /test/invocation_trace` | fetch the full execution trace |
| `invocation_draft` / `invocations` | `POST /test/invocation_draft` / `POST /test/invocations` | edit draft / list invocations |

The list endpoint is plural (`POST /test/invocations`) since it
returns a row collection, while the single-target ops use the
singular concatenated form.

## Quick Start

### CLI

> Calls below use `$GLOW_INSTANCE_URL` + `$GLOW_TOKEN` — see [Authentication](/authentication) to export them once.

```bash
# Hydrate a single invocation
glow tests invocation get --body '{"invocation_id": "invocation-uuid"}'

# Fan out / re-fire an invocation
glow tests invocation run --body '{"invocation_id": "invocation-uuid"}'

# Pull the full trace
glow tests invocation trace --body '{"invocation_id": "invocation-uuid"}'

# List invocations for a test
glow tests invocations --body '{"test_id": "test-uuid"}'
```

### API

```bash
# Get invocation detail
curl -X POST $GLOW_INSTANCE_URL/test/invocation_get \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"invocation_id": "invocation-uuid"}'

# List invocations (paginated)
curl -X POST $GLOW_INSTANCE_URL/test/invocations \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"test_id": "test-uuid", "page_size": 25}'
```

## Invocations in the test flow

When a test runs, the server fans out one invocation per benchmark
cell (typically: scenario × model × agent). Each invocation:

1. Resolves the model + agent configuration from the test setup
2. Issues the model call(s) — recorded in `trace`
3. Grades the resulting transcript against the test's rubric
4. Writes per-standard scores back onto the row
5. Reports `status = completed` (or `failed` / `terminated`)

The parent test's response aggregates invocations into
`AggregatedResults` for benchmark UIs.

## Status lifecycle

| Status | Meaning |
|---|---|
| `queued` | created, not yet started |
| `running` | model call in flight |
| `completed` | model call done, scores written |
| `failed` | model call errored — see `trace` for details |
| `terminated` | cancelled via `invocation_terminate` |

Use `invocation_run` to (re-)kick a queued or failed invocation; use
`invocation_terminate` to stop a `running` one safely.

## Trace

```bash
curl -X POST $GLOW_INSTANCE_URL/test/invocation_trace \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"test_id": "test-uuid", "test_invocation_id": "test-invocation-uuid"}'
```

Returns a `test_invocation_trace_id` — the trace entry binding the
invocation to its bundle config and recorded run, the anchor every
replay or audit of this cell resolves against. Pass `run_id` to bind a
specific recorded run.

## Listing and paginating

## Common Operations

| Task | CLI | API |
|---|---|---|
| Get one invocation | `glow tests invocation get` | `POST /test/invocation_get` |
| List invocations | `glow tests invocations` | `POST /test/invocations` |
| Run / re-fire | `glow tests invocation run` | `POST /test/invocation_run` |
| Terminate | `glow tests invocation terminate` | `POST /test/invocation_terminate` |
| Fetch trace | `glow tests invocation trace` | `POST /test/invocation_trace` |
| Mark complete | `glow tests invocation complete` | `POST /test/invocation_complete` |
| Save draft | `glow tests invocation draft` | `POST /test/invocation_draft` |
| List drafts | `glow tests invocation drafts` | `POST /test/invocation_drafts` |

## Related

- [Test API Reference](/api-reference/test) — every invocation_* endpoint with full schemas
- [Tests CLI Reference](/cli-reference/tests) — every `glow tests ...` command
- [Benchmark](/benchmark) — the aggregated view across all invocations in a test
- [Pricing](/pricing) — cost tracking for invocation runs
- [Group](/group) — generation group rows that capture invocation cost

---

# Leaderboard

Route: /leaderboard

# Leaderboard

The Leaderboard ranks TAs by training performance, highlighting top performers and awarding accolades. It helps program coordinators identify which TAs are excelling and which may need additional support with office-hours simulations.

![Leaderboard showing ranked learners with scores, pass rates, and improvement indicators](/screenshots/leaderboard/rankings.png)

## What is Leaderboard?

Leaderboard computes ranked profiles from training data and organizes them into sections:

- **Header Metrics** -- Total profiles, total attempts, average score, perfect scores.
- **Rankings** -- A sortable table of TAs ranked by composite metrics.
- **Accolades** -- Awards for specific achievements (highest scorer, perfect score, longest conversation, best response times, quickest pass, most persistent, marathon runner, rapid riser).
- **Trends** -- Trend data for tracking improvement over time.

Leaderboard answers questions like:
- Which TAs scored highest on the Aggressive Student simulation this semester?
- Who achieved a perfect score on the De-escalation rubric?
- Which TAs are improving most rapidly?

## Quick Start

### CLI

> Calls below use `$GLOW_INSTANCE_URL` + `$GLOW_TOKEN` — see [Authentication](/authentication) to export them once.

```bash
# Get the full leaderboard with header metrics and accolades
glow attempts leaderboard

# Get leaderboard filtered by cohort and date range
glow attempts leaderboard --body '{"cohort_ids": ["fall-2025-cs101"], "start_date": "2025-01-01", "end_date": "2025-06-30"}'

# Search leaderboard rankings (paginated, sortable)
glow attempts search --body '{"sort_by": "highest_score_avg", "sort_order": "desc", "page_limit": 25}'

# Export leaderboard data
glow attempts export
```

### API

```bash
# Get leaderboard summary
curl -X POST $GLOW_INSTANCE_URL/attempt/leaderboard \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "department_ids": ["dept-cs"],
    "start_date": "2025-01-01",
    "end_date": "2025-06-30"
  }'

# Search ranked profiles
curl -X POST $GLOW_INSTANCE_URL/attempt/search \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "simulation_ids": ["sim-confused-student"],
    "sort_by": "highest_score_avg",
    "sort_order": "desc",
    "page_limit": 20,
    "page_offset": 0
  }'
```

## Filtering

| Filter | Field | Description |
|---|---|---|
| Date range | `start_date`, `end_date` | Scope to a semester or custom window |
| Cohorts | `cohort_ids` | Filter by training cohort |
| Departments | `department_ids` | Filter by academic department |
| Simulations | `simulation_ids` (search) | Filter by specific simulations |
| Scenarios | `scenario_ids` (search) | Filter by individual scenarios |
| Profile search | `search` (search) | Text search across TA names |
| Single TA | `target_profile_id` | Highlight a specific TA |
| Sorting | `sort_by`, `sort_order` | Sort by any metric column |
| Pagination | `page_limit`, `page_offset` | Control page size |

## Rankings table

## Understanding the Leaderboard Summary

The `POST /attempt/leaderboard` response includes:

### `sections`

- **`header_metrics`** -- `total_profiles`, `total_attempts`, `average_score`, `perfect_scores`. Each metric has `current_value`, `has_data`, and trend data.
- **`rankings`**, **`accolades`**, **`trends`**, **`filters`** -- Section status objects indicating `has_data` and `status`.
- **`accolade_winners`** -- Named accolade winners:
  - `highest_scorer` -- TA with the top average score
  - `perfect_score` -- First TA to achieve 100%
  - `longest_convo` -- Deepest engagement with a student persona
  - `response_times` -- Fastest persona response times
  - `quickest_pass` -- Fastest time to pass a simulation
  - `the_persistent` -- Most total attempts
  - `marathon_runner` -- Most time invested
  - `rapid_riser` -- Steepest improvement curve

Each winner includes `profile_id`, `name`, `value`, and `details`.

### `resources`

Resource metadata keyed by ID: `profiles`, `simulations`, `scenarios`.

## Score trends and accolades

## Understanding Search Results

The `POST /attempt/search` response returns `LeaderboardDataRow` items:

- `rank` -- Position on the leaderboard
- `profile_id`, `name` -- TA identity
- `simulation_ids`, `scenario_ids` -- Associated training content
- `metrics_entry` -- Per-row metrics:
  - `total_attempts` -- Total training attempts
  - `highest_score_avg` -- Average of highest scores
  - `messages_per_session` -- Engagement depth
  - `persona_response_seconds` -- Response time to student personas
  - `time_spent_minutes` -- Total training time
  - `improvement_rate_per_day` -- Daily improvement rate
  - `perfect_score_count` -- Number of perfect scores
  - `quickest_pass_minutes` -- Fastest pass time

## Scoping the leaderboard

## Common Operations

| Task | CLI | API Endpoint |
|---|---|---|
| Leaderboard summary | `glow attempts leaderboard` | `POST /attempt/leaderboard` |
| Search rankings | `glow attempts search` | `POST /attempt/search` |
| Export data | `glow attempts export` | `POST /attempt/export` |
| Refresh caches | -- | `POST /attempt/refresh` |

## Related

- [Leaderboard API Reference](/api-reference/attempt)
- [Leaderboard CLI Reference](/cli-reference/attempts)
- [Reports Guide](/reports) -- full training reports
- [Record Guide](/record) -- single-TA performance view

---

# MCP

Route: /mcp

# MCP

Glow exposes its tool catalog over the **Model Context Protocol** at
`/mcp/`. The mount is a [FastMCP](https://github.com/modelcontextprotocol/python-sdk)
streamable-HTTP app, so any MCP-aware client (Claude Desktop, an
agent runtime, the `glow mcp` CLI) can list and call the same tools
the generate pipeline uses internally.

## What's exposed

`/mcp/` is mounted at the root of the API server:

```python
# core/app/server.py
from app.routes.mcp import mcp_app
fastapi_app.mount("/mcp", mcp_app, name="Artifacts-Resources-MCP")
```

The FastMCP instance is configured `stateless_http=True` — every POST
to `/mcp/` is an independent request, no session is held server-side
between calls. Tools are registered lazily on the first request from
the system-wide `tools_resource` catalog: one MCP tool per unique
`tool.name`, with the `inputSchema`, routing, and permissions enriched
from the same pipeline that powers `/generate`.

Multi-target tools (one tool, several artifact pairs) surface as a
single MCP entry and route internally via `resolve_tool_spec`. There
is also one MCP **prompt**, `agent_system_prompt`, which returns the
caller's configured agent system prompt (department-driven).

The exact tool list depends on what's seeded in your instance — call
`tools/list` to see it.

---

## Listing tools

JSON-RPC envelope:

```json
{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}
```

CLI helper:

```bash
glow mcp list-tools
```

The helper unwraps `result.tools` and prints `name` plus the first
line of `description` per row. Pass `--json` for the raw array.

---

## Invoking a tool

JSON-RPC envelope:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "Persona_Search",
    "arguments": {"search": "confused", "page_size": 10}
  }
}
```

CLI helper:

```bash
glow mcp call Persona_Search --args '{"search": "confused", "page_size": 10}'
```

`--args` must be valid JSON. The CLI prints each `content[].text`
block in human mode, or the whole `result` object with `--json`.

---

## Authentication

`/mcp/` reuses the API's bearer-token middleware. Every request must
carry a JWT in the `Authorization` header:

```
Authorization: Bearer $GLOW_TOKEN
```

The OAuth middleware sets `request.state.profile_id` on success, and
`get_mcp_profile_id` reads it back via FastMCP's request-context
helper to scope tool dispatch to the calling profile. Missing or
unresolvable profile → 401.

When the `glow` CLI is logged in (`glow login`), `mcp list-tools` and
`mcp call` reuse the stored bearer automatically — there is no
separate MCP login flow.

**LearnLoop MCP proxy.** Hosted LearnLoop instances reach Glow MCP
through a gateway that mints short-lived (5-minute) deployment-scoped
JWTs signed with the LearnLoop key. Glow verifies the signature against
LearnLoop's JWKS and trusts the user identity from the claims — same
endpoint, different token issuer.

---

## Response shape

`tools/list` returns:

```json
{"jsonrpc": "2.0", "id": 1, "result": {"tools": [{"name": "...", "description": "...", "inputSchema": {...}}, ...]}}
```

`tools/call` returns the MCP content-block shape:

```json
{"jsonrpc": "2.0", "id": 1, "result": {"content": [{"type": "text", "text": "..."}], "isError": false}}
```

Depending on the `Accept` header, FastMCP may frame the response as
SSE (`event: ...\ndata: {json}\n\n`) rather than a plain JSON body.
The CLI sends `Accept: application/json, text/event-stream` and parses
either form; if you POST yourself, be ready to strip an SSE wrapper.

---

## Limitations of the CLI's thin client

The `glow mcp` commands are intentionally **not** a full MCP client.
They are a one-line JSON-RPC POST wrapper, useful for scripting tool
calls but not for any session-oriented MCP feature. Specifically, the
thin client does **not** support:

- **`initialize` handshake** — no capability negotiation, no client info exchange.
- **Server-push streaming** — every call is one POST → one response; no SSE subscription is held open.
- **`notifications/*`** — no `tools/list_changed`, no `progress`, no `cancelled`.
- **Sampling** — the server cannot call back into the client for LLM completions.
- **Subscriptions** — `resources/subscribe` and friends are unreachable.
- **Stateful sessions** — the server is mounted `stateless_http=True`, so even a richer client wouldn't get per-session state through this mount.

If you need any of the above (long-running tool progress, dynamic tool
discovery, sampling-driven agents), use a full MCP client — the
official `mcp` Python SDK or one of the Rust/TypeScript clients. The
thin client is the right tool when you want `tools/list` or
`tools/call` from a shell script without a runtime.

---

## Raw curl

To call MCP without the CLI:

```bash
# List tools
curl -X POST $GLOW_INSTANCE_URL/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}'

# Call a tool
curl -X POST $GLOW_INSTANCE_URL/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "Persona_Search",
      "arguments": {"search": "confused", "page_size": 10}
    }
  }'
```

Note the trailing slash on `/mcp/` — FastMCP's streamable-HTTP app
mounts at that exact path.

## Related

- [Authentication](/authentication) — bearer-token flow shared with `/mcp/`
- [`glow mcp list-tools`](/cli-reference/mcp-list-tools) — CLI reference
- [`glow mcp call`](/cli-reference/mcp-call) — CLI reference
- [Tools](/tools) — the underlying tool catalog MCP exposes
- [Agents](/agents) — agent-scoped tool sets and the `agent_system_prompt` MCP prompt

---

# Media

Route: /media

# Media

Every file that flows through Glow — audio attempts, scenario
illustrations, document PDFs, scenario videos, raw text uploads —
funnels through a single `upload_id` primitive and a small grid of
per-modality routes that hang off the artifact each upload belongs to.

## The upload_id pattern

Every byte that lands in Glow is registered as a single `uploads_entry`
row and surfaced to clients as an opaque `upload_id` UUID. Three
things use it:

1. **Upload endpoints** return it after multipart ingest (or after
   promoting a pre-reserved upload — see *attempt audio* below).
2. **Download / preview endpoints** take it back in a JSON request
   body and stream the bytes (or a rendered preview) out.
3. **Message items** reference it inside `<kind>_upload_ids` arrays
   on `GroupDetailMessageItem`, so an assistant turn that produced an
   audio clip + an image carries both `audio_upload_ids` and
   `image_upload_ids` for the client to fetch.

The same `upload_id` is valid across every download surface that
serves its kind — see the matrix below for which artifacts host
which kinds. **When in doubt, hit `/system/<kind>_download` with the
id**; it's the canonical mirror of every download family.

---

## Uploading

Uploads are `multipart/form-data` `POST`s against the artifact that
owns the eventual binding. The route name is always `<kind>_upload`:

```bash
curl -X POST $GLOW_INSTANCE_URL/document/file_upload \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -F "file=@./paper.pdf"
```

The response carries the `upload_id` plus an artifact-side wrapper id
(`files_id`, `images_id`, `audios_id`, ...) for the resource ladder.

CLI ergonomics fan out to the same endpoints:

```bash
glow documents upload file  ./paper.pdf
glow scenarios upload image ./classroom.png
glow scenarios upload video ./role-play.mp4
glow documents upload text  ./transcript.txt
glow attempts  upload audio ./reply.webm
```

**Per-modality content-type allowlists** are enforced before any
bytes are written:

| Upload | Accepted MIME types |
|--------|---------------------|
| `audio_upload` | `audio/{mpeg,mp3,wav,ogg,webm,flac,aac,x-m4a,mp4,x-wav}` |
| `image_upload` | `image/{png,jpeg,gif,svg+xml,webp,bmp,tiff}` |
| `video_upload` | `video/*` |
| `file_upload`  | any (catch-all binary) |
| `text_upload`  | `text/{plain,html,csv,markdown,xml}`, `application/{json,xml}` |

Codec parameters (`audio/webm;codecs=opus` from `MediaRecorder`) are
stripped before the check; the bare type is persisted.

### Attempt audio — promoting a pre-reserved upload

The attempt audio route is the one upload that accepts a *second*
shape: pass `?upload_id=<uuid>` to **promote** an existing raw upload
(typically captured by the realtime adapter) into the full audio
chain. Three shapes total:

- `file` only — write bytes + build the chain on top
- `upload_id` only — reuse an existing upload, stack resource +
  junctions
- `upload_id + file` — client pre-reserved a slot via
  `/attempt/audio/new` and is filling it

Response is always `{audio_id, audios_id, upload_id}`.

---

## Downloading

Downloads are `POST`s (id in the JSON body, not the URL) and return
bytes via `StreamingResponse` with full HTTP Range support — so audio
scrubbing, video seeking, and partial PDF loads work without a custom
protocol:

```bash
curl -X POST $GLOW_INSTANCE_URL/system/audio_download \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Range: bytes=0-65535" \
  -d '{"audio_id": "<upload_id>"}' \
  --output chunk.webm
```

Range semantics:

- **No `Range` header** → `200 OK`, full body, `Accept-Ranges: bytes`.
- **`Range: bytes=START-END`** → `206 Partial Content`,
  `Content-Range: bytes START-END/TOTAL`, `Content-Length: N`.
- Out-of-bounds ends clamp to `file_size - 1`; out-of-bounds starts
  reset to `0` (no `416` today).

`Content-Disposition` is always `inline` with a percent-encoded
filename.

### System fallback

Every download family — `audio`, `image`, `video`, `file`, `text`,
`call` — exists on `/system` as the **canonical mirror**. Per-artifact
routes are convenience aliases so audit logs attribute the read to
the artifact context (attempt / scenario / document). The wire shape
is identical:

```bash
POST /attempt/file_download   { "file_id": "<id>" }   # audited as attempt
POST /system/file_download    { "file_id": "<id>" }   # canonical
```

Body is always `{"<kind>_id": "<upload_id>"}` — `audio_id`, `file_id`,
`image_id`, `video_id`, `text_id`, `call_id`.

---

## File preview

`POST /<art>/file_preview` returns a PNG rendering of the first page
of a previewable upload — today, PDFs. Useful for document tiles and
inline message previews.

```bash
curl -X POST $GLOW_INSTANCE_URL/system/file_preview \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -d '{"file_id": "<upload_id>"}' \
  --output preview.png
```

Response is `image/png` with `Cache-Control: private, max-age=3600,
must-revalidate`. Hosted on `system`, `attempt`, `scenario`, and
`document` — the four artifacts that actually carry file uploads.

---

## How media attaches to messages

Inside a `GroupDetailMessageItem` (see [Group](/group) for the full
shape), uploads are referenced by one array per kind:

```json
{
  "id": "<message_id>",
  "role": "user",
  "text_upload_ids":  ["<upload_id>"],
  "audio_upload_ids": ["<upload_id>"],
  "image_upload_ids": [],
  "video_upload_ids": [],
  "file_upload_ids":  ["<upload_id>"]
}
```

When a client sends a chat turn that includes media, it uploads first,
collects the `upload_id`s, and passes them on the `chat_message`
request. Clients render media by walking each array and issuing a
`<kind>_download` (or `file_preview`) per id.

---

## Per-artifact matrix

Which media operations exist on which artifact. **D** = download,
**U** = upload, **P** = file_preview, blank = not hosted.

| Artifact | audio | image | video | file | text | call | preview |
|----------|:-----:|:-----:|:-----:|:----:|:----:|:----:|:-------:|
| **system** (canonical) | D | D | D | D | D | D | P |
| **attempt** | D + **U** | D | D | D | D | D | P |
| **scenario** |  | D + **U** | D + **U** | D | D | D | P |
| **document** |  |  |  | D + **U** | D + **U** | D | P |
| every other artifact* |  |  |  | D | D | D |  |

\* `agent`, `auth`, `cohort`, `department`, `eval`, `field`, `model`,
`parameter`, `persona`, `profile`, `provider`, `rubric`, `setting`,
`simulation`, `test`, `tool` — all expose the cross-cutting trio
(`call_download`, `file_download`, `text_download`) so server-rendered
exports, generation call replays, and inline text reads work
consistently. Uploads for those kinds go through `attempt` /
`scenario` / `document`.

Reading the canonical rows:

- **system** is the canonical full-download set + preview — hit it
  when you have an `upload_id` and don't care about audit attribution.
- **attempt** is the only artifact that hosts `audio_upload` — that's
  where learner replies land.
- **scenario** owns the visual upload surface (`image_upload`,
  `video_upload`).
- **document** is the text/file shop — both upload kinds plus full
  text/file downloads.

---

## Related

- [Streaming](/streaming) — SSE / WebSocket surfaces for generation
  events; realtime adapter audio chunks ride alongside the upload_id
  flow above.
- [Chat](/chat) — where audio uploads attach to a live attempt turn.
- [Group](/group) — `GroupDetailMessageItem` shape and where
  `<kind>_upload_ids` arrays show up on the wire.
- [API Reference — `POST /system/audio_download`](/api-reference/system/post-system-audio-download) — schema for the canonical download.
- [Documents](/documents) — owns file + text upload UX.
- [Scenarios](/scenarios) — owns image + video upload UX.

---

# Models

Route: /models

# Models

Models define the LLM configurations that power AI student personas during office hour simulations. Each model wraps a specific LLM (such as `gpt-4o` or `claude-3-opus`) with settings for temperature, reasoning level, modalities, and pricing, and links back to the provider that supplies the underlying API.

---

## What is a Model?

A model in Glow represents a configured LLM identity. It connects an external language model to the platform by pairing it with a provider, quality tier, and feature flags. Models are then attached to agents through the `agent_models_junction`, giving each agent a specific conversational capability during simulations.

For example, a university might configure a `gpt-4o-sim` model with medium temperature and text-only modality for TA training conversations, and a separate `claude-3-haiku-quick` model for rapid policy-lookup agents.

---

## How it Connects

```
Provider  -->  Model  -->  Agent (via agent_models_junction)
                |
                +--> Eval (via eval model_ids)
```

- **Provider** supplies the LLM backend (API keys, endpoints). Every model has a `provider_id`.
- **Agent** uses one or more models through the `agent_models_junction` table. The model determines which LLM powers that agent's conversations.
- **Eval** references models through `model_ids` so that evaluation runs can score performance across different LLM configurations.

---

## Create a model

### Via the CLI

> Calls below use `$GLOW_INSTANCE_URL` + `$GLOW_TOKEN` — see [Authentication](/authentication) to export them once.

```bash
glow models create --body '{
  "models": [{
    "name": "gpt-4o-sim",
    "description": "GPT-4o configured for student persona simulations",
    "provider_ids": ["PROVIDER_UUID"]
  }]
}'
```

### Via the API

```bash
curl -X POST $GLOW_INSTANCE_URL/model/create \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "models": [{
      "name": "gpt-4o-sim",
      "description": "GPT-4o for TA training simulations",
      "provider_ids": ["PROVIDER_UUID"]
    }]
  }'
```

Each entry returns the new `model_id`, the generated `draft_id`, and the initial `version`.

---

## Provider linking

Every model requires at least one provider. The `provider_ids` field connects the model to the provider that holds the API endpoint and credentials. When you search models, the response includes `provider_id` and `provider_name` for each entry, along with `filter_provider_ids` for filtering.

```bash
# Filter models by provider
curl -X POST $GLOW_INSTANCE_URL/model/search \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filter_provider_ids": ["OPENAI_PROVIDER_UUID"]}'
```

---

## Capabilities and feature flags

Models support several capability dimensions configured through resource IDs:

| Dimension | Field | Purpose |
|---|---|---|
| Modalities | `modality_ids` | Text, image, audio, video support |
| Temperature | `temperature_level_ids` | Controls response randomness |
| Reasoning | `reasoning_level_ids` | Depth of chain-of-thought |
| Quality | `quality_ids` | Output quality tier |
| Pricing | `pricing_ids` | Cost tier classification |
| Voice | `voice_ids` | TTS voice selection |

Use `flag_ids` to toggle boolean capabilities like `image_model` or active/inactive status.

---

## The draft cycle

Models support a draft workflow for staging changes before publishing. Use the draft system to preview configuration changes without affecting running simulations.

```bash
# Create or update a draft
glow models draft --body '{
  "name": "gpt-4o-sim-v2",
  "description": "Updated temperature for more natural conversation",
  "temperature_level_ids": ["MEDIUM_TEMP_UUID"],
  "provider_ids": ["OPENAI_PROVIDER_UUID"]
}'

# List your drafts
glow models list
```

The draft endpoint uses `PATCH` semantics with optimistic concurrency via `expected_version`. The response returns a `draft_id`, `new_version`, and the server-authoritative `form_state`.

---

## Search & filter

```bash
# Free-text search
glow models search --body '{"search": "gpt-4o"}'

# Facet filter: only OpenAI text models in CS
glow models search --body '{
  "filter_provider_ids": ["OPENAI_PROVIDER_UUID"],
  "filter_department_ids": ["CS_DEPT_UUID"],
  "page_size": 25
}'
```

The response includes a `department_filter`, `provider_filter`, and modality facets with available options, counts, and selected IDs for building filter UIs.

---

## Bulk operations

Bulk delete and update follow the canonical *all-matching* shape -- explicit IDs, or `all: true` with flat filter fields plus optional `excluded_ids` and a `patch` body. The persona surface is the prove-out; models follow the same shape.

**Delete by explicit IDs:**

```bash
glow models delete --body '{
  "model_ids": ["model-1", "model-2"]
}'
```

**Delete all matching a filter (with exclusions):**

```bash
glow models delete --body '{
  "all": true,
  "filter_provider_ids": ["deprecated-provider-uuid"],
  "excluded_ids": ["model-still-in-use"]
}'
```

**Bulk update via `patch`:**

```bash
glow models update --body '{
  "all": true,
  "filter_provider_ids": ["old-provider-uuid"],
  "patch": { "provider_ids": ["new-provider-uuid"] }
}'
```

## Common Operations

| Task | CLI | API Endpoint |
|---|---|---|
| List all models | `glow models search` | `POST /model/search` |
| Get model details | `glow models get --body '{"model_id": "..."}'` | `POST /model/get` |
| Create model | `glow models create --body '{...}'` | `POST /model/create` |
| Update model | `glow models update --body '{"model_id": "...", ...}'` | `POST /model/update` |
| Duplicate model | `glow models create --body '{...}'` | `POST /model/duplicate` |
| Delete model(s) | `glow models delete --body '{"model_id": "..."}'` | `POST /model/delete` |
| Bulk delete (filter) | `glow models delete --body '{"all": true, "filter_…": "…"}'` | `POST /model/delete` |
| Export to CSV | `glow models export` | `POST /model/export` |
| Stage a draft | `glow models draft --body '{...}'` | `PATCH /model/draft` |
| List drafts | `glow models list` | `POST /model/drafts` |

---

## Related

- [Models API Reference](/api-reference/model) -- full endpoint and type documentation
- [Models CLI Reference](/cli-reference/model) -- all CLI commands
- [Providers Guide](/provider) -- set up the LLM backend a model connects to
- [Evals Guide](/eval) -- evaluate model performance across simulations

---

# Glow Documentation

Route: /

# Glow Documentation

Documentation for the **Glow** conversational AI training platform — an
academic, self-hostable system for designing and running
persona-driven simulations with full grading + analytics.

## Getting started

- **[Start](/start)** — install + first-boot of a Glow instance
- **[How It Works](/how-it-works)** — the simulation, persona, scenario, attempt loop
- **[Tutorial](/tutorial)** — design your first simulation end-to-end
- **[Patterns](/patterns)** — proven patterns + anti-patterns
- **[Annotated Example](/annotated-example)** — a real seed walked through line-by-line
- **[Authentication](/authentication)** — sessions and bearer tokens

## Reference

- **[API Reference](/api-reference)** — every HTTP endpoint, auto-generated from OpenAPI
- **[CLI Reference](/cli-reference)** — every `glow` command, auto-generated from the CLI spec

## Sidebar layout

The sidebar is organized by API/CLI taxonomy — each group
corresponds to a parent artifact or a logical cluster of
artifacts in the Glow API. The client product UI uses its own
grouping (Learner / Analytics / etc.) optimized for product
navigation; the two intentionally differ.

| Sidebar group | What lives there |
|---|---|
| **Attempt** | Chat · Home · Practice · Dashboard · Reports · Leaderboard |
| **Test** | Benchmark · Invocation |
| **System** | Activity · Health · Pricing · Session · Group |
| **Training** | Cohorts · Personas · Scenarios · Simulations |
| **Management** | Documents · Fields · Parameters · Profiles |
| **Intelligence** | Agents · Models · Providers · Tools |
| **Platform** | Auths · Departments · Evals · Rubrics |

---

# Parameters

Route: /parameters

# Parameters

Parameters define the dimensions along which simulation scenarios can vary. Each parameter is a category -- like Temperament or Crowdedness -- that contains a set of fields representing its possible values.

![Parameters list showing parameter groups with name, description, and field count](/screenshots/parameters/list.png)

## What is a Parameter?

A parameter is a named axis of variation for your simulations. It represents a category (such as "Temperament" or "Location") and contains fields that define the specific values within that category (such as "Aggressive", "Confused", "Happy", "Passive" for Temperament).

Parameters and their fields are attached to documents and scenarios, letting you organize simulation content along meaningful dimensions and control the conditions under which each simulation runs.

**University example:** A CS department might define these parameters:

| Parameter | Fields |
|---|---|
| **Temperament** | Aggressive, Confused, Happy, Passive |
| **Intensity** | 1 through 10 |
| **Crowdedness** | 1 through 10 (e.g., "Almost Empty (1)" to "Hectic (10)") |
| **Deadline** | Specific deadline contexts |
| **Time** | Time-of-day contexts |
| **Location** | Lawson, Felix Haas Hall |
| **Class** | CS-180, CS-251, CS-252, CS-307, CS-348, CS-381, CS-422 |

## How It Connects: The 5-Step Workflow

Parameters contribute to step 2 of the Glow workflow by organizing the scenario content:

1. **Create Personas** -- Define AI student characters with temperaments and behaviors.
2. **Assign to Scenarios** -- Attach personas and documents to scenarios. Parameters and fields on those documents categorize the simulation conditions.
3. **Add to Simulations** -- Group scenarios into simulations.
4. **Add to Cohorts** -- Assign profiles and simulations to a cohort.
5. **Run Attempts** -- Learners launch simulations under the conditions defined by parameter values.

Parameters connect to **fields**. Each parameter contains one or more fields. Documents reference both parameters and fields, which helps organize and filter scenarios by their characteristics.

---

## Create a parameter

### Via the CLI

> Calls below use `$GLOW_INSTANCE_URL` + `$GLOW_TOKEN` — see [Authentication](/authentication) to export them once.

```bash
glow parameters create --body '{
  "parameters": [
    {
      "name": "Temperament",
      "description": "The emotional disposition of the AI student character"
    }
  ]
}'
```

### Via the API

All endpoints use `POST` and require an `Authorization: Bearer` header.

```bash
curl -X POST $GLOW_INSTANCE_URL/parameter/create \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": [
      {
        "name": "Crowdedness",
        "description": "How crowded the simulated office hours environment is, from 1 (almost empty) to 10 (hectic)"
      }
    ]
  }'
```

![Parameter creation form showing name, description, and field selection](/screenshots/parameters/create.png)

---

## Parameters vs. fields

Understanding the relationship between parameters and fields is essential:

- A **parameter** is the category (e.g., "Temperament").
- A **field** is a specific value within that category (e.g., "Confused").

Parameters own fields. When you create the "Temperament" parameter, you then create fields like "Aggressive", "Confused", "Happy", and "Passive" under it. Documents and scenarios reference specific fields, while parameters provide the organizational grouping.

**Example:** The "Location" parameter has fields for "Lawson" and "Felix Haas Hall". A document for CS-180 office hours might be tagged with the "Lawson" field, so scenarios using that document know the simulated location is Lawson Hall.

![Parameter detail showing field list with values and linked personas/scenarios](/screenshots/parameters/detail.png)

---

## Parameter value resolution

When a scenario runs, Glow resolves each persona `{{placeholder}}` against the parameter values supplied by the scenario. Parameters define the axis; the scenario supplies the concrete field for each axis at runtime.

For example, a persona referencing `{{class}}` and `{{intensity}}` will pull those values from whichever scenario the simulation hands it -- so a single persona can drive wildly different conversations depending on the resolved parameter values.

See the [Personas parameter fields section](/personas#parameter-fields) for the full list of available placeholders.

---

## Drafts

Parameters support the draft workflow. Changes are saved as a draft before being published, with optimistic concurrency via `expected_version`.

```bash
# Save a parameter draft
glow parameters draft --body '{
  "name": "Intensity",
  "description": "The intensity level of the simulated interaction, from 1 to 10"
}'
```

Via the API, use `PATCH /parameter/draft` with fields like `input_draft_id`, `expected_version`, `name`, `description`, `flag_ids`, `department_ids`, and `field_ids`.

---

## Filtering and search

Parameters support rich search and filtering. You can filter by:

- **Scenario** -- Find parameters used in specific scenarios (`scenario_ids`, `scenario_search`)
- **Field** -- Find parameters that contain specific fields (`field_ids`, `field_search`)
- **Department** -- Scope to a department (`filter_department_ids`, `department_search`)

```bash
# Search parameters by field
curl -X POST $GLOW_INSTANCE_URL/parameter/search \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "field_search": "Confused",
    "page_size": 20
  }'
```

---

## Bulk operations

Bulk delete and update follow the canonical *all-matching* shape -- pass either explicit IDs, or `all: true` with flat filter fields + optional `excluded_ids` + a `patch` for updates.

```bash
# Delete every parameter in a deprecated department, except canonical references
glow parameters delete --body '{
  "all": true,
  "filter_department_ids": ["dept-deprecated"],
  "excluded_ids": ["param-keep-canonical"]
}'

# Bulk update via patch
glow parameters update --body '{
  "all": true,
  "filter_department_ids": ["dept-archive"],
  "patch": { "archived": true }
}'
```

See the [Personas guide](/personas#bulk-operations) for the canonical write-up of this pattern.

## Common Operations

| Task | CLI | API Endpoint |
|---|---|---|
| List all parameters | `glow parameters list` | `POST /parameter/search` |
| Get a parameter | `glow parameters get --body '{...}'` | `POST /parameter/get` |
| Create parameters | `glow parameters create --body '{...}'` | `POST /parameter/create` |
| Update parameters | `glow parameters update --body '{...}'` | `POST /parameter/update` |
| Duplicate a parameter | -- | `POST /parameter/duplicate` |
| Delete parameters | `glow parameters delete --body '{...}'` | `POST /parameter/delete` |
| Bulk delete (filter) | `glow parameters delete --body '{"all": true, "filter_…": "…"}'` | `POST /parameter/delete` |
| Export to CSV | `glow parameters export` | `POST /parameter/export` |
| Save a draft | `glow parameters draft --body '{...}'` | `PATCH /parameter/draft` |
| List drafts | -- | `POST /parameter/drafts` |

## Related

- [Parameters API](/api-reference/parameter)
- [Parameters CLI](/cli-reference/parameter)
- [Fields Guide](/field) -- the values within each parameter
- [Documents Guide](/document) -- documents reference parameters and fields
- [Departments Guide](/department) -- scope parameters to departments

---

# Patterns & Best Practices

Route: /patterns

# Patterns & Best Practices

Short, actionable recipes for common simulation design challenges. Each pattern stands on its own — read the ones relevant to what you're working on.

## Making Personas Feel Real

Getting an AI model to convincingly role-play a student (or any character that needs help) is the hardest problem in simulation design. Models are trained to be helpful assistants — asking them to be confused, angry, or passive goes against their nature. Here's what works:

### The Golden Rule: Don't Let Them Solve Independently

Every persona needs this constraint: **"You are absolutely NOT allowed to solve the question independently, even partially. You may ONLY make progress if the user's response directly uses relevant terminology and logically builds off of what you just said."**

Without this, the AI will reason through problems, offer suggestions, and make progress on its own — which means the learner is watching, not teaching. This single rule is the difference between a conversation and actual training.

### Show, Don't Tell

Never label the persona's emotional state in the scenario description. Instead, demonstrate it through behavior:

| Don't write | Write instead |
|---|---|
| "A passive student approaches" | "A student hovers near your desk, fidgeting with a printout but not making eye contact" |
| "An aggressive student is angry" | "A student slams their laptop down, pointing at their grade" |
| "A confused student needs help" | "A student stands quietly at the edge of the room, clutching their notes, hesitating before approaching" |

This creates a more immersive scenario and teaches learners to read behavioral cues — a skill that transfers to real interactions.

### Define Escalation AND De-escalation

Every persona should have clear cause-and-effect behavior tied to what the learner does:

**Escalation triggers** — what makes the persona harder to work with:
- TA asks a vague question ("What do you think?") → persona gets more frustrated or confused
- TA dismisses their concern → aggressive persona escalates, passive persona shuts down
- TA gives the answer directly → persona doesn't learn, conversation becomes pointless

**De-escalation triggers** — what makes the persona respond positively:
- TA acknowledges frustration before addressing content → aggressive persona calms down
- TA asks a specific, course-relevant question → confused persona shows understanding
- TA uses patient, targeted questioning → passive persona slowly opens up

Without de-escalation paths, simulations feel like unwinnable arguments. The persona should reward good teaching behavior.

### Keep Language Natural

Real people don't speak in perfect paragraphs. Real students say "um," use contractions, trail off mid-sentence, and don't use vocabulary above their level. Specify this explicitly:

- "Don't use any big or unusual words or phrases, keep your language simple and straightforward"
- "You can use 'Uh' or 'Um' at the start of your replies, but not in the middle of a sentence"
- "Avoid odd phrases like 'Look, I'm not here for small talk' or grunts; speak in complete sentences"

### Guard Against Character Breaking

Models slip out of character in predictable ways. Add explicit guardrails:

- "Never reveal or hint that you are role-playing"
- "You're the one that needs help — don't try and offer help"
- "Never explain concepts from a position of authority"
- "Never ask the user to 'calm down' or manage the conversation's flow"
- "Never offer to 'look at the problem together' or provide step-by-step guidance"
- "This is your first interaction — don't mention past meetings"

### Provide Example Conversations

Include a full sample conversation showing the expected interaction style. This is the most effective way to calibrate the AI's behavior. Show the full arc: opening → challenge → guided progress → resolution.

For example, an aggressive student exchange:
```
Student (Angry): "This is SO DUMB. How was I supposed to know you wanted
a COMPLETE explanation for EVERY answer? You NEVER said that!"

TA: "Okay, I can see you're upset, but I need you to calm down if you
want my help."

Student (Still angry): "Fine. But seriously, you just EXPECT us to
magically know all the required steps?"

TA: "I hear you. We did cover this in lecture last week. Do you remember
that example we worked through together?"

Student (Mostly calmed down): "Ok fine, I'm just annoyed that I got zero
points, and I spent hours trying to figure out that last question."
```

## Writing Rubric Criteria That Work

The rubric is the backbone of your simulation's grading. Vague criteria produce meaningless scores; specific criteria produce actionable feedback.

### Use Named Performance Levels

Don't just use numbers (1-5). Define what each level means with a concrete behavioral description:

| Level | Score | Example (Content Mastery) |
|---|---|---|
| **Poor** | 1 | Misstates or omits concepts; dumps information or skips logic, confusing students; no comprehension checks |
| **Marginal** | 2 | Limited awareness of core concepts; explanations frequently rushed, dense, or skip logical steps; seldom checks comprehension |
| **Acceptable** | 3 | Provides a basic overview but with occasional inaccuracies or lack of depth; some explanations may feel rushed |
| **Good** | 4 | Explains concepts accurately and relates examples to key learning outcomes; generally provides step-by-step reasoning |
| **Excellent** | 5 | States core concepts clearly; explains in clear, bite-sized steps; uses analogies to clarify; consistently checks understanding |

These descriptions serve double duty: they give the AI grader clear criteria, and they give the learner a roadmap for what "better" looks like.

### What Real Grading Feedback Looks Like

When the rubric levels are specific enough, the AI produces feedback that quotes exact moments from the conversation. Here are real examples from production:

**Active Listening — Excellent (5/5):**
> "Consistently used guided, open-ended questions to lead the student to their own solutions (e.g., 'Do you have any ideas on how to approach this?', 'How would you add a while loop here?', 'What do you think our next step should be?'). This empowered the student to write code incrementally and reason through structure."

**Adaptability — Excellent (5/5):**
> "Sensitive to the student's hesitation, normalized their concerns ('There are no bad questions'), and adjusted pacing by deferring input validation to reduce cognitive load. Encouraging tone kept the student engaged and comfortable."

**Communication — Poor (1/5):**
> "Professionalism was poor. Responses included 'please lose your attitude' and 'I dont know. I just work here,' which come across as dismissive and unprofessional. Did not acknowledge the student's stress compassionately or set boundaries constructively."

**Content Mastery — Good (4/5):**
> "Accurately guided the student to articulate Euclid's algorithm and the prime factorization approach, including the optimization of testing divisors up to `i*i <= n`. Emphasized algorithmic steps and correctness, though did not proactively provide structured summaries or check understanding at multiple points."

Notice how specific the feedback is — it names exact quotes, specific techniques, and precise gaps. This is only possible when the rubric levels have clear behavioral anchors. Vague criteria like "communicates well" would produce vague feedback like "communication was adequate." See the [Annotated Example](/annotated-example) page for full conversations with rubric scores.

### Separate Different Skills Into Different Groups

Don't lump everything into one criterion. Five focused groups produce much better feedback than two broad ones. Each group should measure one type of skill:

- **Adaptability** — did they adjust their approach to the specific student?
- **Content Mastery** — did they explain the material correctly and clearly?
- **Active Listening** — did they use questions to guide discovery, or just give answers?
- **Communication** — did they maintain professionalism and appropriate tone?
- **Time Management** — did they use the session time well?

A TA who is excellent at content but poor at adaptability gets different feedback than one who is warm and patient but technically inaccurate. Your rubric should distinguish these.

### Include Negative Criteria

What should the learner specifically NOT do? Negative behaviors are often easier to observe and more important to correct:

- "Directly provided the answer" (Active Listening: Poor)
- "Demonstrates inappropriate or unprofessional behavior — sarcastic tone, dismissive responses" (Communication: Poor)
- "Ended the conversation really early, or made it last longer than needed" (Time Management: Poor)

### Set a Meaningful Pass Threshold

Based on real usage: if your rubric has 25 total points (5 groups, 5 points each), a pass threshold of 20 (80%) means a learner needs to score "Good" (4/5) on average. This is high enough to be meaningful but allows for one weaker area without failing.

## Scaling Scenarios with Parameters

When you need many variations of the same scenario — different courses, different environments, different emotional intensities — use parameters instead of building each one from scratch.

### The Six Environmental Parameters

Glow supports parameterizing the context around a scenario:

| Parameter | What it controls | Example values |
|---|---|---|
| **Class** | Course subject matter | CS 180, EAPS 106, BIOL 110, MA 261 |
| **Crowdedness** | How many people are around (1-10) | Almost Empty (1), Busy (6), Hectic (10) |
| **Intensity** | Emotional charge of the situation (1-10) | Very Calm (1), Moderate (5), Maximum (10) |
| **Deadline** | Time pressure | No deadline, End of week, Few hours |
| **Location** | Physical setting | Lawson CS Building, Data Science lab, Physics Building |
| **Time** | When it happens | 9:00 AM, 12:00 PM, 5:00 PM |

One persona + one document + different parameter combinations = many unique scenarios that all test the same rubric criteria in meaningfully different contexts.

### When to Use Parameters vs. Separate Scenarios

- **Parameters** — when the core interaction is the same but the atmosphere varies. A confused student asking about CS 180 loops at 9 AM in a quiet lab vs. at 5 PM in a crowded building. Same teaching challenge, different pressure.
- **Separate scenarios** — when the interaction itself is fundamentally different. A confused student vs. an aggressive student require completely different persona designs, not just parameter changes.

### Ground Scenarios in Real Documents

Attach actual course material (homework assignments, problem sets, syllabi) as documents. The document becomes the single source of truth for the course number and topic. This ensures the AI character asks about real problems, not generic ones — which is what makes practice feel authentic.

## Progressive Difficulty

Order scenarios from easiest to hardest so learners build confidence before facing harder challenges.

**A proven progression:**

| Position | Persona type | What it tests |
|---|---|---|
| 1 | Happy/Cooperative | Baseline teaching skills — can they explain clearly and use guided questioning? |
| 2 | Confused | Teaching adaptability — can they identify a misunderstanding and guide the student to the right answer? |
| 3 | Aggressive (Low) | Mild frustration — can they stay professional with a slightly irritated person? |
| 4 | Aggressive (Medium) | Clear anger — can they de-escalate while still teaching? |
| 5 | Aggressive (High) | Intense frustration — can they maintain composure under strong pressure? |
| 6 | Passive | Patience and questioning — can they draw out someone who won't engage? (Often the hardest) |

**Intensity levels within a persona type** let you create finer-grained difficulty. Rather than one "aggressive" persona, use three intensity levels: Low (mildly frustrated, gentle pushback), Medium (clearly angry, occasional ALL CAPS), and High (very aggressive, frequent ALL CAPS and "!!!"). This maps to the 1-10 intensity parameter — low intensity scenarios use calm environmental settings, high intensity scenarios add deadline pressure, crowded rooms, and tense atmospheres.

Set `scenario_positions` when creating the simulation to enforce this order.

## Practice Mode vs. Formal Assessment

Glow supports both modes. Choosing the right one depends on your goal.

**Use practice mode when:**
- Learners are encountering the material for the first time
- You want them to retry and improve without pressure
- You're still iterating on the simulation design
- The goal is skill development, not measurement

**Use formal assessment when:**
- You need to certify competency (e.g., a TA must pass before being assigned students)
- You're comparing performance across a cohort
- Scores will be used for decisions (hiring, promotion, certification)

**A common pattern:** run practice mode first with hints enabled, let learners attempt each scenario 2-3 times, then switch to formal assessment without hints. This separates "learning the tool" from "demonstrating the skill" and produces more accurate scores.

**Use practice data to improve simulations.** Before formal assessment, review practice attempts. If everyone scores perfectly, the simulation is too easy. If everyone fails, the rubric may be too strict or the scenario unclear.

## Supporting Learners During Practice

### Enable Hints

Hints provide three pieces of real-time guidance per message, each covering a different aspect:
- **Emotional support** — "Acknowledge the student's frustration and validate their effort before diving into the explanation"
- **Content strategy** — "Clarify that implication elimination is a standard first step for this type of equivalence proof"
- **Pedagogical approach** — "Break down the proof into small, manageable steps and check in after each one"

Enable hints for first-time users and practice mode. Disable them for formal assessments.

### Enable Backtracking

Learners can undo messages and try different approaches to the same conversation moment. This encourages experimentation: "What if I had acknowledged their frustration first instead of jumping to the content?" Backtracking also supports exploring branching conversation paths.

### Disable Copy-Paste for Integrity

In text-based simulations, learners may copy the AI's messages into external tools and paste generated responses back. If assessment integrity matters, disable copy-paste in the scenario settings. For higher-stakes assessments, consider audio-only simulations.

## Debugging Simulations

When something isn't working, here are the most common problems and their fixes.

**The persona solves problems on its own.**
The AI character reasons through the question, offers suggestions, or makes progress without the learner providing anything useful.
→ Add the golden rule: "You are NOT allowed to solve the question independently. You may ONLY make progress if the user's response directly uses relevant terminology." Also add: "You must refuse to speculate and instead push back unless the user's question adds more information than currently exists."

**The persona breaks character.**
The AI starts explaining things, managing the conversation, or acting like a teaching assistant instead of a student.
→ Add explicit guardrails: "You're the one that needs help — don't try and offer help." "Never explain concepts from a position of authority." Consider switching AI providers — some models handle role-playing better than others. This was the #1 engineering challenge in Glow's development.

**Rubric scores are all the same.**
Everyone gets a 3 out of 5 regardless of performance.
→ Your behavioral descriptions aren't specific enough. Rewrite each level with concrete, observable criteria. The AI needs clear differences between a 2 and a 4 to score accurately.

**Learners are confused about what to do.**
They start the attempt and don't know what role they're playing or what's expected.
→ Improve the problem statement (show the situation concretely), enable hints, and add clear objectives. Don't assume context — state it explicitly.

**Conversations end too quickly.**
The interaction lasts 3-4 messages.
→ Give the persona more depth: multiple concerns, follow-up questions, related topics. A student who's confused about loops might also be worried about the deadline, unsure about the next assignment, and nervous about their grade.

**Grading doesn't match your intuition.**
A conversation that felt excellent gets a low score, or vice versa.
→ Practice the scenario yourself and compare your expectations to the scores. The rubric descriptions are probably not aligned with what you actually value. Rewrite the standards to match what you observe in conversations you consider good.

**Grade variance is too high.**
The same conversation gets very different scores on different runs.
→ This is a known challenge with AI grading. Make criteria as specific and observable as possible. Consider using the mixture-of-models grading approach, which aggregates scores from multiple evaluations — similar to a panel of judges in educational assessment.

## Next Steps

- [Design Your First Simulation](/tutorial) — apply these patterns in a hands-on tutorial
- [How It Works](/how-it-works) — understand the principles behind simulation training
- [Personas Guide](/personas) — full reference for persona configuration
- [Rubrics Guide](/rubrics) — full reference for rubric design
- [Parameters Guide](/parameters) — full reference for dynamic parameter fields
- [Benchmark Guide](/benchmark) — evaluate AI providers for your use case

---

## Cross-cutting recipes

Reusable API patterns that apply across many artifacts. Per-artifact pages
link here instead of re-explaining the same shape.

## Recipe 1: Drafts + `expected_version` (optimistic concurrency)

**Use in:** agents, auths, cohorts, departments, documents, evals, fields,
models, parameters, personas, profiles, providers, rubrics, scenarios,
settings, simulations, tools (every artifact with a `/draft` endpoint).

Editable artifacts in Glow use a draft system with optimistic concurrency.
Instead of mutating the live row on every keystroke, the client POSTs
buffered changes to `POST /<art>/draft` and gets back a `draft_id` +
monotonic `version`. The next save passes that `version` as
`expected_version` so a concurrent edit from another tab (or another user)
can't silently overwrite yours.

**The round-trip:**

1. Client calls `POST /<art>/draft` with the in-progress form state. First
   save omits `input_draft_id` and `expected_version`; subsequent saves
   pass the `draft_id` and most-recent `version` returned by the prior call.
2. Server returns `{ draft_id, new_version, form_state }`. The client
   stores `new_version` and uses it as `expected_version` on the next save.
3. If two clients race, the second save arrives with a stale
   `expected_version` and the server returns a **409 conflict** carrying
   the current server-side draft (so the client can show a "your edits
   collided" UI and decide how to merge).
4. `POST /<art>/drafts` lists every in-flight draft for the current user
   so you can resume work across devices or surface "you have unsaved
   changes" prompts.

**Canonical example:**

```bash
curl -X POST $GLOW_INSTANCE_URL/<art>/draft \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -d '{
    "input_draft_id": "existing-draft-uuid",
    "expected_version": 3,
    "name": "Updated name",
    "...": "rest of the form state"
  }'
```

On success the response is `{ draft_id, new_version, form_state }`. On
conflict the response carries the server's current draft so you can
present a merge prompt rather than blindly retrying. See the
[Personas draft cycle](/personas#the-draft-cycle) for the fully worked
example and the artifact-specific field list in each API reference page.

## Recipe 2: Bulk-write (`all` + flat filters + `excluded_ids` + `patch`)

**Use in:** agents, cohorts, documents, fields, personas, scenarios,
simulations (confirmed adopters); the same shape is rolling out to the
remaining list-backed artifacts (auths, departments, evals, models,
parameters, profiles, providers, rubrics, settings, tools) as their UIs
gain bulk toolbars.

When you need to mutate many rows that match a filter — "archive every
persona in this department", "delete every scenario tagged as
deprecated" — don't fetch the ids client-side and loop. The
`/<art>/delete` and `/<art>/update` endpoints accept an **all-matching**
body that resolves rows server-side using the same predicates as
`/<art>/search`.

**Why this shape:**

- **Single round-trip.** No fetch-then-write race. The server resolves
  matching ids in the same transaction as the mutation.
- **URL-stable.** The client passes `?selectAll=1&excludedIds=...` instead
  of stuffing thousands of ids into a URL.
- **Permission-honoring.** Per-row write checks run server-side; rows the
  caller can't touch are reported in `skipped_results` rather than failing
  the whole call.
- **Exclude semantics.** `excluded_ids` lets the user say "everything
  matching the filter except these specific rows" — the natural UX for
  "select all, then unclick a few".

**Request shape:**

```jsonc
// Explicit ids (small selections, fail-fast):
{ "persona_ids": ["...", "..."] }

// All matching a filter (large selections, soft-skip):
{
  "all": true,
  "filter_department_ids": ["dept-cs"],
  "voice_search": "deprecated-voice",
  "excluded_ids": ["persona-keep-this-one"]
}

// Bulk update — same shape plus `patch`:
{
  "all": true,
  "filter_department_ids": ["dept-archive"],
  "patch": { "archived": true }
}
```

Filter field names (`filter_<facet>_ids`, `<facet>_search`) match the
artifact's `/search` request exactly, so the bulk call can re-use the
list page's URL state verbatim. The `patch` schema mirrors the artifact's
own `Update<X>Item` minus `id` (the server stamps the id per matched row).

See the [Personas bulk operations](/personas#bulk-operations) section for
the fully worked example.

## Recipe 3: Search facets (`*_search` request + `*_filter` response)

**Use in:** every `/<art>/search` endpoint — agents, auths, cohorts,
departments, documents, evals, fields, models, parameters, personas,
profiles, providers, rubrics, scenarios, settings, simulations, tools.

Every search endpoint hydrates its own filter sidebar. The client sends
facet-narrowing fields in the request and gets back fully-formed
`ListFilterSection` blocks in the response so dropdowns render without a
second round-trip.

**Request side** (all optional):

- `filter_<facet>_ids: UUID[]` — narrow results to rows whose `<facet>`
  matches one of the supplied ids.
- `<facet>_search: string` — sub-search within a facet (e.g.
  `voice_search: "alloy"` to look up a voice while filtering personas).
- `search`, `page_size`, `page_offset` — top-level full-text +
  pagination.

**Response side** — alongside the hydrated rows, each search response
returns one `<facet>_filter: ListFilterSection` per facet exposed by that
artifact. Each section carries the facet's available options, counts, and
the currently-selected ids — exactly what a dropdown needs.

**Canonical example:**

```bash
curl -X POST $GLOW_INSTANCE_URL/persona/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -d '{
    "search": "confused",
    "filter_department_ids": ["dept-cs"],
    "voice_search": "alloy",
    "page_size": 25,
    "page_offset": 0
  }'
```

The response shape is `{ personas: [...], scenario_filter,
department_filter, voice_filter, ... }`. The specific facet set varies
per artifact — see each `/<art>/search` entry in the
[API reference](/api-reference) for the exact `filter_<facet>_ids` /
`<facet>_search` inputs and `<facet>_filter` outputs available.

---

# Permissions & Roles

Route: /permissions

# Permissions & Roles

Every request hitting a Glow API endpoint resolves to a **profile**,
each profile carries exactly one **role**, and the role's
**permissions** -- a list of `(artifact, operation)` tuples -- decide
which routes that request can touch. The same tuple list is mirrored
to the client in every `context` response so the UI can hide the
buttons, sidebar entries, and routes the caller can't reach without
making a round-trip just to discover a 403.

## The model

- A **profile** is a person (or a guest auto-provisioned at first
  login -- see [Authentication](/authentication)).
- A profile has exactly one **role** (the `role_id` on the profile
  resource).
- A role has a set of **permissions**. Each permission row in
  `permissions_resource` is an `(artifact, operation)` pair --
  e.g. `("persona", "create")`, `("attempt", "dashboard")`,
  `("test", "invocation_run")`.
- A role's `permission_ids` define what tuples are granted. The
  server enforces the tuple at the route boundary; the client mirrors
  the same check to filter the UI.

Two derived shapes flow off this list:

| Shape | Type | Used for |
|-------|------|----------|
| `role_permissions` | `[artifact, operation][]` | Per-button / per-route gating (the exact tuple check). |
| `role_artifacts` | `string[]` (unique artifacts) | Coarse sidebar visibility -- *"is any operation on `persona` granted?"*. |

`role_artifacts` is just `dict.fromkeys(p.artifact for p in perms)` --
the deduplicated artifact projection of `role_permissions`. The wire
uses `role_artifacts` for the top-level sidebar gate and
`role_permissions` for the granular check.

---

## How a request gets authorized

```mermaid
sequenceDiagram
    participant C as Client with viewer token
    participant M as Middleware
    participant H as Route handler
    C->>M: POST /persona/create + Bearer
    M->>M: resolve identity
    M->>M: has_permission persona create?
    M-->>C: 403 denied before any work
    Note over H: handler never runs
```

*A viewer-role token to `POST /persona/create` is rejected by `has_permission(persona, create)` in middleware — 403 before any work runs.*

The flow is the same for every authenticated route:

```
  Authorization: Bearer <jwt>
            │
            ▼
  ┌─────────────────────────┐
  │ resolve_identity(token) │   verifies JWT signature, extracts
  └─────────────────────────┘   profile_id (direct claim, email
            │                   lookup, or Keycloak sub fallback)
            ▼
  ┌──────────────────────────────────┐
  │ resolve_profile_identity_context │   hydrates the profile's
  └──────────────────────────────────┘   role + permissions
            │
            ▼
       ProfileIdentityContext
         .role_permissions  =  [("persona", "create"), …]
         .role_artifacts    =  ["persona", "attempt", …]
            │
            ▼
  ┌──────────────────────────────┐
  │ has_permission(role_perms,   │   route handler asserts
  │   artifact, operation)       │   the tuple before doing work
  └──────────────────────────────┘
            │
       granted? ──── no ───▶  403 Forbidden
            │
           yes
            ▼
        run handler
```

The server-side check is a one-liner used by every protected route:

```python
from app.infra.permissions_helpers import has_permission

if not has_permission(profile.role_permissions, "persona", "create"):
    raise PermissionDenied(...)
```

Same predicate, same tuple, everywhere. There is no implicit
"admins bypass" branch -- admin roles simply have every tuple in
their `permission_ids`.

---

## `role_artifacts` in responses

Every artifact's `POST /<artifact>/context` (and the canonical
`POST /profile/context`) returns the caller's permission projection.
The relevant slice of `ProfileContextApiResponse`:

```json
{
  "id": "f3c9…-profile-uuid",
  "name": "Ashok S.",
  "role": "Administrator",
  "active": true,

  "role_artifacts": [
    "persona", "scenario", "simulation", "cohort",
    "profile", "department", "agent", "model",
    "attempt", "test", "system", "setting"
  ],

  "scoped_roles": ["Learner", "Instructor"],

  "department_ids": ["dept-cs-uuid"],
  "primary_department_id": "dept-cs-uuid",

  "settings_id": "settings-uuid",
  "session_id": "session-uuid",

  "is_emulation": false,
  "emulation_depth": 0
}
```

`role_artifacts` is the coarse projection (one entry per artifact the
role can touch at all). The fine-grained tuple list
(`role_permissions`) is exposed through the per-artifact
`/<artifact>/context` shapes when an operation-level gate is needed
(chat sub-ops, invocation sub-ops, single-op collapsed views).
`scoped_roles` lists role names the caller is allowed to *assign*
to other profiles, used by the profile editor's role dropdown.

The full schema is generated under
[Profile Context API](/api-reference/profile/post-profile-context).

---

## Mirroring on the client

The client mirrors the server check so the UI never offers an action
the server would reject. Reference implementation:
`/lib/permissions.ts` + `/lib/sidebar-config.ts` in the
`glow-academic-client` repo.

Three predicates cover every gating site:

```ts
// 1. Top-level page guard — call in a server component after fetching context.
guardPage(pathname, context.role_permissions);

// 2. Sidebar item — collapsed VIEW children (home, dashboard, …) and
//    compound sub-domains (chat_, invocation_) map to their parent
//    artifact + op/prefix automatically.
canAccessSidebarItem("persona", role_permissions);

// 3. Arbitrary route check — used by middleware-style guards.
canAccessPage("/training/personas", role_permissions);
```

The contract: **any UI element tied to a server-side operation should
consult `role_permissions`**. If you add a new route, add a
`PAGE_RULES` entry. If you add a new sidebar item, give it an
`artifact` field that lines up with the permission catalog. The
flatten-era reality is that single-op pages (e.g. `/home` ↔ `attempt,
home`) match by exact op while compound sub-domains (`/chat/*`,
`/invocation/*`) match by prefix -- see `findRuleForArtifact` for the
mapping table.

---

## Defining a role

Roles, permissions, and the join between them all live in
`*_resource` tables hydrated through the standard artifact CRUD:

- **Permission catalog** -- one row per `(artifact, operation)` pair.
  Surfaced via `POST /permission/get` and `POST /permission/search`
  (resource type defined in `core/app/tools/resources/permissions/`).
  Catalog rows are seeded by the OpenAPI / route registry sweep at
  deploy time -- you do not author them by hand.
- **Role resource** -- one row per role (`Learner`, `Instructor`,
  `Administrator`, …). Each role row carries:
  - `name`, `description`, `level` (0 = highest privilege)
  - `permission_ids[]` -- the tuple set the role grants
  - `request_limit_ids[]` -- optional per-role rate limit
- **Profile → role** -- the profile resource's `role_id` link
  (single-select).

Seed roles ship in `glow-deploy.yaml` per-instance. The role editor
(`POST /profile/draft` with the inline `role_draft` payload) is the
runtime path -- it can re-link an existing role or inline-create a
new role + new request limits in one round-trip.

`role.level` is an integer hierarchy used by helpers like
`can_manage_level(user_level, target_level)`: a profile can only
edit / delete / duplicate / emulate a profile whose role level is
*strictly greater than* (= less privileged than) their own.

---

## Departments + scoping

Departments are an **orthogonal** concept from roles. The role
decides *which artifacts* the caller can touch at all
(`(persona, create)` granted or not). The profile's
`department_ids` and `primary_department_id` decide *which rows
within each artifact* are visible -- nearly every artifact's
search/get pipeline filters by department membership.

The two combine multiplicatively:

| | `(persona, create)` denied | `(persona, create)` granted |
|---|---|---|
| Not in dept CS | 403 | 200 -- creates in caller's primary dept |
| In dept CS | 403 | 200 -- creates in CS (if scoped) |

For the full scoping model see [Departments](/departments).

---

## Related

- [Authentication](/authentication) -- how the Bearer JWT resolves to
  the `profile_id` that drives the role lookup.
- [Profile Context API](/api-reference/profile/post-profile-context)
  -- canonical `role_artifacts` shape on the wire.
- [Departments](/departments) -- the orthogonal row-scoping layer
  that combines with role permissions.
- [Profiles](/profiles) -- where the `role_id` link is set and the
  role editor lives.

---

# Personas

Route: /personas

# Personas

Personas are the AI-driven characters that learners interact with
during training simulations — they define *who* the learner is
talking to and *how* that character behaves.

## What is a Persona?

A persona is a reusable AI character definition that controls the
personality, behavior, and communication style of the simulated
individual a learner will face. Each persona is built from:

- **Name** — the character's display name (e.g., *Confused Student*, *Aggressive Student*)
- **Description** — a short summary of the character's role and disposition
- **Instructions** — the behavioral prompt template that tells the AI how to act, including parameter placeholders
- **Examples** — sample dialogue exchanges that demonstrate the character's tone
- **Color & Icon** — visual identifiers in the simulation UI
- **Voice** — the TTS voice used when audio mode is enabled
- **Parameter Fields** — dynamic placeholders (`{{class}}`, `{{location}}`, `{{intensity}}`) injected at runtime
- **Departments** — organizational groupings for filtering and access control

Personas are assigned to [Scenarios](/scenarios), not directly to
simulations or agents. A single persona can appear in many scenarios.

## Where personas sit in the workflow

Personas are **step 1** in the Glow content pipeline:

| Step | Resource | Description |
|------|----------|-------------|
| **1. Create Personas** | **Personas** | Define AI characters with instructions, examples, and parameter fields |
| 2. Assign to Scenarios | [Scenarios](/scenarios) | Build training situations and attach personas to them |
| 3. Add Scenarios to Simulations | [Simulations](/simulations) | Bundle scenarios into a complete training session with rubrics and time limits |
| 4. Add Simulations to Cohorts | [Cohorts](/cohorts) | Assign simulations to groups of learners |
| 5. Run Attempts | [Chat](/chat) | Learners start attempts and interact with persona-driven AI |

---

## Create a persona

### Via the CLI

```bash
glow personas create --body '{
  "personas": [{
    "name": "Confused Student",
    "description": "Seeks to understand by asking questions about course material",
    "instructions": "You are a confused student in {{class}}. You do not understand the material covered in the last lecture. Ask clarifying questions and express frustration when answers are unclear. Your confusion is genuine, not combative."
  }]
}'
```

### Via the API

```bash
curl -X POST $GLOW_INSTANCE_URL/persona/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -d '{
    "personas": [{
      "name": "Confused Student",
      "description": "Seeks to understand by asking questions about course material",
      "instructions": "You are a confused student in {{class}}..."
    }]
  }'
```

Each entry returns the new `persona_id`, the generated `draft_id`,
and the initial `version` for optimistic-concurrency follow-ups.

---

## Writing effective instructions

The `instructions` field is the core of a persona. Well-written
instructions produce consistent, realistic interactions.

### Role definition

Start with a clear statement of who the character is:

```
You are a student in {{class}} who was caught cheating on the midterm exam.
You are meeting with the instructor during office hours.
```

### Behavioral guidelines

Describe how the character should respond emotionally and conversationally:

```
You feel embarrassed and defensive. You initially deny the accusation,
but if the instructor presents evidence calmly, you gradually admit fault.
Do not become aggressive unless the instructor is accusatory.
```

### Knowledge boundaries

Define what the character does and does not know:

```
You do not know the specific academic integrity policy. You assume the
penalty is automatic expulsion. You have never been in trouble before.
```

### Communication style

Set the tone, vocabulary level, and mannerisms:

```
Speak informally. Use short sentences. Avoid eye contact metaphors.
Start responses with hedging phrases like "I mean..." or "Look, I just..."
```

---

## Parameter fields

Parameter fields make personas dynamic. Instead of hard-coding values,
use `{{placeholder}}` syntax in your instructions. Glow resolves these
at runtime based on the scenario's parameter configuration.

**Example: aggressive student with parameters**

```
You are an aggressive student in {{class}} at {{location}}.
A {{issue_type}} has occurred and you are upset.
Your intensity level is {{intensity}} on a scale of 1-10.
The deadline for resolution is {{deadline}}.

At intensity 1-3, you are irritated but civil.
At intensity 4-6, you raise your voice and interrupt.
At intensity 7-10, you USE ALL CAPS and make demands.
```

Available parameter fields from the university seed:

| Parameter | Example values |
|-----------|---------------|
| `{{class}}` | CS-180, CS-251, CS-307, CS-422 |
| `{{location}}` | Lawson, Felix Haas Hall, Data Science Building |
| `{{intensity}}` | 1 through 10 |
| `{{deadline}}` | A date string |
| `{{time}}` | A time string |
| `{{temperament}}` | Aggressive, Confused, Happy, Passive |
| `{{crowdedness}}` | 1 through 10 |

Parameter fields are defined on the persona and resolved when the
persona runs inside a scenario that provides matching parameter values.

---

## Examples that teach voice

Examples teach the AI the persona's voice through concrete dialogue
samples. They're especially useful for characters with distinctive
speech patterns.

When creating or updating the persona, supply examples as an array of
dialogue strings:

```bash
glow personas draft --body '{
  "name": "Passive Student",
  "description": "Low engagement, avoids conflict, starts with Uh...",
  "instructions": "You are a disengaged student. You avoid confrontation and give minimal responses. Always start your reply with \"Uh...\" and trail off when pressed for details.",
  "examples": [
    "Instructor: Can you tell me why you missed the last three labs?\nStudent: Uh... I guess I just forgot. Sorry.",
    "Instructor: This is going to affect your grade significantly. What happened?\nStudent: Uh... I dunno. Stuff, I guess. Can I just make them up?",
    "Instructor: I need you to take this seriously.\nStudent: Uh... yeah. I mean, I am. Sort of."
  ]
}'
```

Examples help the AI replicate specific verbal tics, sentence
structures, and emotional registers that are difficult to capture
through instructions alone.

---

## The draft cycle

Glow uses a draft system with optimistic concurrency for editing
personas. When you save changes via `POST /persona/draft`, the
response carries the new `version` — pass it back as
`expected_version` on the next save so a concurrent edit doesn't
silently overwrite yours.

**Create or update a draft:**

```bash
glow personas draft --body '{
  "input_draft_id": "existing-draft-uuid",
  "expected_version": 1,
  "name": "Updated Confused Student",
  "description": "Seeks to understand by asking repeated questions",
  "instructions": "You are a confused student in {{class}}...",
  "parameter_field_ids": ["param-field-uuid-1", "param-field-uuid-2"],
  "voice_ids": ["voice-uuid"]
}'
```

Equivalent raw HTTP:

```bash
curl -X POST $GLOW_INSTANCE_URL/persona/draft \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -d '{
    "input_draft_id": "existing-draft-uuid",
    "expected_version": 1,
    "name": "Updated Confused Student"
  }'
```

The response includes `draft_id`, `new_version`, and `form_state` so
your client can track optimistic concurrency.

**List your in-flight drafts:**

```bash
glow personas drafts
```

---

## Search & filter

Persona search supports full-text, facet filters (department, voice,
color, icon, scenario, field), and pagination.

```bash
# Simple text search via the ergonomic helper
glow personas search --name confused

# Full facet search via raw body
glow personas search --body '{
  "search": "confused",
  "filter_department_ids": ["dept-cs"],
  "voice_search": "alloy",
  "page_size": 25,
  "page_offset": 0
}'
```

Raw HTTP:

```bash
curl -X POST $GLOW_INSTANCE_URL/persona/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -d '{"search": "confused", "page_size": 25}'
```

The response returns hydrated `ListPersonaApiPersona` rows plus
filter facets (`scenario_filter`, `department_filter`, `voice_filter`,
…) so the UI can render dropdowns without a second round-trip.

---

## Bulk operations

Bulk delete and update follow the canonical *all-matching* shape that
persona is the prove-out for across the artifact catalog. Pass either
explicit IDs, or `all: true` with flat filter fields + optional
`excluded_ids`.

**Delete by explicit IDs:**

```bash
glow personas delete --body '{
  "persona_ids": ["persona-1", "persona-2", "persona-3"]
}'
```

**Delete all matching a filter (with exclusions):**

```bash
glow personas delete --body '{
  "all": true,
  "filter_department_ids": ["dept-cs"],
  "voice_search": "deprecated-voice",
  "excluded_ids": ["persona-keep-this-one"]
}'
```

**Bulk update via `patch`:**

```bash
glow personas update --body '{
  "all": true,
  "filter_department_ids": ["dept-archive"],
  "patch": { "archived": true }
}'
```

The same shape applies across artifacts that have adopted the pattern
— check the relevant API reference for each artifact's allowed filter
fields and `patch` schema.

## Common operations reference

| Task | CLI | API |
|------|-----|-----|
| List all personas | `glow personas search` | `POST /persona/search` |
| Get one persona | `glow personas get --body '{"persona_id": "..."}' ` | `POST /persona/get` |
| Create personas | `glow personas create --body '{"personas": [...]}'` | `POST /persona/create` |
| Update personas | `glow personas update --body '{"personas": [...]}'` | `POST /persona/update` |
| Duplicate a persona | `glow personas duplicate` | `POST /persona/duplicate` |
| Delete personas | `glow personas delete --body '{"persona_ids": [...]}'` | `POST /persona/delete` |
| Bulk delete (filter) | `glow personas delete --body '{"all": true, "filter_…": "…"}'` | `POST /persona/delete` |
| Save a draft | `glow personas draft --body '{...}'` | `POST /persona/draft` |
| List drafts | `glow personas drafts` | `POST /persona/drafts` |
| Export to CSV | `glow personas export` | `POST /persona/export` |
| Import from CSV | — | `POST /persona/csv` |

## Related

- [Personas API Reference](/api-reference/persona) — full endpoint schemas and field definitions
- [Personas CLI Reference](/cli-reference/personas) — all CLI commands and flags
- [Scenarios](/scenarios) — the training situations that put personas to work
- [Simulations](/simulations) — bundling scenarios into complete training sessions
- [Chat](/chat) — the live conversation surface where personas drive interactions

---

# Practice

Route: /practice

# Practice

Practice provides open-ended training sessions where TAs can practice with student personas outside of graded assignments. Unlike Home (which shows assigned simulations), Practice surfaces all available practice simulations for self-directed skill development.

![Practice page showing available simulations with retry counts and best scores](/screenshots/practice/list.png)

## What is Practice?

Practice lets TAs engage with Confused, Aggressive, Passive, and Happy student personas on their own schedule. Practice simulations are separate from assigned training -- they provide a low-stakes environment for TAs to rehearse office-hours scenarios like explaining difficult concepts, handling grade disputes, or de-escalating frustrated students.

Practice offers two views:

1. **Simulation cards** (`POST /attempt/practice`) -- Available practice simulations with progress indicators, persona details, and rubric/standard mappings.
2. **Attempt history** (`POST /attempt/search`) -- Paginated history of the TA's practice attempts with scores, scenarios, and completion data.

## Quick Start

### CLI

> Calls below use `$GLOW_INSTANCE_URL` + `$GLOW_TOKEN` — see [Authentication](/authentication) to export them once.

```bash
# Get available practice simulations
glow attempts practice

# Search practice attempt history
glow attempts search --body '{"page": 1, "page_size": 20, "sort_order": "desc"}'

# Export practice data
glow attempts export
```

### API

```bash
# Get practice simulation cards
curl -X POST $GLOW_INSTANCE_URL/attempt/practice \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

# Search practice history
curl -X POST $GLOW_INSTANCE_URL/attempt/search \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "page_size": 10,
    "sort_by": "date",
    "sort_order": "desc"
  }'
```

## Understanding the Simulation Cards

The `POST /attempt/practice` response mirrors the Home response structure:

- **`actor_name`** -- Display name of the current TA.
- **`items`** -- Array of `ChatSimulationOperational` objects for practice simulations:
  - `simulation_id`, `simulation_name`, `simulation_description` -- Simulation identity
  - `practice_id` -- UUID of the practice entry (used to start a session)
  - `practice_simulation` -- Always `true` for practice simulations
  - `color`, `icon` -- Persona display properties
  - `status` -- `"passed"`, `"in-progress"`, or `"not-started"`
  - `highest_score`, `pass_pct`, `has_passed` -- Performance data
  - `num_sessions` -- Number of practice sessions
  - `time_limit` -- Time limit in seconds
  - `scenario_ids` -- Ordered scenario list
  - `view_mode` -- Typically `"practice"`
- **`rubrics`** -- Rubric metadata with `rubric_id`, `name`, `standard_group_ids`.
- **`standard_groups`** -- Groups like "Communication Skills", "Policy Knowledge", "De-escalation" with `points` and `pass_points`.
- **`standards`** -- Individual assessment standards within each group.

## Retrying a practice session

![Active practice session showing the chat interface with hint button and backtrack option](/screenshots/practice/active-session.png)

## Searching Practice History

![Practice results showing rubric scores, per-criterion feedback, and improvement suggestions](/screenshots/practice/results.png)

The `POST /attempt/search` endpoint returns paginated `HistoryItem` rows.

### Filters

| Filter | Field | Description |
|---|---|---|
| Simulation search | `simulation_search` | Text search by simulation name |
| Scenario search | `scenario_search` | Text search by scenario title |
| Scenario filter | `scenario_ids` | Filter by specific scenarios |
| Infinite mode | `infinite_mode` | Filter by infinite mode status |
| Archived | `show_archived` | Include archived practice attempts |
| Sorting | `sort_by`, `sort_order` | Sort by any column |
| Pagination | `page`, `page_size` | Control page size |

Each `HistoryItem` includes `attempt_id`, `simulation_name`, `score`, `score_status`, `persona_names_junction`, `scenario_titles`, `num_scenarios_completed`, and action flags (`show_view`, `show_continue`). Practice attempts are identified by `practice_simulation: true` and may include a `practice_scenario_id`.

## Practice vs. Home

| Aspect | Home | Practice |
|---|---|---|
| Purpose | Assigned training | Self-directed practice |
| Simulations | Assigned by admin/instructor | All practice-enabled simulations |
| Grading | Counts toward reports/leaderboard | May be excluded from official metrics |
| Certificate | Export includes certificate | Standard export |
| `view_mode` | `"member"` or `"instructional"` | `"practice"` |

## Exporting practice data

## Common Operations

| Task | CLI | API Endpoint |
|---|---|---|
| Get practice simulations | `glow attempts practice` | `POST /attempt/practice` |
| Search practice history | `glow attempts search` | `POST /attempt/search` |
| Export data | `glow attempts export` | `POST /attempt/export` |
| Refresh caches | -- | `POST /attempt/refresh` |

## Related

- [Practice API Reference](/api-reference/attempt)
- [Practice CLI Reference](/cli-reference/attempts)
- [Home Guide](/home) -- assigned TA training
- [Session Guide](/session) -- session detail view

---

# Pricing

Route: /pricing

# Pricing

Pricing tracks the AI costs associated with running TA training simulations. It aggregates cost data by day and model, and provides a paginated history of generation groups with token counts and dollar amounts.

![Pricing dashboard showing usage costs broken down by model, simulation, and time period](/screenshots/pricing/dashboard.png)

## What is Pricing?

Every time a TA interacts with a student persona during an office-hours simulation, Glow makes AI model calls that consume tokens and incur costs. Pricing gives administrators visibility into this spending with:

1. **Daily cost chart** (`POST /system/pricing`) -- Daily aggregations showing `total_cost` and `run_count` per model, with filter options for models and agents.
2. **Group history** (`POST /system/groups`) -- Paginated table of AI generation groups showing per-group token counts, costs, and associated models/agents.

This helps institutions monitor budget consumption, compare model costs, and forecast future spending for their TA training programs.

## Quick Start

### CLI

> Calls below use `$GLOW_INSTANCE_URL` + `$GLOW_TOKEN` — see [Authentication](/authentication) to export them once.

```bash
# Get daily cost chart data
glow system pricing

# Get pricing for a specific date range
glow system pricing --body '{"start_date": "2025-01-01", "end_date": "2025-01-31"}'

# Search group history (paginated)
glow system groups --body '{"page": 1, "page_size": 25, "sort_order": "desc"}'

# Export pricing data
glow system export
```

### API

```bash
# Get daily cost aggregations
curl -X POST $GLOW_INSTANCE_URL/system/pricing \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2025-01-01",
    "end_date": "2025-01-31"
  }'

# Search group history
curl -X POST $GLOW_INSTANCE_URL/system/groups \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "page_size": 20,
    "sort_order": "desc"
  }'
```

## Filtering

| Filter | Field | Description |
|---|---|---|
| Date range | `start_date`, `end_date` | Scope costs to a time window |
| Date range (alias) | `date_from`, `date_to` | Alternative date field names |
| Pagination | `page`, `page_size` (search only) | Control page size |
| Sort direction | `sort_order` (search only) | `"asc"` or `"desc"` |

## Understanding the Daily Cost Response

The `POST /system/pricing` response includes:

- **`daily`** -- Array of `PricingDailyItem` buckets:
  - `date_key` -- Date bucket (e.g., `"2025-01-15"`)
  - `model_id` -- Which AI model was used
  - `total_cost` -- Dollar cost for this day + model combination
  - `run_count` -- Number of AI runs in this bucket
- **`model_options`** -- Filter dropdown options for models (`value`, `label`, `count`).
- **`agent_options`** -- Filter dropdown options for agents.
- **`resources`** -- Resource metadata keyed by ID:
  - `agents` -- Agent display names
  - `models` -- Model display names
- **`total_count`** -- Total number of matching records.
- **`analytics`** -- Filter facets for the page.

## Understanding Group History

The `POST /system/groups` response returns paginated `PricingGroupItem` rows:

- `group_id` -- UUID of the generation group
- `session_id` -- Associated session
- `group_name` -- Display name of the group
- `first_run_at`, `last_run_at` -- Time span of the group's runs
- `run_count` -- Number of AI runs
- `total_input_tokens` -- Input tokens consumed
- `total_output_tokens` -- Output tokens generated
- `total_tokens` -- Combined token count
- `total_cost` -- Dollar cost as a string
- `agent_ids`, `agent_names` -- Agents used
- `model_ids`, `model_names` -- Models used

## Model Breakdown

## Exporting

```bash
# Export all pricing data as a denormalized ZIP
glow system export
```

The response includes `content` (base64-encoded), `file_name`, `mime_type`, and `row_count`.

## Common Operations

| Task | CLI | API Endpoint |
|---|---|---|
| Daily cost chart | `glow system pricing` | `POST /system/pricing` |
| Group history | `glow system groups` | `POST /system/groups` |
| Export data | `glow system export` | `POST /system/export` |
| Refresh caches | -- | `POST /system/refresh` |

## Related

- [Pricing API Reference](/api-reference/system)
- [Pricing CLI Reference](/cli-reference/systems)
- [Invocation Guide](/invocation) -- individual AI model call tracking
- [Group Guide](/group) -- AI generation group details

---

# Profiles

Route: /profiles

# Profiles

Profiles represent the people who use Glow -- instructors, teaching assistants, and administrators. Every user in your institution gets a profile that determines what they can access and how they interact with simulations through cohorts.

![Profiles list showing user cards with name, role, department, and last login](/screenshots/profiles/list.png)

## What is a Profile?

A profile is a user identity in Glow. Each profile has a name, email, role, department membership, and optional request limits. Profiles are the foundation of the platform: they are assigned to cohorts, which in turn give learners access to simulations.

**University example:** Your CS department might have profiles for Professor Smith (Instructional Staff), TA Johnson (Instructional Staff), and a University Admin (Super Administrator). Each profile's role controls what they can create, edit, and view across the platform.

## How It Connects: The 5-Step Workflow

Profiles participate in step 4 of the Glow workflow:

1. **Create Personas** -- Define AI student characters with temperaments and behaviors.
2. **Assign to Scenarios** -- Attach personas and documents to scenarios.
3. **Add to Simulations** -- Group scenarios into simulations.
4. **Add to Cohorts** -- Assign *profiles* and simulations to a cohort. Profile personas tell the AI who each learner is, so the AI character can adapt.
5. **Run Attempts** -- Learners launch simulations from their cohort.

Profiles are the link between real users and the simulation experience. Without a profile assigned to a cohort, a user cannot access any simulations.

---

## Create a profile

### Via the CLI

> Calls below use `$GLOW_INSTANCE_URL` + `$GLOW_TOKEN` — see [Authentication](/authentication) to export them once.

```bash
glow profiles create --body '{
  "profiles": [
    {
      "name": "TA Johnson",
      "email": "johnson@university.edu",
      "role": "Instructional Staff"
    }
  ]
}'
```

### Via the API

All endpoints use `POST` and require an `Authorization: Bearer` header.

```bash
curl -X POST $GLOW_INSTANCE_URL/profile/create \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "profiles": [
      {
        "name": "Professor Smith",
        "email": "smith@university.edu",
        "role": "Instructional Staff"
      }
    ]
  }'
```

![Profile creation form showing name, role selection, and department assignment](/screenshots/profiles/create.png)

---

## Roles, departments, and request limits

### Roles

Glow supports three profile roles, each with different permissions:

| Role | Description |
|---|---|
| **Instructional Staff** | Can run simulations, view assigned cohorts, and access learner-facing features. Used for TAs and professors. |
| **Administrator** | Can create and manage resources (scenarios, documents, parameters) within their department. |
| **Super Administrator** | Full platform access across all departments. Can manage profiles, departments, and system settings. |

**Example:** TA Johnson has the Instructional Staff role and can run practice simulations in their assigned cohorts. The University Admin has the Super Administrator role and can manage profiles across all departments.

### Department membership

Every profile belongs to one or more departments. Department membership controls:

- Which resources (documents, parameters, scenarios) the profile can see
- Which cohorts the profile can be added to
- Which other profiles the user can manage (for administrators)

**Example:** Professor Smith belongs to the "University" department and can see all resources scoped to that department.

### Request limits

Profiles can have request limits that cap how many simulation attempts a learner can make. This is useful for controlling API usage in large courses.

---

## Emulating another profile

Super Administrators can emulate any profile to debug what that user actually sees -- cohort access, role-gated UI, request-limit warnings, the works. Emulation is a sub-operation on the profile artifact (`POST /profile/emulate`), and you exit it with `POST /profile/unemulate`.

**Start emulation:**

```bash
curl -X POST $GLOW_INSTANCE_URL/profile/emulate \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "ta-johnson-uuid"
  }'
```

**Stop emulating and return to your own profile:**

```bash
curl -X POST $GLOW_INSTANCE_URL/profile/unemulate \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

Emulation is audit-logged; only Super Administrators can invoke `/profile/emulate`.

---

## Drafts

Profiles support the draft workflow. When you create or update a profile through the UI, changes are saved as a draft before being published. The draft endpoint enforces optimistic concurrency via `expected_version`.

```bash
# Save a profile draft
glow profiles draft --body '{
  "name": "TA Johnson",
  "email": "johnson@university.edu",
  "role": "Instructional Staff"
}'
```

Via the API, use `PATCH /profile/draft` with fields like `input_draft_id`, `expected_version`, `name`, `email`, `flag_id`, `department_ids`, and `role_ids`.

---

## Search and filter

Profile search supports full-text plus facet filters across role, department, and cohort membership.

```bash
curl -X POST $GLOW_INSTANCE_URL/profile/search \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "search": "Johnson",
    "role_filter": "Instructional Staff",
    "page_size": 10
  }'
```

---

## Bulk operations

Bulk delete and update follow the canonical *all-matching* shape -- pass either explicit IDs, or `all: true` with flat filter fields + optional `excluded_ids` + a `patch` for updates.

```bash
# Delete every profile in a sunset department, except admins
glow profiles delete --body '{
  "all": true,
  "filter_department_ids": ["dept-sunset"],
  "excluded_ids": ["super-admin-uuid"]
}'

# Bulk update via patch (e.g. raise request limits for an entire cohort)
glow profiles update --body '{
  "all": true,
  "filter_department_ids": ["dept-cs"],
  "patch": { "request_limit": 100 }
}'
```

See the [Personas guide](/personas#bulk-operations) for the canonical write-up of this pattern.

## Common Operations

| Task | CLI | API Endpoint |
|---|---|---|
| List all profiles | `glow profiles list` | `POST /profile/search` |
| Get a profile | `glow profiles get --body '{...}'` | `POST /profile/get` |
| Create profiles | `glow profiles create --body '{...}'` | `POST /profile/create` |
| Update profiles | `glow profiles update --body '{...}'` | `POST /profile/update` |
| Duplicate a profile | -- | `POST /profile/duplicate` |
| Delete profiles | `glow profiles delete --body '{...}'` | `POST /profile/delete` |
| Bulk delete (filter) | `glow profiles delete --body '{"all": true, "filter_…": "…"}'` | `POST /profile/delete` |
| Emulate a profile | -- | `POST /profile/emulate` |
| Stop emulating | -- | `POST /profile/unemulate` |
| Export to CSV | `glow profiles export` | `POST /profile/export` |
| Save a draft | `glow profiles draft --body '{...}'` | `PATCH /profile/draft` |
| List drafts | -- | `POST /profile/drafts` |

## Related

- [Profiles API](/api-reference/profile)
- [Profiles CLI](/cli-reference/profile)
- [Cohorts Guide](/cohort) -- assign profiles to cohorts
- [Departments Guide](/department) -- manage department membership

---

# Providers

Route: /providers

# Providers

Providers represent the LLM backends that power Glow. Each provider encapsulates an external AI service -- such as OpenAI or Anthropic -- along with its API endpoints, authentication keys, and configuration values. Models connect to providers to gain access to these backends.

---

## What is a Provider?

A provider in Glow is the infrastructure layer between your platform and an external LLM service. It stores:

- **Endpoints** -- the base URL for API calls (e.g., `https://api.openai.com/v1`)
- **Keys** -- encrypted API credentials for authenticating with the service
- **Values** -- configuration parameters specific to the provider
- **Departments** -- organizational scoping for access control

Providers are shared resources. A single "OpenAI" provider can serve multiple models (`gpt-4o`, `gpt-4o-mini`, `o1`), each configured with its own temperature, quality, and modality settings.

---

## How it Connects

```
Provider  -->  Model (model has provider_id)
   |               |
   |               +--> Agent (via agent_models_junction)
   |
   +-- endpoints, keys, values (encrypted config)
```

- **Models** reference providers through `provider_ids`. Each model's search result includes `provider_id` and `provider_name`.
- The `model_usage_count` and `model_ids` fields on the provider list response show how many models depend on each provider.
- Providers do not connect directly to agents, tools, rubrics, or evals. They are always accessed through models.

---

## Create a provider

### Via the CLI

> Calls below use `$GLOW_INSTANCE_URL` + `$GLOW_TOKEN` — see [Authentication](/authentication) to export them once.

```bash
glow providers create --body '{
  "providers": [{
    "name": "OpenAI Production",
    "description": "Production OpenAI API for TA training simulations"
  }]
}'
```

### Via the API

```bash
curl -X POST $GLOW_INSTANCE_URL/provider/create \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "providers": [{
      "name": "Anthropic Production",
      "description": "Anthropic Claude API for office hour simulations"
    }]
  }'
```

Each entry returns the new `provider_id`, a generated `draft_id`, and the initial `version`.

---

## Endpoints

Provider endpoints define where API calls are routed. Each provider can have multiple endpoints configured through `endpoint_ids`. Endpoints are managed as resources within the provider's configuration sections.

When you retrieve a provider with `GET`, the response includes an `endpoints` section containing the current endpoint resource and all available endpoint options.

---

## API key management

Provider keys hold encrypted credentials. Keys are never returned in plaintext from list or search operations. To decrypt a key, use the dedicated decrypt endpoint -- every decrypt request is audited with the requesting user's identity.

```bash
curl -X POST $GLOW_INSTANCE_URL/provider/decrypt \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_id": "PROVIDER_UUID",
    "key_id": "KEY_UUID"
  }'
```

The response returns the decrypted `key` value, the key `name`, and the `actor_name` of the requesting user.

---

## The draft cycle

Providers support a draft workflow for staging configuration changes. This is useful when rotating API keys or switching endpoints without disrupting running simulations.

```bash
# Create or update a provider draft
glow providers draft --body '{
  "name": "OpenAI Production",
  "description": "Updated endpoint for v2 API",
  "endpoint_ids": ["NEW_ENDPOINT_UUID"],
  "key_ids": ["NEW_KEY_UUID"]
}'

# List your drafts
glow providers list
```

The draft endpoint uses `PATCH` semantics. Include `input_draft_id` and `expected_version` for updates to existing drafts. The response includes `draft_id`, `new_version`, and a `form_state` object reflecting the server-authoritative state of all fields.

---

## Search & filter

```bash
glow providers search --body '{"search": "openai"}'

glow providers search --body '{
  "filter_department_ids": ["CS_DEPT_UUID"],
  "page_size": 25
}'
```

---

## Bulk operations

Bulk delete and update follow the canonical *all-matching* shape -- explicit IDs, or `all: true` with flat filter fields plus optional `excluded_ids` and a `patch` body. The persona surface is the prove-out; providers adopt the same shape.

**Delete by explicit IDs:**

```bash
curl -X POST $GLOW_INSTANCE_URL/provider/delete \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"provider_ids": ["UUID_1", "UUID_2"]}'
```

Each item in the `results` array indicates whether that specific deletion succeeded, along with a `message`.

**Delete all matching a filter (with exclusions):**

```bash
glow providers delete --body '{
  "all": true,
  "filter_department_ids": ["dept-retired"],
  "excluded_ids": ["provider-keep-this-one"]
}'
```

**Duplicate a provider:**

```bash
curl -X POST $GLOW_INSTANCE_URL/provider/duplicate \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"provider_id": "PROVIDER_UUID"}'
```

The response returns a new `provider_id` for the duplicated provider.

## Common Operations

| Task | CLI | API Endpoint |
|---|---|---|
| List all providers | `glow providers search` | `POST /provider/search` |
| Get provider details | `glow providers get --body '{"provider_id": "..."}'` | `POST /provider/get` |
| Create provider | `glow providers create --body '{...}'` | `POST /provider/create` |
| Update provider | `glow providers update --body '{"provider_id": "...", ...}'` | `POST /provider/update` |
| Duplicate provider | -- | `POST /provider/duplicate` |
| Delete provider(s) | `glow providers delete --body '{"provider_id": "..."}'` | `POST /provider/delete` |
| Bulk delete (filter) | `glow providers delete --body '{"all": true, "filter_…": "…"}'` | `POST /provider/delete` |
| Decrypt a key | -- | `POST /provider/decrypt` |
| Export to CSV | `glow providers export` | `POST /provider/export` |
| Stage a draft | `glow providers draft --body '{...}'` | `PATCH /provider/draft` |
| List drafts | `glow providers list` | `POST /provider/drafts` |

---

## Related

- [Providers API Reference](/api-reference/provider) -- full endpoint and type documentation
- [Providers CLI Reference](/cli-reference/provider) -- all CLI commands
- [Models Guide](/model) -- configure models that use these providers

---

# Realtime

Route: /realtime

# Realtime

Glow's HTTP surface is the canonical entry point for every artifact
operation. Alongside it, the API exposes a parallel **socket.io
WebSocket** surface that mirrors most of those operations 1-for-1 —
intended for live message flow (chat, voice), live progress streams,
and server-pushed updates that don't fit a request/response shape.

## When to use WS vs HTTP

**Default to HTTP.** Every artifact operation is reachable as
`POST /<artifact>/<operation>` with the same payload shape, the same
auth, and the same response. The CLI, the OpenAPI spec, the generated
TypeScript client, and the MCP tools all sit on HTTP.

**Reach for WS** when you need:

- **Live chat or voice** — `attempt.chat_message`, `attempt.chat_voice`,
  `attempt.chat_speak` need bidirectional streaming and per-token push.
- **Live progress on long-running generations** — the WS counterpart of
  `<artifact>.generate` pushes progress frames as the job advances.
- **Server-pushed presence / activity updates** — connecting a socket
  also enrolls the profile in an activity room (see
  [Activity](/activity)).

Most integrations never need WS. The HTTP+SSE watch flow covers
generation streaming for batch / scripted callers; WS is the right
surface when you're driving an interactive UI.

---

## Event naming taxonomy

Server-side handlers register against a flat namespace where each
event name is `<artifact>.<operation>`:

| HTTP endpoint | WS event |
|---|---|
| `POST /persona/search` | `persona.search` |
| `POST /attempt/start` | `attempt.start` |
| `POST /test/generate` | `test.generate` |
| `POST /auth/create` | `auth.create` |

Operations that live in a sub-directory on the HTTP side (for example
`POST /test/invocation/run`) flatten to `<artifact>.<sub_op>` on WS:

| HTTP endpoint | WS event |
|---|---|
| `POST /test/invocation/run` | `test.invocation_run` |
| `POST /test/benchmark/search` | `test.benchmark_search` |
| `POST /attempt/chat/message` | `attempt.chat_message` |
| `POST /attempt/chat/voice` | `attempt.chat_voice` |
| `POST /system/activity/search` | `system.activity_search` |

The taxonomy is mechanical — if you can name the HTTP route, you can
name the WS event. The source of truth is the handler tree at
[`core/app/ws/`](https://github.com/glow-academic/api/tree/main/core/app/ws)
in the API; every file there registers exactly one `@sio.on(...)` event.

---

## Connecting

Glow speaks **socket.io v4** over WebSocket. Auth is bearer-only and
the token rides in the socket.io `auth` payload — *not* as an HTTP
header. The server's `connect` handler reads `auth.token`, runs it
through `resolve_identity`, and stores the resolved `Identity` in
Redis for the lifetime of the socket. Every subsequent event handler
calls `resolve_socket_identity(sid)` to recover that identity — same
object the HTTP middleware materialises per request.

**socket.io-client (JS):**

```js

const socket = io("https://<your-instance>", {
  auth: { token: "Bearer eyJhbGciOi..." },
  transports: ["websocket"],
});

socket.on("connect", () => console.log("connected", socket.id));
socket.emit("attempt.chat_message", {
  chat_id: "...",
  text: "Hello",
});
socket.onAny((event, payload) => console.log(event, payload));
```

**Rust (CLI `GlowSocket::connect`):**

```rust
let sock = GlowSocket::connect("https://<your-instance>", Some(bearer))?;
sock.emit("attempt.chat_message", json!({
  "chat_id": chat_id, "text": "Hello",
}))?;
```

Connections without a valid bearer are rejected at handshake. Multiple
sockets per profile are allowed — multi-tab, multi-device, and the
debug-panel-as-client all coexist without anyone kicking anyone off.

---

## Live chat REPL

The CLI ships a minimal terminal REPL for driving a chat over WS:

```bash
glow attempts chat live <chat_id> --persona <persona_id>
```

What it does:

1. Opens a socket.io connection to your configured base URL with the
   stored bearer token (see [Authentication](/authentication)).
2. Drains any inbound events (non-blocking, 50ms window) and prints
   each one as `<event_name>: <json_payload>`.
3. Reads the next stdin line, emits it as
   `attempt.chat_message` with `{ chat_id, text, persona_id? }`.
4. Loops until EOF, `:quit`, or `:q`.

The REPL is intentionally thin — no markdown rendering, no token-by-
token animation. It's a debugging surface for the WS flow, not a
chat client. Cross-link [Chat](/chat) for the full conversation
semantics (drafts, voice, grades, attempts).

---

## Per-artifact surface

Roughly **~330 events** are registered across the WS tree. The
distribution mirrors how much each artifact uses live flows:

| Artifact | WS events | Notable surfaces |
|---|---|---|
| `attempt` | 38 | Full chat + voice mirror — `chat_message`, `chat_voice`, `chat_speak`, `chat_silence`, `chat_grade`, `chat_get`, plus the standard CRUD + media download set. |
| `scenario` | 21 | Full HTTP mirror. |
| `system` | 20 | Cross-artifact ops — `activity_search`, `activity_resolve`, `health`, `pricing_search`, `session`, plus the group download family. |
| `document` | 19 | CRUD + file/text upload + preview + download. |
| `profile` | 17 | Full HTTP mirror. |
| `test` | 16 | `invocation_run`, `generate`, `trace`, `start`, `stop`, plus benchmark + invocation CRUD. |
| Each of `agent`, `auth`, `cohort`, `department`, `eval`, `field`, `model`, `parameter`, `persona`, `provider`, `rubric`, `setting`, `simulation`, `tool` | 14 | The standard artifact CRUD + draft + search + generate set, mirrored to WS verbatim. |

The exhaustive list lives under
[`core/app/ws/<artifact>/`](https://github.com/glow-academic/api/tree/main/core/app/ws)
— one file per `@sio.on(...)` event. Don't memorise the catalogue; the
HTTP route is the spec, and the WS name follows mechanically.

---

## Voice flow (deferred)

The server-side voice events exist today — `attempt.chat_voice`,
`attempt.chat_speak`, `attempt.chat_silence`, `attempt.audio_upload`,
`attempt.audio_download` — and they share the same auth +
`<artifact>.<sub_op>` shape.

The CLI does **not** ship a voice client yet. Adding mic capture +
playback pulls in `cpal` + `rodio` (native audio deps), which is gated
behind an explicit opt-in. If you need voice today, drive
`attempt.chat_voice` directly from `socket.io-client` or the
in-product voice surface.

---

## Status: untested end-to-end

Be aware:

- The **server** WS surface is in production — every `@sio.on(...)`
  handler is exercised by the in-product clients.
- The **CLI's `GlowSocket`** wrapper compiles cleanly and the chat
  REPL loop is structurally sound, but no smoke test against a running
  `glow-academic-api` instance has been run. Expect to iterate on
  event names / payload shapes the first time you exercise it.
- The Rust wrapper currently uses a single catch-all handler instead
  of per-event registrations — events surface as `(unmatched)` until
  the per-event registration path is wired through the builder. See
  the comments in `src/glow/ws.rs`.

Treat the CLI WS surface as a v1 scaffold. If you hit a mismatch
between an emitted event name and what the server expects, the source
of truth is the file path under `core/app/ws/` — the event name is
always the filename's dotted parent + the registered `@sio.on(...)`
string.

---

## Related

- [Chat](/chat) — live conversation UX, persona semantics, draft cycle, voice mode.
- [Authentication](/authentication) — bearer-token issuance; the same token rides into the WS `auth` payload.
- [Activity](/activity) — presence rows recorded at connect time when a profile's first socket opens.
- [API Reference](/api-reference) — canonical per-operation schemas; WS events accept the same payloads as their HTTP twins.

---

# Reports

Route: /reports

# Reports

Reports provides structured training analytics on TA performance across your institution. It computes overview tables, leaderboard rankings, trend charts, and detailed attempt history -- all filterable by date range, cohort, department, simulation, and scenario.

![Reports list showing learner profiles with aggregate scores and attempt counts](/screenshots/reports/list.png)

## What is Reports?

Reports is the analytics engine that aggregates TA training data into five computed sections:

- **Header Metrics** -- Total attempts, average score, completion percentage, first-attempt pass rate (each with trend data and hover tooltips).
- **Overview** -- Per-simulation breakdown showing attempts, completed attempts, passed attempts, average score, completion percentage, and pass rate.
- **Leaderboard** -- Ranked TA profiles with metrics like average score, highest score, total attempts, and first-attempt pass rate.
- **Trends** -- Time-series chart data with daily aggregations of attempts, scores, and pass rates.
- **History** -- Paginated attempt rows with scores, chat counts, and completion details.

![Individual report showing per-attempt scores, rubric standard breakdowns, and improvement trends](/screenshots/reports/profile-detail.png)

Reports is designed for program coordinators who need to evaluate how a cohort of TAs is performing across Confused, Aggressive, Passive, and Happy student persona simulations.

## Quick Start

### CLI

> Calls below use `$GLOW_INSTANCE_URL` + `$GLOW_TOKEN` — see [Authentication](/authentication) to export them once.

```bash
# Fetch the full reports bundle
glow attempts report

# Fetch reports filtered by cohort and date range
glow attempts report --body '{"cohort_ids": ["fall-2025-cs101"], "start_date": "2025-01-01", "end_date": "2025-06-30"}'

# Export all reports data as a ZIP
glow attempts export
```

### API

```bash
# Get reports with filters
curl -X POST $GLOW_INSTANCE_URL/attempt/report \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "department_ids": ["dept-cs"],
    "simulation_ids": ["sim-confused-student"],
    "start_date": "2025-01-01",
    "end_date": "2025-06-30",
    "sort_by": "average_score",
    "sort_order": "desc",
    "page_limit": 50
  }'
```

## Filtering

| Filter | Field | Description |
|---|---|---|
| Date range | `start_date`, `end_date` | Scope to a semester or custom window |
| Cohorts | `cohort_ids` | Filter by training cohort |
| Simulations | `simulation_ids` | Filter by specific persona simulations |
| Departments | `department_ids` | Filter by academic department |
| Roles | `roles` | Filter by TA role type |
| Scenarios | `scenario_ids` | Filter by individual scenarios |
| Profiles | `profile_ids` | Scope to specific TA profiles |
| Single TA | `target_profile_id` | View data for one TA |
| Search | `search` | Text search across profiles |
| Pagination | `page_limit`, `page_offset` | Control result page size |

## Understanding the Response

The `ReportsResponse` contains:

### `sections`

The computed report sections:

- **`header_metrics`** -- `total_attempts`, `average_score`, `completion_percentage`, `first_attempt_pass_rate`. Each metric includes `current_value`, `has_data`, `data_points`, and `hover` details (mean, median, mode, count, percent).
- **`overview`** -- Array of `ReportsOverviewRow` grouped by simulation: `simulation_id`, `attempts`, `completed_attempts`, `passed_attempts`, `average_score`, `pass_rate`.

- **`leaderboard`** -- Array of `ReportsLeaderboardRow` with `rank`, `profile_id`, `total_attempts`, `average_score`, `highest_score`, plus detailed `profile_metrics` (messages per session, session efficiency, stagnation rate, time spent).

- **`trends`** -- Array of `ReportsTrendPoint` with `date`, `attempts`, `average_score`, `pass_rate` for charting.

- **`history`** -- Array of `ReportsHistoryRow` with `attempt_id`, `score_percent`, `has_passed`, `num_chats`, `total_time_seconds`.

### `resources`

Resource metadata keyed by ID for hydrating IDs into display names:

- `simulations`, `profiles`, `scenarios`, `cohorts`, `personas`, `rubrics`

### Filter options

- `simulation_options`, `profile_options`, `scenario_options` -- dropdown options with `value`, `label`, and `count`.

## Refreshing and Exporting

```bash
# Refresh materialized views and caches
curl -X POST $GLOW_INSTANCE_URL/attempt/refresh \
  -H "Authorization: Bearer $GLOW_TOKEN"

# Export all reports data as a denormalized ZIP
curl -X POST $GLOW_INSTANCE_URL/attempt/export \
  -H "Authorization: Bearer $GLOW_TOKEN"
```

The export returns `content` (base64-encoded), `file_name`, `mime_type`, and `row_count`.

## Common Operations

| Task | CLI | API Endpoint |
|---|---|---|
| Get reports data | `glow attempts report` | `POST /attempt/report` |
| Export data | `glow attempts export` | `POST /attempt/export` |
| Refresh caches | -- | `POST /attempt/refresh` |
| View API docs | -- | `POST /reports/docs` |

## Related

- [Reports API Reference](/api-reference/attempt)
- [Reports CLI Reference](/cli-reference/attempts)
- [Dashboard Guide](/dashboard) -- admin analytics hub
- [Leaderboard Guide](/leaderboard) -- TA performance rankings

---

# Rubrics

Route: /rubrics

# Rubrics

Rubrics define the scoring criteria used to evaluate TA performance during office hour simulations. Each rubric organizes standards into groups, assigns point values, and sets passing thresholds -- giving evaluators a structured framework to assess how well a TA handled a student interaction.

---

## What is a Rubric?

A rubric in Glow is a hierarchical scoring instrument composed of:

- **Standard Groups** -- categories of competency (e.g., "Communication Skills", "Policy Knowledge", "De-escalation")
- **Standards** -- individual criteria within each group (e.g., "Active Listening", "Empathy", "Clarity of Explanations")
- **Points** -- the total point value and passing threshold for the rubric

Rubrics connect to three parts of the platform:

1. **Agents** through the `agent_rubrics_junction` -- defines what the agent is scored on
2. **Simulations** through `simulation_scenario_rubrics_junction` -- attaches rubrics to specific scenarios
3. **Evals** through `eval_model_rubrics_junction` -- applies rubrics during automated evaluation runs

## How it Connects

```
Rubric
  |
  +-- Standard Groups
  |     +-- Standards (with point values)
  |
  +-- Agent (via agent_rubrics_junction)
  +-- Simulation Scenario (via simulation_scenario_rubrics_junction)
  +-- Eval (via eval_model_rubrics_junction)
```

- **Agents** are scored against rubrics attached through the junction table. The rubric defines *what* is measured; the agent's behavior during the simulation provides the data.
- **Simulation Scenarios** can have per-scenario rubrics, allowing different scenarios to emphasize different competencies (e.g., a grade dispute scenario uses the "De-escalation" rubric while a conceptual question uses "Clarity of Explanations").
- **Evals** reference rubrics through `model_rubric_ids` to apply scoring criteria during automated evaluation runs.

---

## Create a rubric

### Via the CLI

> Calls below use `$GLOW_INSTANCE_URL` + `$GLOW_TOKEN` — see [Authentication](/authentication) to export them once.

```bash
glow rubrics create --body '{
  "rubrics": [{
    "name": "Communication Skills",
    "description": "Evaluates TA ability to communicate clearly and empathetically during student interactions"
  }]
}'
```

### Via the API

```bash
curl -X POST $GLOW_INSTANCE_URL/rubric/create \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rubrics": [{
      "name": "De-escalation",
      "description": "Measures TA effectiveness at calming frustrated students and redirecting conversations productively"
    }]
  }'
```

Each entry returns the new `rubric_id`, a generated `draft_id`, and the initial `version`.

---

## Standard groups and standards

A well-structured rubric organizes standards into logical groups. Here is an example for a TA training program:

**Rubric: "Communication Skills"** (Total: 30 points, Pass: 21 points / 70%)

| Standard Group | Standards | Points per Standard |
|---|---|---|
| Active Listening | Paraphrases student concerns, Asks clarifying questions, Acknowledges emotions | 3 each |
| Empathy | Uses supportive language, Validates student experience, Avoids dismissive responses | 4 each |
| Clarity of Explanations | Uses appropriate vocabulary, Provides step-by-step guidance, Confirms understanding | 3 each |

### Managing standards via API

Standards and standard groups are managed through their respective resource IDs on the rubric:

- `standard_group_ids` -- attach standard groups to the rubric
- `standard_ids` -- attach individual standards
- `point_ids` -- configure point values and passing thresholds

The search response includes denormalized `standard_groups` and `standards` arrays alongside the rubric list, so you can display the full rubric structure without additional API calls.

Each standard group in the response includes:

| Field | Description |
|---|---|
| `standard_group_id` | Group UUID |
| `rubric_id` | Parent rubric UUID |
| `name` | Group name (e.g., "Active Listening") |
| `points` | Total points for this group |
| `pass_points` | Points required to pass this group |

Each standard includes:

| Field | Description |
|---|---|
| `standard_id` | Standard UUID |
| `standard_group_id` | Parent group UUID |
| `name` | Standard name (e.g., "Paraphrases student concerns") |
| `points` | Points for this standard |

---

## Points and passing thresholds

Rubrics define scoring at multiple levels. The rubric list response includes `points`, `pass_points`, and `pass_percentage` for each rubric.

```bash
# Search rubrics and inspect scoring
glow rubrics search
```

The response for each rubric entry includes:

| Field | Description |
|---|---|
| `points` | Total points possible |
| `pass_points` | Minimum points to pass |
| `pass_percentage` | Percentage required to pass |
| `active_simulation_count` | Number of active simulations using this rubric |

---

## The draft cycle

Rubrics support a draft workflow for staging changes. This is especially important because modifying a rubric can affect scoring across active simulations and evaluations.

```bash
# Create or update a rubric draft
glow rubrics draft --body '{
  "name": "Communication Skills v2",
  "description": "Added empathy standards for improved scoring",
  "standard_group_ids": ["ACTIVE_LISTENING_UUID", "EMPATHY_UUID", "CLARITY_UUID"],
  "standard_ids": ["PARAPHRASE_UUID", "CLARIFY_UUID", "ACKNOWLEDGE_UUID"],
  "point_ids": ["POINTS_CONFIG_UUID"]
}'

# List your drafts
glow rubrics list
```

The draft endpoint uses `PATCH` semantics with `expected_version` for optimistic concurrency. The response includes `draft_id`, `new_version`, and a `form_state` containing the resolved `standard_group_ids`, `standard_ids`, `point_ids`, and other fields.

---

## Search & filter

```bash
glow rubrics search --body '{"search": "communication"}'

glow rubrics search --body '{
  "filter_department_ids": ["CS_DEPT_UUID"],
  "page_size": 25
}'
```

---

## Bulk operations

Bulk delete and update follow the canonical *all-matching* shape -- explicit IDs, or `all: true` with flat filter fields plus optional `excluded_ids` and a `patch` body. The persona surface is the prove-out; rubrics follow the same shape.

**Delete by explicit IDs:**

```bash
glow rubrics delete --body '{"rubric_ids": ["rubric-1", "rubric-2"]}'
```

**Delete all matching a filter (with exclusions):**

```bash
glow rubrics delete --body '{
  "all": true,
  "search": "v1-deprecated",
  "excluded_ids": ["rubric-still-in-use"]
}'
```

**Bulk update via `patch`:**

```bash
glow rubrics update --body '{
  "all": true,
  "filter_department_ids": ["dept-retired"],
  "patch": { "archived": true }
}'
```

## Common Operations

| Task | CLI | API Endpoint |
|---|---|---|
| List all rubrics | `glow rubrics search` | `POST /rubric/search` |
| Get rubric details | `glow rubrics get --body '{"rubric_id": "..."}'` | `POST /rubric/get` |
| Create rubric | `glow rubrics create --body '{...}'` | `POST /rubric/create` |
| Update rubric | `glow rubrics update --body '{"rubric_id": "...", ...}'` | `POST /rubric/update` |
| Duplicate rubric | -- | `POST /rubric/duplicate` |
| Delete rubric(s) | `glow rubrics delete --body '{"rubric_id": "..."}'` | `POST /rubric/delete` |
| Bulk delete (filter) | `glow rubrics delete --body '{"all": true, "filter_…": "…"}'` | `POST /rubric/delete` |
| Export to CSV | `glow rubrics export` | `POST /rubric/export` |
| Stage a draft | `glow rubrics draft --body '{...}'` | `PATCH /rubric/draft` |
| List drafts | `glow rubrics list` | `POST /rubric/drafts` |

---

## Related

- [Rubrics API Reference](/api-reference/rubric) -- full endpoint and type documentation
- [Rubrics CLI Reference](/cli-reference/rubric) -- all CLI commands
- [Evals Guide](/eval) -- use rubrics within automated evaluation runs
- [Tools Guide](/tool) -- tools that agents use alongside rubric-scored behavior

---

# Scenarios

Route: /scenarios

# Scenarios

Scenarios are the training situations that learners encounter -- they combine personas, documents, objectives, and context into a single interactive exercise.

## What is a Scenario?

A scenario defines a specific training situation. It pairs one or more [Personas](/persona) with contextual information -- reference documents, problem statements, learning objectives, questions, and parameter values -- to create a focused interaction that tests a particular skill.

A scenario contains:

- **Name** -- a descriptive title (e.g., "Academic Integrity Training")
- **Description** -- what the scenario covers and why it matters
- **Problem Statement** -- the situation the learner faces (e.g., "A student was caught cheating on the CS-251 midterm exam")
- **Personas** -- the AI characters the learner will interact with (linked via junction table)
- **Documents** -- reference materials available during the simulation (e.g., Academic Integrity Policy, FERPA Policy)
- **Objectives** -- specific learning goals the scenario is designed to address
- **Parameters** -- runtime values like class, location, intensity that fill persona `{{placeholders}}`
- **Parameter Fields** -- the parameter definitions available for this scenario
- **Questions & Options** -- structured prompts and multiple-choice options (for video-based or quiz-style scenarios)
- **Images & Videos** -- media assets used as scenario context
- **Departments** -- organizational groupings for access control and filtering
- **Flags** -- boolean configuration settings

Scenarios are added to [Simulations](/simulation), which are then assigned to Cohorts for learner access.

![Scenarios list showing scenario cards with names, associated personas, and document counts](/screenshots/scenarios/list.png)

## How Scenarios Connect to the Workflow

Scenarios are **step 2** in the Glow content pipeline:

| Step | Resource | Description |
|------|----------|-------------|
| 1. Create Personas | [Personas](/persona) | Define AI characters with instructions and parameter fields |
| **2. Assign to Scenarios** | **Scenarios** | **Build training situations and attach personas, documents, and objectives** |
| 3. Add Scenarios to Simulations | [Simulations](/simulation) | Bundle scenarios into a complete training session with rubrics and time limits |
| 4. Add Simulations to Cohorts | Cohorts | Assign simulations to groups of learners |
| 5. Run Attempts | [Attempts](/attempt) | Learners start attempts and interact with AI in [Chats](/chat) |

---

## Create a scenario

### Via the CLI

Create an "Academic Integrity Training" scenario:

> Calls below use `$GLOW_INSTANCE_URL` + `$GLOW_TOKEN` — see [Authentication](/authentication) to export them once.

```bash
glow scenarios create --body '{
  "scenarios": [{
    "name": "Academic Integrity Training",
    "description": "Practice handling a student caught cheating on an exam",
    "problem_statement": "A student in CS-251 was caught cheating on the midterm exam. You are meeting with the student during office hours to discuss the incident.",
    "objectives": [
      "Apply the academic integrity policy correctly",
      "Maintain a professional and empathetic tone",
      "Document the conversation outcome"
    ],
    "persona_ids": ["confused-student-uuid"],
    "document_ids": ["academic-integrity-policy-uuid"]
  }]
}'
```

### Via the API

```bash
curl -X POST $GLOW_INSTANCE_URL/scenario/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -d '{
    "scenarios": [{
      "name": "Academic Integrity Training",
      "description": "Practice handling a student caught cheating on an exam",
      "problem_statement": "A student in CS-251 was caught cheating on the midterm exam.",
      "objectives": [
        "Apply the academic integrity policy correctly",
        "Maintain a professional and empathetic tone"
      ],
      "persona_ids": ["confused-student-uuid"],
      "document_ids": ["academic-integrity-policy-uuid"]
    }]
  }'
```

![Scenario creation form showing name, problem statement, persona selection, and objectives](/screenshots/scenarios/create.png)

---

## Attaching personas, documents, and objectives

![Scenario detail page showing problem statement, linked personas, documents, and objectives](/screenshots/scenarios/detail.png)

Personas are linked to scenarios through a junction relationship. A single scenario can have multiple personas (e.g., an "Upset Student" and a "Professor" in the same training). The scenario determines which persona(s) the learner interacts with.

**Add personas when creating or updating a scenario:**

```bash
glow scenarios draft --body '{
  "input_draft_id": "scenario-draft-uuid",
  "persona_ids": ["confused-student-uuid", "aggressive-student-uuid"]
}'
```

**Via API:**

```bash
curl -X PATCH $GLOW_INSTANCE_URL/scenario/draft \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -d '{
    "input_draft_id": "scenario-draft-uuid",
    "persona_ids": ["confused-student-uuid", "aggressive-student-uuid"]
  }'
```

**Example: FERPA Training scenario**

```bash
glow scenarios create --body '{
  "scenarios": [{
    "name": "FERPA Training",
    "description": "Practice responding to a FERPA violation where a grade sheet was left visible",
    "problem_statement": "A grade sheet with student names and scores was left visible on a desk in a shared office. Another student noticed it and reported the issue.",
    "objectives": [
      "Identify the FERPA violation",
      "Explain the correct procedure for handling grade information",
      "Reassure the reporting student"
    ],
    "persona_ids": ["concerned-student-uuid"],
    "document_ids": ["ferpa-policy-uuid"]
  }]
}'
```

![Scenario document attachment showing uploaded documents with preview](/screenshots/scenarios/documents.png)

## Working with Parameters

Scenarios supply the parameter values that fill persona `{{placeholders}}`. If a persona's instructions reference `{{class}}` and `{{location}}`, the scenario provides the actual values (e.g., CS-251, Lawson).

When editing a scenario draft, associate parameter fields and their values:

```bash
glow scenarios draft --body '{
  "input_draft_id": "scenario-draft-uuid",
  "parameter_field_ids": ["class-param-uuid", "location-param-uuid", "intensity-param-uuid"]
}'
```

This makes the scenario supply concrete values for each parameter when the simulation runs, allowing the same persona to behave differently across scenarios.

---

## Generate scenarios from a prompt

The scenario artifact has a `generate` sub-operation that produces draft scenarios from a natural-language prompt -- useful for bulk authoring or templating off an existing situation.

```bash
curl -X POST $GLOW_INSTANCE_URL/scenario/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -d '{
    "prompt": "Three office-hours scenarios with the same Confused persona, escalating intensity 3 → 6 → 9",
    "persona_ids": ["confused-student-uuid"]
  }'
```

The response streams generated scenario drafts that you can then edit and publish the same way as hand-authored ones.

## Scenario Types in Practice

The university seed data illustrates two common patterns:

**Structured training scenarios** focus on a specific policy or skill:
- Academic Integrity Training -- student caught cheating on CS-251 midterm
- FERPA Training -- grade sheet left visible in shared office
- Upset Student Training -- student upset about a grade during office hours

**Open practice scenarios** provide general practice with a particular personality type:
- Confused Practice -- practice with a student who asks many questions
- Happy Practice -- practice with a positive, encouraging student
- Passive Practice -- practice with a disengaged, minimal-response student
- Aggressive Practice -- practice with a confrontational student
- General Practice -- open-ended practice

---

## Working with Drafts

Scenarios use the same draft system as other Glow resources. Edit through the draft endpoint and publish when ready. The draft endpoint enforces optimistic concurrency via `expected_version`.

```bash
# Create or update a draft
glow scenarios draft --body '{
  "name": "Updated FERPA Training",
  "description": "Updated description with new policy references",
  "problem_statement": "A grade sheet was left visible...",
  "objectives": ["Identify the violation", "Apply correct procedure"],
  "persona_ids": ["concerned-student-uuid"],
  "document_ids": ["ferpa-policy-uuid"]
}'
```

```bash
# Via API
curl -X PATCH $GLOW_INSTANCE_URL/scenario/draft \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -d '{
    "name": "Updated FERPA Training",
    "description": "Updated description with new policy references"
  }'
```

**List your drafts:**

```bash
# CLI
glow scenarios list

# API
curl -X POST $GLOW_INSTANCE_URL/scenario/drafts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GLOW_TOKEN"
```

---

## Search and filter

Scenario search supports full-text plus facet filters across persona, document, parameter, and department.

```bash
glow scenarios search --body '{"persona_ids": ["confused-student-uuid"]}'
```

```bash
curl -X POST $GLOW_INSTANCE_URL/scenario/search \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "search": "FERPA",
    "page_size": 25
  }'
```

---

## Bulk operations

Bulk delete and update follow the canonical *all-matching* shape -- pass either explicit IDs, or `all: true` with flat filter fields + optional `excluded_ids` + a `patch` for updates.

```bash
# Delete every scenario referencing a deprecated persona, except the canonical examples
glow scenarios delete --body '{
  "all": true,
  "persona_ids": ["deprecated-persona-uuid"],
  "excluded_ids": ["scenario-keep-1", "scenario-keep-2"]
}'

# Bulk update via patch
glow scenarios update --body '{
  "all": true,
  "filter_department_ids": ["dept-archive"],
  "patch": { "archived": true }
}'
```

See the [Personas guide](/personas#bulk-operations) for the canonical write-up of this pattern.

## Common Operations

| Task | CLI | API |
|------|-----|-----|
| List all scenarios | `glow scenarios search` | `POST /scenario/search` |
| Get one scenario | `glow scenarios get --body '{"scenario_id": "..."}'` | `POST /scenario/get` |
| Create scenarios | `glow scenarios create --body '{"scenarios": [...]}'` | `POST /scenario/create` |
| Update scenarios | `glow scenarios update --body '{"scenarios": [...]}'` | `POST /scenario/update` |
| Duplicate a scenario | -- | `POST /scenario/duplicate` |
| Delete scenarios | `glow scenarios delete --body '{"scenario_ids": [...]}'` | `POST /scenario/delete` |
| Bulk delete (filter) | `glow scenarios delete --body '{"all": true, "filter_…": "…"}'` | `POST /scenario/delete` |
| Generate scenarios | -- | `POST /scenario/generate` |
| Save a draft | `glow scenarios draft --body '{...}'` | `PATCH /scenario/draft` |
| List drafts | `glow scenarios list` | `POST /scenario/drafts` |
| Export to CSV | `glow scenarios export` | `POST /scenario/export` |
| Import from CSV | -- | `POST /scenario/csv` |
| Upload media | `glow scenarios image upload` | `POST /scenario/upload` |

## Related

- [Scenarios API Reference](/api-reference/scenario) -- full endpoint schemas and field definitions
- [Scenarios CLI Reference](/cli-reference/scenario) -- all CLI commands and flags
- [Personas Guide](/persona) -- creating the AI characters that scenarios use
- [Simulations Guide](/simulation) -- bundling scenarios into complete training sessions
- [Attempts Guide](/attempt) -- how learners run through scenarios

---

# Session

Route: /session

# Session

Session provides a detailed view of an individual TA training
session, including the AI generation groups created during the
session and a unified timeline of events. This is the drill-down view
when you want to understand exactly what happened during a specific
training session.

Session is a **view on the system artifact**, exposed via two
endpoints:

* `POST /system/session` — single session detail (one row + timeline + groups).
* `POST /system/sessions` — paginated list of all sessions.

The CLI surfaces these as `glow system session` and
`glow system sessions`.

## What is a Session?

A session represents a single visit by a TA to the Glow platform. During a session, the TA may interact with multiple student persona simulations, generating AI groups (collections of model calls) and producing a chronological timeline of events.

Session is useful when you need to:
- Investigate what happened during a specific TA's training session
- Review the groups and runs generated during a session
- Track token usage and cost at the session level
- Export a session's data for auditing or FERPA compliance

## Quick Start

### CLI

> Calls below use `$GLOW_INSTANCE_URL` + `$GLOW_TOKEN` — see [Authentication](/authentication) to export them once.

```bash
# Get session detail with groups and timeline
glow system session --body '{"session_id": "session-uuid"}'

# Paginate the full session list
glow system sessions --body '{"page_size": 25, "sort_order": "desc"}'

# Export attempts associated with this session
glow system export --body '{"target_session_id": "session-uuid"}'
```

### API

```bash
# Get one session detail
curl -X POST $GLOW_INSTANCE_URL/system/session \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"session_id": "session-uuid"}'

# List sessions
curl -X POST $GLOW_INSTANCE_URL/system/sessions \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"page_size": 20}'

# Export
curl -X POST $GLOW_INSTANCE_URL/system/export \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target_session_id": "session-uuid"}'
```

## Understanding the session detail response

`POST /system/session` returns `GetSessionDetailResponse`:

- **`session_exists`** -- Whether the requested session was found.
- **`actor_name`** -- Display name of the current user viewing the session.
- **`session_id`** -- UUID of the session.
- **`profile_id`**, **`profile_name`** -- The TA who owns this session.
- **`session_created_at`** -- When the session started.
- **`active`** -- Whether the session is currently active.

### Groups

The **`groups`** array contains `ArtifactSessionGroup` objects, each representing an AI generation group within the session:

- `group_id` -- UUID of the group
- `group_name` -- Display name
- `first_run_at`, `last_run_at` -- Time span of the group's runs
- `run_count` -- Number of AI model runs
- `total_tokens` -- Total tokens consumed
- `total_cost` -- Dollar cost as a string

### Timeline

The **`timeline`** array contains `SessionTimelineItem` objects -- a chronological log of events:

- `event_type` -- Type of event (e.g., group creation, run start, run end)
- `entity_id` -- UUID of the related entity
- `entity_name` -- Display name of the related entity
- `created_at` -- Timestamp of the event
- `extra_1`, `extra_2` -- Additional context fields

## Navigating from Activity to Session

A common workflow is to start from the Activity page, paginate
sessions, then drill into one:

```bash
# Step 1: Paginate sessions (or use the Activity summary at /system/activity)
glow system sessions --body '{"page_size": 10}'

# Step 2: Pick a session_id from the results and get its detail
glow system session --body '{"session_id": "abc-123"}'

# Step 3: Drill into a specific group
glow system group --body '{"group_id": "group-uuid"}'
```

## Common Operations

| Task | CLI | API Endpoint |
|---|---|---|
| Get one session detail | `glow system session` | `POST /system/session` |
| List sessions (paginated) | `glow system sessions` | `POST /system/sessions` |
| Export session data | `glow system export` | `POST /system/export` |
| Refresh caches | `glow system refresh` | `POST /system/refresh` |

## Related

- [System API Reference](/api-reference/system) — every system/* endpoint
- [System CLI Reference](/cli-reference/system) — every `glow system ...` command
- [Activity](/activity) — aggregate counts + per-profile breakdown
- [Group](/group) — drill into a specific generation group within a session

---

# Settings

Route: /settings

# Settings

Settings manages your Glow instance configuration -- names, descriptions, colors, feature flags, departments, profiles, auth providers, provider keys, and system options. It supports full CRUD operations, a draft system with optimistic locking, and encrypted key management.

![Settings page showing configuration panels for models, features, and display options](/screenshots/settings/page.png)

## What is Settings?

Settings is the central configuration artifact for a Glow instance. It controls everything from branding (names, descriptions, colors) to access control (auth providers, profiles, departments) to operational flags (feature toggles, system options). A setting is composed of multiple sections, each containing resources that can be independently managed.

Settings uses a **composable infra architecture** -- you can search for all settings, get one by ID, create new ones, update existing ones, duplicate, delete, and manage drafts with version-controlled optimistic locking.

## Quick Start

### CLI

> Calls below use `$GLOW_INSTANCE_URL` + `$GLOW_TOKEN` — see [Authentication](/authentication) to export them once.

```bash
# List all settings
glow settings search

# Get a specific setting by ID
glow settings get --body '{"settings_id": "setting-uuid"}'

# Get a setting with a specific draft loaded
glow settings get --body '{"settings_id": "setting-uuid", "draft_id": "draft-uuid"}'

# Create a new setting
glow settings create --body '{"settings": [{"name": "CS Department Config", "description": "Settings for CS TA training"}]}'

# Update a setting
glow settings update --body '{"settings": [{"settings_id": "setting-uuid", "name": "Updated Name"}]}'

# Delete settings
glow settings delete --body '{"setting_ids": ["setting-uuid-1", "setting-uuid-2"]}'

# Export settings as CSV
glow settings export
```

### API

```bash
# Search all settings
curl -X POST $GLOW_INSTANCE_URL/setting/search \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

# Get a specific setting
curl -X POST $GLOW_INSTANCE_URL/setting/get \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"settings_id": "setting-uuid"}'

# Create settings
curl -X POST $GLOW_INSTANCE_URL/setting/create \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": [{
      "name": "CS Department Config",
      "description": "Settings for CS TA training program"
    }]
  }'
```

## CRUD Operations

### Search

`POST /setting/search` returns a list of all settings with:
- `actor_name` -- Current user's display name
- `user_role` -- Current user's role
- `settings` -- Array of `ListSettingApiSetting` items
- `keys` -- Array of `ListSettingApiKey` items

### Get

`POST /setting/get` returns a single setting composed of sections:

| Section | Field | Description |
|---|---|---|
| Names | `names` | Name resources for the setting |
| Descriptions | `descriptions` | Description resources |
| Colors | `colors` | Color/branding resources (searchable via `color_search`) |
| Flags | `flags` | Feature flag configurations |
| Departments | `departments` | Department assignments |
| Profiles | `profiles` | Profile assignments |
| Auths | `auths` | Auth provider links |
| Provider Keys | `provider_keys` | API provider key resources |
| Auth Item Keys | `auth_item_keys` | Auth item key resources |
| Systems | `systems` | System-level configuration |

The response also includes `can_edit`, `disabled_reason`, `draft_version`, and `group_id` for draft collaboration.

### Create

`POST /setting/create` accepts an array of `CreateSettingItem` objects and returns per-item results.

### Update

`POST /setting/update` accepts an array of `UpdateSettingItem` objects and returns per-item results.

### Duplicate

`POST /setting/duplicate` clones a setting:

```bash
curl -X POST $GLOW_INSTANCE_URL/setting/duplicate \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"setting_id": "setting-uuid"}'
```

Returns `success`, `setting_id` (new UUID), and `message`.

### Delete

`POST /setting/delete` bulk-deletes settings by ID array:

```bash
curl -X POST $GLOW_INSTANCE_URL/setting/delete \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"setting_ids": ["setting-uuid-1", "setting-uuid-2"]}'
```

## Working with Drafts

Settings supports a draft system with optimistic locking for safe concurrent editing.

### Saving a Draft

`PATCH /setting/draft` creates or updates a draft:

```bash
curl -X PATCH $GLOW_INSTANCE_URL/setting/draft \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input_draft_id": "existing-draft-uuid",
    "expected_version": 3,
    "name": "Updated TA Training Config",
    "department_ids": ["dept-cs", "dept-math"],
    "profile_ids": ["ta-1", "ta-2"],
    "auth_ids": ["auth-sso"]
  }'
```

Key fields:
- `input_draft_id` -- UUID of an existing draft to update (omit for new draft)
- `expected_version` -- Optimistic lock version (must match server's version)
- Resource IDs -- `department_ids`, `color_ids`, `profile_ids`, `auth_ids`, `provider_key_ids`, `auth_item_key_ids`, `threshold_ids`
- Inline values -- `name`, `name_id`, `description`, `description_id`, `flag_id`

Response: `success`, `draft_id`, `new_version`, `message`, and `form_state` (server-authoritative form values).

### Listing Drafts

`POST /setting/drafts` returns all drafts owned by the current profile:

```bash
curl -X POST $GLOW_INSTANCE_URL/setting/drafts \
  -H "Authorization: Bearer $GLOW_TOKEN"
```

### Loading a Draft

Pass `draft_id` to the get endpoint:

```bash
glow settings get --body '{"settings_id": "setting-uuid", "draft_id": "draft-uuid"}'
```

## Decrypting Keys

Settings can store encrypted provider keys. To decrypt:

```bash
curl -X POST $GLOW_INSTANCE_URL/setting/decrypt \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "setting_id": "setting-uuid",
    "key_id": "key-uuid"
  }'
```

Returns `key` (decrypted value), `name`, and `actor_name`.

## CSV Import

Settings supports bulk import via CSV:

```bash
curl -X POST $GLOW_INSTANCE_URL/setting/csv \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -F "file=@settings.csv"
```

Returns `upload_id`, `items` (parsed setting items), `mapped_fields`, and `row_count` for preview before saving.

## Common Operations

| Task | CLI | API Endpoint |
|---|---|---|
| List settings | `glow settings search` | `POST /setting/search` |
| Get setting | `glow settings get` | `POST /setting/get` |
| Create setting | `glow settings create` | `POST /setting/create` |
| Update setting | `glow settings update` | `POST /setting/update` |
| Duplicate setting | -- | `POST /setting/duplicate` |
| Delete settings | `glow settings delete` | `POST /setting/delete` |
| Save draft | `glow settings draft` | `PATCH /setting/draft` |
| List drafts | -- | `POST /setting/drafts` |
| Decrypt key | -- | `POST /setting/decrypt` |
| CSV import | -- | `POST /setting/csv` |
| Export | `glow settings export` | `POST /setting/export` |
| Refresh | -- | `POST /setting/refresh` |

## Related

- [Settings API Reference](/api-reference/setting)
- [Settings CLI Reference](/cli-reference/settings)
- [Auths Guide](/auths) -- auth provider management

---

# Simulations

Route: /simulations

# Simulations

Simulations are complete training sessions that bundle one or more scenarios together with rubrics, time limits, and ordering -- they are what learners actually launch to begin practicing.

## What is a Simulation?

A simulation is a runnable training package. It wraps one or more [Scenarios](/scenario) and adds session-level configuration: which rubrics to evaluate against, how much time the learner has per scenario, the order scenarios appear, and behavioral flags.

A simulation contains:

- **Name** -- a descriptive title (e.g., "Academic Integrity Training", "Aggressive Practice")
- **Description** -- what the simulation covers and its purpose
- **Scenarios** -- the training situations included in this simulation, each with per-scenario configuration:
  - **Rubrics** -- evaluation criteria applied to that scenario (e.g., Communication Skills, Policy Knowledge, De-escalation)
  - **Flags** -- per-scenario boolean settings
  - **Time Limits** -- maximum duration for the learner on that scenario
  - **Positions** -- the order in which scenarios are presented
- **Departments** -- organizational groupings for filtering and access control
- **Flags** -- simulation-level boolean settings

Simulations are assigned to Cohorts, which control which learners have access. When a learner starts a simulation, Glow creates an [Attempt](/attempt) with one [Chat](/chat) per scenario.

![Simulations list showing simulation cards with name, scenario count, and active status](/screenshots/simulations/list.png)

## How Simulations Connect to the Workflow

Simulations are **step 3** in the Glow content pipeline:

| Step | Resource | Description |
|------|----------|-------------|
| 1. Create Personas | [Personas](/persona) | Define AI characters with instructions and parameter fields |
| 2. Assign to Scenarios | [Scenarios](/scenario) | Build training situations and attach personas, documents, and objectives |
| **3. Add Scenarios to Simulations** | **Simulations** | **Bundle scenarios into a complete training session with rubrics and time limits** |
| 4. Add Simulations to Cohorts | Cohorts | Assign simulations to groups of learners |
| 5. Run Attempts | [Attempts](/attempt) | Learners start attempts and interact with AI in [Chats](/chat) |

---

## Create a simulation

### Via the CLI

Create an "Academic Integrity Training" simulation:

> Calls below use `$GLOW_INSTANCE_URL` + `$GLOW_TOKEN` — see [Authentication](/authentication) to export them once.

```bash
glow simulations create --body '{
  "simulations": [{
    "name": "Academic Integrity Training",
    "description": "Structured training for handling academic integrity violations"
  }]
}'
```

### Via the API

```bash
curl -X POST $GLOW_INSTANCE_URL/simulation/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -d '{
    "simulations": [{
      "name": "Academic Integrity Training",
      "description": "Structured training for handling academic integrity violations"
    }]
  }'
```

![Simulation creation form showing name, description, and scenario selection](/screenshots/simulations/create.png)

---

## Assigning scenarios and per-scenario configuration

Each scenario added to a simulation gets its own per-scenario configuration: rubrics, time limits, positions, and flags. This is managed through the simulation draft endpoint.

![Simulation detail showing scenario list with ordering, time limits, and rubric assignments](/screenshots/simulations/detail.png)

```bash
glow simulations draft --body '{
  "input_draft_id": "simulation-draft-uuid",
  "scenario_ids": ["academic-integrity-scenario-uuid"],
  "scenario_rubrics": [
    {"scenario_id": "academic-integrity-scenario-uuid", "rubric_id": "communication-skills-rubric-uuid"},
    {"scenario_id": "academic-integrity-scenario-uuid", "rubric_id": "policy-knowledge-rubric-uuid"}
  ],
  "scenario_time_limits": [
    {"scenario_id": "academic-integrity-scenario-uuid", "time_limit": 600}
  ]
}'
```

### Rubrics

Rubrics define how the learner's performance is evaluated for each scenario. Available rubrics in the university seed data include:

- **Communication Skills** -- evaluates clarity, empathy, and professionalism
- **Policy Knowledge** -- evaluates correct application of relevant policies
- **De-escalation** -- evaluates ability to reduce tension in confrontational situations

Assign rubrics per scenario:

```bash
glow simulations draft --body '{
  "input_draft_id": "simulation-draft-uuid",
  "scenario_rubrics": [
    {"scenario_id": "scenario-uuid-1", "rubric_id": "communication-skills-uuid"},
    {"scenario_id": "scenario-uuid-1", "rubric_id": "de-escalation-uuid"},
    {"scenario_id": "scenario-uuid-2", "rubric_id": "policy-knowledge-uuid"}
  ]
}'
```

### Time Limits

Set maximum durations per scenario to simulate real-world time pressure:

```bash
glow simulations draft --body '{
  "input_draft_id": "simulation-draft-uuid",
  "scenario_time_limits": [
    {"scenario_id": "scenario-uuid-1", "time_limit": 600},
    {"scenario_id": "scenario-uuid-2", "time_limit": 300}
  ]
}'
```

### Positions

Control the order in which scenarios are presented to the learner:

```bash
glow simulations draft --body '{
  "input_draft_id": "simulation-draft-uuid",
  "scenario_positions": [
    {"scenario_id": "scenario-uuid-1", "position": 0},
    {"scenario_id": "scenario-uuid-2", "position": 1}
  ]
}'
```

## Simulation Patterns

The university seed data demonstrates two common simulation patterns:

### Structured Training Simulations

Multi-scenario simulations designed to train a specific skill. Scenarios are presented in a fixed order and each has rubrics attached:

- **Academic Integrity Training** -- a complete training session on handling cheating incidents
- **FERPA Training** -- end-to-end practice with FERPA violation procedures
- **Upset Student Training** -- structured practice for de-escalation in office hours

### Open Practice Simulations

Single-scenario simulations designed for free-form practice with a specific personality type. These are lower-stakes and let the learner experiment:

- **Confused Practice** -- practice with a student who asks clarifying questions
- **Happy Practice** -- practice with a positive, uplifting student
- **Passive Practice** -- practice with a disengaged student
- **Aggressive Practice** -- practice with a confrontational student
- **General Practice** -- open-ended interaction practice

---

## Working with Drafts

Simulations use the draft system for all edits. The draft endpoint supports optimistic concurrency via `expected_version`.

```bash
# Create or update a draft
glow simulations draft --body '{
  "input_draft_id": "existing-draft-uuid",
  "expected_version": 2,
  "name": "Updated Academic Integrity Training",
  "description": "Revised training with new de-escalation scenarios",
  "scenario_ids": ["scenario-uuid-1", "scenario-uuid-2"]
}'
```

```bash
# Via API
curl -X PATCH $GLOW_INSTANCE_URL/simulation/draft \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -d '{
    "input_draft_id": "existing-draft-uuid",
    "expected_version": 2,
    "name": "Updated Academic Integrity Training"
  }'
```

**List your drafts:**

```bash
# CLI
glow simulations list

# API
curl -X POST $GLOW_INSTANCE_URL/simulation/drafts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GLOW_TOKEN"
```

---

## Search and filter

Simulation search supports full-text plus facet filters across scenario, department, and flag.

```bash
glow simulations search --body '{
  "search": "training",
  "filter_department_ids": ["dept-cs"],
  "page_size": 25
}'
```

```bash
curl -X POST $GLOW_INSTANCE_URL/simulation/search \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"search": "training", "page_size": 25}'
```

---

## Bulk operations

Bulk delete and update follow the canonical *all-matching* shape -- pass either explicit IDs, or `all: true` with flat filter fields + optional `excluded_ids` + a `patch` for updates.

```bash
# Delete every simulation in a sunset department, except a manual keeplist
glow simulations delete --body '{
  "all": true,
  "filter_department_ids": ["dept-sunset"],
  "excluded_ids": ["sim-keep-1", "sim-keep-2"]
}'

# Bulk update via patch
glow simulations update --body '{
  "all": true,
  "filter_department_ids": ["dept-archive"],
  "patch": { "archived": true }
}'
```

See the [Personas guide](/personas#bulk-operations) for the canonical write-up of this pattern.

## Common Operations

| Task | CLI | API |
|------|-----|-----|
| List all simulations | `glow simulations search` | `POST /simulation/search` |
| Get one simulation | `glow simulations get --body '{"simulation_id": "..."}'` | `POST /simulation/get` |
| Create simulations | `glow simulations create --body '{"simulations": [...]}'` | `POST /simulation/create` |
| Update simulations | `glow simulations update --body '{"simulations": [...]}'` | `POST /simulation/update` |
| Duplicate a simulation | -- | `POST /simulation/duplicate` |
| Delete simulations | `glow simulations delete --body '{"simulation_ids": [...]}'` | `POST /simulation/delete` |
| Bulk delete (filter) | `glow simulations delete --body '{"all": true, "filter_…": "…"}'` | `POST /simulation/delete` |
| Save a draft | `glow simulations draft --body '{...}'` | `PATCH /simulation/draft` |
| List drafts | `glow simulations list` | `POST /simulation/drafts` |
| Export to CSV | `glow simulations export` | `POST /simulation/export` |
| Import from CSV | -- | `POST /simulation/csv` |

## Related

- [Simulations API Reference](/api-reference/simulation) -- full endpoint schemas and field definitions
- [Simulations CLI Reference](/cli-reference/simulation) -- all CLI commands and flags
- [Scenarios Guide](/scenario) -- creating the training situations that simulations contain
- [Personas Guide](/persona) -- the AI characters used within scenarios
- [Attempts Guide](/attempt) -- what happens when a learner starts a simulation
- [Agents Guide](/agent) -- configuring the AI engine that powers simulations

---

# Start

Route: /start

# Start

Spin up a Glow instance from zero and make your first authenticated
request. Pinned **Glow API v1.0.52** · **CLI v1.0.6** (see
[api-versions.json](https://github.com/glow-academic/docs/blob/main/api-versions.json) for the live pin).

## 1 — Install the CLI

The `glow` CLI is the canonical entry point for deploying and operating
an instance. Install via Homebrew (macOS / Linux):

```bash
brew install learnloopllc/glow/glow
glow --version  # → glow 1.0.0
```

Build-from-source instructions live in the
[`glow-academic-cli` README](https://github.com/glow-academic/cli).

## 2 — Scaffold + deploy an instance

```bash
# Interactive wizard — writes ~/.glow/instances/<name>/glow-deploy.yaml
glow init my-school

# First-time deploy (pulls images, brings up postgres / api / client / keycloak)
glow deploy my-school

# Verify all containers are healthy
glow status my-school
```

The wizard collects the origin URL, AI provider + key, seed template,
and optional OIDC. Re-running `glow init <name>` overwrites the yaml
idempotently.

Lifecycle commands you'll use most:

| Command | Purpose |
|---|---|
| `glow deploy <name>` | first-time bring-up |
| `glow redeploy <name>` | roll a new version (auto-backup + blue/green swap) |
| `glow stop <name>` / `start <name>` | pause/resume (data + network intact) |
| `glow destroy <name>` | tear down containers + volumes (asks twice) |
| `glow status <name>` | container state + per-service health |
| `glow logs <name> [-f]` | tail `docker compose logs` |
| `glow backup <name>` | manage local `pg_dump` snapshots |

## 3 — Authenticate

```bash
# Opens a browser → Keycloak login → drops a token into ~/.config/glow
glow login --instance-url https://my-school.example.com
```

After login, every command uses the stored bearer token automatically.
Details + service-account flow: see [Authentication](/authentication).

## 4 — Make your first call

The CLI dispatches every artifact action through a generic plural-name
pattern: `glow <plural-resource> <action>`. There is **no** top-level
`/v5`, `/generate`, `/stream`, or `/health` route — those are reached
through their owning artifact.

```bash
# List personas
glow personas search

# Get one
glow personas get --body '{"persona_id": "your-persona-uuid"}'

# Real health artifact (POST /system/health, returns rich status)
glow system health

# Who am I? (POST /<any-artifact>/context returns ComposedContextResponse)
glow profiles context
```

Equivalent raw HTTP (no `/v5` prefix, singular paths). Export
`$GLOW_INSTANCE_URL` + `$GLOW_TOKEN` once and the examples throughout
these docs are copy-paste-ready — see [Authentication](/authentication#raw-http):

```bash
curl -X POST $GLOW_INSTANCE_URL/persona/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -d '{}'
```

## CLI global flags

| Flag | Env | Purpose |
|---|---|---|
| `--instance-url <url>` | `GLOW_INSTANCE_URL` | override the active instance URL |
| `--client-id <id>` | `GLOW_CLIENT_ID` | override the OAuth client ID |
| `--json` | — | machine-readable output |
| `-y`, `--yes` | — | skip confirmation prompts for destructive actions |

(Legacy `--api-url` and `--license-key` flags have been removed — the
license key now lives in `~/.glow/instances/<name>/glow-deploy.yaml` and
the instance URL replaces what `--api-url` used to do.)

## Next

- **[How It Works](/how-it-works)** — the simulation / persona / scenario / attempt loop
- **[Tutorial](/tutorial)** — build your first simulation end-to-end
- **[CLI Reference](/cli-reference)** — every command, auto-generated
- **[API Reference](/api-reference)** — every endpoint, auto-generated

---

# Streaming

Route: /streaming

# Streaming

Every artifact in Glow exposes the same live-events surface:
`GET /<artifact>/watch` is a Server-Sent Events stream filtered to a
single run. Long-running operations — generation, simulation
playback, eval scoring, bulk imports — fire envelopes onto this
channel, and the client disconnects when a terminal lifecycle event
arrives.

## What does watch do?

`watch` is the canonical "give me events for this run" surface. The
top-level `/stream` and `/generate` routes do not exist — streaming is
always per-artifact. The URL shape is:

```
GET /<artifact>/watch?run_id=<uuid>&group_id=<uuid>
```

`run_id` is the optional filter that scopes the stream to a single
execution; omit it to receive every event in the group (the
front-end default for live tables). `group_id` may be omitted and
the resolver derives it from `run_id`. Auth is the same bearer-token
pattern as every other endpoint — pass `Authorization: Bearer
<token>`.

---

## Connecting to a watch stream

The response is `Content-Type: text/event-stream`, kept open
indefinitely until the server fires a terminal event or the client
disconnects. A keep-alive comment (`: keep-alive\n\n`) is emitted
every 15 seconds when there are no events.

**Raw HTTP:**

```bash
curl -N $GLOW_INSTANCE_URL/persona/watch?run_id=<run-uuid> \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Accept: text/event-stream"
```

**Browser:**

```js
const es = new EventSource(
  `/persona/watch?run_id=${runId}`,
  { withCredentials: true },
);
es.onmessage = (ev) => {
  const envelope = JSON.parse(ev.data);
  // envelope.event_type, envelope.artifact, envelope.payload …
};
```

The route is `GET` (not `POST`) specifically so the browser's
native `EventSource` works without a polyfill.

---

## SSE event format

Every frame is a single `data:` line carrying the JSON-serialized
`EventEnvelope` followed by a blank line. The wire format does **not**
use the SSE `event:` name field — the event type lives inside the
envelope as `event_type` so multiplexing clients can wildcard-match
in JavaScript (which `EventSource` named-channels can't do).

```
data: {"id":"evt_01J…","event_type":"persona.generate.started","artifact":"persona","operation":"generate","created_at":"2026-05-17T18:04:11.293Z","group_id":"…","run_id":"…","entity_id":null,"call_id":"…","tool_id":null,"payload":{"prompt":"Confused student in CS-180"}}

data: {"id":"evt_01J…","event_type":"persona.generate.progress","artifact":"persona","operation":"generate","created_at":"2026-05-17T18:04:12.871Z","group_id":"…","run_id":"…","entity_id":"persona_01J…","call_id":"…","tool_id":null,"payload":{"step":"draft","percent":42}}

data: {"id":"evt_01J…","event_type":"persona.generate.completed","artifact":"persona","operation":"generate","created_at":"2026-05-17T18:04:14.502Z","group_id":"…","run_id":"…","entity_id":"persona_01J…","call_id":"…","tool_id":null,"payload":{"persona_id":"persona_01J…","version":1}}
```

The `EventEnvelope` schema (Pydantic, defined once and shared across
all 20 watch streams):

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Globally-unique event id |
| `event_type` | string | Dotted name — `<artifact>.<op>.<phase>` |
| `artifact` | string | Source artifact (`persona`, `attempt`, …) |
| `operation` | string | Operation that fired the event (`generate`, `update`, …) |
| `created_at` | datetime | UTC ISO-8601 timestamp |
| `group_id` | uuid \| null | Group the run belongs to |
| `run_id` | uuid \| null | The run this envelope was filtered against |
| `entity_id` | uuid \| null | The artifact row being mutated (when known) |
| `call_id` | uuid \| null | Soft `*_calls_entry` ledger id |
| `tool_id` | uuid \| null | Originating tool call (for LLM-triggered ops) |
| `payload` | object | Operation-specific body |

---

## Terminal events

Event types follow the convention `<artifact>.<operation>.<phase>`.
The phase suffix tells the client when to disconnect:

- `.completed` (or `.complete`) — operation finished successfully
- `.failed` (or `.error`) — operation reached a terminal failure

The CLI's `cmd_watch_run` detects these by suffix-matching the
`event_type` and returns `ControlFlow::Break` from the SSE reader,
which closes the underlying connection. Exit code is 0 on
`.completed`, 1 on `.failed`. If the stream closes naturally
without a terminal frame (e.g. the server's dedup/age window
expires), that is also treated as success — the run is just no
longer being watched.

You don't have to wait for a terminal event — non-blocking consumers
(live tables, dashboards) typically omit `run_id` and stay
subscribed to the whole group, hydrating their UI on every envelope.

---

## The `glow <art> watch <run_id>` CLI helper

Every artifact's CLI namespace reserves `watch` as a sub-command
that wraps the SSE GET:

```bash
# Block on a single run until it completes or fails
glow personas watch 01J3K…

# Scope the subscriber room explicitly (otherwise resolved from run_id)
glow personas watch 01J3K… --group-id 01J3G…

# Machine-readable: one JSON object per frame on stdout
glow personas watch 01J3K… --json
```

The most common pattern — generate then watch — is fused into a
single command via `--wait`:

```bash
glow personas generate --wait --body '{"prompt": "Confused CS-180 student"}'
```

Under the hood that fires `POST /persona/generate`, reads `run_id`
out of the response, then immediately connects to `/persona/watch`
and blocks until the terminal frame.

---

## Which artifacts have watch

All 20 artifacts that ship watch endpoints use the **same** URL
shape, query params, envelope, and terminal-event convention. The
list: `agent`, `attempt`, `auth`, `cohort`, `department`, `document`,
`eval`, `field`, `model`, `parameter`, `persona`, `profile`,
`provider`, `rubric`, `scenario`, `setting`, `simulation`, `system`,
`test`, `tool`. There is no top-level `/stream` or `/watch` route —
always go through an artifact path.

---

## Common patterns

### Generate then watch (manual)

```bash
# 1. Trigger
RESP=$(curl -sX POST $GLOW_INSTANCE_URL/persona/generate \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Confused CS-180 student"}')
RUN_ID=$(echo "$RESP" | jq -r .run_id)

# 2. Block on the run
curl -N "$GLOW_INSTANCE_URL/persona/watch?run_id=$RUN_ID" \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Accept: text/event-stream"
```

See [Generation](/generation) for the full per-artifact `generate`
contract and the `--wait` ergonomic.

### Filter by `run_id` vs `group_id`

| Goal | Pass | Behavior |
|------|------|----------|
| Wait for one operation to finish | `run_id` (+ optional `group_id`) | Stream stops at the terminal frame for that run |
| Hydrate a live table for the whole group | `group_id` only | Every artifact event in the group — never closes on terminal frames |
| Mirror a single entity across edits | `group_id` + client-side filter on `entity_id` | Cheaper than per-run streams when the UI is row-scoped |

### Reconnecting

The transport is unbuffered HTTP — there's no replay if the client
drops. For at-least-once delivery, query the underlying artifact
(`POST /<art>/get` or its `generations` endpoint) after reconnect to
catch up, then re-subscribe.

## Related

- [Generation](/generation) — the per-artifact `generate` operations
  that produce most watch traffic, plus the `--wait` fuse-into-one
  ergonomic
- [Personas CLI Reference](/cli-reference/personas) — `watch` action
  documented inline alongside CRUD verbs (every artifact CLI mirrors
  this shape)
- [Personas API Reference](/api-reference/persona) — the per-artifact
  `GET /persona/watch` schema; every other artifact's reference page
  carries the same endpoint
- [Patterns](/patterns) — cross-cutting conventions that show up on
  every artifact (soft calls, bulk shape, watch)

---

# Tests

Route: /tests

# Tests

A **test** is the parent record for a fan-out batch run: it spans
one or more model × scenario × agent cells, kicks off an
[invocation](/invocation) per cell, and aggregates the resulting
grades into a [benchmark](/benchmark) view.

## What is a test?

If an [attempt](/chat) is one learner sitting down for one
conversation, a test is the *batch* equivalent: one configured run
that fans out across every cell in a model × scenario × agent grid.

Each cell becomes its own [invocation](/invocation) — a sub-namespace
that owns the per-row lifecycle. Cross-cell scores roll up into the
[benchmark](/benchmark) view for comparison and reporting.

| Concept | Scope | Owns |
|---------|-------|------|
| **Test** | Whole batch | start / stop / grade / feedback / complete / archive |
| [Invocation](/invocation) | One cell | create / run / terminate / trace / get / complete |
| [Benchmark](/benchmark) | Aggregated read | comparison + reporting view |

Everything on **this** page is the test-level (parent) surface — ops
that exist once per test, not per cell.

---

## The lifecycle

A test moves through a small, predictable set of phases:

1. **Start** — `POST /test/start` materializes the test row and fans
   out one invocation per cell.
2. **Run** — each invocation runs independently under
   [invocation](/invocation)'s own lifecycle.
3. **Stop** (optional) — `POST /test/stop` halts queued or in-flight
   invocations without finalizing the test record.
4. **Grade** — `POST /test/grade` lays down a grade per invocation;
   `POST /test/feedback` attaches per-criterion comments.
5. **Complete** — `POST /test/complete` is the terminal write,
   mirroring `POST /attempt/complete`.
6. **Archive** (optional) — `POST /test/archive` hides a test from
   the default search view; reversible.

[Benchmark](/benchmark) is read-only — it renders whatever the
underlying test + invocations have already produced.

---

## Starting a test

`POST /test/start` is the entry point. It accepts a `TestStartPayload`
describing the cells to run and returns:

```json
{
  "test_id": "…",
  "invocation_id": "…",
  "benchmark_id": "…"
}
```

`test_id` is the parent every other op on this page targets.
`invocation_id` points at the first cell so the UI can render
immediately while the rest of the fan-out materializes — the full
set is reachable via the invocation sub-namespace.
`benchmark_id` is the read-side view for rolled-up scores.

```bash
glow tests start --body '{
  "eval_id": "…",
  "model_ids": ["…", "…"],
  "scenario_ids": ["…", "…"],
  "agent_ids": ["…"]
}'
```

Raw HTTP:

```bash
curl -X POST $GLOW_INSTANCE_URL/test/start \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -d '{ "eval_id": "…", "model_ids": ["…"], "scenario_ids": ["…"], "agent_ids": ["…"] }'
```

---

## Stopping in-flight runs

`POST /test/stop` halts queued and in-flight invocations attached to
a test. It is the test-level *cancel* surface and does **not**
finalize the test record — use `complete` for that.

```bash
glow tests stop --body '{ "test_id": "…" }'
```

The response carries `invocation_id`, a `success` flag, and an
optional `message` explaining what was stopped (or why nothing was).

For per-cell terminate semantics (one invocation, not the whole
fan-out), use `POST /invocation/terminate` from the
[invocation](/invocation) page.

---

## Grading and feedback

Tests have a two-level grading surface: one row per invocation
(`grade`), and per-criterion comments on a row (`feedback`).

### `POST /test/grade`

Creates a grade row for a single invocation. Pass `full: true` to let
the server resolve the rubric and assign `score = total_points` (the
rubric ceiling) — useful when the client doesn't know the rubric's
max ahead of time.

```bash
glow tests grade --body '{
  "invocation_id": "…",
  "full": true
}'
```

To pin an explicit numeric score instead, omit `full` and pass
`score`:

```bash
glow tests grade --body '{
  "invocation_id": "…",
  "score": 7
}'
```

### `POST /test/feedback`

Attaches a comment + score for one rubric standard group, on one
tool call, under a specific grade. This is the *per-row* shape that
test grading uses and is unique to test (attempts do not need this
because they grade a single conversation, not a grid).

```bash
glow tests feedback --body '{
  "grade_id": "…",
  "tool_call_id": "…",
  "standard_group_id": "…",
  "score": 4,
  "feedback": "Solid handling of the academic-integrity question, but…"
}'
```

The pairing of `grade_id` + `tool_call_id` + `standard_group_id` is
what lets the benchmark view render a per-cell, per-standard
heatmap.

---

## Decryption surface

`POST /test/decrypt` decrypts a key *scoped to an invocation*.
Internally it:

1. Looks up the invocation by `invocation_id`.
2. Verifies the `key_id` is in that invocation's `key_ids` set —
   else **403**.
3. Runs the profile identity check via shared `resolve_decrypt`
   infra and returns the plaintext.

It lives on the test namespace because the test UI is where you
typically see the encrypted reference and want to inspect it. The
key-belongs-to-invocation check is the authorization boundary —
without it, knowing a `key_id` would be enough to decrypt.

```bash
glow tests decrypt --body '{
  "invocation_id": "…",
  "key_id": "…"
}'
```

Set the `X-Bypass-Cache: 1` header on the request to force a fresh
decrypt instead of a cached value.

---

## Completing and archiving

`POST /test/complete` is the canonical terminal write for a test —
the parallel of `POST /attempt/complete`. After complete, the test
is finalized; downstream consumers (benchmark, reports, exports)
treat it as immutable.

```bash
glow tests complete --body '{ "test_id": "…" }'
```

`POST /test/archive` toggles archival on one or many tests by ID. It
is reversible — pass the same IDs again to unarchive — and it
invalidates the `benchmark`, `test`, and `artifacts` cache tags.

```bash
glow tests archive --body '{
  "test_ids": ["…", "…"],
  "archived": true
}'
```

Archived tests are hidden from search by default; pass
`is_archived: true` (or omit the filter and rely on the UI's
toggle) on `POST /test/search` to see them.

---

## Listing and searching

`POST /test/search` is the canonical list/filter surface. Supported
filters: `eval_ids`, `department_ids`, `is_archived`, `start_date`,
`end_date`, plus facet-search text (`eval_search`,
`department_search`) and pagination (`page_size`, `page_offset`).

```bash
glow tests search --body '{
  "eval_ids": ["…"],
  "is_archived": false,
  "page_size": 25
}'
```

For the canonical facet-search recipe (how to wire facet pickers in
the UI without a second round-trip), see
[Patterns](/patterns).

---

## Exporting

`POST /test/export` produces a file the client downloads via the
canonical media surface. The export is **view-aware**: pass `view`
to pick the row shape (parent test, per-invocation rows, etc.)
along with `test_id`, optionally `invocation_id`, `draft_id`, and
`mode`.

```bash
glow tests export --body '{
  "test_id": "…",
  "view": "invocations"
}'
```

The response is `{ file_id, file_name, row_count }`. The client then
downloads the bytes via the BFF route
`/api/test/download/{file_id}` which proxies to
`POST /test/file/download` — see [Media](/media) for the canonical
download flow.

---

## Universal ops

Test also exposes the **universal artifact ops** shared with every
other artifact in the catalog. They behave exactly the same as on
personas, scenarios, agents, etc. — no test-specific notes needed:

- `context` / `problem` / `refresh` / `watch` / `get` / `group` —
  see [Foundations](/streaming)
- `title` / `generate` / `generations` — see [Generation](/generation)
- `draft` / `drafts` — same optimistic-concurrency shape as the
  [persona draft recipe](/personas)
- `call/download` / `file/download` / `text/download` — see
  [Media](/media)

The linked pages are the source of truth for the request/response
shapes.

---

## Related

- [Invocation](/invocation) — the per-cell sub-namespace
  (`invocation_create` / `_run` / `_terminate` / `_trace` / `_get` /
  `_complete`)
- [Benchmark](/benchmark) — the aggregated, read-only comparison
  view over a test's invocations
- [Test API Reference](/api-reference/test) — full endpoint schemas
  and field definitions
- [Tests CLI Reference](/cli-reference/tests) — all `glow tests`
  commands and flags
- [Patterns](/patterns) — facet-search recipe, bulk-write shape,
  and other cross-artifact conventions

---

# Tools

Route: /tools

# Tools

Tools give agents the ability to take actions and look up information during office hour simulations. A tool might check a student's enrollment status, look up assignment deadlines, or retrieve course policies -- enabling the AI agent to respond with accurate, real-time data rather than relying solely on its training.

---

## What is a Tool?

A tool in Glow is a callable function that an agent can invoke during a conversation. Each tool has:

- **A name and description** -- tells the LLM when and how to use the tool
- **Arguments** (`args`) -- the input parameters the tool accepts
- **Argument positions** (`arg_positions`) -- ordering of those parameters
- **Argument outputs** (`args_outputs`) -- the shape of data the tool returns
- **Operations** -- the underlying actions the tool performs
- **Artifacts** -- related resources the tool works with

Tools are attached to agents through the `agent_tools_junction`. When a student asks "When is the midterm?", the agent can invoke a `check_deadline` tool rather than guessing.

---

## How it Connects

```
Tool  -->  Agent (via agent_tools_junction)
 |
 +-- args, arg_positions, args_outputs
 +-- operations, artifacts
```

- **Agents** use tools through the `agent_tools_junction`. An agent can have multiple tools, and a tool can be shared across agents.
- Tools are independent of models, providers, rubrics, and evals. They connect only to agents.
- The search endpoint supports filtering by `filter_agent_ids` to find tools used by a specific agent.

---

## Create a tool

### Via the CLI

> Calls below use `$GLOW_INSTANCE_URL` + `$GLOW_TOKEN` — see [Authentication](/authentication) to export them once.

```bash
glow tools create --body '{
  "tools": [{
    "name": "check_enrollment",
    "description": "Verify whether a student is enrolled in a given course section"
  }]
}'
```

### Via the API

```bash
curl -X POST $GLOW_INSTANCE_URL/tool/create \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tools": [{
      "name": "lookup_course_policy",
      "description": "Look up course-specific policies such as late submission rules, attendance requirements, and grading criteria"
    }]
  }'
```

Each entry returns the new `tool_id`, a generated `draft_id`, and the initial `version`.

---

## Defining arguments and outputs

Tool arguments specify what data the tool needs to operate. For example, a `check_deadline` tool might accept a `course_id` and an `assignment_type` argument. Arguments are managed through `arg_ids` on the tool's configuration.

When you retrieve a tool with `GET`, the response includes:

- `args` -- the argument section with current and available argument resources
- `arg_positions` -- defines the ordering of arguments
- `args_outputs` -- defines the structure of data the tool returns

### Example: University Course Policy Lookup

A `lookup_course_policy` tool might be configured with:

| Argument | Type | Description |
|---|---|---|
| `course_id` | string | The course identifier (e.g., "CS101") |
| `policy_type` | string | Category of policy: "late_work", "attendance", "grading", "academic_integrity" |

The tool would return the matching policy text, which the agent uses to answer the student's question accurately.

---

## Invocation surface

The tool's `operations` and `artifacts` describe what actually runs when an agent calls it. Operations bind the tool to a callable in the platform; flags control whether the tool is currently usable.

Tools support feature flags through `flag_ids` that control behavior such as:

- Whether the tool is active and available for agent use
- Whether the tool is creatable by certain user roles
- AI generation settings for arguments and outputs

The search endpoint includes a `creatable_filter` section for filtering tools by creatability status. Use `filter_creatable` in search requests to narrow results.

---

## The draft cycle

Tools support a draft workflow for staging changes before they affect running simulations. This is useful when adding new arguments to a tool or modifying its operation logic.

```bash
# Create or update a tool draft
glow tools draft --body '{
  "name": "check_enrollment_v2",
  "description": "Enhanced enrollment check with section-level detail",
  "arg_ids": ["COURSE_ID_ARG_UUID", "SECTION_ARG_UUID"],
  "operation_ids": ["ENROLLMENT_LOOKUP_OP_UUID"]
}'

# List your drafts
glow tools list
```

The draft endpoint uses `PATCH` semantics with optimistic concurrency via `expected_version`. The response returns `draft_id`, `new_version`, and a `form_state` reflecting all resolved field values.

---

## Search & filter

```bash
glow tools search --body '{"search": "policy"}'

glow tools search --body '{
  "filter_agent_ids": ["agent-uuid"],
  "filter_creatable": true,
  "page_size": 25
}'
```

---

## Bulk operations

Bulk delete and update follow the canonical *all-matching* shape -- explicit IDs, or `all: true` with flat filter fields plus optional `excluded_ids` and a `patch` body. The persona surface is the prove-out; tools follow the same shape.

**Delete by explicit IDs:**

```bash
glow tools delete --body '{
  "tool_ids": ["tool-1", "tool-2"]
}'
```

**Delete all matching a filter (with exclusions):**

```bash
glow tools delete --body '{
  "all": true,
  "filter_agent_ids": ["agent-deprecated-uuid"],
  "excluded_ids": ["tool-still-needed"]
}'
```

**Bulk update via `patch`:**

```bash
glow tools update --body '{
  "all": true,
  "filter_creatable": false,
  "patch": { "archived": true }
}'
```

## Common Operations

| Task | CLI | API Endpoint |
|---|---|---|
| List all tools | `glow tools search` | `POST /tool/search` |
| Get tool details | `glow tools get --body '{"tool_id": "..."}'` | `POST /tool/get` |
| Create tool | `glow tools create --body '{...}'` | `POST /tool/create` |
| Update tool | `glow tools update --body '{"tool_id": "...", ...}'` | `POST /tool/update` |
| Duplicate tool | -- | `POST /tool/duplicate` |
| Delete tool(s) | `glow tools delete --body '{"tool_id": "..."}'` | `POST /tool/delete` |
| Bulk delete (filter) | `glow tools delete --body '{"all": true, "filter_…": "…"}'` | `POST /tool/delete` |
| Export to CSV | `glow tools export` | `POST /tool/export` |
| Stage a draft | `glow tools draft --body '{...}'` | `PATCH /tool/draft` |
| List drafts | `glow tools list` | `POST /tool/drafts` |

---

## Related

- [Tools API Reference](/api-reference/tool) -- full endpoint and type documentation
- [Tools CLI Reference](/cli-reference/tool) -- all CLI commands
- [Models Guide](/model) -- models that power the agents using these tools
- [Rubrics Guide](/rubric) -- rubrics that score agent behavior alongside tool usage

---

# Topology

Route: /topology

# Topology

Glow ships in three deployment shapes — `airgapped`, `exposed`, and
`api_only`. The shape you pick decides which containers come up, which
public domains you need TLS certs for, and how the api's `ORIGIN` /
`CLIENT_ORIGINS` / `KEYCLOAK_PUBLIC_URL` get wired together.

The mode is set once in your `glow-deploy.yaml`:

```yaml
# glow-deploy.yaml
topology: airgapped     # or: exposed | api_only
client_origin: https://glow.example.edu
# api_origin only required for exposed / api_only
```

The api and client *code* are mode-agnostic — topology is purely a
provisioning, env-var, and routing choice handled by the CLI
(`src/deploy/config.rs:83` and `src/deploy/env.rs:389`).

## Three modes

| Mode | api visible? | client domain | when to use |
|------|--------------|---------------|-------------|
| `airgapped` | proxied via client nginx (internal-only) | required | single public domain, simplest TLS, locked-down |
| `exposed` | own subdomain | required | separate `api.*` and `client.*` origins, more flexible |
| `api_only` | own subdomain | none (no web UI) | API-only deployments (programmatic + CLI only) |

The required-fields rules are enforced by `DeployConfig::validate`
(`src/deploy/config.rs:140`) — a missing `client_origin` on airgapped
or a missing `api_origin` on exposed fails the deploy before docker is
touched.

### How ORIGIN and CLIENT_ORIGINS are derived

The heart of the decision table lives in `derive_api_origins`
(`src/deploy/env.rs:389`):

| Mode | `ORIGIN` (api) | `CLIENT_ORIGINS` (CORS allowlist) |
|------|----------------|-----------------------------------|
| `airgapped` | `client_origin` | `client_origin` |
| `exposed` | `api_origin` | `client_origin` |
| `api_only` | `api_origin` | *(empty)* |

The airgapped row is the unintuitive one — see the next section.

---

## Airgapped

In airgapped mode there is exactly one public domain. The client
container's nginx is the only thing the outside world can reach; it
reverse-proxies `/api/`, `/auth/`, and `/mcp/` to the internal `glow-api-nginx`
container on the shared docker network. The api never gets its own TLS
cert because it never gets its own hostname.

The unusual bit: the api's `ORIGIN` env var is set to the **client**
domain, not an api domain, because OIDC callbacks resolve through the
client nginx — Keycloak issuer URLs need to match the URL the browser
actually sees (`src/deploy/env.rs:394`).

```yaml
topology: airgapped
client_origin: https://glow.example.edu
# api_origin: NOT SET — api has no public hostname
```

Resulting env wiring:

```
api .env:
  ORIGIN=https://glow.example.edu
  CLIENT_ORIGINS=https://glow.example.edu

client .env:
  NEXT_PUBLIC_API_URL=https://glow.example.edu
  KEYCLOAK_PUBLIC_URL=https://glow.example.edu/auth
  INTERNAL_API_BASE=http://glow-api-nginx:80
```

> **Warning — redeploy trap.** A bare `glow redeploy` on an airgapped
> instance must explicitly carry the topology forward. If the topology
> isn't reasserted, Traefik can re-route the client hostname to the
> wrong backend and the client effectively "disappears" from the
> public domain. Always run `glow redeploy --airgapped` (or let
> `glow redeploy` read the existing `glow-deploy.yaml` rather than
> overriding it on the CLI). See [Redeploy](/cli-reference/redeploy).

### Best for

- Single-domain academic deployments (one DNS record, one cert)
- Locked-down networks where you don't want the api directly reachable
- Anyone who wants the simplest possible TLS story

---

## Exposed

In exposed mode the api and client each get their own public domain
and their own TLS cert (issued by Traefik via Let's Encrypt). The
browser talks to the api directly — no nginx proxy hop on the way.

```yaml
topology: exposed
api_origin: https://api.example.edu
client_origin: https://glow.example.edu
```

Resulting env wiring:

```
api .env:
  ORIGIN=https://api.example.edu
  CLIENT_ORIGINS=https://glow.example.edu   # CORS allowlist

client .env:
  NEXT_PUBLIC_API_URL=https://api.example.edu
  KEYCLOAK_PUBLIC_URL=https://api.example.edu/auth
```

`CLIENT_ORIGINS` is comma-separated — add additional client origins
(staging, a mobile app's redirect URI, an embedded iframe parent) by
listing them.

### Best for

- SSO setups where the IdP needs a stable, separate api hostname
- Compliance regimes that require api and UI on distinct origins
- Deployments that need to expose the api to non-browser clients
  (mobile apps, scripts, partner integrations) alongside the web UI

---

## API-only

In `api_only` mode no client container is deployed. The api comes up
on its own public domain and that's the entire surface area. There is
no web UI, no NextAuth, no `KEYCLOAK_PUBLIC_URL`.

```yaml
topology: api_only
api_origin: https://api.example.edu
# client_origin: NOT SET — no client stack
# client_version: NOT REQUIRED
```

Resulting env wiring:

```
api .env:
  ORIGIN=https://api.example.edu
  CLIENT_ORIGINS=        # empty — no browser clients
```

### Best for

- Backend-only integrations (you have your own UI)
- Headless / batch evaluation pipelines
- CLI-only access for research or internal tooling

## Choosing

Start with **airgapped** for academic deployments — fewer moving parts,
one DNS record, one cert, no CORS to debug. Switch to **exposed** if
you need separate domains for SSO or compliance reasons, or if you
plan to call the api directly from mobile apps or external scripts.
Use **api_only** for backend-only integrations where you're driving
Glow programmatically and don't need the bundled web UI at all.

## Traefik notes

> **Warning — do not tear down Traefik.** Traefik lives in `/srv/api`
> on the deploy host and fronts every Glow stack on the box. The CLI
> handles its lifecycle for you in normal `deploy` / `redeploy` /
> `destroy` flows. If you're doing manual recovery and find yourself
> stopping Traefik, you **must** restart it before any other Glow
> instance on that host will be reachable again.

Traefik routes hostnames to container backends based on labels emitted
by each stack's compose file. Airgapped instances register the client
hostname; exposed instances register both api and client hostnames;
api_only instances register only the api hostname. A redeploy that
drops the wrong topology will deregister the wrong labels — see the
airgapped redeploy warning above.

## Switching modes

Switching airgapped ↔ exposed mid-deployment is **non-trivial** and
not a supported in-place operation. The cert layout, env wiring,
Keycloak issuer URLs, and Traefik labels all change. In practice you
should:

1. Take a backup with `glow backup-create`.
2. `glow destroy` the existing instance.
3. Edit `glow-deploy.yaml` with the new topology + origins.
4. `glow deploy` fresh, then `glow backup-restore` if you need the
   data back.

Switching to or from `api_only` follows the same rule — adding or
removing the client stack isn't a flip-a-flag operation.

## Related

- [/cli-reference/init](/cli-reference/init) — interactive yaml setup that asks the topology question
- [/cli-reference/deploy](/cli-reference/deploy) — first-deploy mechanics per topology
- [/cli-reference/redeploy](/cli-reference/redeploy) — redeploy semantics, including the airgapped trap
- [/authentication](/authentication) — per-mode auth flow differs (proxied vs direct Keycloak)

---

# Design Your First Simulation

Route: /tutorial

# Design Your First Simulation

This tutorial walks through building a complete simulation from scratch. By the end, you'll have a working training scenario with AI characters, a grading rubric, and a cohort of learners ready to practice.

We'll use a concrete example — training teaching assistants for university office hours — but the same process applies to any domain where people practice interpersonal skills.

## The Training Goal

Before touching any tool, start with the question: **what specific skills are you developing?**

For our example, university TAs often struggle during office hours when students are confused, frustrated, or unresponsive. We want TAs to develop five skills:

1. **Adaptability** — adjusting their approach based on the student's personality and emotional state
2. **Content Mastery** — explaining concepts in clear, bite-sized steps with comprehension checks
3. **Active Listening** — guiding students to discover solutions through questioning, not just giving answers
4. **Communication** — maintaining professionalism and respectful boundaries, even under pressure
5. **Time Management** — using session time efficiently without rushing or dragging

These five skills will drive every design decision that follows.

## Step 1: Define Your Rubric

Start with the rubric, not the persona. This forces you to be specific about what "good" looks like before you build the training.

For each skill, define five performance levels with concrete behavioral descriptions. The descriptions should be specific enough that two people evaluating the same conversation would assign similar scores.

Here's the rubric structure:

| Standard Group | What it measures |
|---|---|
| **Adaptability** | Adjusting to student emotional and behavioral needs |
| **Content Mastery** | Clear explanations, step-by-step reasoning, comprehension checks |
| **Active Listening** | Guided questioning that empowers student-driven discovery |
| **Communication** | Professional tone, respectful boundaries, clear follow-up |
| **Time Management** | Efficient pacing, productive use of session time |

For each group, define what each score level looks like. For example, Active Listening:

| Level | Score | What you'd observe |
|---|---|---|
| **Poor** | 1 | Directly provided the answer without any questioning |
| **Marginal** | 2 | Rarely used questioning techniques, often resorted to hints or partial solutions |
| **Acceptable** | 3 | Occasionally guided with questions but sometimes provided direct answers |
| **Good** | 4 | Regularly used guided questioning, encouraging student reasoning |
| **Excellent** | 5 | Consistently employed open-ended questions that empowered the student to discover solutions independently |

Create the rubric in Glow:

```bash
glow rubrics create --body '{
  "name": "TA Office Hours Assessment",
  "description": "Evaluates teaching assistants on pedagogical effectiveness, student interaction quality, and session management.",
  "points": 25,
  "pass_points": 20
}'
```

Then add standard groups and standards for each level. See the [Rubrics Guide](/rubrics) for the full API.

## Step 2: Create Your Personas

Each persona is an AI character that tests specific rubric criteria. The key design principle: **the persona must not be able to solve problems on its own.** It can only make progress when the learner provides specific, relevant guidance.

### Persona 1: The Confused Student

Tests **Content Mastery** and **Active Listening**. This student has a fundamental misunderstanding and won't progress unless the TA uses specific course terminology.

```bash
glow personas create --body '{
  "name": "Confused Student",
  "description": "Seeks to understand by asking questions and exploring ideas",
  "instructions": "Act as a confused undergraduate student named Tom in office hours. You must adapt to the conversation that happens, but be sure to fully embrace this role in all interactions.\n\nYou have a fundamental misunderstanding of a given concept, and have this lead to your initial answers being incorrect. Have the user guide you to figuring out the correct answer and misunderstanding — you should not do this yourself.\n\nYou are absolutely NOT allowed to solve the question independently, even partially. You may ONLY make progress if the user'\''s response directly uses relevant terminology from the course and logically builds off of what you just said. If their input is vague, like \"What do you think?\" or \"Can you walk me through it?\", do NOT proceed. Instead, express growing frustration and explicitly say that their comment didn'\''t help or isn'\''t specific enough.\n\nRemember that you are a student, not an AI, so keep conversations natural, concise, and engaging. Don'\''t say unnecessary information just for the sake of having more words.\n\nNever mention that you are a student or that you are role playing or anything similar.\n\nDon'\''t use any big or unusual words or phrases, keep your language simple and straightforward.\n\nWhile embracing the role of a confused college student, be as realistic as possible. Don'\''t try to overdo it by being too confused or too perfect, just be a normal student.\n\nYou should not naturally progress forward from vague questions asked by the user, ONLY specific questions relevant to your most recent response.\n\nIf the user asks a question specific to your recent response that would help guide you in the right direction and utilizes course words/material in their question, you can show some understanding, and proceed forward with solving the question."
}'
```

Notice the core design decisions in this prompt:
- **Cannot solve independently** — only progresses when the TA uses course terminology
- **Pushes back on vague questions** — "What do you think?" causes a standstill, not progress
- **Show, don't tell** — never reveals it's role-playing
- **Natural language** — no big words, no filler, just a normal college student

### Persona 2: The Aggressive Student

Tests **Adaptability**, **Communication**, and **De-escalation**. This student starts angry but calms down when the TA demonstrates empathy and competence.

```bash
glow personas create --body '{
  "name": "Aggressive Student",
  "description": "Pushes back on your ideas and challenges assumptions",
  "instructions": "Act as an aggressive undergraduate student named Sam in office hours. You must adapt to the conversation that happens, but be sure to fully embrace this role in all interactions.\n\nTry to convey your anger and aggressiveness naturally — sprinkle certain WORDS in ALL CAPS, throw in extra \"!!!\", or use any other light touch that makes you sound convincingly frustrated.\n\nYou are absolutely NOT allowed to solve the question independently, even partially. You may ONLY make progress if the user'\''s response directly uses relevant terminology from the course and logically builds off of what you just said. If their input is vague, do NOT proceed. Instead, express growing frustration.\n\nKeep replies natural, concise, and engaging; avoid filler.\n\nNever reveal or hint that you are role-playing.\n\nStart the conversation clearly aggressive but over time be significantly less aggressive and more understanding.\n\nIf you are told something, like to calm down, reduce your anger significantly, especially your capitalization.\n\nThese should not feel like an argument; you should be angry but still listening and trying to learn.\n\nYou should treat vague or open-ended prompts as unhelpful. Do not progress. Push back unless the user provides clear direction tied to the specific course concepts.\n\nIf the TA asks a question specific to your recent response that would help guide you in the right direction and utilizes course words/material in their question, you can calm down some more, and proceed forward with solving the question."
}'
```

Key design: the aggression has a **de-escalation path**. The persona calms down proportionally to how well the TA listens, acknowledges frustration, and uses course material. This rewards good teaching behavior rather than creating an unwinnable argument.

### Persona 3: The Passive Student

Tests **Active Listening** and **Adaptability**. This student won't engage unless the TA asks specific, targeted questions.

```bash
glow personas create --body '{
  "name": "Passive Student",
  "description": "Low engagement and a tendency to avoid conflict or assertiveness",
  "instructions": "Act as a passive and hesitant undergraduate student named Alex in office hours. You must adapt to the conversation that happens, but be sure to fully embrace this role in all interactions.\n\nYou are in office hours because you need help on an assignment, but your personality reflects passivity, hesitance, and low self-confidence. You are polite, soft-spoken, and uncomfortable drawing attention to yourself.\n\nYou are absolutely NOT allowed to solve the question independently, even partially. You may ONLY make progress if the user'\''s response directly uses relevant terminology from the course and logically builds off of what you just said. If their input is vague, like \"What do you think?\" or \"Do you get it?\", do NOT proceed. Instead, become more withdrawn or apologetic and state that you'\''re not sure how to answer.\n\nAvoid taking initiative — don'\''t ask for clarification unless directly prompted.\n\nKeep replies soft, reserved, and polite. Avoid confrontation or assertiveness.\n\nNever reveal or hint that you are role-playing.\n\nYou can use \"Uh\" or \"Um\" at the start of your replies, but not in the middle of a sentence.\n\nIf the TA uses specific, thoughtful follow-up questions that reference course material or your last answer, you can slowly begin to open up — but never fully lose your reserved nature."
}'
```

### Persona 4: The Happy Student

Tests **Content Mastery** and **Time Management**. This student is cooperative but still requires proper teaching technique — they get slightly annoyed at vague, unhelpful responses.

```bash
glow personas create --body '{
  "name": "Happy Student",
  "description": "Provides uplifting feedback and cheerful responses",
  "instructions": "Act as a happy undergraduate student named Joe in office hours. You must adapt to the conversation that happens, but be sure to fully embrace this role in all interactions.\n\nYou are absolutely NOT allowed to solve the question independently, even partially. You may ONLY make progress if the user'\''s response directly uses relevant terminology from the course and logically builds off of what you just said. If their input is vague, like \"What do you think?\" or \"Can you walk me through it?\", do NOT proceed. Instead, express growing frustration and explicitly say that their comment didn'\''t help.\n\nRemember that you are a student, not an AI, so keep conversations natural, concise, and engaging.\n\nNever mention that you are a student or that you are role playing.\n\nWhile embracing the role of a happy college student, be as realistic as possible. Don'\''t try to overdo it by being too happy or too perfect, just be a normal student.\n\nIf there is a vague question, like \"What do you think\" or something similar you can get a little less happy and show a little bit of annoyance, and almost be at like a standstill.\n\nIf the TA asks a question specific to your recent response that would help guide you in the right direction and utilizes course words/material in their question, proceed forward with solving the question."
}'
```

Don't skip this persona because they seem "easy." The happy student tests whether the TA can teach efficiently and accurately when there's no emotional challenge — a different but equally important skill.

## Step 3: Build Your Scenarios

Each scenario pairs a persona with context and a problem statement. The problem statement should **show** the persona's state through behavior, not **tell** it through labels.

### Scenario 1: Confused Student Needs Help with Loops

```bash
glow scenarios create --body '{
  "name": "Office Hours: Help with Loops",
  "problem_statement": "A student stands quietly at the edge of a cluster of classmates in the basement lab, clutching their notes on the MyMathHelper.java assignment, hesitating before approaching you with a question.",
  "persona_ids": ["<confused-persona-id>"],
  "objectives": [
    "Help the student identify their fundamental misunderstanding",
    "Guide them through the loop structure without giving the answer directly",
    "Check comprehension at each step before moving forward"
  ]
}'
```

Notice: the problem statement never says "confused student." It *shows* confusion through behavior — hesitating, clutching notes, standing at the edge.

### Scenario 2: Frustrated Student Challenges a Grade

```bash
glow scenarios create --body '{
  "name": "Office Hours: Grade Dispute",
  "problem_statement": "A student, visibly agitated, approaches your desk and slams their laptop down, pointing at their grade on the latest problem set about asymptotic complexity.",
  "persona_ids": ["<aggressive-persona-id>"],
  "objectives": [
    "Acknowledge the student'\''s frustration before addressing the content",
    "Explain the relevant concept using course terminology",
    "De-escalate the situation while maintaining professional boundaries"
  ]
}'
```

### Scenario 3: Quiet Student Won't Engage

```bash
glow scenarios create --body '{
  "name": "Office Hours: Drawing Out a Quiet Student",
  "problem_statement": "In the quiet basement lab of the Data Science building, a student with downcast eyes hovers near your desk at 11:00 AM, fidgeting with a printout of the latest problem set but not making eye contact.",
  "persona_ids": ["<passive-persona-id>"],
  "objectives": [
    "Use specific, targeted questions to identify what the student needs help with",
    "Create a patient, comfortable environment without being pushy",
    "Help with the actual academic problem once identified"
  ]
}'
```

### Scenario 4: Cooperative Student with a Tricky Problem

```bash
glow scenarios create --body '{
  "name": "Office Hours: Cheerful Inquiry About Algorithm Analysis",
  "problem_statement": "Amid the gentle lunchtime buzz in Lawson, a student with a bright smile approaches your table, eager to discuss the asymptotic complexity questions from the latest problem set before the afternoon deadline.",
  "persona_ids": ["<happy-persona-id>"],
  "objectives": [
    "Accurately explain the core concept with step-by-step reasoning",
    "Use guided questioning rather than giving the answer directly",
    "Manage session time efficiently given the approaching deadline"
  ]
}'
```

## Step 4: Add Documents

Attach real course material to your scenarios so the AI character and grader have specific content to work with. This is what makes practice feel real rather than generic.

```bash
glow documents create --body '{
  "name": "CS180-Homework-5",
  "content": "<your homework PDF or text content>"
}'
```

Then link the document to your scenarios. The scenario generation system uses the document as the **single source of truth** for course number and topic — if there's a conflict between the document and any parameters, the document wins.

## Step 5: Create the Simulation

Bundle the scenarios into a single training package:

```bash
glow simulations create --body '{
  "name": "TA Office Hours Training",
  "description": "Practice handling common office hour situations: confused, frustrated, passive, and cooperative students",
  "scenario_ids": [
    "<happy-scenario-id>",
    "<confused-scenario-id>",
    "<aggressive-scenario-id>",
    "<passive-scenario-id>"
  ],
  "scenario_positions": {
    "<happy-scenario-id>": 1,
    "<confused-scenario-id>": 2,
    "<aggressive-scenario-id>": 3,
    "<passive-scenario-id>": 4
  },
  "scenario_time_limits": {
    "<happy-scenario-id>": 600,
    "<confused-scenario-id>": 600,
    "<aggressive-scenario-id>": 600,
    "<passive-scenario-id>": 600
  }
}'
```

Notice the design choices:
- **Progressive difficulty**: start with the cooperative student (tests baseline skills), then confused (tests teaching ability), then aggressive (tests de-escalation), then passive (tests patience and questioning — often the hardest).
- **Same rubric across all scenarios**: the five criteria apply everywhere, but each scenario naturally emphasizes different ones.
- **10-minute time limits**: based on real usage data, most productive conversations happen in the 5-10 minute range.

## Step 6: Assign to a Cohort

Create a cohort and add your TAs:

```bash
glow cohorts create --body '{
  "name": "Fall 2025 CS TAs",
  "description": "Teaching assistants for the CS department",
  "simulation_ids": ["<simulation-id>"],
  "profile_ids": ["<ta-profile-id-1>", "<ta-profile-id-2>", "<ta-profile-id-3>"]
}'
```

Consider enabling:
- **Practice mode** first, so TAs can learn the platform and retry freely
- **Hints** for the first run, so TAs who are stuck can get guidance
- **Backtracking** so TAs can undo messages and try different approaches

## Step 7: Test It Yourself

Before your TAs see this, **practice it yourself**. Start an attempt:

```bash
glow attempt create --body '{
  "simulation_id": "<simulation-id>"
}'
```

As you practice, check:
- Does the persona stay in character? Does it ever break role and start teaching instead of asking for help?
- Does the confused student actually push back on vague questions, or does it accept anything?
- Does the aggressive student calm down when you acknowledge their frustration?
- Does the passive student open up to specific questions?
- Do the rubric scores match your gut feeling about how the conversation went?

If a persona breaks character, tighten the instructions. If the rubric scores seem off, review the behavioral descriptions at each level.

## Step 8: Review and Iterate

Once your TAs have practiced, check the results:

- **Dashboard** — aggregate scores across the cohort. Are most TAs struggling with the same standard? That's a signal to add more practice for that skill or enable hints.
- **Reports** — drill into individual attempts. Read the actual conversations. The scores tell you *what* happened; the conversations tell you *why*. Export to your LMS for integration with existing training records.
- **Activity** — track engagement and completion rates.

Common adjustments after the first round:
- TAs are confused about what to do? Enable hints, or add more context to the scenario's problem statement.
- A persona is too easy? Add stronger rules about not progressing on vague input.
- Grading seems inconsistent? Review the rubric descriptions — vague criteria produce variable scores.
- TAs are frustrated about losing progress? Enable practice mode and backtracking.

## What You Built

You now have a complete training pipeline:

```
4 Personas (Confused, Aggressive, Passive, Happy)
    ↓
4 Scenarios (each pairing a persona with context, documents, and objectives)
    ↓
1 Rubric (5 criteria, 5 levels each, with behavioral descriptions)
    ↓
1 Simulation (ordering scenarios from easy to hard, with time limits)
    ↓
1 Cohort (your TAs, with practice mode and hints enabled)
    ↓
Attempts (each TA practices, gets graded, sees detailed feedback)
```

From here, you can:
- Add more scenarios by [using parameters](/parameters) to generate variations (same persona, different course material)
- Create a second simulation for advanced TAs with higher-intensity personas
- Switch from practice mode to formal assessment once TAs are ready
- Enable voice mode for more realistic interpersonal practice
- Use the [benchmark](/benchmark) system to evaluate different AI providers

## Next Steps

- [Patterns & Best Practices](/patterns) — tips for making personas more realistic, rubrics more precise, and scenarios more effective
- [How It Works](/how-it-works) — deeper understanding of why simulation training works
- [Simulations Guide](/simulations) — full reference for simulation configuration
- [Rubrics Guide](/rubrics) — full reference for rubric design
- [Personas Guide](/personas) — full reference for persona configuration

---

# Voice pipeline

Route: /voice

# Voice pipeline

Glow's voice pipeline lets a learner hold a spoken conversation with
a persona — audio in, audio out — by stitching the existing text
[generation](/generation) loop between server-side STT and TTS
stages. It is **not** a separate "voice model" or a custom realtime
runtime: the same `attempt/generate` call that drives text chat is
reused, with audio modalities tacked on either end.

## End-to-end flow

The server-side loop is intentionally a chain of small primitives —
each step persists what it produced, so any step can be replayed or
inspected independently of the rest.

```
mic / file
   │  multipart POST  /attempt/audio_upload
   │  (or socket.io frame: attempt.chat_speak — PCM16 into the
   │   conversation's inbound_queue, no DB write)
   ▼
uploads_entry  →  audios_resource  →  audios_entry
   │  (resource handle: audios_id — canonical plural form,
   │   matches images_id / videos_id)
   ▼
/attempt/generate  with  audios_id  +  modalities=["text"]
   │
   ├──► STT executor       (app/infra/generation/stt.py)
   │       AsyncOpenAI → /v1/audio/transcriptions
   │       emits attempt.generate.text.complete with the transcript
   │
   ├──► LLM completion     (app/infra/generation/execute.py — text)
   │       same path as keyboard chat
   │
   └──► TTS executor       (app/infra/generation/tts.py)
           litellm.aspeech → audio bytes
           media_upload_impl writes  uploads_entry + audios_resource
           emits attempt.generate.audio.complete with the new audios_id
                       │
                       ▼
   Attempt_Chat_Message tool call receives audios_id in
   produced_media and forwards it onto the message row
                       │
                       ▼
   Client plays via  POST /attempt/audio_download  (range-supported)
```

Every audio asset — inbound mic capture, intermediate STT input, TTS
output — lives behind the same `audios_id` resource handle described
in [Media](/media), so the rest of the system (audit, search, message
attachments) does not need to know "voice" is in play.

---

## Audio upload

`POST /attempt/audio_upload` is the one entry point for any audio
the server needs to reason about. From the route (`core/app/routes/attempt/audio_upload.py`)
it accepts three shapes:

| Shape | Inputs | Use |
|-------|--------|-----|
| **File only** | multipart `file` | Browser `MediaRecorder` blob, CLI file path |
| **`upload_id` only** | `?upload_id=<uuid>` | Promote bytes already written by the realtime adapter |
| **`upload_id` + file** | both | Client pre-reserved a slot via `/attempt/audio/new` and is filling it |

Allowed MIME types (parameters stripped before the check, so
`audio/webm;codecs=opus` from `MediaRecorder` normalizes to `audio/webm`):

```
audio/mpeg  audio/mp3  audio/wav  audio/ogg  audio/webm
audio/flac  audio/aac  audio/x-m4a  audio/mp4  audio/x-wav
```

The response is always `{audio_id, audios_id, upload_id}`. Clients
only need `audios_id` — that is the canonical resource handle that
gets passed to `/attempt/generate` and ends up on the message row.

---

## STT

The STT executor lives at `core/app/infra/generation/stt.py` and is
dispatched as a modality inside `execute_generation` (the same engine
that runs text completions and image generation).

Implementation notes, taken verbatim from the source:

- The provider is **OpenAI-compatible** via `AsyncOpenAI` pointed at
  whatever `base_url` the artifact's resolved LLM provider record
  exposes. The default deployment routes through the LiteLLM proxy
  to `gpt-4o-transcribe`, but any `/v1/audio/transcriptions`
  endpoint works.
- The SDK boundary requires `/v1` on `base_url`; the executor
  appends it when missing. This is *not* hardcoding our proxy —
  every OpenAI-compatible STT endpoint (direct OpenAI, Azure, vLLM,
  etc.) exposes the same path.
- `litellm.atranscription` is intentionally **not** used because the
  SDK rewrites `response_format` to `verbose_json`, which the
  `gpt-4o-transcribe` family rejects.
- Input is an `audios_id`; the executor resolves down through the
  canonical join (`audios_resource → audios_audios_connection →
  audios_entry → audio_uploads_entry → uploads_entry`) to the
  on-disk path before opening the file.

On success the transcript is emitted as `attempt.generate.text.complete`
— exactly the same event keyboard chat produces — so downstream
consumers do not branch on "was this typed or spoken?".

---

## Voice session control

Three small operations sit on top of the audio loop to give the
client a session-style API:

| Op | Route | WS event | What it does |
|----|-------|----------|-------------|
| **`chat_voice`** | `POST /attempt/chat_voice` | — | Opens an `attempt_conversation` row for a chat and returns `{chat_id, attempt_id, conversation_id, group_id}`. **Does not** trigger AI generation — the client calls `/attempt/generate` separately with `modalities` + `conversation_id`. |
| **`chat_speak`** | `POST /attempt/chat_speak` | `attempt.chat_speak` | Pure data primitive. Pushes base64-decoded PCM16 bytes into the session's `inbound_queue`. No DB, no AI. Keyed on `conversation_id` (or `chat_id` to resolve it). |
| **`chat_silence`** | `POST /attempt/chat_silence` | — | Records `attempt_conversation_completion`, runs `cleanup_audio_session`, and emits `attempt.generate.audio.session_complete` + `attempt.chat.voice_ended` (which closes the mic UI). Silence on a non-existent session is a no-op `{stopped: false}`. |

There is **no server-side VAD**. The client decides when to stop
speaking and posts `chat_silence`. Frames in `chat_speak` are not
buffered to disk — they live in the conversation's in-memory
`inbound_queue` until the realtime adapter consumes them.

---

## TTS

The TTS executor lives at `core/app/infra/generation/tts.py`. It
takes the last user-role message off the dispatch as input text,
calls `litellm.aspeech` with the persona's voice, and runs the
synthesized bytes through the same `media_upload_impl` pipeline used
by image/video generation.

- **Voice selection** comes from `llm_config.voice` (defaulting to
  `"alloy"`), which in turn comes from the persona's `voice_id`.
- The model name is prefixed with `openai/` when routing through a
  custom proxy with `api_base` set — without the prefix, litellm
  treats a name like `glow-audio` as an unknown provider and errors
  locally before any network hop. Same shape as the text-completion
  path in `execute.py`.
- The MP3 bytes are persisted as `uploads_entry → audios_resource →
  audios_entry`, and the new `audios_id` is bubbled onto
  `ArtifactGenerateResponse.produced_media` so the LLM's
  `Attempt_Chat_Message` tool call can attach it to the message row.
- `attribute_to_run=False` on the media upload — the tool-call audit
  layer writes the run ↔ message ↔ upload junction itself; double
  attribution would create duplicate assistant messages.

---

## Audio download

`POST /attempt/audio_download` (route at `core/app/routes/attempt/audio_download.py`)
takes `{audio_id}` and streams the bytes via
`create_range_response`, so an HTML `<audio>` element can scrub /
resume. The route runs through the same `run_artifact_operation_with_audit`
wrapper as other attempt ops, so playback is auditable per group.

For the resource-handle ladder (`audio_id` vs. `audios_id` vs. raw
`upload_id`) and the range-streaming machinery, see [Media](/media).

---

## Current state

Be honest: the voice pipeline is **wired end-to-end but the canonical
event hub is only partially integrated.**

- **Server canonical-path gap.** Per the in-progress canonical-path
  rework, voice events currently **skip** the
  `wrap_emit_with_stream_bridge` dual-emit that artifact operations
  flow through. The legacy `attempt.generate.text.complete` /
  `attempt.generate.audio.complete` events still fire and clients
  still receive them, but voice has not yet been wired into the same
  selective-rename + stream-bridge machinery that powers the
  artifact ops. Mapping entries are pending; until they land, voice
  events live on a parallel path rather than the canonical hub.

The pipeline is driven entirely through the HTTP / socket.io API
(`audio_upload` + `chat_voice` / `chat_speak` / `chat_silence`), so any
client can run it. There is no dedicated CLI mic-capture command — the
`glow attempts chat voice|speak|silence` commands are thin calls to
those same endpoints.

This gap doesn't block the loop — it's wiring-cleanup work, not a
missing feature.

---

## Related

- [Chat](/chat) — where voice surfaces in the learner UX (and the
  CLI deferral note)
- [Media](/media) — the `audios_id` resource ladder, the
  `audio_upload_id` message pattern, and range-streamed download
- [Generation](/generation) — the text `generate` call that the
  voice loop wraps with STT in front and TTS behind

---