Documentation
Product GuideREST API ReferenceMCP Server for AI AgentsWebhooks & EventsIntegrations
DESTRUCTIVE

create_use_case

Adds a use case as a draft, with its main, alternate and exception flows, so how a persona reaches a goal is written step by step.

Add a use case: project_id and title are required; actor_persona_id names the persona who acts, secondary_actors the others in words, goal, trigger, preconditions and postconditions (HTML), frequency and priority (should by default) fill in the record, and steps lays down the flows in one go, each row with actor_action (required), system_response, flow (main by default, or alternate, exception), flow_label such as "3a. Card declined" and branches_from, the main-flow step number an alternate or exception branches from. The use case takes the next number of its sequence, starts as a draft, writes its first version and is announced as use_case.created.

A use case reaches in review and approved through submit_for_review and the approvers, never by hand. A staff token with use-case:create on the project is needed.

Requires ability

use-case:create

The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.

Runs the same action as

POST/v1/projects/{project}/use-cases

The REST endpoint and this tool share one action, so validation, permissions and events are identical.

Fires one event

use_case.created

Delivered to every endpoint subscribed to it once the change is made.

Annotations

Destructive

A client that honours annotations asks a person before running it.

Arguments

project_id*string

UUID of the project.

title*string

What the use case is called, 3 to 200 characters.

actor_persona_idstringoptional

UUID of the persona who acts.

secondary_actorsstring[]optional

The other actors in the room, in words; the list replaces the current one.

goalstringoptional

What the actor is trying to achieve.

triggerstringoptional

What starts it.

preconditionsstringoptional

What must be true before, as HTML.

postconditionsstringoptional

What is true after, as HTML.

frequencystringoptional

How often it happens.

prioritystringoptional

Its MoSCoW priority; should by default.

mustshouldcouldwont
stepsarrayoptional

The steps replacing the list, in order: objects with actor_action (required), system_response, flow (main, alternate, exception), flow_label and branches_from; a row with an id keeps that step.

What it returns

{  "data": {    "id": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b",    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",    "number": 2,    "reference": "SCL-UC-2",    "title": "Book a pickup",    "actor_persona_id": "6f7a8b9c-0d1e-4f2a-8b3c-4d5e6f7a8b9c",    "actor_persona_name": "Busy parent",    "secondary_actors": ["Driver"],    "goal": "Have the laundry collected from home",    "trigger": "The customer has an order ready to hand over",    "preconditions": "<p>The order is paid.</p>",    "postconditions": "<p>A pickup slot is held and the driver's route includes the address.</p>",    "frequency": "Daily",    "priority": "must",    "status": "draft",    "steps": [      {        "id": "f6a7b8c9-d0e1-4f2a-8b3c-4d5e6f7a8b9c",        "use_case_id": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b",        "position": 1,        "flow": "main",        "flow_label": null,        "actor_action": "Chooses a pickup slot",        "system_response": "Shows the slots with capacity",        "branches_from": null      },      {        "id": "a7b8c9d0-e1f2-4a3b-8c4d-5e6f7a8b9c0d",        "use_case_id": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b",        "position": 2,        "flow": "main",        "flow_label": null,        "actor_action": "Confirms the booking",        "system_response": "Sends the confirmation",        "branches_from": null      },      {        "id": "b8c9d0e1-f2a3-4b4c-8d5e-6f7a8b9c0d1e",        "use_case_id": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b",        "position": 3,        "flow": "alternate",        "flow_label": "1a. Slot taken",        "actor_action": "Picks a slot that just filled",        "system_response": "Offers the next three slots",        "branches_from": 1      }    ],    "position": 2,    "version": 1,    "approved_at": null,    "approved_revision_id": null,    "created_at": "2026-10-28T10:50:00+00:00",    "updated_at": "2026-10-28T10:50:00+00:00"  }}

How it fails

VALIDATION_FAILED

title missing or outside 3 to 200 characters, a priority outside MoSCoW, a persona that is not the project's, more steps than allowed, a step without an actor action, a flow outside the three, or a branch from a step that does not exist.

RESOURCE_NOT_FOUND

unknown project_id, or a project outside the token's scope or the person's visibility.

FORBIDDEN

the token is a client guest's, or the holder's role on the project does not carry use-case:create.

TOKEN_MISSING_ABILITY

token lacks use-case:create.

Related

list_use_casesthe use cases of the project today.update_use_casechange the fields or the steps later.create_story_draftthe stories a flow becomes.Use cases APIthe same doors over REST.

How is this guide?

Last updated on