> ## Documentation Index > Fetch the complete documentation index at: https://docs.beliefstate.ai/llms.txt > Use this file to discover all available pages before exploring further. # Quick start > Make your first REST request and verify its source evidence. ## Choose your connection Choose the path that fits your workflow. The steps below use REST. Sign in with OAuth from a supported client. No API key needed. Create a key and make your first belief request. 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](https://beliefstate.ai/pricing). 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](https://beliefstate.ai/account#api-keys), 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. ```bash theme={null} curl --fail-with-body \ --header "Authorization: Bearer $BELIEFSTATE_API_KEY" \ "https://beliefstate.ai/v1/status" ``` > Keep the key out of AI chats, browser bundles, logs, screenshots, and committed files. Automated local agents can use the separate [device authorization guide](https://beliefstate.ai/auth.md). ## 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. ```bash theme={null} curl --fail-with-body \ "https://beliefstate.ai/v1/tickers" ``` 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. ```bash theme={null} curl --fail-with-body --get \ --header "Authorization: Bearer $BELIEFSTATE_API_KEY" \ --data-urlencode "ticker=${BELIEFSTATE_TICKER:?Set the requested ticker from current coverage}" \ --data-urlencode "limit=1" \ --header "X-Request-ID: ${BELIEFSTATE_REQUEST_ID:?Set a new UUID for this request; keep it for retries}" \ "https://beliefstate.ai/v1/beliefs" ``` Prefer a browser? Open the [belief API playground](/api-reference/beliefs/find-investor-beliefs-or-inspect-a-full-record), 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](/api-reference/beliefs/find-investor-beliefs-or-inspect-a-full-record) * [Understand evidence and provenance](/concepts/provenance) ## Next steps Recover from the first failed request, then expand your query. * `401`: check the Bearer header and use an active key from [API keys](https://beliefstate.ai/account#api-keys). * `402`: inspect [billing and available credit](https://beliefstate.ai/billing) for the account that owns the key, including spend limits. * `404` or `503`: check [released coverage](/api-reference/tickers/find-tickers-with-available-research). The ticker, record, or service may be unavailable; don't treat this as missing credit. * `429` or a timeout: wait before retrying. Follow Retry-After when present and reuse the same `X-Request-ID` only for the same logical request. * [Get a research brief](/api-reference/brief/get-an-evidence-backed-research-brief-for-a-ticker) * [Read results at a historical cutoff](/guides/point-in-time) * [Continue through paginated results](/guides/pagination) ## Agent feedback Report unclear, stale, or incorrect documentation through [BeliefState support](https://beliefstate.ai/contact). Include this page URL and the smallest reproducible detail. *Last updated: 2026-09-26 · API version: v1 (Latest) · OpenAPI publication: 2026-09-13.* This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.