Cookbook: An Agent Scoped to One Collection

Updated October 15, 2026

You want an agent, or a product feature built on one, to answer only from one licensed collection, such as one publisher's medical titles.

You can do this two ways:

  1. Use an all-purpose key and pass collection=<id> on every request.
  2. Give the agent its own API key scoped to that one collection.

Use option 2. A filter only works if every request sends it. Agents build their own requests, and one that leaves the filter off, or a new tool that never had it, searches everything the key can reach. A key scoped to a collection limits every request it makes, server-side, whatever the request says.

1. Find the collection ID

With an existing key:

curl "https://cashmere.io/api/v2/collections?search=medicine" \
  -H "Authorization: Bearer YOUR_API_KEY"

Each item in items has an id and a name.

2. Create the scoped key

Keys are created in the console, at Settings > API Keys (step by step: Creating an API Key). For this agent:

  • Name: something that identifies the agent, e.g. support-bot-medicine
  • Scope API Key to Collections: select only the one collection
  • Access Type: Read Only, if the agent only searches and reads. A read-only key is refused any method other than GET, HEAD and OPTIONS.
  • Tokens Limit (optional): caps how much the key can consume
  • Allowed Endpoints (optional, under Advanced access management): restricts which API areas the key can call. Leave it empty for all of them, or tick Search and Omnipub for a search-and-read agent. (The MCP server hides tools whose endpoint the key can't reach.)

3. What the scope does

With the key scoped to one collection:

  • /search returns results only from that collection. A collection filter can narrow results within the scope but can't widen it. Asking for a collection outside the scope returns no results from it.
  • /omnipubs lists only publications in that collection.
  • Reading a licensed publication outside the scope (GET /omnipub/{uuid} and its section endpoints) returns 404. Publications your own organization published stay readable by ID.
  • On MCP, the tool descriptions list only that collection, so the model sees the right scope too.

The key reaches content only while your organization's license covers it. If the license ends, the key stops returning that content.

Check what a key can do at any time:

curl "https://cashmere.io/api/v2/allowed-endpoints" \
  -H "Authorization: Bearer AGENT_API_KEY"

This returns unrestricted, allowed_endpoints, write_allowed and key_type. Any key can call it, even one with an endpoint allowlist.

4. Use it

Searches need no filter:

curl "https://cashmere.io/api/v2/search?q=first-line+treatment+for+hypertension" \
  -H "Authorization: Bearer AGENT_API_KEY"

For an MCP client, put the scoped key in the server URL (setup: Connecting MCP to Claude, Connecting MCP to ChatGPT):

https://mcp.cashmere.io?api_key=AGENT_API_KEY

Several agents, several scopes

Make one key per agent or per scope, not one shared key with per-request filters. Each key then shows up separately in usage reporting, and you can revoke one without touching the others.

If one key does need several collections, select them all on the key. To narrow a single request further, repeat collection (?collection=12&collection=34).