# Quickstart Make and verify the first request > Section: Overview > Last updated: **2026-10-24**. > API version: **v1 (Latest)**. OpenAPI publication: **2026-11-08**. ## Choose your connection This account-based walkthrough is for a developer using a terminal, notebook, or server. You need curl and a BeliefState account with available credits or an included request allowance. For accountless research, x402 offers eighteen data tools at 0.02 USDC per call on Base, including full cases and current/historical briefs. Built-in comparisons cost 0.50 USDC; search costs 1.50 USDC. Check free coverage first, then follow the [accountless x402 quickstart](https://beliefstate.ai/agent-quickstart.md#pay-per-call-with-x402). The steps below use account-based access. Using an AI chat instead? Start with [Agent setup](https://beliefstate.ai/docs/mcp-server) to check your client's availability and connect with OAuth. You don't need to create an API key for that path. Review [access options](https://beliefstate.ai/pricing) for research requests. Successful intelligence requests use your existing allowance or credits; creating a key does not add either. 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 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 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 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](https://beliefstate.ai/docs/api/beliefs), 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](https://beliefstate.ai/docs/api/beliefs) - [Understand evidence and provenance](https://beliefstate.ai/docs/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](https://beliefstate.ai/docs/api/tickers). 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](https://beliefstate.ai/docs/api/brief) - [Read results at a historical cutoff](https://beliefstate.ai/docs/guides/point-in-time) - [Continue through paginated results](https://beliefstate.ai/docs/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.