Cases

Use epismo_case_start when an outcome must be shared or resumed. Start from a playbook version or create an ad hoc case with a title.

Case detail and access-get accept a UUID or immutable case code such as PANDA-317. Other operations use the UUID. Case get includes the latest ten records. Continue with its records_next_cursor and records_scope (self) in the CLI, or recordsNextCursor and recordsScope on API/MCP.

Public cases publish the current title, input, tasks, records, and readable handoffs, including later additions. Public account references for authors and assignees remain visible; private grants, linked sources, review reports and summaries, and private configuration are omitted. Public visibility grants reading only. Explicit viewers can also read private cases and their linked sources; writes require editing.

Public case reads cost 0 credits without login on Web, CLI, API, and MCP. Work-detail reads on API / CLI / MCP bundle supporting reads into one 1-credit case get; ordinary Web reads remain free.

• Keep local intermediate work in the agent runtime.
• Append outcomes, decisions, assessments (kind=note), shared commitments (kind=agreement), and handoff summaries with epismo_case_record_append.
• Edit or redact a record you created with epismo_case_record_update or epismo_case_record_delete.
• Create tasks with epismo_case_task_create only for explicit responsibility or approval.
• Case editors can queue an asynchronous AI assessment across the case's evidence and records with epismo_report_case_generate. The call returns immediately with job metadata. Review uses built-in evaluation instructions; custom home guidance and per-request prompts are not supported. Inspect the resulting assessment and proposals with epismo_report_case_get. Confirm or dismiss proposals (such as creating follow-up tasks) with epismo_report_case_act. Review the full saved proposal, then send reportId, proposalId, and action (create or dismiss), with optional dismissal feedback. Creation uses the saved contents unchanged to create a task, a case with a directed handoff, a suggestion, or a playbook with its first version. Do not send title, content, definition overrides, or idempotencyKey; retries use the proposal identity. Decisions are retained per proposal, so repeating a handled proposal returns the current saved report without creating more work.

New cases and playbooks use the acting caller’s active billing home with restricted creator access; source sharing and external sources are not copied. Starting a case adds a directed handoff from the reviewed case and does not close it. Playbook creation is proposed sparingly, for evidenced recurring patterns with likely future reuse; handled Playbook-creation recommendations are not proposed again for that case. A stale report shows an advisory reevaluation notice and does not block actions; live permissions and domain validation still apply.

• Connect related workflows using epismo_case_handoff_create, and inspect the DAG with epismo_case_handoff_graph_get.
• Query eligible next or previous cases with epismo_case_handoff_candidates_list (direction=outgoing or direction=incoming) to avoid loops and duplicate links.
• Generate a fresh idempotency key for each new mutation.
• Read the latest lock version before changing a case or task.

After a conflict, re-read the object and decide whether the intent remains valid. Never replay a stale request by changing only its lock version.

Do not invent an agent assignee. When a user assignment is needed, select an ID from the users resource and ensure that user is already in the case ACL.

Use epismo_case_record_list with the case ID to resume from that case's timeline. Pass scope (self, ancestors, descendants, neighbors, connected) to include records across connected handoffs while respecting individual case ACLs. Task, author, kind, and origin filters only narrow that timeline; they never grant access.

Explicit creation settings and sharing updates use access: { visibility, grants }: restricted/public visibility and user/team UUID or registered user email keys with viewer/editor values. Emails resolve to user UUIDs before saving; responses contain UUID keys. An unregistered email or conflicting roles for the same resolved user rejects the entire write. Updates replace the whole object; preserve unrelated grants and include your own grant if you want to retain it. Owners retain management independently of grants. Assignees and maintainers receive no implicit access. Editors can inspect and replace sharing, retain at least one explicit editor when changing grants, and archive or restore. Ordinary resource JSON omits private grant maps; editors can retrieve the complete settings with access-get. See Access and identity.

Input and playbook selection

Use epismo_case_update with caseId, the latest expectedLockVersion, and an idempotencyKey to update an open case. Set versionId to attach or replace a readable, non-archived playbook version, set it to null to remove the playbook, or omit it to preserve the current selection. Case editing access is required.

Every title, input, or playbook update validates the resulting input against the selected version's input schema, when a playbook is selected. Supplied input replaces the complete object; omission reuses the current input. Playbook selection and optional input replacement commit together; a validation failure saves neither change. Removing the playbook preserves input without applying the old schema.

{
	"caseId": "<case-uuid>",
	"versionId": "<version-uuid>",
	"input": { "customer": "Acme" },
	"expectedLockVersion": 1,
	"idempotencyKey": "<new-uuid>"
}

To remove the playbook, send "versionId": null with the latest lock version and a new idempotency key.

Attaching, replacing, or removing a playbook creates a system activity identifying the previous and selected versions as applicable. Existing tasks, records, and reports are preserved; tasks keep their original step references.

Ownership, responsibility, and lifecycle

Playbooks and cases have an owning user or workspace account (ownerId), which is also the billing home. A personal owner has full rights; current owners and admins exercise ownership rights for a workspace. Other members need explicit user or team grants, or public visibility for published reads. Workspace membership alone grants no resource access. Removing a workspace member clears their direct grants on items owned by that workspace, including archived and completed items. If removal would leave any affected item without an explicit editor, add another user or team editor first, including on completed and archived items. Personal and other-workspace shares remain unchanged. Team and management authority follow current membership. Required SSO applies to members; non-member direct shares use normal Epismo authentication. Cross-workspace team sharing verifies the participation workspace's SSO. Lists use explicit access and supported public visibility; ownership alone does not include an item.

Case and task mutations require the latest expectedLockVersion (the read response contains lockVersion). On conflict, read current state and reconsider the change. Case editors may assign, retitle, close, reopen, change all sharing, archive, and restore. Assignment grants no access; the selected assignee must already be able to edit. Clearing sharing does not change assignment. startedBy, creators, and completed approvals remain history.

Omit ownerId on creation or copy to use the active workspace, or your personal account when no workspace is selected. Supplying it explicitly chooses the home subject to authorization. When a workspace is selected, including a saved connection default, creation requires exactly one of private: true, non-empty teamIds, or access. Personal creation may omit sharing. Team editor access covers the creator without adding a redundant direct grant; an explicitly requested creator grant is preserved. Maintenance and assignment do not replace sharing.

Archiving is separate from closing. Editors and owners can archive through Web, CLI, API, or MCP. Archived cases disappear from active views, counts, and handoff graphs and cannot be opened, but their work is retained. List with archived=true (case list --archived) to obtain the UUID and latest lock version, then restore without changing status, assignment, or sharing. Only an owner may permanently delete an archived case, with the latest expectedLockVersion; this removes its tasks, records, sources, and handoff links. Other cases and external provider content remain.

epismo_case_archive / epismo_case_restore / epismo_case_delete

Transfer case ownership with epismo_case_owner_transfer, case owner transfer <case-id> --owner-id <account-id> --lock-version <n>, or PATCH /v1/cases/{caseId}/owner (ownerId, expectedLockVersion, idempotencyKey). Current ownership is required. A personal case may move into the connected workspace; a public case also requires destination workspace management rights. A workspace case may move to its creator or a workspace owner. User-to-user and workspace-to-workspace moves are rejected. The transfer preserves assignment and sharing, changes the billing home, and clears derived case evaluation reports. Reassignment alone does none of these ownership changes.

Discover public cases with epismo_case_list, without login. Results use update-time order and include cases without records. Filter a source playbook with playbookId. With login, omit sharingScope to include all readable cases, or choose only_me, shared, or anyone. Filters never grant access; see Access and identity.

Discover public cases with epismo_case_list; login is optional for public listing. Results use update-time order and include cases without records. Filter a source playbook with playbookId. With login, omit sharingScope to include all readable cases, or choose private, shared, or anyone. Filters never grant access; see Access and identity.

Browse saved evaluations

Case detail includes the latest readable report and generation job without loading history or running AI. Use epismo_report_case_list with caseId, optional pageSize, and optional cursor for newest-first dates, health diagnoses, and summaries. Pass a saved reportId to epismo_report_case_get to read its full contents.

History reads require current case work access and match the current sharing audience. Public-only readers cannot see reports or summaries. Superseded reports have historical: true and are read-only: creating or dismissing an unhandled proposal from one returns HTTP 409. Read the latest report and reconsider its proposal before acting. Changes to evidence alone still show an advisory reevaluation notice.

Records use note, output, server-authored activity, or agreement. New records and kind changes accept note, output, or agreement. Human and agent assessments can be saved as notes; AI Review saves separate reports.

Personal and team reports

Personal reports are private to the generating user in the active billing home. Team reports and proposal handling are shared with current team members in the active workspace. See AI review for work selection, health diagnoses, history and sharing behavior.

Team generate/get/list require teamId; team act derives its scope from the saved reportId. Generation takes a UUID idempotencyKey and returns a job. Read using jobId or reportId, never both; paginate lists with pageSize and cursor. Before acting, read the full proposal and send reportId, proposalId, action (create or dismiss) and optional dismissal feedback. Actions use saved contents unchanged and do not take an idempotency key.