Anomalies API

This page documents the REST endpoints for working with anomalies in Qualytics. All endpoints share the base URL of your deployment (for example, https://your-instance.qualytics.io/api) and require a Bearer token.

Sections below are grouped by what you are trying to do. The same anomaly object is exchanged across reads and writes: see the Anomaly schema section for the field reference.

Anomaly schema

Every read endpoint that returns an anomaly emits the same shape. The most relevant fields are:

{
  "id": 12345,
  "uuid": "8e8b9f8b-1234-4abc-9def-012345678901",
  "type": "record",
  "status": "Active",
  "weight": 54,
  "anomalous_records_count": 1,
  "description": "Customer ID is missing for new orders",
  "created": "2026-05-15T17:22:08Z",
  "fingerprint": 9182736455,
  "global_tags": [{ "id": 7, "name": "High" }],
  "assignees": [
    { "id": 42, "name": "Alice Lee", "email": "alice@example.com" }
  ],
  "failed_checks": [{ "id": 778, "rule_type": "notNull", "message": "..." }]
}

List and retrieve

List anomalies

Returns a paginated list of anomalies sorted by creation timestamp and severity (most recent first).

Endpoint: GET /api/anomalies

Permission: Member. Results are scoped to datastores the caller can see.

Common query parameters (all optional, most accept multiple values):

curl -X GET "https://your-instance.qualytics.io/api/anomalies?status=Active&assignee=42&tag=High&sort_weight=desc" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get a single anomaly

Endpoint: GET /api/anomalies/{id}

{id} accepts either the numeric ID or the UUID. Pass include_deleted=true to surface anomalies that have been soft-deleted.

curl -X GET "https://your-instance.qualytics.io/api/anomalies/12345" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get failed checks for an anomaly

Returns the list of checks that produced the anomaly, with the message text and the rule type for each.

Endpoint: GET /api/anomalies/{id}/failed-checks

Update

Update a single anomaly

Updates the writable fields of an anomaly. Only the fields you include in the body are changed; omitted fields are left untouched.

Endpoint: PUT /api/anomalies/{id}

Permission: Member role + Author team permission on the anomaly's datastore. This covers status, tags, assignee, and description updates.

Body fields:

curl -X PUT "https://your-instance.qualytics.io/api/anomalies/12345" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "Acknowledged",
    "description": "Investigating with the data engineering team",
    "tags": ["High", "Customer-Impact"],
    "assignee_ids": [42, 57]
  }'

Bulk update anomalies

Applies the same changes to many anomalies in one call.

Endpoint: PATCH /api/anomalies

Permission: Member role + Author team permission on each anomaly's datastore. This covers status, tags, assignee, and description updates.

Body: A list of bulk-update entries, each with the anomaly identifier plus the fields to change. Per-entry fields match the single-update body, with the addition of:

curl -X PATCH "https://your-instance.qualytics.io/api/anomalies" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    { "id": 12345, "status": "Acknowledged" },
    { "id": 12346, "assignee_ids": [42] },
    { "id": 12347, "tags": [] }
  ]'

Manage assignees

Assignees are managed via the standard update endpoints. The assignee_ids field is replace-only, so pass the full target set on every write rather than the changes you want to apply.

Endpoints:

• PUT /api/anomalies/{id} with assignee_ids in the body for a single anomaly.
• PATCH /api/anomalies with assignee_ids per entry for many anomalies.
• GET /api/anomalies?assignee=<id> to filter the list by assignee.

Behavior:

• Each user passed in assignee_ids must have at least the Viewer team permission on the anomaly's datastore. Users without access are rejected.
• Pass assignee_ids: [] to unassign everyone.
• To add a user to an existing set, read assignees first and submit the union. The API does not support append.
• Auto-assignment from a check's default assignee runs only at anomaly creation and is not reachable through this endpoint. See Deep Dive · Anomaly Assignees · Inheritance.

curl -X PUT "https://your-instance.qualytics.io/api/anomalies/12345" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "assignee_ids": [42, 57] }'

curl -X PUT "https://your-instance.qualytics.io/api/anomalies/12345" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "assignee_ids": [] }'

curl -X PATCH "https://your-instance.qualytics.io/api/anomalies" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    { "id": 12345, "assignee_ids": [42, 57] },
    { "id": 12346, "assignee_ids": [42] },
    { "id": 12347, "assignee_ids": [] }
  ]'

See Deep Dive · Anomaly Assignees for inheritance rules, notification behavior, and history tracking.

Archive and delete

The single-anomaly endpoint covers both the archive flow (mark with a resolution status and keep for audit) and the hard-delete flow (remove the record entirely). Bulk versions follow the same pattern.

Archive or delete a single anomaly

Endpoint: DELETE /api/anomalies/{id}

Permission: Member role + Author team permission on the anomaly's datastore.

Query parameters:

Body (optional): Lets you attach a comment and tag teammates when archiving.

curl -X DELETE "https://your-instance.qualytics.io/api/anomalies/12345?archive=true&status=Resolved" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "Resolved after backfill, see @[Alice Lee](42)",
    "mentioned_user_ids": [42]
  }'

curl -X DELETE "https://your-instance.qualytics.io/api/anomalies/12345?archive=false" \
  -H "Authorization: Bearer YOUR_TOKEN"

Bulk archive or delete

Endpoint: DELETE /api/anomalies

Permission: Member role + Author team permission on each anomaly's datastore.

Body: A list of entries combining the anomaly ID with the same fields used in the single-anomaly delete (status, comment, mentioned_user_ids, archive).

curl -X DELETE "https://your-instance.qualytics.io/api/anomalies" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    { "id": 12345, "archive": true, "status": "Resolved" },
    { "id": 12346, "archive": true, "status": "Duplicate" },
    { "id": 12347, "archive": false }
  ]'

Timeline and comments

Get the anomaly history

Returns the paginated change log behind the anomaly's Timeline section: status changes, description edits, tag updates, assignee changes, and external ticket links and unlinks. Each entry carries the user who made the change and a timestamp.

Endpoint: GET /api/anomalies/{id}/history

Query parameters:

{
  "items": [
    {
      "changeset": {
        "status": ["Active", "Acknowledged"],
        "assignees": [
          [{ "id": 42, "name": "Alice Lee" }],
          [{ "id": 42, "name": "Alice Lee" }, { "id": 57, "name": "Bob Patel" }]
        ],
        "ticket_link": [
          null,
          {
            "ticket_number": "INC0010001",
            "ticket_url": "https://example.service-now.com/incident.do?sys_id=abc123sys",
            "integration_type": "servicenow"
          }
        ]
      },
      "transaction": {
        "id": 9876,
        "issued_at": "2026-05-15T17:22:08Z",
        "user": { "id": 1, "name": "Alice Lee" }
      },
      "operation": "update"
    }
  ],
  "total": 124,
  "page": 1,
  "size": 50,
  "pages": 3
}

Each changeset field inside items[].changeset is a [before, after] tuple, so you can reconstruct the audit trail offline. The transaction object on each item carries the id, the issued_at timestamp, and the user who made the change. The operation field reports whether the entry is an insert, update, or delete. To load successive windows, increment page until it reaches pages.

Get comments

Returns the comments on an anomaly, newest first, as a plain array rather than a paginated envelope. Replies are returned together with the comment that starts their thread, and a comment that was deleted while it still had replies is returned with an empty message and its mentions cleared.

Endpoint: GET /api/anomalies/{id}/comments

Permission: Reporter team permission on the anomaly's datastore or above.

Query parameters:

Each comment carries the following fields alongside its message and created timestamp:

Post a comment

Endpoint: POST /api/comments

Permission: Viewer team permission on the anomaly's datastore or above.

Body fields:

curl -X POST "https://your-instance.qualytics.io/api/comments" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "anomaly",
    "entity_id": 12345,
    "transaction_id": 9876,
    "message": "Expected during the migration window. @[Alice Lee](42) please confirm.",
    "mentioned_user_ids": [42]
  }'

Use PUT /api/comments/{id} to update a comment (author only) and DELETE /api/comments/{id} to delete it (author, or any user with the Admin role). Deleting a comment that still has replies keeps it as a placeholder so the replies survive; a comment with no replies is removed outright. Deleting the last remaining reply also removes the placeholder it hung from, so placeholders do not pile up in the thread.

The create and update responses carry the comment's message, author, and mentions only; to read entity_type, entity_id, transaction_id, parent_id, or deleted_at back, fetch the comment again through one of the GET endpoints.

Rejected writes come back with a status code that tells you what to correct:

Reading comments on an archived anomaly still works. Only writes are blocked while it stays archived.

The same comment endpoints serve containers, quality checks, and check templates. Container comments are read through GET /api/containers/{id}/comments. A check template is a quality check for commenting purposes, so both quality checks and check templates are read through GET /api/quality-checks/{id}/comments and posted with entity_type: quality_check. Both endpoints accept the same query parameters as the anomaly endpoint above. A check template does not belong to a datastore, so its comments are not gated by team permissions: any user with the Member role can read and post them. The paginated GET /api/comments feed spans every asset type only for users with the Admin role; for everyone else it returns anomaly comments alone.

Source records

Source records are the raw rows from the source data that contributed to a record anomaly. Two formats are available: JSON for inline display and CSV for export.

Get source records as JSON

Endpoint: GET /api/anomalies/{id}/source-record

Query parameters:

Download source records as CSV

Endpoint: GET /api/anomalies/{id}/source-record/download

Streams a CSV file (source_records_<id>.csv). Same query parameters as the JSON endpoint.

Tickets

Manage the link between an anomaly and an external ticket (Jira, ServiceNow). Linking does not call the external system; it just records the association so the UI can render the linked ticket.

List ticket links

Endpoint: GET /api/anomalies/{anomaly_id}/ticket-links

Create a ticket link

Endpoint: POST /api/anomalies/{anomaly_id}/ticket-links

Permission: Manager role + Author team permission on the anomaly's datastore.

Body fields:

curl -X POST "https://your-instance.qualytics.io/api/anomalies/12345/ticket-links" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_id": 3,
    "ticket_id": "abc123sys",
    "ticket_number": "INC0010001",
    "ticket_url": "https://example.service-now.com/incident.do?sys_id=abc123sys",
    "status": "New"
  }'

Delete a ticket link

Endpoint: DELETE /api/anomalies/{anomaly_id}/ticket-links/{link_id}

Permission: Manager role + Author team permission on the anomaly's datastore. Removes the association only; the external ticket is left untouched.