Quality Events API

The Quality Events API manages quality-related events including deviations, Corrective and Preventive Actions (CAPAs), and audit findings. These events integrate with workflows for approval and tracking.

Quality Event Model

{
  "id": "qe_abc123def456",
  "type": "deviation",
  "number": "DEV-2024-0042",
  "title": "Out-of-specification result for Assay test",
  "description": "Batch 2024-001 of Magnesium Stearate showed assay result of 97.2%, below the specification of 98.0-102.0%.",
  "status": "investigation",
  "priority": "high",
  "classification": "major",
  "category": "laboratory",
  "related_entities": [
    {
      "type": "component",
      "id": "ent_component_456",
      "name": "Magnesium Stearate"
    },
    {
      "type": "supplier",
      "id": "ent_supplier_789",
      "name": "Acme Chemicals GmbH"
    },
    {
      "type": "certificate",
      "id": "cert_xyz123",
      "name": "CoA - Batch 2024-001"
    }
  ],
  "root_cause": {
    "category": "pending",
    "description": null,
    "identified_date": null
  },
  "impact_assessment": {
    "products_affected": ["PRD-001", "PRD-002"],
    "batches_affected": ["2024-001"],
    "patient_impact": "none",
    "regulatory_reportable": false
  },
  "assigned_to": "user_quality_lead",
  "due_date": "2024-02-15",
  "created_at": "2024-01-20T08:30:00Z",
  "updated_at": "2024-01-20T14:00:00Z",
  "created_by": "user_lab_analyst"
}

Event Types

Type	Description
deviation	Departure from approved procedures or specifications
capa	Corrective and Preventive Action
audit_finding	Finding from internal or external audit
complaint	Customer or regulatory complaint
change_request	Change control request

Event Status

Status	Description
draft	Initial creation, not yet submitted
submitted	Submitted for review
investigation	Under investigation
root_cause_identified	Root cause determined
action_planning	Planning corrective actions
implementation	Actions being implemented
verification	Verifying effectiveness
closed	Event closed
rejected	Event rejected or cancelled

Classification

Level	Description
critical	Significant impact on product quality or patient safety
major	Notable deviation requiring investigation
minor	Small deviation with limited impact
observation	Noted for tracking, no immediate action required

List Quality Events

GET /v1/quality-events

Query Parameters

Parameter	Type	Description
type	string	Filter by event type
status	string	Filter by status
priority	string	Filter by priority
classification	string	Filter by classification
category	string	Filter by category
assigned_to	string	Filter by assignee
related_entity_id	string	Filter by related entity
due_before	date	Events due before date
overdue	boolean	Only overdue events

Example Request

curl

curl -X GET "https://api.cohera.io/v1/quality-events?type=deviation&status=investigation&priority=high" \
  -H "Authorization: Bearer YOUR_API_KEY"

Python

response = requests.get(
    "https://api.cohera.io/v1/quality-events",
    params={
        "type": "deviation",
        "status": "investigation",
        "priority": "high"
    },
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

events = response.json()["data"]
for event in events:
    print(f"{event['number']}: {event['title']} - Due: {event['due_date']}")

TypeScript

const params = new URLSearchParams({
  type: "deviation",
  status: "investigation",
  priority: "high",
});

const response = await fetch(
  `https://api.cohera.io/v1/quality-events?${params}`,
  {
    headers: {
      Authorization: `Bearer ${process.env.COHERA_API_KEY}`,
    },
  }
);

const { data: events } = await response.json();
events.forEach((event) => {
  console.log(`${event.number}: ${event.title} - Due: ${event.due_date}`);
});

Create Quality Event

POST /v1/quality-events

Request Body

Field	Type	Required	Description
type	string	Yes	Event type
title	string	Yes	Brief title
description	string	Yes	Detailed description
priority	string	No	Priority level (default: medium)
classification	string	No	Event classification
category	string	No	Event category
related_entities	array	No	Related entity IDs
assigned_to	string	No	Assignee user ID
due_date	date	No	Due date

curl

curl -X POST "https://api.cohera.io/v1/quality-events" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "deviation",
    "title": "Out-of-specification result for Assay test",
    "description": "Batch 2024-001 of Magnesium Stearate showed assay result of 97.2%, below the specification of 98.0-102.0%.",
    "priority": "high",
    "classification": "major",
    "category": "laboratory",
    "related_entities": [
      {"type": "component", "id": "ent_component_456"},
      {"type": "supplier", "id": "ent_supplier_789"},
      {"type": "certificate", "id": "cert_xyz123"}
    ],
    "assigned_to": "user_quality_lead",
    "due_date": "2024-02-15"
  }'

Python

payload = {
    "type": "deviation",
    "title": "Out-of-specification result for Assay test",
    "description": "Batch 2024-001 of Magnesium Stearate showed assay result of 97.2%, below the specification of 98.0-102.0%.",
    "priority": "high",
    "classification": "major",
    "category": "laboratory",
    "related_entities": [
        {"type": "component", "id": "ent_component_456"},
        {"type": "supplier", "id": "ent_supplier_789"},
        {"type": "certificate", "id": "cert_xyz123"}
    ],
    "assigned_to": "user_quality_lead",
    "due_date": "2024-02-15"
}

response = requests.post(
    "https://api.cohera.io/v1/quality-events",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json=payload
)

event = response.json()["data"]
print(f"Created {event['number']}: {event['title']}")

TypeScript

const payload = {
  type: "deviation",
  title: "Out-of-specification result for Assay test",
  description:
    "Batch 2024-001 of Magnesium Stearate showed assay result of 97.2%, below the specification of 98.0-102.0%.",
  priority: "high",
  classification: "major",
  category: "laboratory",
  related_entities: [
    { type: "component", id: "ent_component_456" },
    { type: "supplier", id: "ent_supplier_789" },
    { type: "certificate", id: "cert_xyz123" },
  ],
  assigned_to: "user_quality_lead",
  due_date: "2024-02-15",
};

const response = await fetch("https://api.cohera.io/v1/quality-events", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.COHERA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});

const { data: event } = await response.json();
console.log(`Created ${event.number}: ${event.title}`);

Update Quality Event

PATCH /v1/quality-events/{event_id}

curl

curl -X PATCH "https://api.cohera.io/v1/quality-events/qe_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "root_cause": {
      "category": "supplier_quality",
      "description": "Supplier process variation led to sub-specification material"
    },
    "status": "root_cause_identified"
  }'

Python

response = requests.patch(
    f"https://api.cohera.io/v1/quality-events/{event_id}",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "root_cause": {
            "category": "supplier_quality",
            "description": "Supplier process variation led to sub-specification material"
        },
        "status": "root_cause_identified"
    }
)

TypeScript

const response = await fetch(
  `https://api.cohera.io/v1/quality-events/${eventId}`,
  {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${process.env.COHERA_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      root_cause: {
        category: "supplier_quality",
        description:
          "Supplier process variation led to sub-specification material",
      },
      status: "root_cause_identified",
    }),
  }
);

CAPAs (Corrective and Preventive Actions)

Create CAPA from Deviation

Link a CAPA to an existing deviation.

POST /v1/quality-events/{deviation_id}/capa

curl

curl -X POST "https://api.cohera.io/v1/quality-events/qe_deviation_123/capa" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Implement incoming material testing enhancement",
    "description": "Enhance incoming QC testing for Magnesium Stearate to include additional assay verification",
    "corrective_actions": [
      {
        "description": "Reject affected batch 2024-001",
        "assigned_to": "user_qc_manager",
        "due_date": "2024-01-25"
      },
      {
        "description": "Request supplier investigation report",
        "assigned_to": "user_supplier_qual",
        "due_date": "2024-02-01"
      }
    ],
    "preventive_actions": [
      {
        "description": "Add duplicate assay testing for critical excipients",
        "assigned_to": "user_qc_manager",
        "due_date": "2024-03-01"
      },
      {
        "description": "Review supplier qualification criteria",
        "assigned_to": "user_supplier_qual",
        "due_date": "2024-03-15"
      }
    ],
    "effectiveness_criteria": "No OOS results for Magnesium Stearate in 6 months following implementation"
  }'

Python

capa_payload = {
    "title": "Implement incoming material testing enhancement",
    "description": "Enhance incoming QC testing for Magnesium Stearate",
    "corrective_actions": [
        {
            "description": "Reject affected batch 2024-001",
            "assigned_to": "user_qc_manager",
            "due_date": "2024-01-25"
        },
        {
            "description": "Request supplier investigation report",
            "assigned_to": "user_supplier_qual",
            "due_date": "2024-02-01"
        }
    ],
    "preventive_actions": [
        {
            "description": "Add duplicate assay testing for critical excipients",
            "assigned_to": "user_qc_manager",
            "due_date": "2024-03-01"
        }
    ],
    "effectiveness_criteria": "No OOS results for Magnesium Stearate in 6 months"
}

response = requests.post(
    f"https://api.cohera.io/v1/quality-events/{deviation_id}/capa",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json=capa_payload
)

capa = response.json()["data"]
print(f"Created CAPA: {capa['number']}")

TypeScript

const capaPayload = {
  title: "Implement incoming material testing enhancement",
  description: "Enhance incoming QC testing for Magnesium Stearate",
  corrective_actions: [
    {
      description: "Reject affected batch 2024-001",
      assigned_to: "user_qc_manager",
      due_date: "2024-01-25",
    },
  ],
  preventive_actions: [
    {
      description: "Add duplicate assay testing for critical excipients",
      assigned_to: "user_qc_manager",
      due_date: "2024-03-01",
    },
  ],
  effectiveness_criteria: "No OOS results in 6 months",
};

const response = await fetch(
  `https://api.cohera.io/v1/quality-events/${deviationId}/capa`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.COHERA_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(capaPayload),
  }
);

const { data: capa } = await response.json();
console.log(`Created CAPA: ${capa.number}`);

Update Action Status

Update the status of individual corrective or preventive actions.

PATCH /v1/quality-events/{capa_id}/actions/{action_id}

{
  "status": "completed",
  "completion_date": "2024-01-24",
  "completion_notes": "Batch 2024-001 rejected and quarantined. Supplier notified.",
  "evidence": ["doc_rejection_form_123"]
}

Audit Findings

Create Audit Finding

POST /v1/quality-events

{
  "type": "audit_finding",
  "title": "Incomplete batch record documentation",
  "description": "Batch records for Product X missing operator initials on 3 of 15 steps.",
  "priority": "medium",
  "classification": "minor",
  "category": "documentation",
  "audit_details": {
    "audit_type": "internal",
    "audit_date": "2024-01-18",
    "auditor": "user_internal_auditor",
    "audit_reference": "INT-AUD-2024-005",
    "area": "Manufacturing - Building A"
  },
  "response_due_date": "2024-02-18"
}

Impact Assessment

AI-Powered Impact Analysis

Trigger AI analysis to identify affected products and batches.

POST /v1/quality-events/{event_id}/impact-analysis

curl

curl -X POST "https://api.cohera.io/v1/quality-events/qe_abc123/impact-analysis" \
  -H "Authorization: Bearer YOUR_API_KEY"

Python

response = requests.post(
    f"https://api.cohera.io/v1/quality-events/{event_id}/impact-analysis",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

analysis = response.json()["data"]
print(f"Products affected: {len(analysis['products_affected'])}")
print(f"Batches affected: {len(analysis['batches_affected'])}")

TypeScript

const response = await fetch(
  `https://api.cohera.io/v1/quality-events/${eventId}/impact-analysis`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.COHERA_API_KEY}`,
    },
  }
);

const { data: analysis } = await response.json();
console.log(`Products affected: ${analysis.products_affected.length}`);
console.log(`Batches affected: ${analysis.batches_affected.length}`);

Response

{
  "data": {
    "event_id": "qe_abc123",
    "analysis_timestamp": "2024-01-20T15:00:00Z",
    "products_affected": [
      {
        "id": "ent_product_001",
        "name": "Product Alpha 100mg",
        "impact_level": "direct",
        "reason": "Uses affected component in formulation"
      },
      {
        "id": "ent_product_002",
        "name": "Product Beta 50mg",
        "impact_level": "indirect",
        "reason": "Shares manufacturing equipment"
      }
    ],
    "batches_affected": [
      {
        "batch_number": "2024-001",
        "product": "Product Alpha 100mg",
        "status": "in_production",
        "units": 50000
      }
    ],
    "regulatory_impact": {
      "reportable": false,
      "reason": "No distributed product affected",
      "jurisdictions": []
    },
    "recommended_actions": [
      "Quarantine batch 2024-001 pending investigation",
      "Review all batches using same material lot",
      "Document impact assessment in deviation record"
    ]
  }
}

Note

Impact analysis uses the ontology relationships to trace the full impact chain from affected materials through products and batches.

Quality Metrics

Get Quality Dashboard Data

GET /v1/quality-events/metrics

Query Parameters

Parameter	Type	Description
period	string	Time period: 30d, 90d, 1y
group_by	string	Grouping: type, category, classification

Response

{
  "data": {
    "period": "90d",
    "summary": {
      "total_events": 45,
      "open_events": 12,
      "closed_events": 33,
      "overdue_events": 3,
      "average_closure_days": 18.5
    },
    "by_type": {
      "deviation": {"total": 28, "open": 8},
      "capa": {"total": 12, "open": 4},
      "audit_finding": {"total": 5, "open": 0}
    },
    "by_classification": {
      "critical": 2,
      "major": 15,
      "minor": 23,
      "observation": 5
    },
    "trends": {
      "events_by_week": [
        {"week": "2024-W03", "count": 8},
        {"week": "2024-W04", "count": 5},
        {"week": "2024-W05", "count": 12}
      ]
    }
  }
}