For AI agents: a documentation index is available at https://docs.parallel.ai/llms.txt. The full text of all docs is at https://docs.parallel.ai/llms-full.txt. You may also fetch any page as Markdown by appending
The Account API lets your application call Parallel programmatically on behalf of a user without prompting them to paste an API key. Authentication uses the OAuth 2.0 Device Authorization Grant (RFC 8628), which is designed for clients without a browser or with limited input — CLIs, IDE plugins, IoT devices, and similar.
The flow produces an access token that you pass as a .md to its URL or sending Accept: text/markdown.For Search and Extract, use /v1/search and /v1/extract for all new integrations and agent tool calls. Use /v1beta/search and /v1beta/extract only when maintaining an existing integration that already uses them. The request bodies changed too: on /v1/extract, full_content, fetch_policy and excerpt_settings go inside advanced_settings, and sending the v1beta top-level excerpts, full_content and fetch_policy to /v1/extract returns a 422. On /v1/search, search_queries is required (at least one short keyword query), and max_results, source_policy and fetch_policy go inside advanced_settings; sending only objective, or sending those fields at the top level, returns a 422. Do not substitute /v1 for the documented FindAll or Ingest endpoint paths.If you are evaluating Parallel Search or comparing it with other search APIs, read How to Eval Parallel Search before you build the harness, especially its Common pitfalls section. The most common mistake is sending the raw question as both objective and the only entry in search_queries. Write a goal-style objective and 1-3 short keyword queries instead.Bearer token on every Account API request. See the full endpoint reference in the Account API tab in the navigation.
Base URL
The OAuth endpoints below are rooted at:https://api.parallel.ai/account.
Overview
The full lifecycle is:- Register your client once, to obtain a
client_id. - Request a device code to start an authorization session.
- Prompt the user to verify in their browser using the verification URL and user code returned in step 2.
- Poll the token endpoint until the user approves and you receive an
access_tokenandrefresh_token. - Call the Account API with
Authorization: Bearer <access_token>. - Refresh the access token when it expires, or revoke the refresh token when the user signs out.
The
access_token returned by step 4 is what authorizes Account API calls. Without a valid bearer token, requests to the Account API will be rejected.1. Register your client
Register your application once to receive aclient_id. Send a description of your client and the platform it runs on:
client_id you reuse for all subsequent device-code requests from the same installation.
2. Request a device code
Start an authorization session by requesting a device code. The body isapplication/x-www-form-urlencoded:
device_code— opaque code your client uses when polling the token endpoint.user_code— short code the user types in the browser.verification_uri(and typicallyverification_uri_complete) — the URL to send the user to.expires_in— lifetime of the device code, in seconds.interval— minimum number of seconds to wait between polls.
user_code and verification_uri to the user, or open verification_uri_complete in their browser directly.
Scopes
Thescope parameter sets which Account API operations the resulting access token can perform. Valid scopes are:
apps:readapps:createapps:deletekeys:readkeys:createkeys:deletebalance:readbalance:addusage:read
%20 or + in the form body), for example scope=keys:read%20usage:read. Request only the scopes your application needs.
3. Poll for the access token
While the user completes verification in the browser, poll the token endpoint at the interval the server specified:authorization_pending— user has not yet approved. Waitintervalseconds and try again.slow_down— you are polling too fast. Increase your polling interval by 5 seconds for this and subsequent requests.access_denied— the user rejected the request. Stop polling.expired_token— the device code expired. Restart from step 2.- Success — a JSON body containing
access_token,refresh_token,token_type(Bearer), andexpires_in.
access_token, you can call the Account API.
4. Call the Account API
Every Account API request must include anAuthorization header with the access token from step 3:
5. Refresh the access token
Access tokens expire 10 minutes after they are issued. When one expires, exchange your refresh token for a new pair without prompting the user again:access_token and a new refresh_token. Parallel rotates the refresh token every time it issues a new access token, so you must persist the new refresh_token and use it for the next refresh. Earlier refresh tokens from the same session can’t be reused.
Token lifetimes
- Access tokens expire after 10 minutes. A session can have multiple valid access tokens at the same time.
- Refresh tokens expire after 30 days without use. Each session has exactly one active refresh token: the one returned by the most recent token response. As long as you keep refreshing within that 30-day window, the session doesn’t expire.
- Authorization expiry is returned as
authorization_expires_inon every token response. Each refresh extends it, so it doesn’t end a session you keep refreshing.