Data Suitability Recipe 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.

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 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.

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."
  }'

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 bound asset.

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

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

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"
  }'

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

curl -X POST "https://your-instance.qualytics.io/api/ai-use-cases/31/baseline" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"

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.

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" }'

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" }'

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

curl -X POST "https://your-instance.qualytics.io/api/ai-use-cases/31/attestations" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"

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

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

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.

Reading Records and Evidence

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

Error Responses

{ "detail": "Invalid certification transition: Draft -> Certified. Allowed: ['InReview']" }

{ "detail": "Cannot generate an attestation until the AI use case is certified" }

{ "detail": "Cannot generate an attestation because the asset scope changed after baseline capture" }

{ "detail": "Only a Manager of the bound datastores or an Admin can certify or revoke this AI use case" }

Related

• AI Use Cases: the record, its lifecycle, and what an attestation contains.
• Permissions: the roles, team permissions, and ownership rule behind each call.
• How It Works: how the recipe saves its progress on the record.