Use cases
GET /api/public/use-cases — list use cases
Lists use cases, paginated.
| Parameter | In | Required | Description |
|---|---|---|---|
page | query | No | Page number. Default 1. |
limit | query | No | Results per page. Default 20. See the pagination gotcha below. |
viewDetails | query | No | Boolean — return full field detail vs. a summary. |
Successful response:
{
"data": [
{
"id": "string",
"title": "string",
"description": "string",
"status": "draft",
"created_at": "2026-02-27T23:07:28.600Z",
"updated_at": "2026-02-27T23:07:28.600Z",
"delete_flag": false
}
]
}Pagination gotcha — read this before you build a sync job. Loop
page = 0, 1, 2, … until page >= meta.totalPages, using limit=100.
Do not set limit above roughly 100. Requesting limit=1000 does not
error — it silently returns only 50 rows with meta.totalPages: 1, which
looks like “that’s everything” and will quietly truncate any bulk sync. Keep
limit at 100 or below and trust meta.totalPages to know when you’re done.
POST /api/public/use-cases — create a use case
Creates a use case.
Request body:
{ "name": "string" }For the full field-mapping shape used by production pipelines (source IDs, custom fields, etc.), see Field configuration & data mapping.
Response: 201 Created with the new use case object, or 400/401/500 with { "data": null, "error": "..." }.
PATCH /api/public/use-cases/{caseId} — update a use case
Partially updates a use case. Only the fields you send are changed — this is a merge, not a replace.
Request body:
{ "custom_fields": { "key": "value" } }{caseId} is the AlignAI database ID, not your source system’s ID. If
you’re syncing from an external system (e.g., a customer/BreadBox/Medallia
ID), you must resolve that external ID to the AlignAI numeric id first —
usually by pulling the list and matching on source_id — before you can
PATCH.
There is no single-record GET. GET /api/public/use-cases/{id} returns
405 Method Not Allowed — the {id} path only accepts OPTIONS, PATCH,
and PUT. To read one record, pull the paginated list (or use
POST /use-cases/filter below) and filter client-side.
Verifying a write: because there’s no single-record GET, verify a PATCH by re-pulling the list and checking the field. A 200 OK response with a field that still looks blank usually means one of: the source value really was blank, you sent a dropdown’s display label instead of its option key (see Writing data), or the field key was mistyped.
POST /api/public/use-cases/filter — filter use cases with background filters
The closest thing to a query endpoint. Filters are applied server-side and the response also returns the available fields for further filtering. Max batch size is 200 (this is also the default if unspecified).
Request:
{
"filters": {
"status": "submitted",
"theme": "creditRiskOps"
},
"pageParam": {
"pageNumber": 0,
"batchSize": 200
}
}Response (200):
{
"data": [
{
"id": "uc-123",
"title": "Sample Use Case",
"description": "A sample use case for testing",
"status": "active",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z",
"delete_flag": false
}
],
"fields": [
{ "key": "status", "type": "string", "display": "Status" }
]
}Error responses: 400 (invalid filter format), 401 (bad/missing token), 500.