---
title: Bot Quickstart
description: Get an AI agent querying PostGrad knowledge feeds in under five minutes.
---

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](/docs/mcp-integration) guide instead — it is one JSON paste and done.

## 1. Get an API key

1. Sign up at [postgrad.io](https://postgrad.io) and subscribe to a plan
2. Go to [Dashboard → API Keys](https://postgrad.io/dashboard/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:

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

Response:

```json
{
  "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:

```bash
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:

```bash
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):

```bash
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):

```bash
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? } }`.

| Status | Code | What to do |
|---|---|---|
| 401 | `UNAUTHORIZED` | Invalid or missing `Authorization` header |
| 400 | `INVALID_FEED` | Malformed `X-PostGrad-Feed` (expected UUID, `all`, or omitted on search). Call `GET /api/v1/feeds` for valid ids. |
| 403 | `FEED_NOT_SUBSCRIBED` | You passed a feed id you don't own — check `/api/v1/feeds` |
| 403 | `SUBSCRIPTION_INACTIVE` | Your PostGrad plan lapsed — reactivate at `/dashboard/settings?tab=billing` |
| 429 | `RATE_LIMIT_EXCEEDED` | Check `Retry-After` header for seconds to wait |

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:**

```bash
npm install postgrad
```

```ts
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:**

```bash
pip install postgrad
```

```python
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](/docs/sdks/typescript) and [Python SDK](/docs/sdks/python) reference for the full surface.

## 6. Or use MCP

If your agent runs in Claude Desktop, Cursor, or Windsurf, the [MCP Integration](/docs/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.