Entities API

Entities are the core data objects in QANATIX. Each entity belongs to a vertical and has structured data in vertical_data.

POST /entities

Create a single entity.

curl -X POST https://api.qanatix.com/api/v1/entities \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Stainless Steel Bolt M8x40",
    "vertical": "manufacturing",
    "entity_type": "fastener",
    "vertical_data": {
      "part_number": "SS-M8-40-A2",
      "material": "Stainless Steel A2",
      "price_eur": 0.12,
      "in_stock": true
    }
  }'

Response (201)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Stainless Steel Bolt M8x40",
  "vertical": "manufacturing",
  "entity_type": "fastener",
  "vertical_data": { "..." },
  "embedding_status": "pending",
  "created_at": "2026-03-07T10:00:00Z"
}

The entity is created immediately. Embedding and indexing happen asynchronously via the pipeline.

GET /entities

List entities with cursor-based pagination and optional filtering.

curl "https://api.qanatix.com/api/v1/entities?vertical=manufacturing&limit=10" \
  -H "Authorization: Bearer sk_live_abc123..."

Query parameters

Parameter	Type	Default	Description
`vertical`	string	—	Filter by vertical
`entity_type`	string	—	Filter by entity type
`q`	string	—	Full-text search on name
`status`	string	`active`	`active`, `archived`, or `draft`
`limit`	integer	20	Results per page (1-100)
`cursor`	string	—	Pagination cursor from previous response

Response (200)

{
  "items": [
    {
      "id": "550e8400-...",
      "name": "Stainless Steel Bolt M8x40",
      "vertical": "manufacturing",
      "entity_type": "fastener",
      "embedding_status": "completed",
      "created_at": "2026-03-07T10:00:00Z",
      "updated_at": "2026-03-07T10:05:00Z"
    }
  ],
  "cursor": "eyJpZCI6...",
  "has_more": true
}

GET /entities/{id}

Get a single entity with all fields.

curl https://api.qanatix.com/api/v1/entities/550e8400-... \
  -H "Authorization: Bearer sk_live_abc123..."

Response (200)

Returns the full entity including vertical_data, description_llm, embedding_status, and timestamps.

PATCH /entities/{id}

Update an entity. Only include fields you want to change.

curl -X PATCH https://api.qanatix.com/api/v1/entities/550e8400-... \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "vertical_data": {
      "price_eur": 0.15,
      "in_stock": false
    }
  }'

Updates trigger re-embedding and re-indexing in Qdrant automatically.

Response (200)

Returns the updated entity.

DELETE /entities/{id}

Soft-delete (archive) an entity. Removes it from search results and Qdrant.

curl -X DELETE https://api.qanatix.com/api/v1/entities/550e8400-... \
  -H "Authorization: Bearer sk_live_abc123..."

Response

204 No Content

PATCH /entities/bulk

Bulk update multiple entities.

curl -X PATCH https://api.qanatix.com/api/v1/entities/bulk \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "entity_ids": ["550e8400-...", "660f9500-..."],
    "update": {
      "vertical_data": {
        "in_stock": false
      }
    }
  }'

Response (200)

{
  "updated": 2
}

POST /entities/bulk-delete

Soft-delete multiple entities.

curl -X POST https://api.qanatix.com/api/v1/entities/bulk-delete \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "entity_ids": ["550e8400-...", "660f9500-..."]
  }'

Response (200)

{
  "deleted": 2
}

POST /entities/retry-reset

Reset failed embedding retries. Entities stuck in failed status are reset to pending so the pipeline retries them.

curl -X POST https://api.qanatix.com/api/v1/entities/retry-reset \
  -H "Authorization: Bearer sk_live_abc123..."

Response (200)

{
  "reset": 5
}

Entities API

On this page