Postman

Open the SpecStream workspace on Postman (opens in a new tab) and fork the SpecStream collection into a workspace of your own.

The OpenAPI spec for the same API sits beside the collection. The collection's baseUrl variable already points at https://api.specstream.ai.

In the SpecStream workspace, open Agents & API, choose the API keys tab, and click Create API key. Label the key Postman.

Tick every permission except Read projects and Manage projects and members. Ticking Authorize paid work adds a Total spending limit field. Click Set a total limit and enter the most this key may spend in total.

Set Expires after, days to cover the time you plan to use the key, from 1 to 365. Click Create API key and copy the key. SpecStream shows it once.

In Postman, open the forked collection's Variables tab and paste the key into the current value of api_key. The collection sends that value as a Bearer token with every request. You don't set up authorization on each one.

Postman keeps a current value on your machine and doesn't sync it to the workspace.

In the Plans & billing folder, send Read available work balance. A response with your balance means the key works.

Read account permissions and spending limits shows what the key may do and how much of its spending limit remains.

In the Requests folder, open Read a natural-language request and write what you want in the body's q field. Reading a request starts no paid work.

The response has read_back, which is your request in plain words, and ast_hash. Copy ast_hash into the collection variable of the same name.

{
  "q": "Independent bookstores in Portland, Oregon, with their website and phone number",
  "locale": "en-US"
}

In Plans & billing, send Get a price before work starts. Its body uses {{ast_hash}} and asks for 25 results. minimum_units is the fewest results worth delivering, and below it nothing is charged. Change either number to fit.

The response has quote_id, quote_hash, maximum_cents, and expires_at. Copy quote_id and quote_hash into the variables of the same names. A price stays open for 30 minutes.

{
  "ast_hash": "{{ast_hash}}",
  "operation": "find",
  "requested_units": 25,
  "minimum_units": 5
}

Open Approve a price and start work. In the body, change confirm_max_cents from 0 to the maximum_cents from the price. Replace the placeholder idempotency_key with a value of your own, 8 to 128 characters long.

Send it. The response names the find in find_id. SpecStream holds the approved maximum from your balance while the work runs and charges only for the results that match.

{
  "quote_id": "{{quote_id}}",
  "quote_hash": "{{quote_hash}}",
  "confirm_max_cents": 250,
  "idempotency_key": "postman-bookstores-001"
}

In the Results folder, set the path variable id to your find_id on the request's Params tab. Read find status shows progress. Read results and possible matches returns the results, each value with the page it was read from.

Possible matches come back apart from rows and are never billed. Read finished results and sources returns the finished results with the pages behind them, and Export results returns a one-use download link.