PostGrad
API Reference

List categories for a feed

View as Markdown

Returns the distinct categories present in the specified feed along with entry counts. **Feed scoping:** Pass a feed UUID in `X-PostGrad-Feed`, or omit the header to auto-select your most-populated feed (the chosen feed is reported in the `X-PostGrad-Feed-Auto-Selected` response header).

GET
/categories

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

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/categories"
{
  "data": [
    {
      "category": "ai_architecture",
      "count": 23,
      "description": "string"
    }
  ],
  "pagination": null,
  "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."
  }
}

Get a knowledge entry by ID

Returns a single knowledge entry by its UUID. Requires a feed UUID in the `X-PostGrad-Feed` header — knowledge ids are scoped per feed so `all` is NOT accepted here. Returns 404 if the entry does not exist in the specified feed.

Get knowledge base statistics

Returns high-level statistics about the knowledge base including total entries, number of categories, and last updated timestamp. This is a public endpoint that does not require authentication. Responses are cached for 5 minutes.