> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tied.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Orchestration Studio cases API readiness

> Current case reads and the missing Studio case actions, checked 2026-10-22.

Availability was checked against source revision `b72687ec48d4f446d9c7be46d802165dffbca063` on 2026-10-22. Four case read operations are already documented and covered by ENG-5405. The case controller and the account routes expose those reads only. None of the write, rule, or export actions below has a matching customer Studio route or OpenAPI operation today.

This page records availability and the work each missing action still needs. It does not define a callable API contract. Each missing action is owned by ENG-5893. Its inactive inventory is `docs/platform-api/proposals/ENG-5854.json`.

## Current case reads

The existing operations are `list-orchestration-studio-cases`, `get-orchestration-studio-cases-summary`, `get-orchestration-studio-case`, and `list-orchestration-studio-case-conversations`. They are documented in the [Orchestration Studio read API](/api-reference/orchestration-studio) page and registered in `spec/contract/orchestration_studio_spec.rb`.

These reads use `Api::V1::Accounts::CasesController`. They require an authenticated account administrator and the account's `orchestration_studio` feature. With the feature off, authenticated account members receive 404. With it enabled, a non-administrator receives 403; anonymous and nonmember callers receive 401. This is the proven role contract for these reads only. It does not establish authorization for any missing action.

Case and linked-conversation lists use page-number pagination, 25 rows per page, and return `meta.count` and `meta.current_page`. The case detail includes a first page of 25 conversations. The existing read API does not provide the requested future export cursor. See the read API page for response fields, filters, and error behavior.

## Missing action availability

The requested single-case `cases.change` behaviors are cancel or pause check-ins, hand to owner, allow check-ins, take over, close, and move a check-in. The bulk rows below describe the same seven behaviors across multiple cases; they should share transition rules rather than define a competing case resource.

| Frontend action | Current availability | Reuse boundary | Requirement before a callable API exists |
| - | - | - | - |
| `cases.change` | No matching Studio route or OpenAPI operation. The existing case controller is read-only. | Reuse the account-scoped case records and timeline conventions; the read controller does not authorize or implement changes. | Define editable fields and allowed transitions, actor audit, concurrency and idempotency behavior, and the action's authorization contract. |
| `cases.bulk.applyToCase`: cancel check-ins | No matching Studio route or OpenAPI operation. | Existing check-in records and cadence code may inform the implementation; neither is this customer API. | Define cancellation effects and outbound-message handling, consent checks, confirmation, actor audit, and per-case outcomes. |
| `cases.bulk.applyToCase`: pause check-ins | No matching Studio route or OpenAPI operation. | Existing check-in records and cadence code may inform the implementation. | Define what is paused and how it resumes, outbound-message handling, consent checks, confirmation, actor audit, and per-case outcomes. |
| `cases.bulk.applyToCase`: hand to owner | No matching Studio route or OpenAPI operation. | Reuse account-owned case and conversation associations where their behavior matches; the current case reads do not transfer ownership. | Define the owner identity and eligible states, actor audit, concurrency behavior, confirmation, and per-case outcomes. |
| `cases.bulk.applyToCase`: allow check-ins | No matching Studio route or OpenAPI operation. | Existing check-in data can inform the future state model; it does not prove permission to send. | Define consent and channel checks, outbound behavior, confirmation, actor audit, and per-case outcomes. |
| `cases.bulk.applyToCase`: take over | No matching Studio route or OpenAPI operation. | Existing conversation takeover code is a possible implementation reference, not a case API or a guarantee that every case has a conversation. | Define the case-to-conversation relationship, eligible states, actor audit, idempotency, confirmation, and per-case outcomes. |
| `cases.bulk.applyToCase`: close | No matching Studio route or OpenAPI operation. | Reuse case status and timeline data only where future closure semantics match. | Define closure transitions and required evidence or reason, actor audit, concurrency and idempotency behavior, and per-case outcomes. |
| `cases.bulk.applyToCase`: move a check-in | No matching Studio route or OpenAPI operation. | Existing check-in records and cadence code may inform date handling; they do not define an HTTP request. | Define accepted time values, scheduling and duplicate rules, consent and outbound handling, actor audit, and per-case outcomes. |
| `cases.createExport` | No matching Studio route or OpenAPI operation. | Existing case list data is available through the read API; its page-number pagination is not the requested export cursor. | Define bounded export selection and cursor behavior, job state, storage and retention, actor audit, and download authorization. |
| `cases.getExport` | No matching Studio route or OpenAPI operation. | No current customer Studio export job or download resource is exposed. | Define status and failure states, account ownership, storage expiry, and authorization on every download. |
| `cases.checkInRules` | No matching Studio route or OpenAPI operation. | Existing check-in records and cadence code may inform rule behavior; no callable customer rules resource is exposed. | Define the rule resource, defaults and validation, account ownership, and whether reads expose effective or configured values. |
| `cases.milestoneSets` | No matching Studio route or OpenAPI operation. | Existing milestone-set data and `Cases::MilestoneSets` are possible reuse points; they do not provide this API. | Define list and selection behavior, ownership, validation, and how changes affect new and existing cases. |
| `cases.saveCheckInRules` | No matching Studio route or OpenAPI operation. | Existing check-in cadence code may inform validation; no customer write endpoint is exposed. | Define accepted rule fields and ranges, actor audit, concurrency and idempotency, and effects on scheduled check-ins. |
| `cases.create` | No matching Studio route or OpenAPI operation. | Existing account-owned case, contact, milestone, and conversation data can inform creation; the case controller does not create cases. | Define required inputs, contact and milestone ownership checks, initial state, actor audit, and duplicate-request behavior. |

The current code contains case, milestone, check-in, and conversation data and internal services such as `Cases::Open`, `Cases::MilestoneSets`, `Cases::CompleteMilestone`, and `Cases::ReverseMilestoneCompletion`. These are implementation references for their owning work. Their presence does not create a callable route or settle a customer-facing authorization, confirmation, idempotency, or event contract.

## Shared requirements for future work

For bulk actions, define a maximum batch size and per-item result behavior before implementation. No maximum or all-or-nothing guarantee is established today. Any outbound check-in action needs a defined consent and channel check, confirmation behavior, and actor audit. Export work needs bounded pagination, job and storage rules, retention, and download authorization. Rule and create actions need validation and actor audit. Scope names, emitted events, and write-role guarantees remain pending review; no proposed case or export event is promised as delivered.

Before these missing routes are published, ENG-5893 must provide tests for the chosen role and feature contract, anonymous and foreign-account refusals, and account-owned resource lookups. Refused or invalid writes must preserve the prior case, check-in and ownership state and must not create success audit entries. Successful changes need actor audit evidence. These are future implementation requirements, not tests delivered by this documentation slice.

Supported idempotency and retry tests apply to case creation and every bulk variant in the table: cancel, pause, hand to owner, allow, take over, close, and move a check-in. Repeating a logical command must not apply it or write its success audit twice. Bulk tests must cover the selected batch limit, every item's reported result, and preservation of refused items. Successful items must remain visible in the result if the eventual design permits partial success; this page establishes no all-or-nothing batch guarantee. Export tests must prove account ownership and authorization for both job status and downloads, including refused or expired access.

The missing-action inventory is inactive: it adds no route, operation ID, scope, or event, and does not expose an MCP or SDK action. The three existing `moves_money` operation IDs remain unchanged.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.