Get a use case

curl https://api.example.test/v1/use-cases/$USE_CASE_ID \  -H "Authorization: Bearer $TOKEN"

One use case with its actor persona's name and its steps in order. A use case of a project the token may not see, or a draft read through a client guest's token, is 404 RESOURCE_NOT_FOUND.

status is draft, in_review, approved or deprecated; priority is must, should, could or wont; a step's flow is main, alternate or exception, and a branch carries a flow_label and the main step it leaves in branches_from.

Requires ability

use-case:view

The token must hold this ability, or the call is refused with 403.

MCP tool

get_use_case

Runs the same action from an agent, behind the same ability.

Authorization

bearerToken

AuthorizationBearer <token>

A personal access token minted in the app under Account Settings, then API Tokens, sent as Authorization: Bearer zg_live_…. The token carries the abilities each endpoint lists under Requires ability and is frozen to one team, and optionally to one project, at mint time.

In: header

Path Parameters

useCase*string

The use case, bound by the middleware.

Formatuuid

Responses

200OKapplication/json

The use case with its actor and its steps.

data*

The response's payload.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (a zg_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

The token is valid but does not carry the ability this endpoint requires; error.context.required_ability names the one to grant. An endpoint that also checks who registered a row answers FORBIDDEN with the same status, and says so in its own description.

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

An id in the path names nothing the token can see. TENANT_MISMATCH: the project sits outside the token's scope:project: allow-list, or the token carries no team scope. Both answer 404 rather than 403 so that existence outside the token's scope cannot be inferred.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X GET "https://example.com/v1/use-cases/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "data": {    "id": "e6f7a8b9-c0d1-4e2f-9a3b-4c5d6e7f8091",    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",    "number": 4,    "reference": "CRM-UC-4",    "title": "Redeem a voucher at checkout",    "actor_persona_id": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a81",    "actor_persona_name": "Nadeesha, the returning shopper",    "secondary_actors": [      "Payment provider"    ],    "goal": "Pay less for the basket with a voucher the member holds",    "trigger": "The member opens the checkout with a voucher in their wallet",    "preconditions": "<p>The member is signed in and the basket is not empty.</p>",    "postconditions": "<p>The voucher is marked used and the order carries the discount.</p>",    "frequency": "A few hundred times a day in a campaign week",    "priority": "must",    "status": "approved",    "steps": [      {        "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",        "use_case_id": "e6f7a8b9-c0d1-4e2f-9a3b-4c5d6e7f8091",        "position": 0,        "flow": "main",        "flow_label": null,        "actor_action": "The member opens the checkout",        "system_response": "The system shows the basket and the vouchers in the wallet",        "branches_from": null      },      {        "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",        "use_case_id": "e6f7a8b9-c0d1-4e2f-9a3b-4c5d6e7f8091",        "position": 1,        "flow": "main",        "flow_label": null,        "actor_action": "The member picks a voucher",        "system_response": "The system applies the discount and shows the new total",        "branches_from": null      },      {        "id": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f",        "use_case_id": "e6f7a8b9-c0d1-4e2f-9a3b-4c5d6e7f8091",        "position": 2,        "flow": "exception",        "flow_label": "2a",        "actor_action": "The member picks a voucher that expired",        "system_response": "The system refuses it, says why and keeps the total",        "branches_from": 2      }    ],    "position": 3,    "version": 0,    "approved_at": "2026-11-05T15:00:00+00:00",    "approved_revision_id": null,    "created_at": "2026-10-28T09:20:00+00:00",    "updated_at": "2026-11-05T15:00:00+00:00"  }}

Type definitions

The shapes above as types, ready to paste into your client.

export interface Response {  data: UseCaseResource;}export interface UseCaseResource {  id: string;  project_id: string;  number: number;  reference: string;  title: string;  actor_persona_id: string | null;  actor_persona_name: string | null;  secondary_actors: string[];  goal: string | null;  trigger: string | null;  preconditions: string | null;  postconditions: string | null;  frequency: string | null;  priority: string;  status: string;  steps: unknown[];  position: number;  version: number;  approved_at: string | null;  approved_revision_id: string | null;  created_at: string | null;  updated_at: string | null;}

Get a use case

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Authorization

Path Parameters

Responses