Entities

GET /v1/entities

List entities for a tenant, optionally filtered by type.

Request

GET /v1/entities?tenant_id=my-app&type=technology&limit=20&offset=0
Authorization: Bearer <api-key>

| Parameter | Type | Required | Description | |---|---|---|---| | tenant_id | string | Yes | Tenant identifier | | namespace | string | No | Scope to namespace | | type | string | No | Filter by entity type | | limit | integer | No | Max results (default: 100) | | offset | integer | No | Pagination offset |

Response (200 OK)

{
  "entities": [
    {
      "id": "ent_001",
      "name": "CockroachDB",
      "type": "technology",
      "mention_count": 14,
      "first_seen": "2026-02-15T00:00:00Z",
      "last_seen": "2026-03-15T10:00:00Z"
    },
    {
      "id": "ent_003",
      "name": "PostgreSQL",
      "type": "technology",
      "mention_count": 22,
      "first_seen": "2026-01-05T00:00:00Z",
      "last_seen": "2026-03-10T14:00:00Z"
    }
  ],
  "total": 2,
  "limit": 20,
  "offset": 0
}

Example

curl https://api.cortexdb.io/v1/entities \
  -H "Authorization: Bearer your-api-key" \
  -G -d "tenant_id=my-app" -d "type=technology" -d "limit=20"

---

GET /v1/entities/:id

Get a specific entity with its relationships.

Request

GET /v1/entities/ent_001?tenant_id=my-app
Authorization: Bearer <api-key>

Response (200 OK)

{
  "id": "ent_001",
  "name": "CockroachDB",
  "type": "technology",
  "aliases": ["CRDB", "cockroach"],
  "mention_count": 14,
  "first_seen": "2026-02-15T00:00:00Z",
  "last_seen": "2026-03-15T10:00:00Z",
  "relationships": [
    {
      "type": "used_by",
      "target": {
        "id": "ent_002",
        "name": "payments service",
        "type": "service"
      },
      "confidence": 0.95,
      "evidence_count": 5,
      "first_seen": "2026-03-10T00:00:00Z",
      "last_seen": "2026-03-15T10:00:00Z"
    },
    {
      "type": "replaced",
      "target": {
        "id": "ent_003",
        "name": "PostgreSQL",
        "type": "technology"
      },
      "confidence": 0.92,
      "evidence_count": 3,
      "first_seen": "2026-03-10T00:00:00Z"
    }
  ],
  "episodes": [
    {
      "id": "ep_a1b2c3d4",
      "content": "Chose CockroachDB for the payments service.",
      "episode_type": "decision",
      "timestamp": "2026-03-15T10:00:00Z"
    }
  ]
}

Example

curl https://api.cortexdb.io/v1/entities/ent_001 \
  -H "Authorization: Bearer your-api-key" \
  -G -d "tenant_id=my-app"