The Knowledge API · Reference

Discover

Map everything a project knows before you query it.

Discover tells you what a project knows before you ask it anything. It lists every source, its sync state, and what it contains — so a caller (human or agent) can make informed decisions about what to search.

Request

bash

GET /projects/:project_id/knowledge/discover

Headers:

Header	Required	Description
`X-API-Key`	One of	Service-level key for server-to-server calls
`Authorization`	One of	`Bearer <jwt>` for user-scoped calls

No request body. No query parameters in the basic form.

Response

json

{
  "project_id": "proj_abc123",
  "sources": [
    {
      "source": "code",
      "status": "indexed",
      "providers": [
        { "provider": "github", "repository": "acme/api", "branch": "main", "last_sync": "2025-12-01T14:22:00Z", "sync_state": "ok" },
        { "provider": "github", "repository": "acme/web", "branch": "main", "last_sync": "2025-12-01T14:18:00Z", "sync_state": "ok" }
      ],
      "entity_count": 4218,
      "searchable": true
    },
    {
      "source": "graph",
      "status": "indexed",
      "providers": [],
      "entity_count": 12450,
      "searchable": true
    },
    {
      "source": "database",
      "status": "indexed",
      "providers": [
        { "provider": "postgresql", "connection": "analytics-prod", "last_sync": "2025-12-01T12:00:00Z", "sync_state": "ok" }
      ],
      "entity_count": 340,
      "searchable": true
    },
    {
      "source": "work_items",
      "status": "indexed",
      "providers": [
        { "provider": "jira", "project_key": "PROJ", "last_sync": "2025-12-01T14:00:00Z", "sync_state": "ok" }
      ],
      "entity_count": 892,
      "searchable": true
    }
  ]
}

Reading the response

status — indexed means the source has been ingested and is searchable. pending means ingestion is in progress. error means the last sync failed — check the provider's sync_state for details.
providers — the external systems feeding this source. Each carries its own sync_state: ok, syncing, error, or stale.
entity_count — how many entities this source contains. Useful for sanity-checking: if you connected a large repo and entity_count is 0, something went wrong.
searchable — whether the source can participate in search queries. A source in pending status may not be searchable yet.

Empty vs broken

A source with status: "indexed" and entity_count: 0 is empty — the ingestion ran but found nothing. A source with status: "error" is broken — the ingestion failed. The distinction matters when debugging: empty means "check what you connected," broken means "check the credential or the provider."

Auth failure

A request with a missing or invalid key returns:

json

{
  "error": "unauthorized",
  "message": "Missing or invalid authentication. Provide X-API-Key or Authorization: Bearer <jwt>."
}

HTTP status: 401.

Next: Search.