PostGrad
API Reference

Search knowledge entries

View as Markdown

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.

GET
/knowledge/search

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

q*string

Search query string. Required.

Length1 <= length
categories?string

Comma-separated list of categories to filter search results.

mode?string

Retrieval mode. keyword (tsvector) is available on every tier; semantic (pgvector) requires Pro+; hybrid (RRF fusion) requires Scale. Requesting a tier-blocked mode returns 403 TIER_INSUFFICIENT with a retry hint.

Default"keyword"
Value in"keyword" | "semantic" | "hybrid"
confidence_min?number

Minimum confidence (0-1). Applied by semantic + hybrid modes.

Range0 <= value <= 1
limit?integer

Maximum number of results to return.

Default5
Range1 <= value <= 50
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

curl -X GET "https://postgrad.io/api/v1/knowledge/search?q=string&categories=ai_architecture%2Ctech_stack"
{
  "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": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again later."
  }
}

List knowledge entries

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