Issues API

Manage data quality issues and track resolution.

Endpoints Overview

Method	Endpoint	Description
GET	/issues	List issues
POST	/issues	Create issue
GET	/issues/{id}	Get issue details
PATCH	/issues/{id}	Update issue
DELETE	/issues/{id}	Delete issue
POST	/spaces/{slug}/record-issues/external-sync	Sync externally mastered record issues

---

List Issues

GET /issues

Query Parameters

Parameter	Type	Description
space_id	uuid	Filter by space
product_id	uuid	Filter by product
status	string	open, in_progress, resolved
priority	string	low, medium, high, critical
assignee_id	uuid	Filter by assigned user
page	integer	Page number
size	integer	Items per page

Response

{
  "items": [
    {
      "id": "...",
      "title": "Customer ID nulls increased",
      "description": "Seeing 15% null rate in customer_id column",
      "status": "open",
      "priority": "high",
      "product": {
        "id": "...",
        "name": "Customer Events"
      },
      "assignee": {
        "id": "...",
        "name": "Jane Developer"
      },
      "reporter": {
        "id": "...",
        "name": "Bob Smith"
      },
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-01-15T12:00:00Z"
    }
  ],
  "total": 8,
  "page": 1,
  "size": 20
}

---

Create Issue

POST /issues

Request Body

{
  "title": "Missing transactions for Jan 14",
  "description": "## Summary\n\nNo transaction records loaded for 2026-01-14.\n\n## Impact\n\nDaily revenue reporting is blocked.",
  "priority": "critical",
  "product_id": "product-uuid",
  "space_id": "space-uuid",
  "assignee_id": "user-uuid"
}

Required Fields

Field	Type	Description
title	string	Issue title
space_id	uuid	Space containing the issue

Optional Fields

Field	Type	Description
description	string	Markdown description
priority	string	low, medium, high, critical
product_id	uuid	Related product
assignee_id	uuid	User to assign

---

Update Issue

PATCH /issues/{id}

Status Transitions

{
  "status": "in_progress"
}

Valid statuses: open, in_progress, resolved

Assign User

{
  "assignee_id": "user-uuid"
}

Change Priority

{
  "priority": "critical"
}

---

Issue Comments

List Comments

GET /issues/{id}/comments

Add Comment

POST /issues/{id}/comments

{
  "content": "Identified the root cause - upstream pipeline failed."
}

Response

{
  "id": "...",
  "content": "Identified the root cause...",
  "author": {
    "id": "...",
    "name": "Jane Developer",
    "avatar_url": "..."
  },
  "created_at": "2026-01-15T14:00:00Z"
}

---

Issue History

Audit trail of changes:

GET /issues/{id}/history

{
  "items": [
    {
      "id": "...",
      "action": "status_changed",
      "old_value": "open",
      "new_value": "in_progress",
      "actor": {"id": "...", "name": "Jane Developer"},
      "timestamp": "2026-01-15T14:00:00Z"
    }
  ]
}

---

Link to Alert

Create issue from quality alert:

POST /issues

{
  "title": "Freshness check failed",
  "alert_id": "alert-uuid",
  "product_id": "product-uuid",
  "space_id": "space-uuid",
  "priority": "high"
}

This links the issue to the alert for traceability.

---

Sync External Record Issues

POST /spaces/{slug}/record-issues/external-sync

Synchronize a snapshot of row-level record issues from an external master such as Airflow, a warehouse error table, or a custom validation service.

Request Body

{
  "source_kind": "airflow",
  "source_key": "orders_daily_validation",
  "connector_id": "connector-uuid",
  "auto_resolve_missing": true,
  "records": [
    {
      "product_slug": "orders-daily",
      "primary_key_values": {"order_id": "10042"},
      "external_issue_key": "orders_daily:10042:missing_customer",
      "title": "Missing customer_id",
      "description_markdown": "The order row has no customer_id after enrichment.",
      "severity": "error",
      "status": "open",
      "category": "completeness",
      "metadata": {"rule": "not_null_customer_id"}
    }
  ]
}

Fields

Field	Type	Description
source_kind	string	airflow, error_table, custom, or manual
source_key	string	Stable identifier for the external snapshot source
connector_id	uuid	Optional connector that produced the snapshot
auto_resolve_missing	boolean	Resolve previously synced issues missing from this snapshot
records[].product_id	uuid	Product UUID. Use this or product_slug.
records[].product_slug	string	Product slug. Use this or product_id.
records[].primary_key_values	object	Row identity for the affected record
records[].external_issue_key	string	Stable external issue identity
records[].severity	string	info, warning, or error
records[].status	string	open, resolved, or accepted

Response

{
  "status": "success",
  "created_count": 3,
  "updated_count": 12,
  "resolved_count": 2,
  "skipped_count": 0,
  "integration_event_id": null
}

Status aliases from external sources are normalized. For example, active and new become open, while closed and fixed become resolved.