Bot Quickstart

This guide shows the full flow for pointing an AI agent at PostGrad: create a key, discover which feeds you can access, query them, and handle the common errors.

If you are building for Claude Desktop, Cursor, or Windsurf, skip to the MCP Integration guide instead — it is one JSON paste and done.

1. Get an API key

1. Sign up at postgrad.io and subscribe to a plan
2. Go to Dashboard → API Keys
3. Click Create New Key, copy it immediately (shown only once)

Keys look like pg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx. Send them in the Authorization: Bearer ... header.

2. List your subscribed feeds

Knowledge requests are feed-scoped via the X-PostGrad-Feed header. The header accepts a feed UUID, the string all to search across every feed you own, or can be omitted on search endpoints to auto-select your most-populated feed. To find your feed ids:

curl https://postgrad.io/api/v1/feeds \
  -H "Authorization: Bearer pg_live_xxxxxxxx"

Response:

{
  "data": [
    {
      "id": "b1a2c3d4-e5f6-7890-abcd-ef0123456789",
      "slug": "business-strategy",
      "name": "Business Strategy",
      "description": "Curated frameworks for...",
      "categories": ["business", "operations"],
      "licensor_name": "Example Co",
      "entry_count": 247,
      "subscription_status": "active",
      "subscribed_at": "2026-01-15T14:22:00Z"
    }
  ],
  "meta": { "total": 1 },
  "error": null
}

This endpoint is authenticated but does not require the X-PostGrad-Feed header — it is the discovery endpoint.

3. Query a feed

Pick a feed id from the list and query it:

curl https://postgrad.io/api/v1/knowledge \
  -H "Authorization: Bearer pg_live_xxxxxxxx" \
  -H "X-PostGrad-Feed: b1a2c3d4-e5f6-7890-abcd-ef0123456789"

Search one feed:

curl "https://postgrad.io/api/v1/knowledge/search?q=pricing%20strategy" \
  -H "Authorization: Bearer pg_live_xxxxxxxx" \
  -H "X-PostGrad-Feed: b1a2c3d4-e5f6-7890-abcd-ef0123456789"

Search across all your feeds at once (merged, relevance-ranked, one quota charge):

curl "https://postgrad.io/api/v1/knowledge/search?q=pricing%20strategy" \
  -H "Authorization: Bearer pg_live_xxxxxxxx" \
  -H "X-PostGrad-Feed: all"

Let PostGrad pick a feed for you (response header X-PostGrad-Feed-Auto-Selected tells you which one):

curl "https://postgrad.io/api/v1/knowledge/search?q=pricing%20strategy" \
  -H "Authorization: Bearer pg_live_xxxxxxxx"

On /knowledge (list) and /knowledge/:id (fetch by id), the X-PostGrad-Feed header is required — those paths have pagination and identity semantics that need a scoped feed.

4. Handle errors

Every error returns JSON in the shape { "data": null, "error": { code, message, details? } }.

Rate limit responses always include a Retry-After header. Respect it.

5. Use an SDK instead

The SDKs handle auth headers, retries on 429, and feed routing.

TypeScript / JavaScript:

npm install postgrad

import { PostGrad } from 'postgrad'

const client = new PostGrad({
  apiKey: process.env.POSTGRAD_API_KEY,
  defaultFeed: 'b1a2c3d4-e5f6-7890-abcd-ef0123456789',
})

const results = await client.knowledge.search({ q: 'pricing strategy' })

Python:

pip install postgrad

from postgrad import PostGrad

client = PostGrad(
    api_key=os.environ["POSTGRAD_API_KEY"],
    default_feed="b1a2c3d4-e5f6-7890-abcd-ef0123456789",
)

results = client.knowledge.search(q="pricing strategy")

Both SDKs let you override defaultFeed per call, so a single client can query multiple feeds. See the TypeScript SDK and Python SDK reference for the full surface.

6. Or use MCP

If your agent runs in Claude Desktop, Cursor, or Windsurf, the MCP Integration guide gets you running with a single JSON config entry. The MCP server exposes search_knowledge, list_feeds, and four other tools — no REST code required.