REST API

Use the same search, enrichment, saved work, and balance as the workspace.

Base URL: https://api.specstream.ai

Authentication

Create an API key in your workspace settings. Send it in the Authorization header as a Bearer token. Keep the key on the server or in a local environment variable.

export SPECSTREAM_API_KEY="your-api-key"

curl https://api.specstream.ai/v1/capacity/catalog \
  -H "Authorization: Bearer $SPECSTREAM_API_KEY" \
  -H "Accept: application/json"

The public catalog returns the current free balance, top-up rules, and monthly plans. It doesn’t start any work.

Interpret a request

Send what you want to find in everyday language in the q field. Include conditions, exclusions, and the details you want returned.

curl https://api.specstream.ai/v1/parse \
  -H "Authorization: Bearer $SPECSTREAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"Find software companies in Germany with 50 to 500 employees that are hiring salespeople","locale":"en-US"}'

This interprets the request. Review the returned structure before requesting a quote. Use GET /v1/spec-options/{target} to inspect the available fields and operators for a record type.

Quoting and authorization

New research requires a quote for the exact request revision and operation. Authorization includes the quote identifier, signature, approved maximum, and a stable request key.

Keep the request key for retries. If a response is uncertain, recover the original request instead of starting a second purchase. Expired quotes or changed scope need a new review.

Follow a find as it runs

Poll GET /v1/finds/{id}/events. Progress events carry the phase, how many results were found, checked and matched so far, the target, and how many sources and pages the engine has read. Row events carry the matches so far: each poll returns the current set, with any changed facts, so replace your list every time.

When the find finishes, GET /v1/finds/{id}/rows returns the delivered results. Beside rows, possible lists results with some conditions still open, each with its reasons and sources. Possible matches are free: they’re never billed, never counted in totals and never carry contacts.

Decisions you can check

Every condition gets an answer. A model reads the request and each result’s sources and answers every condition with a short reason; code checks typed facts such as numbers, dates and places, and confirms each quote is on the page it cites. A result with a quote for every condition is marked Verified and listed first. Records are resolved on stable identifiers, and every delivered result keeps a content-addressed decision receipt.

Read the decisions behind a find with GET /v1/finds/{id}/decisions and replay them with GET /v1/finds/{id}/decisions/replay. A replay rechecks the recorded rules, AI answers and quotes against the saved evidence and checks the receipt hashes. It makes no source or model calls and costs nothing.

Endpoint reference

Operations cover request revisions, follow-up work, sources, projects and members, snapshots, exports, reusable request links, schedules, and spending controls.

The OpenAPI schema describes the request and response types, supported operations, and required fields. The clients use the same contracts.

Use the Python or TypeScript client →

Use a signed completion webhook to notify your application when a find finishes.

Permissions

API keys and delegated access stay inside their project permissions, scope, and spending limits. Having balance doesn’t give a key permission to run any work it likes.