Skip to main content
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 .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.
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 Bearer token on every Account API request. See the full endpoint reference in the Account API tab in the navigation.
The Parallel CLI handles the entire device-OAuth flow for you — register, device code, polling, refresh, and revoke — and wraps the balance endpoints as the parallel-cli balance get and parallel-cli balance add commands. If you don’t need to embed the flow in your own application, the CLI is the fastest way to use the Account API. The rest of this page describes what the CLI does under the hood, for clients that need to implement it themselves.

Base URL

The OAuth endpoints below are rooted at:
Account API endpoints are rooted at https://api.parallel.ai/account.

Overview

The full lifecycle is:
  1. Register your client once, to obtain a client_id.
  2. Request a device code to start an authorization session.
  3. Prompt the user to verify in their browser using the verification URL and user code returned in step 2.
  4. Poll the token endpoint until the user approves and you receive an access_token and refresh_token.
  5. Call the Account API with Authorization: Bearer <access_token>.
  6. 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 a client_id. Send a description of your client and the platform it runs on:
The response contains a 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 is application/x-www-form-urlencoded:
The response includes:
  • 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 typically verification_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.
Display the user_code and verification_uri to the user, or open verification_uri_complete in their browser directly.

Scopes

The scope parameter sets which Account API operations the resulting access token can perform. Valid scopes are:
  • apps:read
  • apps:create
  • apps:delete
  • keys:read
  • keys:create
  • keys:delete
  • balance:read
  • balance:add
  • usage:read
To request multiple scopes, separate them with spaces (URL-encoded as %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:
Polling returns one of:
  • authorization_pending — user has not yet approved. Wait interval seconds 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), and expires_in.
Once you have the access_token, you can call the Account API.

4. Call the Account API

Every Account API request must include an Authorization header with the access token from step 3:
Requests without a valid bearer token are rejected. The endpoint catalogue is documented in the Account API tab in the navigation. For a worked example of a read endpoint, see Usage Data.

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:
The response contains a new 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_in on every token response. Each refresh extends it, so it doesn’t end a session you keep refreshing.
If the refresh token or the authorization expires, restart the flow from step 2 to have the user authorize again.

6. Revoke a refresh token

When the user signs out, or when you want to invalidate a session, revoke the refresh token:
After revocation, the refresh token can no longer be used to obtain new access tokens. Existing access tokens remain valid until they expire on their own.

End-to-end example