Skip to main content

​
Choose your connection

Choose the path that fits your workflow. The steps below use REST.

Connect an AI

Sign in with OAuth from a supported client. No API key needed.

Use REST

Create a key and make your first belief request.

Check coverage

Find released tickers before a metered request.
For REST, you need curl and a BeliefState account with available credits or an included request allowance. Review access options. Creating a key does not add credit. The status check and public coverage lookup below do not debit credits.

​
Make a request

Create a key and verify access before requesting intelligence.
  1. Open API keys in your account, sign in, and select Create. Name the key for your integration. Workspace admins can create keys; other members need an admin-provided key.
  2. Copy the secret when it appears. Store it as BELIEFSTATE_API_KEY in your server-side secret manager and load that environment variable in your terminal or runtime. The full key is shown once.
  3. Run the status request below. Continue when status is ready and dataMode is live. A valid key alone does not guarantee remaining credit or ticker coverage.
Keep the key out of AI chats, browser bundles, logs, screenshots, and committed files. Automated local agents can use the separate device authorization guide.

​
Read your first belief

Find a released ticker, then request one compact belief: who held the view, what they believed, and when it was observed.
Match the company in your question to a symbol in tickers. Set BELIEFSTATE_TICKER in your terminal to that symbol. If the company is absent, report missing coverage; don’t substitute another company. An empty list means no beliefs are currently released. A 404 or 503 means coverage is unavailable; buying more credit does not resolve that state. Set BELIEFSTATE_REQUEST_ID to a new UUID before each new research request. Keep it unchanged only when retrying that exact request after a timeout or error. Use a new ID when changing the endpoint, ticker, filters, or page. Reusing the ID makes retries count as one logical request.
Prefer a browser? Open the belief API playground, select Try it, enter your key and released ticker, set limit to 1, then select Send. This makes the same metered request; it does not send automatically. Generated reference examples use schema placeholders; inspect the actual response for research data.

​
Verify the result

A useful result contains a belief you can attribute and trace. HTTP 200 alone is not evidence that the response is complete or suitable for your research.
  • Read data.beliefs[0] for the person, thesis, direction, and observation time. An empty list means no matching released belief. Check the requested ticker and filters; report the coverage gap if no relevant records are available.
  • Check data_status.mode, data_status.freshness, data_status.coverage, and warnings. Preview data is for testing; preserve any stale, partial, or insufficient coverage labels.
  • Follow the belief’s detail_url with the same Bearer header for full claims, revisions, and citations. This is another metered read. Keep citation IDs attached to the claims they support.
  • Treat missing confidence, horizon, or outcomes as unknown. Save as_of with the response so later research retains its observation cutoff.
  • Inspect belief fields and detail responses
  • Understand evidence and provenance

​
Next steps

Recover from the first failed request, then expand your query.

​
Agent feedback

Report unclear, stale, or incorrect documentation through BeliefState support. Include this page URL and the smallest reproducible detail. Last updated: 2026-09-26 · API version: v1 (Latest) · OpenAPI publication: 2026-09-13.