# Data Suitability Recipe API

Source: https://userguide.qualytics.io/recipes/data-suitability/api/

The Data Suitability recipe is a guided flow over the **AI Use Case** endpoints. Everything it does, from creating the record to exporting an attestation, is available through the API in the same order the recipe follows: create the use case, bind its assets and standard, capture a baseline, move it through certification, generate the attestation, and export it. The recipe's saved progress is itself a resource, the use case's latest recipe run.

> **Tip**
>
> For complete API documentation, including request/response schemas, visit the [API docs](https://userguide.qualytics.io/api/docs).

All endpoints use the base URL of your Qualytics deployment (e.g., `https://your-instance.qualytics.io/api`) and require a Personal API Token. Every call needs the **Member** role. Reading a use case needs the **Viewer** team permission on every datastore it binds; changing it needs **Author** on all of them, and Members can only change records they created; certifying or revoking needs the **Manager** role plus **Editor** on all of them, or the **Admin** role. See [Permissions](https://userguide.qualytics.io/recipes/data-suitability/deep-dive/permissions/) for the full matrix. Responses carry two flags, `can_edit` and `can_certify`, that tell you which of these the caller holds.

## The Recipe Sequence

### 1. Create the Use Case

The Model step creates the record. Bindings can be sent at creation or added later.

**Endpoint**: `POST /ai-use-cases`

**Permission**: **Author** team permission on every datastore in `datastore_ids`. A record created with no bindings needs Author on at least one datastore anywhere.

| Field | Required | Description |
| --- | --- | --- |
| `name` | Yes | Unique name, up to 255 characters. |
| `risk_tier` | No | Free text up to 100 characters. The recipe offers `minimal`, `limited`, and `high`. |
| `description` | No | What the model decides and who relies on it. |
| `datastore_ids` | No | The datastores the model reads. |
| `container_ids` | No | Containers inside the bound datastores. |
| `quality_check_ids` | No | Checks on the bound assets that pin the standard. Empty means every active check at generation time. |
| `crontab`, `timezone` | No | The certification expiry schedule. |
| `certification_expires_at` | No | A validity date for the certification. |

> **Example: Example request**
>
> ```bash
> curl -X POST "https://your-instance.qualytics.io/api/ai-use-cases" \
>   -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "Retail Credit Scoring v4",
>     "risk_tier": "high",
>     "description": "Scores retail credit applications; relied on by underwriting."
>   }'
> ```
>
> **Response** (200 OK): the use case, with `id`, `certification_state: "Draft"`, `can_edit`, and `can_certify`.

### 2. Bind Inputs and the Standard

The Inputs and Standard steps update the record. Fields you omit are left unchanged; an explicit `null` on a list clears it. Containers must belong to a bound datastore, and checks to a container of a bound datastore.

> **Warning: Narrowing the containers keeps their checks**
>
> Removing a container from `container_ids` does not remove its checks from the standard, because a check only has to belong to a bound datastore. When you narrow `container_ids`, send `quality_check_ids` in the same request with the checks you want to keep.

**Endpoint**: `PATCH /ai-use-cases/{id}`

**Permission**: **Author** team permission on every bound datastore, before and after the change; Members must own the record

> **Example: Example request**
>
> ```bash
> curl -X PATCH "https://your-instance.qualytics.io/api/ai-use-cases/31" \
>   -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "datastore_ids": [12, 14],
>     "container_ids": [145, 146, 201],
>     "quality_check_ids": [812, 813],
>     "crontab": "0 6 * * *",
>     "timezone": "America/New_York"
>   }'
> ```
>
> **Response** (200 OK): the updated use case.

### 3. Capture the Baseline

The Baseline step snapshots the bound containers' quality scores, profile identifiers, and row counts. Capturing again replaces the referent and returns the record to Draft.

**Endpoint**: `POST /ai-use-cases/{id}/baseline`

**Permission**: **Author** team permission on every bound datastore; Members must own the record

> **Example: Example request**
>
> ```bash
> curl -X POST "https://your-instance.qualytics.io/api/ai-use-cases/31/baseline" \
>   -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"
> ```
>
> **Response** (200 OK): the use case with its `baseline`, including `captured_at` and the container count.

### 4. Move Through Certification

The Evidence step's transition buttons call one endpoint with the target state. Only the allowed transitions are accepted: Draft to InReview, InReview to Certified or back to Draft, Certified to Revoked, Expired to InReview, and Revoked to Draft. `Expired` can never be set directly. `certification_expires_at` is applied only when moving to `Certified`.

**Endpoint**: `POST /ai-use-cases/{id}/certification`

**Permission**: `Certified` and `Revoked` need the **Manager** role plus **Editor** on every bound datastore, or **Admin**. `InReview` and `Draft` need **Author** on every bound datastore, and Members must own the record.

> **Example: Example requests**
>
> Submit for review:
>
> ```bash
> curl -X POST "https://your-instance.qualytics.io/api/ai-use-cases/31/certification" \
>   -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{ "state": "InReview" }'
> ```
>
> Certify with a validity date:
>
> ```bash
> curl -X POST "https://your-instance.qualytics.io/api/ai-use-cases/31/certification" \
>   -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{ "state": "Certified", "certification_expires_at": "2027-09-14T23:59:59.999Z" }'
> ```
>
> **Response** (200 OK): the use case with `certification_state`, `certified_at`, `certified_by`, and `certification_expires_at`.

### 5. Generate the Attestation

The Evidence step generates the immutable evidence record. The record must be Certified, a baseline must exist, and the bound containers must not have changed since the baseline.

**Endpoint**: `POST /ai-use-cases/{id}/attestations`

**Permission**: **Author** team permission on every bound datastore; Members must own the record

> **Example: Example request**
>
> ```bash
> curl -X POST "https://your-instance.qualytics.io/api/ai-use-cases/31/attestations" \
>   -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"
> ```
>
> **Response** (200 OK): the attestation, with `id`, `created`, `supersedes_id`, `generated_by`, and the full `content`.

### 6. Export the Attestation

The Complete step downloads the record as JSON or HTML.

**Endpoint**: `GET /ai-use-cases/{id}/attestations/{attestation_id}/export?format=json|html`

**Permission**: **Viewer** team permission on every bound datastore

> **Example: Example request**
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/ai-use-cases/31/attestations/57/export?format=html" \
>   -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN" \
>   -o attestation_31_57.html
> ```
>
> **Response** (200 OK): the file, named `attestation_{id}_{attestation_id}.{format}`.

## Recipe Runs

The recipe's saved progress is stored on the use case as its latest run. Reading it returns `null` when the record has never been opened in the recipe.

| Endpoint | Purpose | Permission |
| --- | --- | --- |
| `GET /ai-use-cases/{id}/runs/latest` | The latest run: `recipe_key`, `active_step`, `state`, `completed_at`. | Viewer on every bound datastore |
| `PUT /ai-use-cases/{id}/runs/latest` | Save progress: `recipe_key` (`data-suitability`), `active_step`, `state`, `completed`. Updates the open run, or starts a new one when the latest is complete. | Author on every bound datastore; Members must own the record |

## Reading Records and Evidence

| Endpoint | Purpose |
| --- | --- |
| `GET /ai-use-cases` | Page through the use cases you can see, with `name`, `certification_state`, `deactivated`, and sort parameters. Each row carries counts of bound datastores, containers, and checks, and the latest run. |
| `GET /ai-use-cases/{id}` | One use case with its bindings, baseline, latest run, and permission flags. |
| `GET /ai-use-cases/{id}/history` | Every saved version of the record, with the acting user. |
| `GET /ai-use-cases/{id}/attestations` | The attestation history, newest first. |
| `GET /ai-use-cases/{id}/attestations/as-of?date=...` | The attestation that was current at a point in time: the newest one generated at or before `date`. A date without a time means 00:00 UTC that day, so pass a date and time (for example `2026-09-30T23:59:59`) to include attestations generated during the day. |
| `GET /ai-use-cases/{id}/attestations/{attestation_id}` | One attestation with its content. |
| `GET /ai-use-cases/{id}/attestations/{attestation_id}/comparison` | The attestation compared with the current state: movement from baseline to attestation and from attestation to now, per container, plus the check set comparison. |
| `POST /ai-use-cases/{id}/evaluate` | Re-evaluate expiry, marking a lapsed certification Expired. This is what the expiry schedule calls; it needs the **Manager** role. |
| `DELETE /ai-use-cases/{id}` | Delete the record. Same permission as editing. |

All reads need the **Viewer** team permission on every bound datastore.

## Error Responses

| Status Code | Description |
| --- | --- |
| `401 Unauthorized` | Missing or invalid API token. |
| `403 Forbidden` | The caller lacks the team permission on a bound datastore, does not own the record as a Member, or is not a Manager of the bound datastores when certifying. Also returned for bindings to datastores, containers, or checks the caller cannot access. |
| `404 Not Found` | No use case or attestation exists with the specified ID, or the caller cannot see it. Also returned when no attestation was current on the requested date. |
| `409 Conflict` | The name is already taken, or the certification transition is not allowed from the current state. |
| `422 Unprocessable Entity` | Invalid request body, such as a container or check outside the bound scope, an invalid schedule, a baseline with no bound containers, or an attestation requested before certification, before a baseline, or after the scope changed. |

> **Example: Error response examples**
>
> **409 Conflict** (transition not allowed):
>
> ```json
> { "detail": "Invalid certification transition: Draft -> Certified. Allowed: ['InReview']" }
> ```
>
> **422 Unprocessable Entity** (not certified yet):
>
> ```json
> { "detail": "Cannot generate an attestation until the AI use case is certified" }
> ```
>
> **422 Unprocessable Entity** (scope changed):
>
> ```json
> { "detail": "Cannot generate an attestation because the asset scope changed after baseline capture" }
> ```
>
> **403 Forbidden** (certifying without the right):
>
> ```json
> { "detail": "Only a Manager of the bound datastores or an Admin can certify or revoke this AI use case" }
> ```

## Related

- [AI Use Cases](https://userguide.qualytics.io/recipes/data-suitability/deep-dive/ai-use-cases/): the record, its lifecycle, and what an attestation contains.
- [Permissions](https://userguide.qualytics.io/recipes/data-suitability/deep-dive/permissions/): the roles, team permissions, and ownership rule behind each call.
- [How It Works](https://userguide.qualytics.io/recipes/data-suitability/deep-dive/how-it-works/): how the recipe saves its progress on the record.

*Last updated: October 19, 2026.*
