PostGrad
API Reference

List knowledge entries

View as Markdown

Returns paginated knowledge entries from a specific feed, with optional filtering by category, search query, confidence threshold, and date. Results are ordered by most recently updated. **Feed scoping:** This endpoint requires a feed UUID in the `X-PostGrad-Feed` header — pagination and ordering need a single scoped feed. Call `GET /api/v1/feeds` to list the feeds you are subscribed to. `all` is NOT accepted here; use `/knowledge/search?feed=all` for cross-feed queries.

GET
/knowledge

Authorization

AuthorizationBearer <token>

API key passed as Bearer token. Keys use the pg_live_ prefix for production and pg_test_ for test environments.

In: header

Query Parameters

category?string

Filter entries by knowledge category. Categories are licensor-defined per feed -- there is no closed enum. Call GET /api/v1/categories with the feed id to discover the categories actually populated on a given feed.

search?string

Full-text search query to filter entries. q is accepted as an alias.

q?string

Alias for search. Either spelling is accepted.

confidence_min?number

Minimum confidence score (0 to 1). Only entries at or above this threshold are returned.

Range0 <= value <= 1
since?string

ISO 8601 date-time. Only entries updated after this timestamp are returned.

Formatdate-time
limit?integer

Maximum number of entries to return.

Default5
Range1 <= value <= 50
offset?integer

Number of entries to skip for pagination.

Default0
Range0 <= value
verbosity?string

Entry shape. full (default for REST) includes created_at, updated_at, and raw_score. compact drops them — useful for LLM consumers that pay per token. The MCP search_knowledge tool defaults to compact.

Default"full"
Value in"compact" | "full"

Header Parameters

X-PostGrad-Feed?string

Which feed(s) the request should query. Three accepted values:

  • A feed UUID — scopes the request to that one feed.
  • all — (search endpoints only) fans out across every subscribed feed with published content, merges results, ranks by relevance. Counts as one request against your monthly quota. Max 10 feeds per fan-out; X-PostGrad-Feeds-Truncated response header reports any overage.
  • Omitted — on search endpoints, PostGrad auto-selects your most-populated feed and reports the choice via the X-PostGrad-Feed-Auto-Selected response header. On list (/knowledge) and fetch-by-id (/knowledge/:id) endpoints, a UUID is required.

Legacy compatibility: the feed id is also accepted as a ?feed_id=<uuid> query parameter or {"feed_id":"<uuid>"} JSON body field. Both paths return a Warning: 299 postgrad response header asking you to migrate to this header.

Call GET /api/v1/feeds to discover the feed ids you have access to.

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://postgrad.io/api/v1/knowledge"
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "feed_id": "9369c69c-ec8e-4e41-ac71-b17373635837",
      "feed_name": "string",
      "feed_slug": "string",
      "title": "AI agent architecture uses RAG with vector embeddings",
      "category": "ai_architecture",
      "tags": [
        "rag",
        "vector-embeddings",
        "supabase"
      ],
      "content": "string",
      "confidence": 1,
      "score": 1,
      "permalink": "https://postgrad.io/dashboard/marketplace/agency-growth/entries/550e8400-e29b-41d4-a716-446655440000",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "raw_score": 0
    }
  ],
  "pagination": {
    "total": 142,
    "limit": 5,
    "offset": 0,
    "has_more": true
  },
  "usage": {
    "queries_used": 42,
    "queries_limit": 1000,
    "queries_remaining": 958,
    "period_start": "2026-05-01T00:00:00Z",
    "period_end": "2026-06-01T00:00:00Z",
    "tier": "starter"
  },
  "context": {
    "feed": {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "slug": "string",
      "provider": "string"
    },
    "next_steps": {}
  },
  "error": null
}
{
  "data": null,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}
{
  "data": null,
  "error": {
    "code": "FORBIDDEN",
    "message": "Category 'deal_structure' not included in your starter plan",
    "details": {
      "allowed_categories": [
        "deal_evaluation",
        "ai_architecture",
        "sales_process"
      ]
    }
  }
}
{
  "data": null,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again later."
  }
}

List your subscribed feeds

Returns every feed the authenticated account is actively subscribed to. This is the discovery endpoint bots should call first — every request to `/knowledge` or `/categories` requires a feed id from this list in the `X-PostGrad-Feed` header. No feed header is required to call this endpoint.

Search knowledge entries

Full-text search across knowledge entries, ranked by relevance. The `q` parameter is required. Optionally filter by one or more categories (comma-separated). **Feed scoping** (three modes): - Pass a feed UUID via `X-PostGrad-Feed` to scope to one feed. - Pass `X-PostGrad-Feed: all` (or `?feed=all`) to fan out across every subscribed feed and receive merged, relevance-ranked results. Each hit includes `feed_id` + `feed_name`. Counts as one request against your monthly quota. Max 10 feeds per fan-out; `X-PostGrad-Feeds-Searched` and `X-PostGrad-Feeds-Truncated` response headers report the result. - Omit the header to let PostGrad auto-select your most-populated feed. The `X-PostGrad-Feed-Auto-Selected` response header reports the choice.