PostGrad
API Reference

Get a knowledge entry by ID

View as Markdown

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/{id}

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

Path Parameters

id*string

UUID of the knowledge entry.

Formatuuid

Query Parameters

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

application/json

application/json

curl -X GET "https://postgrad.io/api/v1/knowledge/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{
  "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": 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": "VALIDATION_ERROR",
    "message": "Search query parameter \"q\" is required"
  }
}
{
  "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": "NOT_FOUND",
    "message": "Knowledge entry not found"
  }
}
{
  "data": null,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again later."
  }
}

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.

List categories for a feed

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).