Entities API

Entities are the core building blocks of the Cohera ontology. They represent objects in your pharmaceutical data model such as suppliers, components, products, and certificates.

Entity Model

Every entity has the following structure:

{
  "id": "ent_abc123def456",
  "type": "supplier",
  "name": "Acme Chemicals GmbH",
  "attributes": {
    "country": "DE",
    "qualification_status": "qualified",
    "primary_contact": "supplier@acme-chemicals.de",
    "risk_level": "low"
  },
  "relationships": [
    {
      "type": "supplies",
      "target_id": "ent_component_789",
      "attributes": {
        "primary_supplier": true
      }
    }
  ],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T14:45:00Z",
  "created_by": "user_xyz789",
  "version": 3
}

Entity Types

Type	Description
supplier	Material or service suppliers
component	Raw materials, excipients, packaging
product	Finished pharmaceutical products
certificate	CoA, CoC, GMP certificates
equipment	Manufacturing equipment
facility	Manufacturing sites
document	Controlled documents

List Entities

Retrieve a paginated list of entities.

GET /v1/entities

Query Parameters

Parameter	Type	Description
type	string	Filter by entity type
name	string	Filter by name (partial match)
attributes.*	string	Filter by attribute value
created_after	datetime	Filter by creation date
created_before	datetime	Filter by creation date
updated_after	datetime	Filter by update date
page	integer	Page number (default: 1)
per_page	integer	Items per page (default: 25, max: 100)
sort	string	Sort field (prefix with - for descending)

Example Request

curl

curl -X GET "https://api.cohera.io/v1/entities?type=supplier&attributes.country=DE&per_page=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Python

import requests

response = requests.get(
    "https://api.cohera.io/v1/entities",
    params={
        "type": "supplier",
        "attributes.country": "DE",
        "per_page": 10
    },
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

entities = response.json()["data"]
for entity in entities:
    print(f"{entity['name']} - {entity['attributes']['qualification_status']}")

TypeScript

const params = new URLSearchParams({
  type: "supplier",
  "attributes.country": "DE",
  per_page: "10",
});

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

const { data: entities } = await response.json();
entities.forEach((entity) => {
  console.log(`${entity.name} - ${entity.attributes.qualification_status}`);
});

Response

{
  "data": [
    {
      "id": "ent_abc123",
      "type": "supplier",
      "name": "Acme Chemicals GmbH",
      "attributes": {
        "country": "DE",
        "qualification_status": "qualified"
      },
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "total": 45,
    "page": 1,
    "per_page": 10,
    "total_pages": 5
  }
}

Get Entity

Retrieve a single entity by ID.

GET /v1/entities/{entity_id}

Path Parameters

Parameter	Type	Description
entity_id	string	The entity ID

Query Parameters

Parameter	Type	Description
include	string	Comma-separated list of relationships to include

Example Request

curl

curl -X GET "https://api.cohera.io/v1/entities/ent_abc123?include=relationships" \
  -H "Authorization: Bearer YOUR_API_KEY"

Python

entity_id = "ent_abc123"

response = requests.get(
    f"https://api.cohera.io/v1/entities/{entity_id}",
    params={"include": "relationships"},
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

entity = response.json()["data"]
print(f"Entity: {entity['name']}")
print(f"Relationships: {len(entity.get('relationships', []))}")

TypeScript

const entityId = "ent_abc123";

const response = await fetch(
  `https://api.cohera.io/v1/entities/${entityId}?include=relationships`,
  {
    headers: {
      Authorization: `Bearer ${process.env.COHERA_API_KEY}`,
    },
  }
);

const { data: entity } = await response.json();
console.log(`Entity: ${entity.name}`);
console.log(`Relationships: ${entity.relationships?.length ?? 0}`);

Response

{
  "data": {
    "id": "ent_abc123",
    "type": "supplier",
    "name": "Acme Chemicals GmbH",
    "attributes": {
      "country": "DE",
      "qualification_status": "qualified",
      "primary_contact": "supplier@acme-chemicals.de"
    },
    "relationships": [
      {
        "type": "supplies",
        "target_id": "ent_component_789",
        "target_name": "Magnesium Stearate",
        "attributes": {
          "primary_supplier": true
        }
      }
    ],
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T14:45:00Z",
    "created_by": "user_xyz789",
    "version": 3
  }
}

Create Entity

Create a new entity.

POST /v1/entities

Request Body

Field	Type	Required	Description
type	string	Yes	Entity type
name	string	Yes	Display name
attributes	object	No	Type-specific attributes
relationships	array	No	Initial relationships

Example Request

curl

curl -X POST "https://api.cohera.io/v1/entities" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-supplier-$(date +%s)" \
  -d '{
    "type": "supplier",
    "name": "PharmaChem Industries",
    "attributes": {
      "country": "US",
      "qualification_status": "pending",
      "primary_contact": "quality@pharmachem.com",
      "risk_level": "medium",
      "supplier_code": "SUP-2024-001"
    }
  }'

Python

import requests
import uuid

payload = {
    "type": "supplier",
    "name": "PharmaChem Industries",
    "attributes": {
        "country": "US",
        "qualification_status": "pending",
        "primary_contact": "quality@pharmachem.com",
        "risk_level": "medium",
        "supplier_code": "SUP-2024-001"
    }
}

response = requests.post(
    "https://api.cohera.io/v1/entities",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4())
    },
    json=payload
)

if response.status_code == 201:
    entity = response.json()["data"]
    print(f"Created entity: {entity['id']}")
else:
    print(f"Error: {response.json()['error']['message']}")

TypeScript

import { randomUUID } from "crypto";

const payload = {
  type: "supplier",
  name: "PharmaChem Industries",
  attributes: {
    country: "US",
    qualification_status: "pending",
    primary_contact: "quality@pharmachem.com",
    risk_level: "medium",
    supplier_code: "SUP-2024-001",
  },
};

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

if (response.status === 201) {
  const { data: entity } = await response.json();
  console.log(`Created entity: ${entity.id}`);
} else {
  const { error } = await response.json();
  console.error(`Error: ${error.message}`);
}

Response

{
  "data": {
    "id": "ent_def456ghi789",
    "type": "supplier",
    "name": "PharmaChem Industries",
    "attributes": {
      "country": "US",
      "qualification_status": "pending",
      "primary_contact": "quality@pharmachem.com",
      "risk_level": "medium",
      "supplier_code": "SUP-2024-001"
    },
    "relationships": [],
    "created_at": "2024-01-20T09:15:00Z",
    "updated_at": "2024-01-20T09:15:00Z",
    "created_by": "user_abc123",
    "version": 1
  }
}

Update Entity

Update an existing entity. Supports partial updates.

PATCH /v1/entities/{entity_id}

Path Parameters

Parameter	Type	Description
entity_id	string	The entity ID

Request Body

Include only the fields you want to update:

Field	Type	Description
name	string	Display name
attributes	object	Attributes to update (merged with existing)

Note

Attribute updates are merged with existing attributes. To remove an attribute, set its value to null.

Example Request

curl

curl -X PATCH "https://api.cohera.io/v1/entities/ent_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "attributes": {
      "qualification_status": "qualified",
      "qualification_date": "2024-01-20",
      "risk_level": "low"
    }
  }'

Python

entity_id = "ent_abc123"

updates = {
    "attributes": {
        "qualification_status": "qualified",
        "qualification_date": "2024-01-20",
        "risk_level": "low"
    }
}

response = requests.patch(
    f"https://api.cohera.io/v1/entities/{entity_id}",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json=updates
)

entity = response.json()["data"]
print(f"Updated version: {entity['version']}")

TypeScript

const entityId = "ent_abc123";

const updates = {
  attributes: {
    qualification_status: "qualified",
    qualification_date: "2024-01-20",
    risk_level: "low",
  },
};

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

const { data: entity } = await response.json();
console.log(`Updated version: ${entity.version}`);

Response

{
  "data": {
    "id": "ent_abc123",
    "type": "supplier",
    "name": "Acme Chemicals GmbH",
    "attributes": {
      "country": "DE",
      "qualification_status": "qualified",
      "qualification_date": "2024-01-20",
      "primary_contact": "supplier@acme-chemicals.de",
      "risk_level": "low"
    },
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-20T11:30:00Z",
    "created_by": "user_xyz789",
    "version": 4
  }
}

Delete Entity

Delete an entity. This is a soft delete by default.

DELETE /v1/entities/{entity_id}

Caution

Deleting an entity does not delete related entities. Relationships pointing to this entity will become orphaned.

Path Parameters

Parameter	Type	Description
entity_id	string	The entity ID

Query Parameters

Parameter	Type	Description
hard	boolean	Permanently delete (default: false)

Example Request

curl

curl -X DELETE "https://api.cohera.io/v1/entities/ent_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Python

entity_id = "ent_abc123"

response = requests.delete(
    f"https://api.cohera.io/v1/entities/{entity_id}",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

if response.status_code == 204:
    print("Entity deleted successfully")

TypeScript

const entityId = "ent_abc123";

const response = await fetch(
  `https://api.cohera.io/v1/entities/${entityId}`,
  {
    method: "DELETE",
    headers: {
      Authorization: `Bearer ${process.env.COHERA_API_KEY}`,
    },
  }
);

if (response.status === 204) {
  console.log("Entity deleted successfully");
}

Response

Returns 204 No Content on success.

Manage Relationships

Add Relationship

POST /v1/entities/{entity_id}/relationships

Request Body

Field	Type	Required	Description
type	string	Yes	Relationship type
target_id	string	Yes	Target entity ID
attributes	object	No	Relationship attributes

Example

curl

curl -X POST "https://api.cohera.io/v1/entities/ent_supplier_123/relationships" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "supplies",
    "target_id": "ent_component_456",
    "attributes": {
      "primary_supplier": true,
      "lead_time_days": 14
    }
  }'

Python

response = requests.post(
    "https://api.cohera.io/v1/entities/ent_supplier_123/relationships",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "type": "supplies",
        "target_id": "ent_component_456",
        "attributes": {
            "primary_supplier": True,
            "lead_time_days": 14
        }
    }
)

TypeScript

const response = await fetch(
  "https://api.cohera.io/v1/entities/ent_supplier_123/relationships",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.COHERA_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      type: "supplies",
      target_id: "ent_component_456",
      attributes: {
        primary_supplier: true,
        lead_time_days: 14,
      },
    }),
  }
);

Remove Relationship

DELETE /v1/entities/{entity_id}/relationships/{relationship_id}

Entity History

Retrieve the version history of an entity.

GET /v1/entities/{entity_id}/history

Response

{
  "data": [
    {
      "version": 3,
      "changes": {
        "attributes.qualification_status": {
          "from": "pending",
          "to": "qualified"
        }
      },
      "changed_at": "2024-01-20T11:30:00Z",
      "changed_by": "user_abc123"
    },
    {
      "version": 2,
      "changes": {
        "attributes.risk_level": {
          "from": "high",
          "to": "medium"
        }
      },
      "changed_at": "2024-01-18T09:00:00Z",
      "changed_by": "user_def456"
    }
  ]
}

Bulk Operations

Bulk Create

Create multiple entities in a single request.

POST /v1/entities/bulk

{
  "entities": [
    {"type": "supplier", "name": "Supplier A", "attributes": {...}},
    {"type": "supplier", "name": "Supplier B", "attributes": {...}}
  ]
}

Bulk Update

Update multiple entities.

PATCH /v1/entities/bulk

{
  "updates": [
    {"id": "ent_abc123", "attributes": {"risk_level": "low"}},
    {"id": "ent_def456", "attributes": {"risk_level": "medium"}}
  ]
}

Note

Bulk operations are atomic. If any entity fails validation, the entire operation is rolled back.