Use Cases API

Use Cases describe the approved business purposes for a data product. The API lets you manage the space-level use case catalog, review product registration requests, and inspect use case coverage across a space or organization.

All endpoints are served under /api/v1.0. Paths below omit that prefix.

Endpoint Overview

Method	Endpoint	Purpose
GET	`/spaces/{slug}/use-case-workflows`	List active workflow definitions that can be assigned to use cases.
GET	`/spaces/{slug}/use-cases/overview`	List use cases with registration counts and product registrations for a space.
GET	`/organizations/{slug}/use-cases/overview`	List use cases with product registrations across organization spaces visible to the caller.
GET	`/spaces/{slug}/use-cases`	List active use cases in a space.
POST	`/spaces/{slug}/use-cases`	Create a use case in a space.
GET	`/spaces/{slug}/use-cases/{use_case_id}`	Get one use case with overview data.
PUT	`/spaces/{slug}/use-cases/{use_case_id}`	Update a use case.
DELETE	`/spaces/{slug}/use-cases/{use_case_id}`	Permanently delete a use case that has no active registrations.
POST	`/spaces/{slug}/use-cases/{use_case_id}/archive`	Archive a use case.
POST	`/spaces/{slug}/use-cases/{use_case_id}/unarchive`	Restore an archived use case.
GET	`/spaces/{slug}/use-cases/{use_case_id}/comments`	List comments on a use case.
POST	`/spaces/{slug}/use-cases/{use_case_id}/comments`	Add a comment or reply to a use case.
PUT	`/spaces/{slug}/use-cases/{use_case_id}/comments/{comment_id}`	Update a use case comment.
DELETE	`/spaces/{slug}/use-cases/{use_case_id}/comments/{comment_id}`	Delete a use case comment.
GET	`/spaces/{slug}/products/{product_id}/use-case-registrations`	List use case registrations for one product.
POST	`/spaces/{slug}/products/{product_id}/use-case-registrations`	Request or create a registration between a product and use case.
GET	`/spaces/{slug}/use-case-registrations/pending`	List pending registrations in the space for governance review.
POST	`/spaces/{slug}/use-case-registrations/{registration_id}/review`	Approve or reject a pending registration.
DELETE	`/spaces/{slug}/use-case-registrations/{registration_id}`	Revoke a registration.

Authorization Model

Space routes resolve {slug} to the current space context. Organization overview routes resolve {slug} to an organization and aggregate only spaces the caller can access.

Use case catalog operations use the use_case resource:

Action	Typical baseline roles
`view`	`member`, `owner`, `steward`, `dpo`, `space_admin`, `superadmin`
`create`	`space_admin`, `superadmin`
`edit`	`space_admin`, `superadmin`
`delete`	`space_admin`, `superadmin`

Registration review and revocation use the use_case_registration resource and also check governance authority on the product. The reviewer must be a superadmin or have an active governance assignment on that product.

Use Case Object

Use case list and create/update responses return this shape:

{
  "id": "5a8f0b7a-4181-4d81-a0c4-c17f8aa4a76b",
  "name": "Customer retention analytics",
  "description": "Customer behavior analysis for retention programs.",
  "long_description": "Long-form markdown guidance for stewards and reviewers.",
  "business_value_score": 80,
  "requires_approval": true,
  "workflow_id": "8ec5f4e3-40a2-4fb4-a43d-cd745c2ca813",
  "workflow_name": null,
  "is_archived": false
}

Field	Notes
`name`	Required when creating a use case.
`description`	Short summary shown in use case lists and registration cards.
`long_description`	Longer markdown-capable description used by detail views.
`business_value_score`	Integer score. Missing values are stored and returned as `0`.
`requires_approval`	Defaults to `true`. If `false`, product registrations are approved immediately.
`workflow_id`	Optional workflow definition identifier stored on the use case. Use `/use-case-workflows` to discover active definitions.
`is_archived`	Archived use cases are hidden from the basic list endpoint and can be included in overview calls.

List Workflows

GET /spaces/{slug}/use-case-workflows

Returns active workflow definitions that can be selected on use cases.

[
  {
    "id": "8ec5f4e3-40a2-4fb4-a43d-cd745c2ca813",
    "name": "Governance Review",
    "description": "Steward and owner approval flow"
  }
]

The use case registration endpoint creates a governance request when approval is required and returns its request_id. The registration response does not include a workflow instance identifier.

Overview

GET /spaces/{slug}/use-cases/overview?search=retention&status=pending&include_archived=true
GET /organizations/{slug}/use-cases/overview?search=retention&status=pending

Use overview endpoints for governance dashboards. They return use case metadata, registration status counts, and product registration summaries.

Query parameter	Space overview	Organization overview	Notes
`search`	Yes	Yes	Case-insensitive use case name search.
`status`	Yes	Yes	Filters returned registrations by status. Use `all` or omit for all statuses.
`include_archived`	Yes	No	Includes archived use cases in the space response.

[
  {
    "id": "5a8f0b7a-4181-4d81-a0c4-c17f8aa4a76b",
    "space_id": "d4f6b12d-5c91-48d0-aa8d-083cb6b9c72b",
    "space_name": "Retail",
    "space_slug": "retail",
    "name": "Customer retention analytics",
    "description": "Customer behavior analysis for retention programs.",
    "long_description": null,
    "business_value_score": 80,
    "requires_approval": true,
    "workflow_id": null,
    "workflow_name": null,
    "is_archived": false,
    "status_counts": {
      "pending": 1,
      "approved": 2,
      "rejected": 0,
      "cancelled": 0
    },
    "registrations": [
      {
        "id": "a0c8e6f4-00a9-4a0e-9d7d-71b0112fc7a5",
        "product_id": "9ae66075-37a4-4dd8-a13f-9f85d7a77122",
        "product_name": "Customer 360",
        "status": "pending",
        "justification": "Used by the retention modeling team.",
        "requested_by": {
          "id": "6f77342c-b7ad-4c2d-af7e-c2d742466725",
          "email": "steward@example.com",
          "full_name": "Data Steward"
        },
        "requested_at": "2026-06-26T14:22:17",
        "request_id": "8ac7a921-b157-4fc9-9283-01cbfcf51538"
      }
    ]
  }
]

Manage Use Cases

List Use Cases

GET /spaces/{slug}/use-cases

Returns active, non-archived use cases in name order.

Create Use Case

POST /spaces/{slug}/use-cases
Content-Type: application/json

{
  "name": "Fraud detection",
  "description": "Transaction scoring and case investigation.",
  "long_description": "Approved for fraud operations and analyst review.",
  "business_value_score": 90,
  "requires_approval": true,
  "workflow_id": "8ec5f4e3-40a2-4fb4-a43d-cd745c2ca813"
}

Get Use Case

GET /spaces/{slug}/use-cases/{use_case_id}

Returns one use case in the same overview shape used by /use-cases/overview, including status counts and registrations. Archived use cases can be returned by this endpoint if the caller can view them.

Update Use Case

PUT /spaces/{slug}/use-cases/{use_case_id}
Content-Type: application/json

All fields are optional. To clear the stored workflow, send "workflow_id": null.

{
  "description": "Transaction scoring for fraud operations.",
  "requires_approval": false,
  "workflow_id": null
}

Archive And Restore

POST /spaces/{slug}/use-cases/{use_case_id}/archive
POST /spaces/{slug}/use-cases/{use_case_id}/unarchive

Archive is a soft delete. It sets archive metadata and removes the use case from the basic list endpoint. Restore clears archive metadata.

Both endpoints return:

{
  "message": "Use case archived"
}

or:

{
  "message": "Use case restored"
}

Delete Use Case

DELETE /spaces/{slug}/use-cases/{use_case_id}

Deletes the use case record permanently. The request fails with 409 Conflict when the use case has active pending or approved registrations.

{
  "message": "Use case deleted"
}

If deletion is blocked, archive the use case or resolve active registrations first.

Registration Lifecycle

Use case registrations connect data products to the business purposes they serve. A product and use case can have only one registration record.

Registration statuses are:

Status	Meaning
`pending`	Approval is required and the registration is awaiting review.
`approved`	The registration is active.
`rejected`	The registration was reviewed and denied. A later request can reset it.
`revoked`	A previously approved registration was revoked.
`cancelled`	The linked governance request was cancelled while pending.

List Product Registrations

GET /spaces/{slug}/products/{product_id}/use-case-registrations?status_filter=approved

Returns registrations for one product, newest first.

[
  {
    "id": "a0c8e6f4-00a9-4a0e-9d7d-71b0112fc7a5",
    "product_id": "9ae66075-37a4-4dd8-a13f-9f85d7a77122",
    "use_case": {
      "id": "5a8f0b7a-4181-4d81-a0c4-c17f8aa4a76b",
      "name": "Customer retention analytics",
      "description": "Customer behavior analysis for retention programs.",
      "long_description": null,
      "business_value_score": 80
    },
    "status": "approved",
    "justification": "Used by the retention modeling team.",
    "requested_by": {
      "id": "6f77342c-b7ad-4c2d-af7e-c2d742466725",
      "email": "steward@example.com",
      "full_name": "Data Steward",
      "avatar_url": null
    },
    "requested_at": "2026-06-26T14:22:17",
    "reviewed_by": {
      "id": "f04a24bb-92f7-49ef-a678-c75f0994d4d2",
      "email": "owner@example.com",
      "full_name": "Product Owner",
      "avatar_url": null
    },
    "reviewed_at": "2026-06-27T08:31:44",
    "reviewer_notes": "Approved for the retention program.",
    "request_id": "8ac7a921-b157-4fc9-9283-01cbfcf51538"
  }
]

Request Registration

POST /spaces/{slug}/products/{product_id}/use-case-registrations
Content-Type: application/json

{
  "use_case_id": "5a8f0b7a-4181-4d81-a0c4-c17f8aa4a76b",
  "justification": "Used by the retention modeling team."
}

Behavior:

Condition	Result
`requires_approval` is `true`	Creates a `pending` registration and a pending governance request. The response includes `request_id`.
`requires_approval` is `false`	Creates an `approved` registration immediately.
Existing registration is `pending`	Returns `400` with `Registration already pending`.
Existing registration is `approved`	Returns `400` with `Use case already registered`.
Existing registration is `rejected`	Resets the existing record to `pending` or `approved`, depending on current use case approval settings.
Product or use case is outside the URL space	Returns `404`.

List Pending Registrations

GET /spaces/{slug}/use-case-registrations/pending

Returns all pending registrations in the space with product summaries. Use this endpoint for governance review queues.

Review Registration

POST /spaces/{slug}/use-case-registrations/{registration_id}/review
Content-Type: application/json

{
  "action": "approve",
  "notes": "Approved for the stated campaign scope."
}

action must be approve or reject. The registration must currently be pending; otherwise the API returns 400. Successful review sets reviewed_by, reviewed_at, and reviewer_notes, then returns the updated registration detail.

Revoke Registration

DELETE /spaces/{slug}/use-case-registrations/{registration_id}

Sets the registration status to revoked and records the revoking reviewer and timestamp.

{
  "message": "Registration revoked"
}

The endpoint verifies that the registration belongs to the URL space through its product. The caller must have governance authority on that product or be a superadmin.

Comments

Use case comments share the product comment payload shape.

GET /spaces/{slug}/use-cases/{use_case_id}/comments?search=approval
POST /spaces/{slug}/use-cases/{use_case_id}/comments
PUT /spaces/{slug}/use-cases/{use_case_id}/comments/{comment_id}
DELETE /spaces/{slug}/use-cases/{use_case_id}/comments/{comment_id}

Create a top-level comment:

{
  "content_markdown": "Please confirm this use case includes only approved customer segments."
}

Create a reply by passing the parent comment identifier:

{
  "content_markdown": "Confirmed for campaign-scoped records only.",
  "parent_id": "b361aa2c-4428-4d80-b00c-e0f0fdcf9920"
}

List responses include pagination headers. Update requires content_markdown. Only comment authors can edit their own comments. Delete is limited to the author or an administrator.

Error Reference

Status	Cause
`400`	Duplicate pending or approved registration, invalid review action, or reviewing a non-pending registration.
`403`	Missing space, resource, or product governance permission.
`404`	Space, organization, use case, product, registration, or parent comment was not found in the resolved scope.
`409`	Deleting a use case with active `pending` or `approved` registrations.

Implementation Notes

Use case catalog routes are mounted from the versioned API router at /api/v1.0/spaces.
Organization overview routes are mounted at /api/v1.0/organizations.
Use case records are space-scoped. Organization overview aggregates across spaces visible to the caller.
Registration review and revocation are product-governance actions, not only use case catalog edits.
If a pending governance request is cancelled through the Requests API, the linked registration status becomes cancelled.

Endpoint Overview​

Authorization Model​

Use Case Object​

List Workflows​

Overview​

Manage Use Cases​

List Use Cases​

Create Use Case​

Get Use Case​

Update Use Case​

Archive And Restore​

Delete Use Case​

Registration Lifecycle​

List Product Registrations​

Request Registration​

List Pending Registrations​

Review Registration​

Revoke Registration​

Comments​

Error Reference​

Implementation Notes​