openapi: 3.1.0 info: title: AnchorBrowser API version: 1.0.0 description: | Anchor Browser ([anchorbrowser.io](https://anchorbrowser.io)) provides cloud browsers built for AI agents and automation. Use this API to launch and control browser sessions, run natural-language web tasks, authenticate into third-party web apps with managed identities, and capture recordings — reliably and at scale, without operating browser infrastructure yourself. ## Core resources - **Sessions** (`/v1/sessions`): launch configurable cloud browsers — residential proxies, stealth browsing, captcha solving, profiles, extensions, recording — and connect over CDP with Playwright, Puppeteer, or any CDP client. - **AI tools** (`/v1/tools/perform-web-task`): state a goal in natural language and the built-in agent completes it inside the browser. Related tools fetch webpages, take screenshots, render PDFs, and execute code in a session. - **Tasks** (`/v1/task`): create, version, deploy, and monitor repeatable browser automations built to run reliably in production. - **Applications and identities** (`/v1/applications`, `/v1/identities`): managed authentication into third-party web apps — including multi-step logins and TOTP-based 2FA — so agents can act on behalf of users. - **Profiles** (`/v1/profiles`): persist cookies and login state across sessions. - **OS-level control** (`/v1/sessions/{sessionId}/mouse`, `/keyboard`, `/clipboard`): raw input for flows that resist DOM automation. - Plus batch sessions for running browser fleets in parallel, session recordings, webhooks, events, extensions, client certificates, and billing usage. ## Authentication Pass an API key in the `anchor-api-key` header on every request. Create keys at [app.anchorbrowser.io](https://app.anchorbrowser.io) under API Access. AI agents that have no key yet can obtain one autonomously through the unauthenticated [agent-access flow](https://docs.anchorbrowser.io/quickstart/agent-access) (`POST /v1/agent-access`). ## For AI agents and LLMs - Docs: [docs.anchorbrowser.io](https://docs.anchorbrowser.io), with a machine-readable index at [/llms.txt](https://docs.anchorbrowser.io/llms.txt) and the full corpus at [/llms-full.txt](https://docs.anchorbrowser.io/llms-full.txt). - MCP server for hosted browser control: `https://api.anchorbrowser.io/mcp`. - Official SDKs: `anchorbrowser` on [npm](https://www.npmjs.com/package/anchorbrowser) and [PyPI](https://pypi.org/project/anchorbrowser/). `DELETE` operations terminate sessions or permanently remove resources (profiles, identities, extensions); `GET` operations are safe and read-only. servers: - url: https://api.anchorbrowser.io description: API server components: securitySchemes: api_key_header: type: apiKey in: header name: anchor-api-key description: | API key for your Anchor Browser account, sent as the `anchor-api-key` header on every request. Create one at [app.anchorbrowser.io](https://app.anchorbrowser.io) (API Access), or obtain one programmatically via the unauthenticated agent-access flow (`POST /v1/agent-access`). schemas: # ============================== # SHARED RESPONSE SCHEMAS # ============================== # These schemas are used across multiple resources SuccessResponse: type: object properties: data: type: object properties: status: type: string ErrorResponse: type: object properties: error: type: object properties: code: type: integer message: type: string # ============================== # PROXY CONFIGURATION SCHEMAS # ============================== ProxyConfig: description: | Proxy Documentation available at [Proxy Documentation](/advanced/proxy) type: object oneOf: - $ref: '#/components/schemas/AnchorProxy' - $ref: '#/components/schemas/CustomProxy' AnchorProxy: title: Anchor Proxy type: object properties: active: type: boolean type: type: string enum: [anchor_proxy] description: Create a session with a proxy to access websites as if you're browsing from a computer in that country. title: anchor_proxy country_code: $ref: '#/components/schemas/AnchorProxyCountryCode' description: | Supported country codes ISO 2 lowercase region: type: string description: | Region code for more specific geographic targeting. The city parameter can only be used when region is also provided. city: type: string description: | City name for precise geographic targeting. Supported for anchor_proxy only. Can only be used when region is also provided. required: [active] CustomProxy: title: Custom Proxy type: object properties: type: type: string enum: [custom] server: type: string description: Proxy address in **PROTOCOL://HOST:PORT** format (e.g., https://proxy.example.com:443). See [Bring Your Own Proxy](/advanced/bring-your-own-proxy). username: type: string description: Proxy username password: type: string description: Proxy password active: type: boolean required: [type, server, username, password, active] AnchorProxyCountryCode: type: string title: anchor_proxy enum: [ af, al, dz, ad, ao, as, ag, ar, am, aw, au, at, az, bs, bh, bb, by, be, bz, bj, bm, bo, ba, br, bg, bf, cm, ca, cv, td, cl, co, cg, cr, ci, hr, cu, cy, cz, dk, dm, do, ec, eg, sv, ee, et, fo, fi, fr, gf, pf, ga, gm, ge, de, gh, gi, gr, gd, gp, gt, gg, gn, gw, gy, ht, hn, hu, is, in, ir, iq, ie, il, it, jm, jp, jo, kz, kw, kg, lv, lb, ly, li, lt, lu, mk, ml, mt, mq, mr, mx, md, mc, me, ma, nl, nz, ni, ng, no, pk, pa, py, pe, ph, pl, pt, pr, qa, ro, lc, sm, sa, sn, rs, sc, sl, sk, si, so, za, kr, es, sr, se, ch, sy, st, tw, tj, tg, tt, tn, tr, tc, ua, ae, us, uy, uz, ve, ye, ] default: us # ============================== # PROFILE SCHEMAS # ============================== ProfileRequestSchema: type: object required: - name properties: name: type: string description: The name of the profile. description: type: string description: A description of the profile. source: type: string description: The source of the profile data. currently only `session` is supported. enum: - session session_id: type: string format: uuid description: The browser session ID is required if the source is set to `session`. The browser session must be running, and the profile will be stored once the browser session terminates. dedicated_sticky_ip: type: boolean description: Whether to use a dedicated sticky IP for this profile. Defaults to false. ProfileResponseSchema: type: object properties: name: type: string description: The name of the profile. description: type: string description: A description of the profile. source: type: string description: The source of the profile data. enum: - session session_id: type: string format: uuid description: The browser session ID used to create this profile, if applicable. status: type: string description: The current status of the profile. created_at: type: string format: date-time description: The timestamp when the profile was created. ProfileListResponse: type: object properties: data: type: object properties: count: type: integer description: Total number of profiles items: type: array items: $ref: '#/components/schemas/ProfileResponseSchema' ProfileResponse: type: object properties: data: $ref: '#/components/schemas/ProfileResponseSchema' # ============================== # BROWSER SESSION SCHEMAS # ============================== SessionConfig: type: object description: Session-related configurations. properties: initial_url: type: string format: uri description: The URL to navigate to when the browser session starts. If not provided, the browser will load an empty page. tags: type: array items: type: string description: Custom labels to categorize and identify browser sessions. Useful for filtering, organizing, and tracking sessions across your workflows. example: ['production', 'scraping', 'customer-123'] recording: type: object description: Configuration for session recording. properties: active: type: boolean description: Enable or disable video recording of the browser session. Defaults to `true`. proxy: $ref: '#/components/schemas/ProxyConfig' timeout: type: object description: Timeout configurations for the browser session. properties: max_duration: type: integer description: Maximum time (in minutes) the session can run before automatically terminating. Defaults to `20`. Set to `-1` to disable this limit. idle_timeout: type: integer description: Time (in minutes) the session waits for new connections after all others are closed before stopping. Defaults to `5`. Set to `-1` to disable this limit. live_view: type: object description: Configuration for live viewing the browser session. properties: read_only: type: boolean description: Enable or disable read-only mode for live viewing. Defaults to `false`. one_time_url: type: boolean description: >- Generate a single-use live view URL. After the first viewer connects, the link becomes invalid. Requires a headful browser. Defaults to `false`. x402: type: boolean default: false description: Allow this browser session to automatically pay x402-protected resources using Amazon Bedrock AgentCore Payments. putSessionTags: type: object description: Update/Create Browser Session tags, will overwrite existing tags required: - tags properties: tags: type: array items: type: string description: Tags to set on the session. Replaces any existing tags. example: ['production', 'scraping', 'customer-123'] SessionTagsResponse: type: object required: - tags properties: tags: type: array nullable: true items: type: string description: Tags currently associated with the session, or null if none are set. SessionTagsMutationResponse: type: object required: - success properties: success: type: boolean description: Whether the tags operation succeeded. message: type: string description: Human-readable result message. BrowserConfig: type: object description: Browser-specific configurations. properties: profile: type: object description: Options for managing and persisting browser session profiles. properties: name: type: string description: The name of the profile to be used during the browser session. persist: type: boolean description: Indicates whether the browser session profile data should be saved when the browser session ends. Defaults to `false`. adblock: type: object description: Configuration for ad-blocking. properties: active: type: boolean description: Enable or disable ad-blocking. Defaults to `true`. popup_blocker: type: object description: Configuration for popup blocking. properties: active: type: boolean description: Blocks popups, including ads and CAPTCHA consent banners. Requires adblock to be active. Defaults to `true`. captcha_solver: type: object description: Configuration for captcha-solving. properties: active: type: boolean description: Enable or disable captcha-solving. Requires proxy to be active. Defaults to `false`. headless: type: object description: Configuration for headless mode. properties: active: type: boolean description: Whether browser should be headless or headful. Defaults to `false`. viewport: type: object description: Configuration for the browser's viewport size. properties: width: type: integer description: Width of the viewport in pixels. Defaults to `1440`. height: type: integer description: Height of the viewport in pixels. Defaults to `900`. fullscreen: type: object description: Configuration for fullscreen mode. properties: active: type: boolean description: Enable or disable fullscreen mode. When enabled, the browser will start in fullscreen mode. Defaults to `false`. pdf_viewer: type: object description: Configuration for PDF viewer mode. properties: active: type: boolean description: Enable or disable PDF viewer mode. When disabled, the browser will download PDFs instead of viewing them. Defaults to `true`. p2p_download: type: object description: Configuration for peer-to-peer download capture functionality. properties: active: type: boolean description: Enable or disable P2P downloads. When enabled, the browser will capture downloads for direct data extraction, instead of uploading them on Anchor's storage. Defaults to `false`. extensions: type: array description: Array of extension IDs to load in the browser session. Extensions must be previously uploaded using the Extensions API. items: type: string format: uuid volume: type: object description: Mount a persistent volume into the session. Files the browser downloads are written to the volume's `downloads/` folder and remain available after the session ends. Create volumes with the Volumes API. required: - id properties: id: type: string format: uuid description: ID of a volume owned by your team (see `POST /v1/volumes`). The volume must be in the `ready` state. read_only: type: boolean description: Mount the volume read-only. Downloads then stay local to the session instead of being written to the volume. Defaults to `false`. disable_web_security: type: object description: Configuration for disabling web security features. properties: active: type: boolean description: Whether to disable web security features (CORS, same-origin policy, etc.). Allows accessing iframes and resources from different origins. Defaults to `false`. extra_stealth: type: object description: Enables our dedicated patched Chromium build, designed to avoid bot detection and blocking. Works with Anchor Proxy enabled only. properties: active: type: boolean description: Enable or disable extra stealth mode. force_popups_as_tabs: type: object description: Configuration for forcing popups to open as tabs instead of popup windows. properties: active: type: boolean description: Enable or disable forcing popups as tabs. Defaults to `false`. web_bot_auth: type: object description: Configuration for Cloudflare Web Bot Auth HTTP message signing. Enables authentication with websites that require Cloudflare's web bot authentication. properties: active: type: boolean description: Enable or disable web bot auth. Defaults to `false`. disable_dialogs: type: object description: Suppresses native browser dialogs (window.alert, window.confirm, window.prompt). Useful for automated workflows where dialogs would block execution. properties: active: type: boolean description: Enable or disable suppression of native browser dialogs. Defaults to `false`. tracing: type: object description: Configuration for browser tracing and debugging capabilities. properties: active: type: boolean description: Enable or disable tracing. Defaults to `true`. snapshots: type: boolean description: Enable or disable snapshot capture in traces. Defaults to `false`. sources: type: boolean description: Enable or disable source code capture in traces. Defaults to `true`. sensitive_data_mask: type: object description: Automatically detects and masks sensitive data (passwords, emails, phone numbers, credit card fields, tokens) in web pages. Supports custom CSS selectors globally or per site, and custom regex patterns. properties: active: type: boolean description: Enable or disable sensitive data masking. Defaults to `false`. custom_selectors: type: array items: type: string description: Additional CSS selectors to mask globally across all sites. Matched elements will be blurred. site_selectors: type: object additionalProperties: type: array items: type: string description: Per-site CSS selectors. Keys are hostnames (supports wildcard prefix like `*.bank.com`), values are arrays of CSS selectors. Matched elements will be blurred. custom_patterns: type: array items: type: object properties: regex: type: string description: Regular expression pattern to match sensitive data. mask: type: string description: Replacement string for matched text. Defaults to `****`. description: Custom regex patterns to detect and mask additional sensitive data types. SessionCreateRequestSchema: type: object properties: session: $ref: '#/components/schemas/SessionConfig' browser: $ref: '#/components/schemas/BrowserConfig' integrations: type: array description: Array of integrations to load in the browser session. Integrations must be previously created using the Integrations API. items: $ref: '#/components/schemas/Integration' example: [ { 'id': '550e8400-e29b-41d4-a716-446655440000', 'type': '1PASSWORD', 'configuration': { 'load_mode': 'all' }, }, ] identities: description: | Activates an authenticated session. type: array items: type: object description: Previously configured identity to be used for the authenticated session. properties: id: type: string description: The identity ID to use for the browser session. example: [{ 'id': '123e4567-e89b-12d3-a456-426614174000' }] identity_skip_validation: type: boolean default: true description: | When `true` (default), skip profile validation for active identities and reuse the saved browser profile. Set to `false` to validate the profile and re-authenticate if it is no longer signed in. Pending identities still authenticate on first use. identity_async_auth: type: boolean default: false description: Run identity authentication in the background and return the session immediately. SessionCreateResponseSchema: type: object properties: data: type: object properties: id: type: string description: Unique identifier for the browser session cdp_url: type: string description: The CDP websocket connection string live_view_url: type: string description: The browser session live view url AsyncSessionCreateResponseSchema: type: object properties: data: type: object required: - request_id - status - session_id properties: request_id: type: string format: uuid description: | Identifier of the async request. Use it to poll `GET /v1/sessions/async/{request_id}/status` for the resolved `session_id`, `cdp_url` and `live_view_url` once the pod comes up. status: type: string enum: [pending] description: Always `pending` immediately after creation. session_id: type: 'null' description: Always `null` immediately after creation; resolved via the polling endpoint. AsyncSessionStatusResponseSchema: type: object description: | Polling response for `GET /v1/sessions/async/{request_id}/status`. properties: data: type: object required: - request_id - status - created_at - progress properties: request_id: type: string format: uuid description: The `request_id` returned from `POST /v1/sessions/async`. status: type: string enum: [pending, processing, ready, completed, failed, cancelled] description: | Lifecycle of the async request itself. `ready` is surfaced once the underlying browser pod is up and the session is connectable. created_at: type: string format: date-time description: When the async request was accepted. session: $ref: '#/components/schemas/BatchSessionItemSchema' description: | The single browser session backing this async request. Absent until the underlying pod registers and the session row is inserted. progress: type: object required: - current_phase properties: current_phase: type: string enum: [queued, provisioning, configuring, ready] description: The session's current pod-provisioning phase. SessionStatus: type: object properties: session_id: type: string description: Unique identifier for the browser session status: type: string description: Current status of the browser session tags: type: array items: type: string description: Custom labels assigned to this browser session created_at: type: string format: date-time description: Timestamp when the browser session was created required: - session_id - status - created_at SessionListResponse: type: object properties: data: type: object properties: count: type: integer description: Total number of browser sessions items: type: array items: $ref: '#/components/schemas/SessionStatus' SessionHistoryPageItem: type: object description: A single session record in paginated history listing. properties: id: type: string description: Unique session identifier. status: type: string description: Current session status. tags: type: array nullable: true description: Tags associated with the session. items: type: string headless: type: boolean description: Whether the session ran in headless mode. recording: type: boolean description: Whether recording was enabled for the session. used_credits: oneOf: - type: number - type: string pattern: '^-?\d+(\.\d+)?$' - type: string enum: ['N/A'] description: Credits consumed by the session (number or decimal string), or `N/A` while still running. proxy_bytes: type: number nullable: true description: Proxy bandwidth used in bytes. proxy_type: type: string nullable: true description: Proxy type configured for the session. steps: type: number nullable: true description: Number of AI/browser steps recorded. duration: type: number nullable: true description: Session duration in seconds. created_at: type: string format: date-time description: Session creation timestamp in UTC ISO 8601 format. user_configuration: type: object additionalProperties: true description: Full user configuration payload saved for the session. task_initiated: type: boolean description: Whether the session was initiated by a task execution. task_executions_count: type: number description: Number of non-internal task executions associated with this session. api_key_name: type: string description: Display name of the API key that created the session. browser_ip: type: string nullable: true description: Browser/proxy IP observed for the session. domains: type: array nullable: true description: Domains observed during session execution. items: type: string required: - id - status - headless - recording - used_credits - created_at - user_configuration - task_initiated - task_executions_count - api_key_name - browser_ip SessionHistoryPageResponse: type: object description: Paginated session history listing response. properties: data: type: object properties: sessions: type: array description: Session records in the current page. items: $ref: '#/components/schemas/SessionHistoryPageItem' total: type: number description: Total number of matching sessions. page: type: number description: Current page number. total_pages: type: number description: Total number of pages. required: - sessions - total - page - total_pages SessionHistoryDataPoint: type: object properties: date: type: string description: Date/time period for this data point. session_count: type: number description: Number of sessions created in this period. proxy_bytes: type: number description: Total proxy bytes used in this period. ai_steps: type: number description: Total AI steps taken in this period. session_hours: type: number description: Total session hours in this period (duration/3600). credits_used: type: number description: Total credits used in this period. screenshots: type: number description: Total screenshots taken in this period. network_bytes_total: type: number description: Total network bytes sent and received in this period. SessionHistorySummary: type: object properties: total_sessions: type: number description: Total number of sessions in the time range. total_proxy_bytes: type: number description: Total proxy bytes used in the time range. total_ai_steps: type: number description: Total AI steps taken in the time range. total_session_hours: type: number description: Total session hours in the time range. total_credits_used: type: number description: Total credits used in the time range. total_screenshots: type: number description: Total screenshots taken in the time range. total_network_bytes_total: type: number description: Total network bytes sent and received in the time range. SessionHistoryPagination: type: object properties: current_page: type: integer total_pages: type: integer total_records: type: integer has_next: type: boolean has_prev: type: boolean SessionHistoryResponse: type: object properties: data: type: array description: Historical data points. items: $ref: '#/components/schemas/SessionHistoryDataPoint' summary: $ref: '#/components/schemas/SessionHistorySummary' pagination: $ref: '#/components/schemas/SessionHistoryPagination' BillingInfoResponse: type: object properties: data: type: object properties: credits: type: number description: Available credit balance for the authenticated project. credits_used: type: number description: Credits used in the current billing period. included_credits: type: number description: Credits included in the current tier before overage. billing_period: type: string description: Current billing period in YYYY-MM format. tier: type: string description: Billing tier for the project. gifts_balance: type: number description: Available gift or prepaid credit balance before applicable overage. max_concurrent_browsers: type: number description: Maximum concurrent browser sessions allowed for the project. `-1` means unlimited. cost_limit: type: number nullable: true description: Optional configured credit spend limit for the project. required: - credits - credits_used - included_credits - billing_period - tier usage: type: object description: >- Credits-usage time series. Present only when at least one of the `from_date`, `to_date`, or `granularity` query parameters is provided. Sums per-session credits bucketed by session creation time (UTC); recent buckets can still grow while sessions settle. Unlocker credits are tracked per calendar month and are not included in this series, so the bucket total can be lower than `credits_used`. The series matches `GET /v1/sessions/history?metrics=credits_used`. properties: from_date: type: string format: date-time description: Resolved start of the aggregation window. to_date: type: string format: date-time description: Resolved end of the aggregation window. granularity: type: string enum: [hour, day, week, month] description: Bucket size used for aggregation. total_credits_used: type: number description: Sum of credits used across the window. data: type: array description: Buckets ordered newest first. Periods with no sessions are omitted. items: type: object properties: date: type: string format: date-time description: Start of the bucket (ISO 8601, UTC). credits_used: type: number description: Credits used in this bucket. required: - date - credits_used required: - from_date - to_date - granularity - total_credits_used - data # ============================== # RECORDING SCHEMAS # ============================== RecordingItem: type: object properties: id: type: string description: Unique identifier for the recording is_primary: type: boolean description: Indicates if this is the primary recording file_link: type: string description: URL to access the recording file suggested_file_name: type: string description: Suggested filename for the recording duration: type: string description: Duration of the recording size: type: number description: Size of the recording file in bytes created_at: type: string format: date-time description: Timestamp when the recording was created RecordingListResponse: type: object properties: data: type: object properties: count: type: integer description: Total number of video recordings items: type: array items: $ref: '#/components/schemas/RecordingItem' # ============================== # DOWNLOAD SCHEMAS # ============================== DownloadItem: type: object properties: id: type: string description: The unique ID of the download record. file_link: type: string format: uri description: The URL to download the file from anchorbrowser servers. Requires api key authentication. original_download_url: type: string format: uri description: The URL used to download the file. origin_url: type: string format: uri description: The original URL where the file was found. suggested_file_name: type: string description: The suggested file name for saving the file. original_file_name: type: string description: The original file name before any modification. duration: type: integer description: The time it took to process or download the file, in milliseconds. size: type: integer description: The size of the file in bytes. created_at: type: string format: date-time description: The timestamp when the file record was created. DownloadListResponse: type: object properties: data: type: object properties: count: type: integer description: Total number of downloads items: type: array items: $ref: '#/components/schemas/DownloadItem' # ============================== # TOOL SCHEMAS # ============================== FetchWebpageRequestSchema: type: object properties: url: type: string description: The URL of the webpage or PDF to fetch content from. When left empty, the current webpage is used. format: type: string description: The output format of the content. enum: - html - markdown wait: type: integer description: The time to wait for **dynamic** content to load in **milliseconds**. new_page: type: boolean description: Whether to create a new page for the content. page_index: type: integer description: The index of the page to fetch content from. **Overides new_page**. return_partial_on_timeout: type: boolean description: Whether to return partial content if the content is not loaded within the 20 seconds. WebUnlockerRequestSchema: type: object required: - url properties: url: type: string description: The fully-qualified URL to fetch, including the scheme (e.g. `https://www.linkedin.com/company/openai`). options: type: object description: Optional retrieval settings. properties: return_partial_on_timeout: type: boolean default: true description: When a page is still loading at the deadline, return the content rendered so far instead of failing. Set to `false` to receive a `504` instead of partial content. WebUnlockerErrorResponse: type: object required: - error properties: error: type: string description: Human-readable reason the fetch failed. example: Could not resolve host ExecuteCodeRequestSchema: type: object required: - code properties: code: type: string description: TypeScript snippet (async function body) with injected page, browser, context, sessionId, anchorClient. ExecuteCodeToolResponseSchema: type: object required: - success - message properties: success: type: boolean message: type: string output: type: string description: JSON string of the return value when execution succeeds. error: type: string executionResultId: type: string format: uuid PerformWebTaskRequestSchema: type: object required: - prompt properties: url: type: string description: The URL of the webpage. If not provided, the tool will use the current page in the session. prompt: type: string description: The task to be autonomously completed. agent: type: string description: The AI agent to use for task completion. Defaults to browser-use. enum: - browser-use - openai-cua - gemini-computer-use - anthropic-cua - yutori - jev provider: type: string description: The AI provider to use for task completion. enum: - openai - gemini - groq - azure - xai model: type: string description: The specific model to use for task completion. see our [models](/agentic-browser-control/ai-task-completion#available-models) page for more information. detect_elements: type: boolean description: Enable element detection for better interaction accuracy. Improves the agent's ability to identify and interact with UI elements. human_intervention: type: boolean description: Allow human intervention during task execution. When enabled, the agent can request human input for ambiguous situations. max_steps: type: integer description: Maximum number of steps the agent can take to complete the task. Defaults to 200. llm_timeout: type: integer minimum: 10 maximum: 600 description: Timeout in seconds for each LLM call made by the agent (browser-use agent only). Raise it when tasks with deep context (long histories, large pages) hit LLM call timeouts. When omitted, the agent uses its model-based defaults. secret_values: type: object additionalProperties: type: string description: Secret values to pass to the agent for secure credential handling. Keys and values are passed as environment variables to the agent. highlight_elements: type: boolean description: Whether to highlight elements during task execution for better visibility. output_schema: type: object description: JSON Schema defining the expected structure of the output data. async: type: boolean description: Whether to run the task asynchronously. If true, the task will be run asynchronously and the response will include a workflow ID. default: false PerformWebTaskSyncResponseData: type: object title: sync properties: result: type: object description: The outcome or answer produced by the autonomous task. required: - result PerformWebTaskAsyncResponseData: type: object title: async properties: status: type: string enum: - running description: The status of the asynchronous task execution. workflow_id: type: string description: The workflow ID for tracking the asynchronous task execution. required: - status - workflow_id PerformWebTaskResponseSchema: type: object properties: data: oneOf: - $ref: '#/components/schemas/PerformWebTaskSyncResponseData' - $ref: '#/components/schemas/PerformWebTaskAsyncResponseData' x-oneOf-labels: - sync - async PerformWebTaskStatusSuccessResponseData: type: object title: success properties: status: type: string enum: - COMPLETED description: The workflow has completed successfully. result: type: object description: The outcome or answer produced by the autonomous task. sessionId: type: string description: Browser session the task ran on. Omitted when the job has no session. required: - status - result PerformWebTaskStatusRunningResponseData: type: object title: running properties: status: type: string enum: - RUNNING description: The workflow is currently running. sessionId: type: string description: Browser session the task ran on. Present as soon as the job exists when a session was created or reused. Omitted when the job has no session. required: - status PerformWebTaskStatusFailedResponseData: type: object title: failed properties: status: type: string enum: - FAILED description: The workflow has failed. error: type: string description: Error message describing why the workflow failed. sessionId: type: string description: Browser session the task ran on. Omitted when the job has no session. required: - status - error PerformWebTaskStatusResponseSchema: type: object properties: data: type: object oneOf: - $ref: '#/components/schemas/PerformWebTaskStatusSuccessResponseData' - $ref: '#/components/schemas/PerformWebTaskStatusRunningResponseData' - $ref: '#/components/schemas/PerformWebTaskStatusFailedResponseData' required: - data # ============================== # HUMAN INTERVENTION SCHEMAS # ============================== HumanInterventionField: type: object properties: name: type: string description: Field identifier used in the response payload. label: type: string description: Human-readable label displayed in the UI. description: type: string nullable: true description: Optional helper text for the field. required: type: boolean nullable: true description: Whether the field must be filled before submitting a response. type: type: string nullable: true enum: [text, number, url, email, password] description: Input type for the field. placeholder: type: string nullable: true description: Placeholder text shown in the input. defaultValue: type: string nullable: true description: Default value for the field (camelCase alias). required: - name - label HumanInterventionRequest: type: object description: A pending human-in-the-loop request from the agent. properties: requestId: type: string description: Unique identifier for the intervention request. Use this when responding. message: type: string description: The agent's prompt or question for the human operator. inputType: type: string enum: [text, confirm, fields] description: Expected response format (camelCase alias). fields: type: array nullable: true description: Form fields to collect when `inputType` is `fields`. items: $ref: '#/components/schemas/HumanInterventionField' required: - requestId - message PendingInterventionItem: allOf: - $ref: '#/components/schemas/HumanInterventionRequest' - type: object properties: sessionId: type: string description: The browser session that raised the intervention request. tags: type: array items: type: string description: Tags associated with the session. required: - sessionId - tags PendingInterventionsResponse: type: object properties: data: type: object properties: count: type: integer description: Total number of pending intervention requests across active sessions. items: type: array items: $ref: '#/components/schemas/PendingInterventionItem' required: - count - items required: - data HumanInterventionRequestsResponse: type: object properties: data: type: object properties: status: type: string description: Operation status (e.g. `success`). message: type: string description: Human-readable status message from the browser agent. requests: type: array description: Pending intervention requests for this session. items: $ref: '#/components/schemas/HumanInterventionRequest' required: - status - requests required: - data HumanInterventionResponseRequest: type: object properties: requestId: type: string description: | ID of the intervention request to respond to. If omitted, the most recent pending request for the session is used. response: description: | Response payload. For `text` input type, pass a string. For `confirm`, pass a boolean or confirmation string. For `fields`, pass an object keyed by field name. oneOf: - type: string - type: boolean - type: object additionalProperties: true required: - response HumanInterventionResponseResponse: type: object properties: data: type: object properties: status: type: string description: Operation status (e.g. `success`). message: type: string description: Human-readable confirmation from the browser agent. required: - status required: - data ScreenshotRequestSchema: type: object properties: url: type: string description: The URL of the webpage to capture. width: type: integer description: The width of the browser viewport in pixels. height: type: integer description: The height of the browser viewport in pixels. image_quality: type: integer description: Quality of the output image, on the range 1-100. 100 will not perform any compression. wait: type: integer description: Duration in milliseconds to wait after page has loaded, mainly used for sites with JS animations. scroll_all_content: type: boolean description: If true, scrolls the page and captures all visible content. capture_full_height: type: boolean description: If true, captures the entire height of the page, ignoring the viewport height. s3_target_address: type: string description: Presigned S3 url target to upload the image to. # ============================== # OS LEVEL CONTROL SCHEMAS # ============================== CoordinatesRequestSchema: type: object required: - x - y properties: x: type: integer description: X coordinate y: type: integer description: Y coordinate MouseClickRequestSchema: allOf: - $ref: '#/components/schemas/CoordinatesRequestSchema' - type: object properties: button: type: string description: Mouse button to use enum: [left, middle, right] MouseSingleClickRequestSchema: type: object description: Mouse click request. Must provide either (x, y) coordinates or a selector, but not both. properties: x: type: number description: X coordinate y: type: number description: Y coordinate button: type: string description: Mouse button to use enum: [left, middle, right] selector: type: string description: A valid CSS selector for the requested element timeout: type: number description: If a selector was passed, timeout in ms for waiting for the DOM element to be selected. Defaults to 5000 (5 seconds). index: type: number description: If a selector was passed and multiple elements match the selector, the index of the element in the list (0-based). Defaults to 0. DragDropRequestSchema: type: object required: - startX - startY - endX - endY properties: startX: type: integer description: Starting X coordinate startY: type: integer description: Starting Y coordinate endX: type: integer description: Ending X coordinate endY: type: integer description: Ending Y coordinate button: type: string description: Mouse button to use enum: [left, middle, right] ScrollRequestSchema: allOf: - $ref: '#/components/schemas/CoordinatesRequestSchema' - type: object required: - deltaY properties: deltaX: type: integer description: Horizontal scroll amount (positive is right, negative is left) deltaY: type: integer description: Vertical scroll amount (positive is down, negative is up) steps: type: integer description: Number of steps to break the scroll into for smoother scrolling useOs: type: boolean description: Whether to use the OS scroll or the Playwright scroll TypeTextRequestSchema: type: object required: - text properties: text: type: string description: Text to type delay: type: integer description: Delay between keystrokes in milliseconds KeyboardShortcutRequestSchema: type: object required: - keys properties: keys: type: array description: Array of keys to press simultaneously items: type: string holdTime: type: integer description: Time to hold the keys down in milliseconds ClipboardResponseSchema: type: object properties: data: type: object properties: text: type: string description: Text content of the clipboard ClipboardRequestSchema: type: object required: - text properties: text: type: string description: Text to set in the clipboard CopyResponseSchema: type: object properties: text: type: string description: The text that was copied PasteRequestSchema: type: object required: - text properties: text: type: string description: Text to paste NavigateRequestSchema: type: object required: - url properties: url: type: string description: The URL to navigate to # ============================== # EVENT COORDINATION SCHEMAS # ============================== # Schemas related to event signaling and coordination between workflows/sessions WaitForEventRequestSchema: type: object properties: timeoutMs: type: integer description: Timeout in milliseconds to wait for the event. Defaults to 60000ms (1 minute). SignalEventRequestSchema: type: object required: - data properties: data: type: object description: Event data to be passed to waiting clients additionalProperties: true example: message: 'Task completed' result: 'success' timestamp: '2024-01-01T12:00:00Z' EventResponseSchema: type: object properties: data: type: object description: The event data that was signaled additionalProperties: true example: message: 'Task completed' result: 'success' timestamp: '2024-01-01T12:00:00Z' # ============================== # EXTENSION SCHEMAS # ============================== # Schemas related to browser extension management ExtensionManifest: type: object properties: name: type: string version: type: string manifest_version: type: integer description: type: string permissions: type: array items: type: string additionalProperties: true ExtensionResponseSchema: type: object properties: id: type: string format: uuid description: Unique identifier for the extension name: type: string description: Extension name manifest: $ref: '#/components/schemas/ExtensionManifest' createdAt: type: string format: date-time description: Timestamp when the extension was created updatedAt: type: string format: date-time description: Timestamp when the extension was last updated ExtensionListResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/ExtensionResponseSchema' ExtensionResponse: type: object properties: data: $ref: '#/components/schemas/ExtensionResponseSchema' # ============================== # VOLUME SCHEMAS # ============================== # Persistent storage that can be mounted into browser sessions VolumeResponseSchema: type: object properties: id: type: string format: uuid description: Unique identifier for the volume. Use it in `browser.volume.id` when creating a session. name: type: string description: Volume name, unique within your team state: type: string enum: [creating, ready, deleting, deleted, error] description: Lifecycle state. Only `ready` volumes can be mounted or written to. error_reason: type: string nullable: true description: Why the volume entered the `error` state, if it did created_at: type: string format: date-time updated_at: type: string format: date-time last_used_at: type: string format: date-time nullable: true description: Last time the volume was mounted into a session deleted_at: type: string format: date-time nullable: true VolumeResponse: type: object properties: data: $ref: '#/components/schemas/VolumeResponseSchema' VolumeListResponse: type: object properties: data: type: object properties: count: type: integer description: Number of volumes returned items: type: array items: $ref: '#/components/schemas/VolumeResponseSchema' VolumeFileEntrySchema: type: object properties: path: type: string description: Path relative to the volume root, e.g. `downloads/report.pdf` type: type: string enum: [file, directory] size: type: integer nullable: true description: Size in bytes (`null` for directories) last_modified: type: string format: date-time nullable: true etag: type: string nullable: true VolumeFileListResponse: type: object properties: data: type: object properties: items: type: array items: $ref: '#/components/schemas/VolumeFileEntrySchema' next_cursor: type: string nullable: true description: Pass as `cursor` to fetch the next page; `null` when there are no more entries VolumePathListResponse: type: object properties: data: type: object properties: items: type: array items: type: string description: Every file path in the volume, relative to its root next_cursor: type: string nullable: true VolumeFileInfoSchema: type: object properties: path: type: string size: type: integer description: Size in bytes etag: type: string nullable: true content_type: type: string nullable: true last_modified: type: string format: date-time nullable: true VolumeFileInfoResponse: type: object properties: data: $ref: '#/components/schemas/VolumeFileInfoSchema' VolumeUploadUrlResponse: type: object properties: data: type: object properties: signed_url: type: string description: Pre-signed URL to `PUT` the file body to method: type: string enum: [PUT] headers: type: object additionalProperties: type: string description: Headers that must be sent with the `PUT` exactly as returned; they are part of the signature expires_in: type: integer description: Seconds until the URL expires VolumeDownloadUrlResponse: type: object properties: data: type: object properties: signed_url: type: string description: Pre-signed URL that serves the file with a `GET` expires_in: type: integer description: Seconds until the URL expires size: type: integer description: Size in bytes content_type: type: string nullable: true # ============================== # CERTIFICATE SCHEMAS # ============================== # Schemas related to CA certificate management CertificateResponseSchema: type: object properties: id: type: string format: uuid description: Unique identifier for the certificate name: type: string description: Certificate name (used to reference in sessions) description: type: string nullable: true description: Optional description of the certificate createdAt: type: string format: date-time description: Timestamp when the certificate was uploaded CertificateListResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/CertificateResponseSchema' CertificateResponse: type: object properties: data: $ref: '#/components/schemas/CertificateResponseSchema' # ============================== # BATCH SESSION SCHEMAS # ============================== # Schemas related to batch browser session management BatchSessionRequestSchema: type: object required: - count properties: count: type: integer minimum: 1 maximum: 1000 description: Number of sessions to create in the batch (1-1000) configuration: $ref: '#/components/schemas/SessionCreateRequestSchema' description: Configuration that applies to all sessions in the batch metadata: type: object additionalProperties: true description: Optional batch-level metadata for identification and organization BatchSessionResponseSchema: type: object properties: batch_id: type: string format: uuid description: Unique identifier for the batch status: type: string enum: [pending, processing, completed, failed, cancelled] description: Current status of the batch total_requests: type: integer description: Total number of sessions requested in the batch created_at: type: string format: date-time description: Timestamp when the batch was created BatchSessionItemSchema: type: object properties: item_index: type: integer description: Index of this session within the batch (0-based) session_id: type: string format: uuid description: Unique identifier for the browser session (if created successfully) status: type: string enum: [pending, processing, completed, failed, cancelled] description: Current status of this individual session cdp_url: type: string description: CDP websocket connection URL (if session is ready) live_view_url: type: string description: Live view URL for the session (if session is ready) error: type: string description: Error message if session creation failed retry_count: type: integer description: Number of times this session creation has been retried started_at: type: string format: date-time description: Timestamp when session creation started completed_at: type: string format: date-time description: Timestamp when session creation completed metadata: type: object additionalProperties: true description: Session-specific metadata BatchSessionStatusResponseSchema: type: object properties: batch_id: type: string format: uuid description: Unique identifier for the batch status: type: string enum: [pending, processing, completed, failed, cancelled] description: Current status of the batch total_requests: type: integer description: Total number of sessions requested completed_requests: type: integer description: Number of sessions successfully created failed_requests: type: integer description: Number of sessions that failed to create processing_requests: type: integer description: Number of sessions currently being processed pending_requests: type: integer description: Number of sessions waiting to be processed created_at: type: string format: date-time description: Timestamp when the batch was created actual_completion_time: type: string format: date-time description: Timestamp when the batch completed (if completed) error: type: string description: Error message if batch failed sessions: type: array items: $ref: '#/components/schemas/BatchSessionItemSchema' description: Array of individual session details progress: type: object properties: percentage: type: number minimum: 0 maximum: 100 description: Completion percentage (0-100) current_phase: type: string enum: [queued, provisioning, configuring, ready] description: Current processing phase BatchSessionListItemSchema: type: object properties: batch_id: type: string format: uuid description: Unique identifier for the batch status: type: string enum: [pending, processing, completed, failed, cancelled] description: Current status of the batch total_requests: type: integer description: Total number of sessions requested completed_requests: type: integer description: Number of sessions successfully completed failed_requests: type: integer description: Number of sessions that failed created_at: type: string format: date-time description: Timestamp when the batch was created actual_completion_time: type: string format: date-time description: Timestamp when the batch completed (if completed) BatchSessionListResponseSchema: type: object properties: batches: type: array items: $ref: '#/components/schemas/BatchSessionListItemSchema' description: Array of batch session summaries pagination: type: object properties: current_page: type: integer description: Current page number total_pages: type: integer description: Total number of pages total_records: type: integer description: Total number of batch records has_next: type: boolean description: Whether there is a next page has_prev: type: boolean description: Whether there is a previous page BatchSessionDeleteResponseSchema: type: object properties: batch_id: type: string format: uuid description: Unique identifier for the batch deleted_sessions: type: integer description: Number of sessions successfully deleted failed_deletions: type: integer description: Number of sessions that failed to delete errors: type: array items: type: object properties: session_id: type: string description: ID of the session that failed to delete error: type: string description: Error message description: Details of deletion failures (only present if there were failures) message: type: string description: Summary message of the deletion operation BatchSessionUpdateRequestSchema: type: object required: - status properties: status: type: string enum: [cancelled] description: Target status for the batch BatchSessionUpdateResponseSchema: type: object properties: batch_id: type: string format: uuid description: Unique identifier for the batch status: type: string enum: [cancelled] description: New status of the batch cancelled_sessions: type: integer description: Number of running sessions that were terminated message: type: string description: Summary message BatchSessionRetryRequestSchema: type: object properties: retry_failed_only: type: boolean default: true description: Whether to only retry failed sessions max_retries: type: integer minimum: 1 maximum: 3 default: 1 description: Maximum number of attempts per failed session. Each session is retried up to this many times, stopping on first success. BatchSessionRetryResponseSchema: type: object properties: batch_id: type: string format: uuid description: Unique identifier for the batch status: type: string enum: [pending, processing, completed, failed, cancelled] description: Current status of the batch after retry retried_sessions: type: integer description: Number of sessions that were retried message: type: string description: Summary message # INTEGRATION SCHEMAS # ============================== # Schemas related to third-party integrations like 1Password IntegrationType: type: string enum: - 1PASSWORD description: The type of integration OnePasswordAllSecretsConfig: type: object required: - load_mode properties: load_mode: type: string enum: [all] description: Load all secrets from 1Password OnePasswordSpecificSecretsConfig: type: object required: - load_mode - secrets properties: load_mode: type: string enum: [specific] description: Load specific secrets from 1Password secrets: type: array items: type: string minItems: 1 description: Array of secret references to load example: ['op://vault/item/field'] OnePasswordConfig: oneOf: - $ref: '#/components/schemas/OnePasswordAllSecretsConfig' - $ref: '#/components/schemas/OnePasswordSpecificSecretsConfig' OnePasswordIntegration: type: object required: - id - type - configuration properties: id: type: string format: uuid description: Unique integration ID example: '550e8400-e29b-41d4-a716-446655440000' type: type: string enum: [1PASSWORD] description: Integration type configuration: $ref: '#/components/schemas/OnePasswordConfig' Integration: oneOf: - $ref: '#/components/schemas/OnePasswordIntegration' discriminator: propertyName: type ServiceAccountCredentials: type: object required: - type - data properties: type: type: string enum: [serviceAccount] description: Credential type data: type: object required: - serviceAccount properties: serviceAccount: type: string description: Service account token example: 'ops_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx' CreateIntegrationRequest: type: object required: - name - type - credentials properties: name: type: string minLength: 1 description: Name for the integration example: 'My 1Password Integration' type: $ref: '#/components/schemas/IntegrationType' credentials: $ref: '#/components/schemas/ServiceAccountCredentials' IntegrationItem: type: object properties: id: type: string format: uuid description: Unique integration ID example: '550e8400-e29b-41d4-a716-446655440000' name: type: string description: Integration name example: 'My 1Password Integration' type: $ref: '#/components/schemas/IntegrationType' path: type: string description: Storage path for the integration example: 'integrations/team-id/550e8400-e29b-41d4-a716-446655440000' createdAt: type: string format: date-time description: Timestamp when the integration was created example: '2024-01-01T00:00:00.000Z' IntegrationListResponse: type: object properties: data: type: object properties: integrations: type: array items: $ref: '#/components/schemas/IntegrationItem' IntegrationResponse: type: object properties: data: type: object properties: integration: $ref: '#/components/schemas/IntegrationItem' # ============================== # TASK MANAGEMENT SCHEMAS # ============================== Task: type: object properties: id: type: string format: uuid description: Unique identifier for the task name: type: string pattern: '^[a-zA-Z0-9_-]+$' minLength: 1 maxLength: 255 description: Task name (letters, numbers, hyphens, and underscores only) teamId: type: string format: uuid description: Team identifier that owns this task description: type: string maxLength: 1000 description: Optional description of the task latestVersion: type: string description: Latest version identifier (draft, latest, or version number) code: type: string description: Base64 encoded task code language: type: string enum: [typescript] description: Programming language for the task browserConfiguration: $ref: '#/components/schemas/SessionConfig' description: Browser configuration for task execution deleted: type: boolean description: Whether the task is soft deleted createdAt: type: string format: date-time description: Task creation timestamp updatedAt: type: string format: date-time description: Task last update timestamp required: [id, name, teamId, latestVersion, code, language, deleted, createdAt, updatedAt] TaskMetadata: type: object properties: id: type: string format: uuid description: Unique identifier for the task name: type: string pattern: '^[a-zA-Z0-9_-]+$' minLength: 1 maxLength: 255 description: Task name teamId: type: string format: uuid description: Team identifier that owns this task description: type: string maxLength: 1000 description: Optional description of the task latest: type: string description: Latest version identifier deleted: type: boolean description: Whether the task is soft deleted createdAt: type: string format: date-time description: Task creation timestamp updatedAt: type: string format: date-time description: Task last update timestamp required: [id, name, teamId, latest, deleted, createdAt, updatedAt] TaskVersion: type: object properties: id: type: string format: uuid description: Unique identifier for the task version taskId: type: string format: uuid description: Parent task identifier version: type: string description: Version identifier (draft, latest, or version number) code: type: string description: Base64 encoded task code language: type: string enum: [typescript] description: Programming language for the task description: type: string maxLength: 1000 description: Optional description of the version browserConfiguration: $ref: '#/components/schemas/SessionConfig' description: Browser configuration for task execution deleted: type: boolean description: Whether the version is soft deleted createdAt: type: string format: date-time description: Version creation timestamp updatedAt: type: string format: date-time description: Version last update timestamp required: [id, taskId, version, code, deleted, createdAt, updatedAt] TaskExecutionResult: type: object properties: id: type: string format: uuid description: Unique identifier for the execution result taskVersionId: type: string format: uuid description: Task version identifier version: type: string description: Version that was executed status: type: string enum: [success, failure, timeout, cancelled, queued, running] description: Execution status output: type: string nullable: true description: Task execution output errorMessage: type: string nullable: true description: Error message if execution failed startTime: type: string format: date-time description: Execution start time executionTime: type: number nullable: true description: Execution duration in milliseconds required: [id, taskVersionId, version, status, startTime] CreateTaskRequest: type: object properties: name: type: string pattern: '^[a-zA-Z0-9_-]+$' minLength: 1 maxLength: 255 description: Task name (letters, numbers, hyphens, and underscores only) code: type: string pattern: '^[A-Za-z0-9+/]*={0,2}$' description: Base64 encoded task code (optional) language: type: string enum: [typescript] description: Programming language for the task description: type: string maxLength: 1000 description: Optional description of the task browserConfiguration: $ref: '#/components/schemas/SessionConfig' description: Browser configuration for task execution required: [name, language] UpdateTaskMetadataRequest: type: object properties: name: type: string pattern: '^[a-zA-Z0-9_-]+$' minLength: 1 maxLength: 255 description: Task name (letters, numbers, hyphens, and underscores only) description: type: string maxLength: 1000 description: Optional description of the task DraftTaskRequest: type: object properties: code: type: string minLength: 1 pattern: '^[A-Za-z0-9+/]*={0,2}$' description: Base64 encoded task code language: type: string enum: [typescript] description: Programming language for the task description: type: string maxLength: 1000 description: Optional description of the version browserConfiguration: $ref: '#/components/schemas/SessionConfig' description: Browser configuration for task execution required: [code] PublishVersionRequest: type: object properties: code: type: string minLength: 1 pattern: '^[A-Za-z0-9+/]*={0,2}$' description: Base64 encoded task code (required for new versions) language: type: string enum: [typescript] description: Programming language for the task description: type: string maxLength: 1000 description: Optional description of the version browserConfiguration: $ref: '#/components/schemas/SessionConfig' description: Browser configuration for task execution RunTaskRequest: type: object properties: taskId: type: string format: uuid description: Task identifier version: type: string pattern: '^(draft|latest|\d+)$' description: Version to run (draft, latest, or version number) sessionId: type: string format: uuid description: Optional existing browser session ID to use for task execution async: type: boolean description: Whether to run the task asynchronously. overrideBrowserConfiguration: $ref: '#/components/schemas/SessionConfig' description: Override browser configuration for this execution inputs: type: object additionalProperties: type: string patternProperties: '^ANCHOR_.*$': type: string description: Environment variables for task execution (keys must start with ANCHOR_) cleanupSessions: type: boolean description: Whether to cleanup browser sessions after task execution. Defaults to true. default: true required: [taskId] RunTaskByNameRequest: type: object properties: sessionId: type: string format: uuid description: Optional existing browser session ID to use for task execution async: type: boolean description: Whether to run the task asynchronously overrideBrowserConfiguration: $ref: '#/components/schemas/SessionConfig' description: Override browser configuration for this execution inputs: type: object additionalProperties: type: string patternProperties: '^ANCHOR_.*$': type: string description: Environment variables for task execution (keys must start with ANCHOR_) cleanupSessions: type: boolean description: Whether to cleanup browser sessions after task execution. Defaults to true. default: true RunTaskV2Request: type: object properties: input_params: type: object additionalProperties: type: string description: Key-value pairs of input parameters for the task identity_id: type: string description: Optional identity ID to use for the task session_id: type: string description: Optional session ID to run the task in cleanup_sessions: type: boolean description: 'Whether to clean up sessions after execution (default: true)' default: true identity_skip_validation: type: boolean default: true description: | When `true` (default), skip profile validation for active identities and reuse the saved browser profile. Set to `false` to validate the profile and re-authenticate if it is no longer signed in. Pending identities still authenticate on first use. sync: type: boolean default: false description: Wait for the task to complete before returning. Defaults to `false`. required: [input_params] ReauthenticateIdentityRequest: type: object properties: sync: type: boolean default: true description: | When `true` (default), wait for authentication to finish and persist the refreshed profile before returning. When `false`, start authentication asynchronously. ReauthenticateIdentityResponse: type: object required: [identityId, async, sessionId, auth_status] properties: identityId: type: string description: The identity that was reauthenticated async: type: boolean description: Whether authentication is still running in the background sessionId: type: string description: Browser session that ran the reauthentication; its recording shows what happened auth_status: type: string enum: [authenticated, pending] description: >- authenticated: the identity is signed in again; pending: an async run is still in progress method: type: string enum: [profile, task, mixed] description: >- How the identity got authenticated: profile = stored profile was still signed in, task = agentic authentication task, mixed = both. Absent while pending. AuthFlowV2StartRequest: type: object required: [url, host] properties: url: type: string format: uri description: Landing URL to open in the session (login page). example: 'https://example.com/login' host: type: string description: Hostname of `url`. Must match the URL hostname after normalization. example: 'example.com' AuthFlowV2DecisionResolve: title: decision type: object required: [choice] description: Send this when the last presentation was a decision step. properties: choice: type: string description: One of `options[].step_id` from the decision view. example: 'root/login/google' AuthFlowV2FormResolve: title: form type: object required: [option_index, values] description: Send this when the last presentation was a form step. properties: option_index: type: integer minimum: 0 description: Index into that form's `options` list. example: 0 values: type: object additionalProperties: type: string description: Map of input name → value for the selected option (`options[option_index].inputs` lists the names). example: username: 'user@example.com' password: 'secret' AuthFlowV2ResolveRequest: oneOf: - $ref: '#/components/schemas/AuthFlowV2FormResolve' - $ref: '#/components/schemas/AuthFlowV2DecisionResolve' description: | Body depends on the last `view.type`. Use the `decision` shape or the `form` shape — not both. AuthFlowV2FinalizeRequest: type: object properties: identity_name: type: string description: Optional name for the created identity. profile_name: type: string description: Optional browser profile name. Defaults to `profile-`. AuthFlowV2DecisionOption: type: object required: [step_id, label, automatable] description: | One option on a `decision` step. The option's `step_id` is the value to send as `choice` on `/resolve`; the decision view's `step_id` identifies the step that is asking you to choose. properties: step_id: type: string description: Opaque identifier for this option; pass it back as `choice`. label: type: string description: Human-readable name of the login path (e.g. "Continue with Google"). automatable: type: boolean description: True if this path is known to be replayable unattended, without a human. AuthFlowV2FormOption: type: object required: [type, automatable] description: | One way to complete a `form` step. Pick it with `option_index` on `/resolve`. `automatable` is true when this option can be replayed unattended (typically `credentials`, `totp_secret`, `gmail_one_click_integration`). Captcha, passkey, consent, and magic_link are typically false. `gmail_one_click_integration`: open `extra_data.create_integration_url` in a browser once; it returns a value to send as `values.gmail_tokens` on `/resolve`. The token is bound to the Gmail account, not to this flow — reuse it on any later email MFA form for that account, across applications, without authorizing again. properties: type: type: string enum: - credentials - mfa_totp - mfa_sms - mfa_email - sso - captcha - consent - magic_link - passkey - generic - totp_secret - gmail_one_click_integration automatable: type: boolean description: True if this option can be replayed unattended without a human. inputs: type: array items: type: object required: [name, type] properties: name: type: string type: type: string label: type: string placeholder: type: string value: type: string extra_data: type: object additionalProperties: true description: Type-specific extras. Present only when the option has any. properties: create_integration_url: type: string format: uri description: On `gmail_one_click_integration`. Browser URL to connect Gmail; see the option description for the token it returns. number: type: string description: On `consent`. Device confirmation number from the live page, when shown. message: type: string provider: type: string phoneHint: type: string AuthFlowV2ViewBase: type: object required: [session_id, host, current_step_label, step_id, cdp_url, live_view_url] properties: session_id: type: string host: type: string description: Hostname the flow was started for. current_step_label: type: string description: Human-readable label of the current login step. step_id: type: string description: Identifier of the current login step. cdp_url: type: string description: CDP websocket URL of the session driving the login. live_view_url: type: string description: URL to watch or take over the session in a browser. discovery_error: type: string description: Set when automatic step detection hit an error. A partial flow may still be presented. AuthFlowV2DecisionView: title: decision allOf: - $ref: '#/components/schemas/AuthFlowV2ViewBase' - type: object required: [type, options] properties: type: type: string enum: [decision] options: type: array description: | Each item is `{ step_id, label, automatable }`. POST `/resolve` with `{ "choice": "" }`. items: $ref: '#/components/schemas/AuthFlowV2DecisionOption' AuthFlowV2FormView: title: form allOf: - $ref: '#/components/schemas/AuthFlowV2ViewBase' - type: object required: [type, options] properties: type: type: string enum: [form] options: type: array description: | Each item includes `type` and `automatable`. POST `/resolve` with `{ "option_index": n, "values": { ... } }`. items: $ref: '#/components/schemas/AuthFlowV2FormOption' credentials_rejected: type: boolean description: The last submission was rejected (e.g. wrong password) and the same form is re-presented. credentials_passed: type: boolean description: The previous step just cleared. Transient. AuthFlowV2DetectionFailedView: title: detection_failed allOf: - $ref: '#/components/schemas/AuthFlowV2ViewBase' - type: object required: [type, node_status, retryable, message] properties: type: type: string enum: [detection_failed] node_status: type: string enum: [detected, failed, explored] description: How far the current step has been analyzed. last_error: type: string description: The most recent navigation error, if any. retryable: type: boolean description: True means keep polling `/state`; false means stop and use `live_view_url`. message: type: string description: | Why detection stopped. Open `live_view_url` to finish signing in in the browser. Do not resolve. If `retryable` is true, you may also poll GET `/state`. AuthFlowV2AuthenticatedView: title: authenticated allOf: - $ref: '#/components/schemas/AuthFlowV2ViewBase' - type: object required: [type] properties: type: type: string enum: [authenticated] message: type: string description: Human-readable status. POST `/finalize` to persist the identity. AuthFlowV2FailedView: title: failed allOf: - $ref: '#/components/schemas/AuthFlowV2ViewBase' - type: object required: [type, error, retryable] properties: type: type: string enum: [failed] error: type: string description: What went wrong. retryable: type: boolean description: True means keep polling `/state`; false means stop. AuthFlowV2View: description: | Presentation returned by start/resolve. GET `/state` nests the same object as `view` when there is something to show. Discriminated on `type`. Call `/resolve` only for `decision` or `form`. oneOf: - $ref: '#/components/schemas/AuthFlowV2DecisionView' - $ref: '#/components/schemas/AuthFlowV2FormView' - $ref: '#/components/schemas/AuthFlowV2DetectionFailedView' - $ref: '#/components/schemas/AuthFlowV2AuthenticatedView' - $ref: '#/components/schemas/AuthFlowV2FailedView' discriminator: propertyName: type mapping: decision: '#/components/schemas/AuthFlowV2DecisionView' form: '#/components/schemas/AuthFlowV2FormView' detection_failed: '#/components/schemas/AuthFlowV2DetectionFailedView' authenticated: '#/components/schemas/AuthFlowV2AuthenticatedView' failed: '#/components/schemas/AuthFlowV2FailedView' AuthFlowV2State: type: object description: | Poll this after retryable `detection_failed`, a request timeout, or 409. `view` is the same presentation start/resolve return (`type` discriminant). When `phase` is `settled`, it is the current step. When `phase` is `navigating`, it may already describe the next step so you can render (or answer) before the browser finishes moving; it is omitted until there is something to show. Call `/resolve` only when `view.type` is `decision` or `form`. required: - session_id - graph_id - current_step_id - discovery_status - phase - updated_at - nav properties: session_id: type: string graph_id: type: integer description: Internal identifier for this auth flow. current_step_id: type: string description: | Identifier of the step the flow last committed. While `phase` is `navigating`, `view` may already describe a later step. discovery_status: type: string enum: [in_progress, complete, failed] description: Whether automatic detection of the login steps is still running. discovery_error: type: string phase: type: string enum: [navigating, settled] description: | `navigating` — a browser transition is in flight; `view` may already be the next step. `settled` — idle at a step; `view` is that step. updated_at: type: number description: Unix epoch milliseconds of the last state change. target: type: object description: | Step the browser is moving toward. Present only while `phase` is `navigating`. Use for progress copy (for example "Preparing {label}…"). Not a second presentation — `view` is what to show. properties: step_id: type: string label: type: string nav: type: object required: [status] description: Outcome of the latest navigation operation. properties: status: type: string enum: [pending, succeeded, failed, none] error: type: string credentials_rejected: type: boolean view: allOf: - $ref: '#/components/schemas/AuthFlowV2View' description: | What to render or answer. Same shape as start/resolve, derived read-only. - `phase: settled` — the current step. - `phase: navigating` — the upcoming step, when known; omitted until then. AuthFlowV2FinalizeResult: type: object required: [identityId, profileName, automatable, nonAutomatableReasons] properties: identityId: type: string profileName: type: string automatable: type: boolean description: | Identity-level replay flag. False if any passed form option was not automatable. Distinct from `options[].automatable` on `decision`/`form` views, which is per choice. nonAutomatableReasons: type: array description: Why the login cannot be replayed unattended. Empty when `automatable` is true. items: type: string TaskRunStatusV2Response: type: object properties: run_id: type: string description: The ID of the task run status: type: string enum: [queued, running, success, failure, timeout, cancelled] description: Current task run status result: type: object additionalProperties: true description: Task output when available error: type: string description: Error message when the run fails session_id: type: string description: Session ID used for this task run required: [run_id, status] TaskParameterV2: type: object description: A single input or output parameter for a generated task. properties: name: type: string description: The field name/key type: type: string enum: [string, number, boolean, secret, file] description: Data type of the parameter required: type: boolean default: true description: Whether the parameter is required description: type: string nullable: true description: Description of the parameter defaultValue: nullable: true description: Default value of the parameter, used when not provided options: type: array nullable: true items: type: string description: Allowed values for the parameter, if constrained required: [name, type] GenerateTaskV2Request: type: object properties: taskName: type: string description: Name of the task taskPrompt: type: string description: Natural-language description of what the task should do, used for AI generation. Make it as detailed as possible with all the logic and steps needed to complete the task. async: type: boolean default: true description: Whether to generate the task asynchronously description: type: string description: Description of the task application_id: type: string format: uuid description: Optional application (connection) ID to associate with the task identity_id: type: string description: Optional identity ID to use during task generation input_schema: type: array default: [] items: $ref: '#/components/schemas/TaskParameterV2' description: Input parameters the task accepts output_schema: type: array default: [] items: $ref: '#/components/schemas/TaskParameterV2' description: Output fields the task produces output_file_only: type: boolean default: false description: Whether task runs should return only the bundled session downloads file human_intervention: type: boolean default: false description: Allow human intervention during task execution browser_session_id: type: string description: Existing finished browser session id to generate the workflow from task_browser_default_configuration: type: object additionalProperties: true description: Optional default browser/session configuration when running this task required: [taskName, taskPrompt] GenerateTaskV2Response: type: object properties: id: type: string description: The ID of the created task (use with generation-status and run endpoints) status: type: string enum: [generating] description: Whether the task is still generating, ready to run, or failed taskId: type: string description: The ID of the task being generated taskVersionId: type: string description: The ID of the task version being generated projectId: type: string description: The ID of the underlying generation project required: [id, status] TaskGenerationStatusV2Response: type: object properties: id: type: string description: Identifier of the generation request status: type: string enum: [generating, ready, failed, waiting-for-session] description: Current task generation status project_state: type: string description: Internal state of the generation project error: type: string description: Error message when generation failed required: [id, status] TaskListResponse: type: object properties: data: type: object properties: tasks: type: array items: $ref: '#/components/schemas/Task' total: type: integer minimum: 0 description: Total number of tasks page: type: integer minimum: 1 description: Current page number limit: type: integer minimum: 1 maximum: 100 description: Number of tasks per page required: [tasks, total, page, limit] TaskResponse: type: object properties: data: $ref: '#/components/schemas/Task' TaskMetadataResponse: type: object properties: data: $ref: '#/components/schemas/TaskMetadata' TaskVersionResponse: type: object properties: data: $ref: '#/components/schemas/TaskVersion' TaskVersionsListResponse: type: object properties: data: type: object properties: taskId: type: string format: uuid description: Task identifier versions: type: array items: type: object properties: version: type: string description: Version identifier description: type: string description: Version description createdAt: type: string format: date-time description: Version creation timestamp updatedAt: type: string format: date-time description: Version last update timestamp required: [version, createdAt, updatedAt] required: [taskId, versions] TaskExecutionResultsListResponse: type: object properties: data: type: object properties: results: type: array items: $ref: '#/components/schemas/TaskExecutionResult' pagination: type: object properties: page: type: integer minimum: 1 description: Current page number limit: type: integer minimum: 1 description: Number of results per page total: type: integer minimum: 0 description: Total number of results totalPages: type: integer minimum: 0 description: Total number of pages required: [page, limit, total, totalPages] required: [results, pagination] TaskExecutionResultResponse: type: object properties: data: $ref: '#/components/schemas/TaskExecutionResult' RunTaskResponse: type: object properties: data: type: object properties: success: type: boolean description: Whether the task executed successfully async: type: boolean description: Whether the task was executed asynchronously message: type: string description: Execution result message taskId: type: string format: uuid description: Task identifier executionTime: type: number description: Execution duration in milliseconds (only present in sync mode) output: type: string description: Task execution output (only present in sync mode) error: type: string description: Error message if execution failed (only present in sync mode) executionResultId: type: string format: uuid description: Execution result identifier for tracking and polling (present in async mode) required: [success, async, message, taskId] DeleteTaskResponse: type: object properties: data: type: object properties: success: type: boolean description: Whether the deletion was successful message: type: string description: Deletion result message required: [success, message] # ============================== # APPLICATION SCHEMAS # ============================== ApplicationItem: type: object properties: id: type: string format: uuid description: Unique identifier for the application name: type: string description: Name of the application url: type: string nullable: true description: URL of the application description: type: string nullable: true description: Description of the application identity_count: type: integer description: Number of identities associated with this application auth_methods: type: array items: type: string description: Authentication methods available for this application created_at: type: string format: date-time description: Timestamp when the application was created updated_at: type: string format: date-time description: Timestamp when the application was last updated CreateApplicationRequest: type: object required: - source properties: source: type: string format: uri description: The source URL of the application name: type: string description: Name of the application description: type: string description: Description of the application CreateApplicationResponse: type: object properties: id: type: string format: uuid description: Unique identifier for the application name: type: string description: Name of the application url: type: string nullable: true description: URL of the application description: type: string nullable: true description: Description of the application created_at: type: string format: date-time description: Timestamp when the application was created ListApplicationsResponse: type: object properties: applications: type: array items: $ref: '#/components/schemas/ApplicationItem' GetApplicationResponse: type: object properties: id: type: string format: uuid description: Unique identifier for the application name: type: string description: Name of the application url: type: string nullable: true description: URL of the application description: type: string nullable: true description: Description of the application identity_count: type: integer description: Number of identities associated with this application auth_methods: type: array items: type: string description: Authentication methods available for this application created_at: type: string format: date-time description: Timestamp when the application was created updated_at: type: string format: date-time description: Timestamp when the application was last updated UpdateApplicationRequest: type: object properties: allowed_domains: type: array items: type: string description: List of allowed domains for this application UpdateApplicationResponse: type: object properties: id: type: string format: uuid description: Unique identifier for the application url: type: string nullable: true description: URL of the application DeleteApplicationResponse: type: object properties: success: type: boolean description: Whether the deletion was successful ApplicationIdentityItem: type: object properties: id: type: string format: uuid description: Unique identifier for the identity name: type: string description: Name of the identity auth_flow: type: string nullable: true description: Authentication flow associated with this identity status: type: string enum: [pending, validated, failed] description: Status of the identity created_at: type: string format: date-time description: Timestamp when the identity was created updated_at: type: string format: date-time description: Timestamp when the identity was last updated ListApplicationIdentitiesResponse: type: object properties: identities: type: array items: $ref: '#/components/schemas/ApplicationIdentityItem' CustomFieldDefinition: type: object required: - name properties: name: type: string description: Name of the custom field AuthFlowItem: type: object properties: id: type: string format: uuid description: Unique identifier for the authentication flow name: type: string description: Name of the authentication flow description: type: string nullable: true description: Description of the authentication flow is_recommended: type: boolean description: Whether this is the recommended authentication flow methods: type: array items: type: string description: Authentication methods in this flow custom_fields: type: array items: $ref: '#/components/schemas/CustomFieldDefinition' description: Custom fields for this authentication flow created_at: type: string format: date-time description: Timestamp when the authentication flow was created updated_at: type: string format: date-time description: Timestamp when the authentication flow was last updated ListApplicationAuthFlowsResponse: type: object properties: auth_flows: type: array items: $ref: '#/components/schemas/AuthFlowItem' CreateAuthFlowRequest: type: object required: - name - methods properties: name: type: string description: Name of the authentication flow description: type: string description: Description of the authentication flow is_recommended: type: boolean description: Whether this is the recommended authentication flow methods: type: array items: type: string enum: [username_password, authenticator, custom] minItems: 1 description: Authentication methods in this flow custom_fields: type: array items: $ref: '#/components/schemas/CustomFieldDefinition' description: Custom fields for this authentication flow CreateAuthFlowResponse: type: object properties: id: type: string format: uuid description: Unique identifier for the authentication flow name: type: string description: Name of the authentication flow description: type: string nullable: true description: Description of the authentication flow is_recommended: type: boolean description: Whether this is the recommended authentication flow methods: type: array items: type: string description: Authentication methods in this flow custom_fields: type: array items: $ref: '#/components/schemas/CustomFieldDefinition' description: Custom fields for this authentication flow created_at: type: string format: date-time description: Timestamp when the authentication flow was created updated_at: type: string format: date-time description: Timestamp when the authentication flow was last updated UpdateAuthFlowRequest: type: object properties: name: type: string description: Name of the authentication flow description: type: string description: Description of the authentication flow is_recommended: type: boolean description: Whether this is the recommended authentication flow methods: type: array items: type: string enum: [username_password, authenticator, custom] description: Authentication methods in this flow custom_fields: type: array items: $ref: '#/components/schemas/CustomFieldDefinition' description: Custom fields for this authentication flow UpdateAuthFlowResponse: type: object properties: id: type: string format: uuid description: Unique identifier for the authentication flow name: type: string description: Name of the authentication flow description: type: string nullable: true description: Description of the authentication flow is_recommended: type: boolean description: Whether this is the recommended authentication flow methods: type: array items: type: string description: Authentication methods in this flow custom_fields: type: array items: $ref: '#/components/schemas/CustomFieldDefinition' description: Custom fields for this authentication flow created_at: type: string format: date-time description: Timestamp when the authentication flow was created updated_at: type: string format: date-time description: Timestamp when the authentication flow was last updated DeleteAuthFlowResponse: type: object properties: success: type: boolean description: Whether the deletion was successful # ============================== # IDENTITY SCHEMAS # ============================== UsernamePasswordCredential: title: username_password type: object required: - type - username - password properties: type: type: string enum: [username_password] description: Credential type username: type: string description: Username for authentication password: type: string description: Password for authentication AuthenticatorCredential: title: authenticator type: object required: - type - secret properties: type: type: string enum: [authenticator] description: Credential type secret: type: string description: TOTP secret for authenticator otp: type: string description: Optional OTP code CustomFieldItem: type: object required: - name - value properties: name: type: string description: Field name value: type: string description: Field value CustomCredential: title: custom type: object required: - type - fields properties: type: type: string enum: [custom] description: Credential type fields: type: array items: $ref: '#/components/schemas/CustomFieldItem' description: Array of custom fields CredentialData: oneOf: - $ref: '#/components/schemas/UsernamePasswordCredential' - $ref: '#/components/schemas/AuthenticatorCredential' - $ref: '#/components/schemas/CustomCredential' discriminator: propertyName: type CreateIdentityRequest: type: object required: - source properties: name: type: string description: Name of the identity. Defaults to "Unnamed Identity" if not provided. source: type: string format: uri description: The source URL for the identity (e.g., login page URL) credentials: type: array items: $ref: '#/components/schemas/CredentialData' description: | Optional credentials to associate with this identity (for example username/password or authenticator secrets). Omit this field or supply an empty array when you only need an identity for the given source URL and optional metadata. metadata: type: object additionalProperties: true description: Optional metadata for the identity applicationName: type: string description: Optional application name to associate with the identity applicationDescription: type: string description: Optional application description CreateIdentityResponse: type: object properties: id: type: string format: uuid description: Unique identifier for the identity name: type: string description: Name of the identity status: type: string enum: [pending, validated, failed] description: Status of the identity metadata: type: object additionalProperties: true description: Metadata associated with the identity created_at: type: string format: date-time description: Timestamp when the identity was created GetIdentityResponse: type: object properties: id: type: string format: uuid description: Unique identifier for the identity name: type: string description: Name of the identity source: type: string description: Source URL for the identity status: type: string enum: [pending, validated, failed] description: Status of the identity metadata: type: object additionalProperties: true description: Metadata associated with the identity created_at: type: string format: date-time description: Timestamp when the identity was created updated_at: type: string format: date-time description: Timestamp when the identity was last updated UpdateIdentityRequest: type: object properties: name: type: string description: Name of the identity metadata: type: object additionalProperties: true description: Metadata for the identity credentials: type: array items: $ref: '#/components/schemas/CredentialData' description: Array of credentials for authentication UpdateIdentityResponse: type: object properties: id: type: string format: uuid description: Unique identifier for the identity name: type: string description: Name of the identity metadata: type: object additionalProperties: true description: Metadata associated with the identity updated_at: type: string format: date-time description: Timestamp when the identity was last updated DeleteIdentityResponse: type: object properties: message: type: string description: Deletion result message GetIdentityCredentialsResponse: type: object properties: id: type: string format: uuid description: Unique identifier for the identity name: type: string description: Name of the identity source: type: string description: Source URL for the identity credentials: type: array items: $ref: '#/components/schemas/CredentialData' description: Array of credentials with sensitive data # ============================== # IDENTITY TOKEN SCHEMAS # ============================== CreateIdentityTokenRequest: type: object required: - callbackUrl properties: callbackUrl: type: string format: uri description: The HTTPS URL where the user will be redirected after authentication. Must use HTTPS protocol. example: 'https://example.com/callback' IdentityTokenResponse: type: object required: - token - expiresAt - tokenHash properties: token: type: string description: The generated identity token for authentication expiresAt: type: string format: date-time description: The timestamp when the token expires tokenHash: type: string description: A hash of the token for verification purposes WebhookEventType: type: string description: | Catalog of webhook event types Anchor can deliver. Adding a new event type is a coordinated change between session-manager (publisher), webhook-dispatcher (consumer), and the dashboard. enum: - task.completed - task.failed - task.cancelled - task.healed - session.ready - session.completed - session.failed - session.recording.ready - batch.completed - batch.failed - intervention.requested - intervention.resolved - identity.authenticated - identity.authentication_failed WebhookPublic: type: object description: A registered webhook subscription. The signing secret is NEVER returned by GET/list endpoints. required: - id - project_id - url - description - subscribed_events - enabled - created_at - updated_at properties: id: type: string description: Webhook id. Use as the path parameter on subsequent calls. example: wh_01HXJ4MZ7K9P3Q6R8S2T4V5W7Y project_id: type: string format: uuid description: The project (team) the webhook belongs to. example: 5d2c31f6-ab7e-481a-b6fd-8b4a96a4e197 url: type: string format: uri description: HTTPS URL Anchor will POST events to. example: https://your-app.example.com/anchor/webhooks description: type: string nullable: true maxLength: 256 description: Optional human-readable description. example: Production task notifications subscribed_events: type: array description: Event types this webhook is currently subscribed to. items: $ref: '#/components/schemas/WebhookEventType' enabled: type: boolean description: When `false`, no events fan out to this webhook. example: true created_at: type: string format: date-time nullable: true updated_at: type: string format: date-time nullable: true WebhookWithSecret: description: | Same shape as `WebhookPublic` plus the freshly minted signing secret. Returned ONLY by create and rotate-secret. Store it the first time — Anchor never returns it again. If lost, rotate to mint a new one. allOf: - $ref: '#/components/schemas/WebhookPublic' - type: object required: - secret properties: secret: type: string description: HMAC-SHA256 signing secret. Use this to verify the `Anchor-Signature` header on each delivery. example: 36da51b166a69268a59a8d5ee0b32c9f5e5aaee7d301c7a5a36844318e116fc6 WebhookCreateRequest: type: object required: - url - subscribed_events properties: url: type: string format: uri minLength: 1 maxLength: 2048 description: | HTTPS endpoint Anchor will POST events to. Rejected (400) if it points at loopback / private / link-local IPs, cloud metadata services, internal-only TLDs, AWS STS / IAM / EKS endpoints, or contains basic-auth credentials. example: https://your-app.example.com/anchor/webhooks description: type: string maxLength: 256 description: Optional human-readable description. example: Production task notifications subscribed_events: type: array description: Events this webhook should receive. At least one is required. minItems: 1 items: $ref: '#/components/schemas/WebhookEventType' WebhookUpdateRequest: type: object description: Partial update — only the fields you include are changed. properties: url: type: string format: uri minLength: 1 maxLength: 2048 description: type: string nullable: true maxLength: 256 subscribed_events: type: array minItems: 1 items: $ref: '#/components/schemas/WebhookEventType' enabled: type: boolean WebhookListResponse: type: object required: - webhooks properties: webhooks: type: array items: $ref: '#/components/schemas/WebhookPublic' WebhookTestRequest: type: object required: - event_type properties: event_type: $ref: '#/components/schemas/WebhookEventType' WebhookTestResponse: type: object required: - external_event_id - event_type properties: external_event_id: type: string description: The synthetic event id that will appear on the receiver as `id` in the envelope. example: evt_56a4c6e7f11e4b44eafce28a event_type: $ref: '#/components/schemas/WebhookEventType' WebhookEventDeliveryRow: type: object description: One row from the events / deliveries history for a webhook. required: - id - external_event_id - event_type - status - attempt properties: id: type: string description: Internal events-row id (one row per logical delivery to one webhook). external_event_id: type: string description: Customer-facing event id. Same value lands in the envelope `id` field. example: evt_56a4c6e7f11e4b44eafce28a event_type: $ref: '#/components/schemas/WebhookEventType' status: type: string enum: - pending - succeeded - failed - dead description: | * `pending` — accepted; delivery in progress or awaiting retry. * `succeeded` — receiver returned 2xx. * `failed` — receiver returned non-retryable 4xx. * `dead` — exhausted all retry attempts. attempt: type: integer minimum: 0 description: Attempt number for the most recent completed try (0 = no attempt finished yet, 1 = first attempt, ≤ 6 with default policy). response_status: type: integer nullable: true description: HTTP status code from the most recent attempt, if any. error_message: type: string nullable: true scheduled_at: type: string format: date-time nullable: true completed_at: type: string format: date-time nullable: true payload: type: object additionalProperties: true description: > The sanitized event `data` exactly as delivered to your endpoint. Only present when the request sets `include_payload=true`. WebhookEventsListResponse: type: object required: - events - pagination properties: events: type: array items: $ref: '#/components/schemas/WebhookEventDeliveryRow' pagination: type: object required: - limit - offset - total properties: limit: type: integer description: Number of rows in this response (max 100). offset: type: integer description: How many rows were skipped from the beginning of the result set. total: type: integer description: Total matching rows across all pages. WebhookDeleteResponse: type: object required: - ok properties: ok: type: boolean example: true AgentAccessNextStep: type: object required: - method - path - description properties: method: type: string enum: [GET, POST] description: HTTP method for the next call in the Agent Access onboarding flow. path: type: string description: Path on https://api.anchorbrowser.io for the next call. Prepend the method to execute it. description: type: string description: Plain-language instruction for what to do on the next call and what you receive afterward. AgentAccessInstructions: type: object required: - submit - appendix - api_key_header - optional_identity - anonymous_credits - identity_credits properties: submit: type: string description: After solving the puzzle, call this endpoint with { token, answer }. token is from this response; answer is the final integer as a string. appendix: type: string description: Optional path hint from the challenge response. api_key_header: type: string description: After POST succeeds, send the returned api_key using this request header on authenticated API calls. optional_identity: type: string description: Optional identity_token on the same POST for more credits and an agent_identity_token for later calls. anonymous_credits: type: number description: Credits granted when POST omits identity_token or the token has no verified email. identity_credits: type: number description: Credits granted when POST includes identity_token with a verified email. AgentAccessError: type: object required: - error - next - docs properties: error: type: string description: Why the request failed. next: $ref: '#/components/schemas/AgentAccessNextStep' docs: type: string description: Human-readable guide URL for Agent Access. example: https://docs.anchorbrowser.io/quickstart/agent-access paths: /v1/agent-access: get: summary: Agent Access guide description: | Unauthenticated onboarding guide. This GET does **not** issue an API key. Follow the `next` field: GET `/v1/agent-access/challenge`, solve, then POST `/v1/agent-access` with `{ token, answer }`. Optional `identity_token` (OIDC JWT) grants more credits. Docs: https://docs.anchorbrowser.io/quickstart/agent-access tags: - Agent Access security: [] responses: '200': description: Ordered flow. Follow `next`. content: application/json: schema: type: object required: - purpose - docs - credits - ttl_seconds - limits - flow - identity - next properties: purpose: type: string description: What Agent Access is for. docs: type: string description: Human-readable guide URL. credits: type: object required: [anonymous, with_identity] properties: anonymous: type: number description: Credits when onboarding without verified-email identity. with_identity: type: number description: Credits when POST includes identity_token with verified email. ttl_seconds: type: number description: Challenge token TTL in seconds. limits: type: object required: [session_max_duration_minutes] properties: session_max_duration_minutes: type: number description: Maximum session duration in minutes for keys issued through Agent Access. flow: type: array description: All onboarding steps in order. For the immediate action, prefer next. items: type: object required: [step, method, path, why] properties: step: type: number description: Order in the onboarding sequence. method: type: string enum: [GET, POST] description: HTTP method for this step. path: type: string description: Path for this step. why: type: string description: Why this step exists. next: $ref: '#/components/schemas/AgentAccessNextStep' identity: type: object required: [optional, extra_credits, submit, oidc] properties: optional: type: boolean description: Whether identity_token is optional on POST. extra_credits: type: number description: Credits granted with verified-email identity_token. submit: type: string description: How to pass identity_token on POST. oidc: type: array description: Supported OIDC identity providers. items: type: object required: [provider, issuer, how] properties: provider: type: string description: Provider alias (google, github, vercel). issuer: type: string description: Expected JWT iss claim. how: type: string description: How to obtain a token from this provider. '429': description: Too many requests from this source. content: application/json: schema: $ref: '#/components/schemas/AgentAccessError' post: summary: Create Agent Access project description: | Issue an Agent Access API key. Submit the challenge `token` and computed integer `answer` from GET /v1/agent-access/challenge. GET on this path returns a guide, not a key. Optional `identity_token` as an OIDC JWT grants more credits. `identity_provider` is optional when the JWT `iss` is Google (`https://accounts.google.com`), GitHub Actions (`https://token.actions.githubusercontent.com`), or Vercel (`https://vercel.com`). Returns `api_key` for header `anchor-api-key`. Docs: https://docs.anchorbrowser.io/quickstart/agent-access tags: - Agent Access security: [] requestBody: required: true content: application/json: schema: type: object required: - token - answer properties: token: type: string minLength: 1 description: Token returned by GET /v1/agent-access/challenge. Not the puzzle answer. answer: type: string minLength: 1 description: Final integer from the challenge prompt, as a string. identity_provider: type: string description: 'Optional when identity_token is an OIDC JWT whose iss matches a known provider (google, github, or vercel). Required for opaque OAuth access tokens (google or github).' identity_token: type: string description: 'OIDC JWT preferred (iss auto-detected). GitHub Actions — GET $ACTIONS_ID_TOKEN_REQUEST_URL with Authorization bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN. Google — ID token JWT. Vercel — Sign in with Vercel user ID token (iss https://vercel.com). Opaque OAuth access tokens also work with identity_provider set.' identity_audience: type: string description: Optional. Pin the JWT aud claim. Omit unless you requested a specific aud. responses: '200': description: API key issued. Follow `next` to make an authenticated call. content: application/json: schema: type: object required: - api_key - project_id - credits_granted - auth - next - docs - limits properties: api_key: type: string description: API key for authenticated requests. Send as header anchor-api-key. project_id: type: string description: Anchor project id created or reused for this onboarding. credits_granted: type: number description: Credits added by this POST. 0 when the Agent Access project already existed for this owner. agent_identity_token: type: string description: When present, send as header anchor-identity-token on later API calls when auth.identity_token_required is true. auth: type: object required: - api_key_header - identity_token_required properties: api_key_header: type: string description: Header name for api_key (anchor-api-key). identity_token_header: type: string description: Header name for agent_identity_token when identity_token_required is true. identity_token_required: type: boolean description: When true, authenticated API calls must include anchor-identity-token in addition to anchor-api-key. upgrade: type: object required: [message] properties: message: type: string description: How to repeat onboarding with identity_token to receive more credits. next: $ref: '#/components/schemas/AgentAccessNextStep' docs: type: string description: Human-readable guide URL for Agent Access. limits: type: object required: [session_max_duration_minutes] properties: session_max_duration_minutes: type: number description: Maximum session duration in minutes for keys issued through Agent Access. '400': description: Missing token/answer, expired token, or incomplete identity fields. Follow `next`. content: application/json: schema: $ref: '#/components/schemas/AgentAccessError' '401': description: Incorrect answer or invalid identity token. Follow `next`. content: application/json: schema: $ref: '#/components/schemas/AgentAccessError' '429': description: Too many onboarding attempts from this source. content: application/json: schema: $ref: '#/components/schemas/AgentAccessError' '500': description: Failed to create project. content: application/json: schema: $ref: '#/components/schemas/AgentAccessError' /v1/agent-access/challenge: get: summary: Get Agent Access challenge description: Get a puzzle and token. Follow next and challenge.prompt, then POST /v1/agent-access with token and answer. tags: - Agent Access security: [] responses: '200': description: Challenge payload. content: application/json: schema: type: object required: - challenge - token - instructions properties: challenge: type: object required: [id, type, icon, title, description, prompt, timeLimit] properties: id: type: string description: Challenge instance id. type: type: string description: Challenge type (semantic_logic). icon: type: string description: Display icon for UIs. title: type: string description: Short challenge title. description: type: string description: Short challenge summary. prompt: type: string description: Multi-step puzzle text. Follow the instructions to compute the final integer answer. timeLimit: type: number description: Suggested solve time in seconds. token: type: string description: Opaque challenge token. Pass to POST /v1/agent-access as token. This is not the puzzle answer. appendix_ref: type: string appendix_url: type: string instructions: $ref: '#/components/schemas/AgentAccessInstructions' next: $ref: '#/components/schemas/AgentAccessNextStep' '429': description: Too many challenge requests from this source. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Challenge generation failed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/agent-access/appendix/{appendixRef}: get: summary: Agent Access challenge data description: Supporting data for an active Agent Access challenge. Path comes from the challenge response. tags: - Agent Access security: [] parameters: - name: appendixRef in: path required: true schema: type: string responses: '200': description: Appendix payload. content: application/json: schema: type: object required: - appendix_ref - inventory properties: appendix_ref: type: string inventory: type: string description: Text payload for the active challenge. Parse with challenge.prompt to compute the final integer answer. next: $ref: '#/components/schemas/AgentAccessNextStep' '404': description: Appendix expired or unknown. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Too many requests from this source. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/tools/perform-web-task: post: summary: Perform Web Task description: Start from a URL and perform the given task. tags: - AI Tools security: - api_key_header: [] parameters: - in: query name: sessionId schema: type: string title: Browser Session description: An optional browser session identifier to reference an existing running browser sessions. When passed, the tool will be executed on the provided browser session. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PerformWebTaskRequestSchema' responses: '200': description: The result of the autonomous task. content: application/json: schema: $ref: '#/components/schemas/PerformWebTaskResponseSchema' examples: sync: summary: Synchronous response value: data: result: result: nodes_cpu_usage: - node: 'pool-e1ro5g0nq-559g5' cluster: 'do-nyc1-demo-infra' cpu_avg_percentage: 8.29 - node: 'pool-e1ro5g0nq-559gk' cluster: 'do-nyc1-demo-infra' cpu_avg_percentage: 24.8 async: summary: Asynchronous response value: data: status: 'running' workflow_id: 'perform-web-task-execution-123e4567-e89b-12d3-a456-426614174000-550e8400-e29b-41d4-a716-446655440000' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/tools/perform-web-task/{workflowId}/status: get: summary: Get Perform Web Task Status description: Get the status of an asynchronous perform-web-task execution by workflow ID. tags: - AI Tools security: - api_key_header: [] parameters: - in: path name: workflowId required: true schema: type: string description: The workflow ID returned when starting an asynchronous perform-web-task execution. responses: '200': description: The current status of the task execution. content: application/json: schema: $ref: '#/components/schemas/PerformWebTaskStatusResponseSchema' examples: completed: summary: Completed workflow value: data: status: 'COMPLETED' sessionId: '550e8400-e29b-41d4-a716-446655440000' result: nodes_cpu_usage: - node: 'pool-e1ro5g0nq-559g5' cluster: 'do-nyc1-demo-infra' cpu_avg_percentage: 8.29 - node: 'pool-e1ro5g0nq-559gk' cluster: 'do-nyc1-demo-infra' cpu_avg_percentage: 24.8 running: summary: Running workflow value: data: status: 'RUNNING' sessionId: '550e8400-e29b-41d4-a716-446655440000' failed: summary: Failed workflow value: data: status: 'FAILED' sessionId: '550e8400-e29b-41d4-a716-446655440000' error: 'Maximum number of steps exceeded' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/sessions: get: summary: List Sessions History Page description: | Retrieves a paginated list of sessions for the authenticated team with support for sorting and advanced filtering. This endpoint mirrors the backend session history-page filtering behavior. security: - api_key_header: [] tags: - Browser Sessions parameters: - in: query name: page required: false description: Page number to fetch. schema: type: integer minimum: 1 default: 1 - in: query name: limit required: false description: Number of sessions per page. Supported values are 10, 20, and 50. schema: type: integer enum: [10, 20, 50] default: 10 - in: query name: sort_by required: false description: | Sort field. Common values are `created_at`, `session_id`, `used_credits`, `created_at`, and `api_key_name`. schema: type: string default: created_at - in: query name: sort_order required: false description: Sort direction. schema: type: string enum: [asc, desc] default: asc - in: query name: search required: false description: Comma-separated tag search terms (partial, case-insensitive). schema: type: string - in: query name: status required: false description: Exact session status filter. schema: type: string - in: query name: tags required: false description: Comma-separated tag list. Session must include all provided tags. schema: type: string example: production,scraping - in: query name: domains required: false description: Comma-separated domain list. Session must include all provided domains. schema: type: string example: example.com,anchorbrowser.io - in: query name: created_from required: false description: Include sessions created at or after this timestamp (ISO 8601). schema: type: string format: date-time - in: query name: created_to required: false description: Include sessions created at or before this timestamp (ISO 8601). schema: type: string format: date-time - in: query name: batch_id required: false description: Filter by batch identifier. schema: type: string - in: query name: task_initiated required: false description: Filter by whether the session was task-initiated. schema: type: boolean - in: query name: proxy required: false description: Filter by whether proxy was active for the session. schema: type: boolean - in: query name: extra_stealth required: false description: Filter by whether extra stealth mode was active. schema: type: boolean - in: query name: profile_name required: false description: Case-insensitive partial match on browser profile name. schema: type: string example: Default profile responses: '200': description: Paginated sessions history retrieved successfully. content: application/json: schema: $ref: '#/components/schemas/SessionHistoryPageResponse' examples: filteredSessionsPage: summary: Example filtered session page value: data: sessions: - id: sess_123456 status: completed tags: ['production', 'scraping'] headless: false recording: true used_credits: 12.5 proxy_bytes: 102400 proxy_type: anchor_proxy steps: 48 duration: 420 created_at: '2026-03-09T12:34:56.789Z' user_configuration: session: idle_timeout: 300 task_initiated: true task_executions_count: 2 api_key_name: automation-key browser_ip: 192.0.2.10 domains: ['example.com'] total: 145 page: 1 total_pages: 15 '400': description: Invalid query parameters (for example unsupported limit or sort options). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' post: summary: Start Browser Session description: Allocates a new browser session for the user, with optional configurations for ad-blocking, captcha solving, proxy usage, and idle timeout. security: - api_key_header: [] tags: - Browser Sessions requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/SessionCreateRequestSchema' responses: '200': description: Successfully returned a browser object content: application/json: schema: $ref: '#/components/schemas/SessionCreateResponseSchema' '400': description: Bad Request - Invalid request parameters or configuration. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: captchaSolverRequiresProxy: summary: CAPTCHA solver requires proxy to be active. value: error: code: 400 message: CAPTCHA solver requires proxy to be active. '402': description: Payment Required - Insufficient credits to allocate a new browser content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Too many requests — session creation rate limit exceeded. headers: RateLimit: description: | IETF draft-8 Rate-limit headers. schema: type: string example: '"5-in-1min"; r=0; t=58' RateLimit-Policy: schema: type: string example: '"5-in-1min"; q=5; w=60; pk=:ZGQ0YzBjYzVhZjQ1:' Retry-After: description: Seconds until the rate-limit window resets (matches the `t` parameter in `RateLimit` when the limit is exceeded). schema: type: integer example: 58 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: sessionCreationRateLimited: summary: Session creation rate limit exceeded value: error: code: 429 message: Session creation rate limit exceeded. /v1/sessions/async: post: summary: Start Browser Session (async) description: | Non-blocking variant of `POST /v1/sessions`. Returns a `request_id` immediately and provisions the underlying browser pod in the background. Poll `GET /v1/sessions/async/{request_id}/status` until `status` becomes `ready` to obtain the resolved `session_id`, `cdp_url` and `live_view_url`. security: - api_key_header: [] tags: - Browser Sessions requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/SessionCreateRequestSchema' responses: '200': description: Async session creation accepted; poll the status endpoint to resolve. content: application/json: schema: $ref: '#/components/schemas/AsyncSessionCreateResponseSchema' '400': description: Invalid request parameters or configuration. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '402': description: Payment Required - Insufficient credits. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Project cost limit reached. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: API key would exceed batch browser limit. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/sessions/async/{request_id}/status: get: summary: Async Session Status description: | Polling endpoint paired with `POST /v1/sessions/async`. Returns the current lifecycle `status` of the async request and, once the pod is up, the embedded `session` object containing `session_id`, `cdp_url` and `live_view_url`. security: - api_key_header: [] tags: - Browser Sessions parameters: - name: request_id in: path required: true description: The `request_id` returned from `POST /v1/sessions/async`. schema: type: string format: uuid responses: '200': description: Async session status retrieved successfully. content: application/json: schema: $ref: '#/components/schemas/AsyncSessionStatusResponseSchema' '401': description: Invalid API Key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Async request not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/sessions/all: delete: summary: End All Sessions description: Terminates all active browser sessions associated with the provided API key. tags: - Browser Sessions security: - api_key_header: [] responses: '200': description: Successfully terminated all active browser sessions. content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' /v1/sessions/all/status: get: summary: List All Sessions Status description: Retrieves status information for all browser sessions associated with the API key. security: - api_key_header: [] tags: - Browser Sessions parameters: - in: query name: tags required: false description: Comma-separated list of session tags to filter by. Sessions must contain all provided tags. schema: type: string example: production,scraping - in: query name: domains required: false description: Comma-separated list of domains to filter by. Sessions must contain all provided domains. schema: type: string example: example.com,anchorbrowser.io - in: query name: created_from required: false description: Include sessions created at or after this timestamp (ISO 8601). schema: type: string format: date-time - in: query name: created_to required: false description: Include sessions created at or before this timestamp (ISO 8601). schema: type: string format: date-time - in: query name: batch_id required: false description: Filter sessions by batch identifier. schema: type: string - in: query name: task_initiated required: false description: Filter by whether the session was initiated by a task. schema: type: boolean - in: query name: proxy required: false description: Filter by whether proxy was active for the session. schema: type: boolean - in: query name: extra_stealth required: false description: Filter by whether extra stealth mode was active for the session. schema: type: boolean - in: query name: profile_name required: false description: Filter sessions by browser profile name (case-insensitive partial match). schema: type: string example: Default profile responses: '200': description: Successfully retrieved status for all browser sessions content: application/json: schema: $ref: '#/components/schemas/SessionListResponse' '401': description: Invalid API Key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/sessions/history: get: summary: Get Sessions History description: Retrieves session usage analytics for the authenticated team. security: - api_key_header: [] tags: - Browser Sessions parameters: - in: query name: from_date required: false description: Start date for filtering (ISO 8601 format). schema: type: string format: date-time - in: query name: to_date required: false description: End date for filtering (ISO 8601 format). schema: type: string format: date-time - in: query name: granularity required: false description: Time granularity for aggregation. schema: type: string enum: [hour, day, week, month] default: day - in: query name: metrics required: false description: Metrics to include in the response. schema: oneOf: - type: string - type: array items: type: string enum: - session_count - proxy_bytes - ai_steps - session_hours - credits_used - screenshots - network_bytes_total default: - session_count - in: query name: page required: false description: Page number for pagination. schema: type: integer minimum: 1 default: 1 - in: query name: limit required: false description: Number of records per page. schema: type: integer minimum: 1 maximum: 1000 default: 100 responses: '200': description: Session history analytics retrieved successfully. content: application/json: schema: $ref: '#/components/schemas/SessionHistoryResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/sessions/{session_id}: get: summary: Get Browser Session description: Retrieves detailed information about a specific browser session. tags: - Browser Sessions parameters: - in: path name: session_id required: true description: The ID of the session to retrieve. schema: type: string security: - api_key_header: [] responses: '200': description: Session retrieved successfully. content: application/json: schema: type: object properties: data: type: object description: The session data. properties: session_id: type: string description: The unique identifier of the session. team_id: type: string description: The team ID associated with the session. duration: type: integer description: The duration of the session in seconds. status: type: string description: The current status of the session. credits_used: type: number description: The number of credits consumed by the session. configuration: type: object description: The configuration settings for the session. proxy_bytes: type: integer description: The number of bytes transferred through the proxy. tokens: type: object description: Token usage information. steps: type: integer description: Number of AI agent steps executed in the session. tags: type: array items: type: string description: Tags associated with the session. created_at: type: string format: date-time description: The timestamp when the session was created. '404': description: Session not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to fetch session. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' delete: summary: End Browser Session description: Deletes the browser session associated with the provided browser session ID. Requires a valid API key for authentication. tags: - Browser Sessions parameters: - in: path name: session_id required: true description: The ID of the browser session to end. schema: type: string security: - api_key_header: [] responses: '200': description: Browser session ended successfully. content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' '401': description: Invalid API Key or browser session ID content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/sessions/{session_id}/tags: get: summary: Get Session Tags description: Retrieves the tags associated with a specific browser session. tags: - Browser Sessions parameters: - in: path name: session_id required: true description: The ID of the session to retrieve tags for. schema: type: string security: - api_key_header: [] responses: '200': description: Session tags retrieved successfully. content: application/json: schema: $ref: '#/components/schemas/SessionTagsResponse' '400': description: Session ID is required. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Invalid API Key or unauthorized access. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Session not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to fetch session tags. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' put: summary: Put Session Tags description: | Create or replace tags on a browser session. This overwrites any existing tags with the provided list. See [Session Tags](/advanced/session-tags). tags: - Browser Sessions parameters: - in: path name: session_id required: true description: The ID of the session to update tags for. schema: type: string security: - api_key_header: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/putSessionTags' responses: '200': description: Session tags updated successfully. content: application/json: schema: $ref: '#/components/schemas/SessionTagsMutationResponse' '400': description: Invalid request or missing session ID. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Invalid API Key or unauthorized access. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Session not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to update session tags. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' delete: summary: Delete Session Tags description: Clears all tags from a browser session. tags: - Browser Sessions parameters: - in: path name: session_id required: true description: The ID of the session to clear tags for. schema: type: string security: - api_key_header: [] responses: '200': description: Session tags deleted successfully. content: application/json: schema: $ref: '#/components/schemas/SessionTagsMutationResponse' '400': description: Session ID is required. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Invalid API Key or unauthorized access. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Session not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to delete session tags. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/sessions/{session_id}/pages: get: summary: Get Browser Session Pages description: Retrieves a list of pages associated with a specific browser session. tags: - Browser Sessions parameters: - in: path name: session_id required: true description: The ID of the session to retrieve pages for. schema: type: string security: - api_key_header: [] responses: '200': description: Session pages retrieved successfully. content: application/json: schema: type: object properties: data: type: object properties: count: type: number description: The number of pages returned. items: type: array items: type: object properties: id: type: string description: The unique identifier of the page. title: type: string description: The title of the page. url: type: string description: The URL of the page. frontend_url: type: string description: The frontend URL for accessing the page. required: - id - title - url - frontend_url required: - count - items required: - data '401': description: Invalid API Key or unauthorized access. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Session not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/sessions/{sessionId}/uploads: post: summary: Upload Files description: | Upload files directly to a browser session for use with web forms and file inputs. Files are saved to the session's uploads directory and can be referenced in CDP commands (for example `DOM.setFileInputFiles`). The saved paths are returned in `file_paths`. A `.zip` upload is unpacked into the uploads directory by default and the archive itself is not kept. Pass `extract=false` to store the archive as-is, for example to attach the zip itself to a file input. security: - api_key_header: [] tags: - Browser Sessions parameters: - name: sessionId in: path required: true description: The browser session ID schema: type: string format: uuid - name: extract in: query required: false description: | Whether a `.zip` upload is unpacked into the uploads directory. Defaults to `true`. Set to `false` to keep the archive itself so it can be attached to a file input as-is. Any other value is treated as `true`. Has no effect on non-zip files. schema: type: string enum: - 'true' - 'false' default: 'true' requestBody: required: true content: multipart/form-data: schema: type: object required: - file properties: file: type: string format: binary description: File to upload to the browser session responses: '200': description: File uploaded successfully content: application/json: schema: type: object properties: data: type: object properties: status: type: string message: type: string file_paths: type: array description: Absolute paths of the saved files inside the session (the archive entries when a zip was extracted) items: type: string '400': description: Invalid request (no file uploaded or file too large) content: application/json: schema: type: object properties: error: type: object properties: code: type: integer message: type: string '404': description: Session not found content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to upload file content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/ErrorResponse' /v1/sessions/{session_id}/downloads: get: summary: List Session Downloads description: Retrieves metadata of files downloaded during a browser session. Requires a valid API key for authentication. tags: - Browser Sessions parameters: - in: path name: session_id required: true description: The unique identifier of the browser session to retrieve downloads for. schema: type: string security: - api_key_header: [] responses: '200': description: A list of download metadata associated with the browser session. content: application/json: schema: $ref: '#/components/schemas/DownloadListResponse' '401': description: Invalid or missing API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: The browser session or its downloads metadata could not be found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Too many requests, please try again later. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v2/tasks/{taskId}/run: post: summary: Run a Task description: | Triggers execution of a task by ID using the non-deprecated Tasks endpoints. security: - api_key_header: [] tags: - Tasks parameters: - name: taskId in: path required: true description: The ID of the task to run schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RunTaskV2Request' examples: runTaskV2: summary: Run a task with input parameters value: input_params: File Name: 'invoice-2026-02.pdf' Operation: 'extract_text' responses: '200': description: Task run started successfully content: application/json: schema: $ref: '#/components/schemas/TaskRunStatusV2Response' '404': description: Task not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to run task content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v2/tasks/runs/{runId}/status: get: summary: Get Task Run Status description: | Retrieves the current status and result of a task run in the non-deprecated Tasks endpoints. security: - api_key_header: [] tags: - Tasks parameters: - name: runId in: path required: true description: The ID of the task run schema: type: string responses: '200': description: Task run status retrieved successfully content: application/json: schema: $ref: '#/components/schemas/TaskRunStatusV2Response' '404': description: Task run not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to retrieve task run status content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v2/tasks/generate: post: summary: Generate a Task description: | Starts asynchronous generation of a new task from a natural-language prompt. Poll `GET /v2/tasks/{taskId}/generation-status` until the status is `ready`. security: - api_key_header: [] tags: - Tasks requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GenerateTaskV2Request' examples: generateTask: summary: Generate a task from a prompt value: taskName: file-downloader taskPrompt: Create a task that downloads a specific file from a given URL. input_schema: - name: url type: string required: true description: URL of the file to download output_schema: - name: success type: boolean description: Whether the download succeeded responses: '200': description: Task generation started content: application/json: schema: $ref: '#/components/schemas/GenerateTaskV2Response' '400': description: Invalid task generation request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error generating task content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v2/tasks/{taskId}/generation-status: get: summary: Get Task Generation Status description: | Returns the generation status of a task created via `POST /v2/tasks/generate`. security: - api_key_header: [] tags: - Tasks parameters: - name: taskId in: path required: true description: The ID of the task schema: type: string responses: '200': description: Current generation status content: application/json: schema: $ref: '#/components/schemas/TaskGenerationStatusV2Response' '404': description: Task not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to get task generation status content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/tools/execute-code: post: summary: Execute Code Snippet description: Run a TypeScript snippet in the sandbox against the browser session (query `sessionId` required). tags: - Tools security: - api_key_header: [] parameters: - in: query name: sessionId required: true schema: type: string format: uuid description: Browser session to run the snippet against. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExecuteCodeRequestSchema' responses: '200': description: Snippet execution finished. content: application/json: schema: $ref: '#/components/schemas/ExecuteCodeToolResponseSchema' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/tools/fetch/webpage: post: summary: Web Unlocker description: | Fetch the fully rendered HTML of any URL — including CAPTCHA- and bot-protected sites — with a single sessionless request. Each request runs in a stealth browser behind a residential proxy. JavaScript is fully rendered, cookie-consent dialogs are dismissed, and CAPTCHA or bot-detection challenges (Cloudflare, reCAPTCHA, FunCaptcha, DataDome, Kasada, Akamai) are solved automatically — you receive the page behind the challenge, never the interstitial. No browser session is created and the request does not count against your concurrent-browser limit. **Response:** the page body is returned directly (not wrapped in JSON). HTML pages return `text/html`; PDFs and file downloads are passed through as binary with their original content type and a `Content-Disposition: attachment` header. **Limits:** 2,000 requests per minute per API key by default. Requests can take up to about two minutes when a challenge must be solved, so configure client timeouts of at least 120 seconds. **Billing:** 0.005 credits per `200` response, regardless of page content. `4xx` and `5xx` responses are not billed. See the [Web Unlocker guide](/advanced/web-unlocker) for examples, retry guidance, and a comparison with browser sessions. tags: - Tools security: - api_key_header: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebUnlockerRequestSchema' responses: '200': description: | Page content returned successfully. The body is the resource itself, not a JSON envelope. The `Content-Type` header reflects the target: HTML pages return `text/html`; PDFs and file downloads are returned as binary with `Content-Disposition: attachment`; other resources keep their upstream content type. content: text/html: schema: type: string description: The rendered HTML content of the webpage. application/pdf: schema: type: string format: binary description: The PDF file when the URL points to a PDF. text/csv: schema: type: string format: binary description: A CSV file when the URL triggers a CSV download. application/octet-stream: schema: type: string format: binary description: Any other file download (XLSX, ZIP, …). application/json: schema: description: The upstream JSON body, passed through unchanged when the URL serves JSON. application/xml: schema: type: string description: The upstream XML body, passed through unchanged when the URL serves XML. text/plain: schema: type: string description: The upstream plain-text body, passed through unchanged when the URL serves plain text. '400': description: Invalid request — check the URL and try again. content: application/json: schema: $ref: '#/components/schemas/WebUnlockerErrorResponse' '402': description: Insufficient credits balance. content: application/json: schema: $ref: '#/components/schemas/WebUnlockerErrorResponse' '403': description: Project cost limit reached. content: application/json: schema: $ref: '#/components/schemas/WebUnlockerErrorResponse' '422': description: Could not reach the requested URL, the hostname did not resolve, or the challenge could not be solved. content: application/json: schema: $ref: '#/components/schemas/WebUnlockerErrorResponse' '429': description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to fetch the requested page. content: application/json: schema: $ref: '#/components/schemas/WebUnlockerErrorResponse' '503': description: Service temporarily unavailable — retry with backoff. content: application/json: schema: $ref: '#/components/schemas/WebUnlockerErrorResponse' '504': description: The page took too long to load. content: application/json: schema: $ref: '#/components/schemas/WebUnlockerErrorResponse' /v1/tools/screenshot: post: summary: Screenshot Webpage description: This endpoint captures a screenshot of the specified webpage using Chromium. Users can customize the viewport dimensions and capture options. tags: - Tools security: - api_key_header: [] parameters: - in: query name: sessionId schema: type: string description: An optional browser session identifier to reference an existing running browser sessions. When passed, the tool will be executed on the provided browser session. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ScreenshotRequestSchema' responses: '200': description: Screenshot successfully captured. content: image/png: schema: type: string format: binary '400': description: Invalid input parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to take screenshot. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/tools/page-pdf: post: summary: Get Page PDF description: Generates a PDF of the current page for a browser session and returns it as a binary PDF file. tags: - Tools security: - api_key_header: [] parameters: - in: query name: sessionId required: false schema: type: string format: uuid description: Optional browser session ID. If omitted, `url` in the request body is required. requestBody: required: true content: application/json: schema: type: object required: - url properties: url: type: string format: uri description: The URL of the page to print to PDF. landscape: type: boolean description: Paper orientation. Defaults to false. displayHeaderFooter: type: boolean description: Display header and footer. Defaults to false. printBackground: type: boolean description: Print background graphics. Defaults to false. scale: type: number minimum: 0.1 maximum: 2 description: Scale of the webpage rendering. Defaults to 1. paperWidth: type: number exclusiveMinimum: 0 description: Paper width in inches. Defaults to 8.5. paperHeight: type: number exclusiveMinimum: 0 description: Paper height in inches. Defaults to 11. marginTop: type: number minimum: 0 description: Top margin in inches. Defaults to ~0.4. marginBottom: type: number minimum: 0 description: Bottom margin in inches. Defaults to ~0.4. marginLeft: type: number minimum: 0 description: Left margin in inches. Defaults to ~0.4. marginRight: type: number minimum: 0 description: Right margin in inches. Defaults to ~0.4. pageRanges: type: string pattern: '^\d+(-\d+)?(,\s*\d+(-\d+)?)*$' description: "Page ranges to print, e.g. '1-5, 8, 11-13'. Defaults to all pages." headerTemplate: type: string description: HTML template for the print header. footerTemplate: type: string description: HTML template for the print footer. preferCSSPageSize: type: boolean description: Prefer page size as defined by CSS. Defaults to false. responses: '200': description: PDF generated successfully content: application/pdf: schema: type: string format: binary '400': description: Invalid parameters content: application/json: schema: type: object properties: error: type: string details: type: array items: type: string '404': description: Session not found content: application/json: schema: type: object properties: error: type: string '500': description: Failed to generate PDF content: application/json: schema: type: object properties: error: type: string /v1/applications: post: summary: Create Application description: | Creates a new application for identity management. security: - api_key_header: [] tags: - Applications requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateApplicationRequest' examples: createApplication: summary: Create a new application value: source: 'https://example.com' name: 'Example App' description: 'An example application' responses: '201': description: Application created successfully content: application/json: schema: $ref: '#/components/schemas/CreateApplicationResponse' '400': description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to create application content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' get: summary: List Applications description: | Retrieves all applications for the authenticated team. security: - api_key_header: [] tags: - Applications parameters: - name: search in: query required: false description: Search query to filter applications by name schema: type: string responses: '200': description: List of applications retrieved successfully content: application/json: schema: $ref: '#/components/schemas/ListApplicationsResponse' '500': description: Failed to list applications content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/applications/{applicationId}: get: summary: Get Application description: | Retrieves details of a specific application by its ID. security: - api_key_header: [] tags: - Applications parameters: - name: applicationId in: path required: true description: The ID of the application to retrieve schema: type: string format: uuid responses: '200': description: Application details retrieved successfully content: application/json: schema: $ref: '#/components/schemas/GetApplicationResponse' '404': description: Application not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to get application content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' delete: summary: Delete Application description: | Deletes an existing application. security: - api_key_header: [] tags: - Applications parameters: - name: applicationId in: path required: true description: The ID of the application to delete schema: type: string format: uuid responses: '200': description: Application deleted successfully content: application/json: schema: $ref: '#/components/schemas/DeleteApplicationResponse' '404': description: Application not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to delete application content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/applications/{applicationId}/identities: get: summary: List Application Identities description: | Retrieves all identities associated with a specific application. security: - api_key_header: [] tags: - Applications parameters: - name: applicationId in: path required: true description: The ID of the application schema: type: string format: uuid - name: search in: query required: false description: Search query to filter identities by name schema: type: string - name: metadata in: query required: false description: Filter identities by metadata. Pass a **JSON object** to filter identities whose metadata contains the specified key-value pairs. schema: type: string additionalProperties: true style: deepObject explode: true example: department: 'Engineering' role: 'admin' responses: '200': description: List of identities retrieved successfully content: application/json: schema: $ref: '#/components/schemas/ListApplicationIdentitiesResponse' '500': description: Failed to list application identities content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/applications/{applicationId}/auth-flows: get: summary: List Application Authentication Flows description: | Retrieves all authentication flows for a specific application. security: - api_key_header: [] tags: - Applications parameters: - name: applicationId in: path required: true description: The ID of the application schema: type: string format: uuid responses: '200': description: List of authentication flows retrieved successfully content: application/json: schema: $ref: '#/components/schemas/ListApplicationAuthFlowsResponse' '500': description: Failed to list application authentication flows content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' post: summary: Create Authentication Flow description: | Creates a new authentication flow for an application. security: - api_key_header: [] tags: - Applications parameters: - name: applicationId in: path required: true description: The ID of the application schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAuthFlowRequest' examples: createAuthFlow: summary: Create an authentication flow with username/password value: name: 'Standard Login' description: 'Username and password authentication' is_recommended: true methods: ['username_password'] custom_fields: [] responses: '201': description: authentication flow created successfully content: application/json: schema: $ref: '#/components/schemas/CreateAuthFlowResponse' '400': description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to create authentication flow content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/applications/{applicationId}/auth-flows/{authFlowId}: patch: summary: Update Authentication Flow description: | Updates an existing authentication flow. security: - api_key_header: [] tags: - Applications parameters: - name: applicationId in: path required: true description: The ID of the application schema: type: string format: uuid - name: authFlowId in: path required: true description: The ID of the authentication flow to update schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateAuthFlowRequest' examples: updateAuthFlow: summary: Update authentication flow name and methods value: name: 'Updated Login Flow' methods: ['username_password', 'authenticator'] responses: '200': description: authentication flow updated successfully content: application/json: schema: $ref: '#/components/schemas/UpdateAuthFlowResponse' '500': description: Failed to update authentication flow content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' delete: summary: Delete Authentication Flow description: | Deletes an existing authentication flow. security: - api_key_header: [] tags: - Applications parameters: - name: applicationId in: path required: true description: The ID of the application schema: type: string format: uuid - name: authFlowId in: path required: true description: The ID of the authentication flow to delete schema: type: string format: uuid responses: '200': description: authentication flow deleted successfully content: application/json: schema: $ref: '#/components/schemas/DeleteAuthFlowResponse' '500': description: Failed to delete authentication flow content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/applications/{applicationId}/tokens: post: summary: Create Identity Token description: | Creates an identity token for a specific application. This token is used to initiate an authentication flow for linking user identities to the application. The callback URL must use HTTPS and is where the user will be redirected after authentication. security: - api_key_header: [] tags: - Applications parameters: - name: applicationId in: path required: true description: The unique identifier of the application schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateIdentityTokenRequest' examples: createToken: summary: Create an identity token value: callbackUrl: 'https://example.com/auth/callback' responses: '201': description: Identity token created successfully content: application/json: schema: $ref: '#/components/schemas/IdentityTokenResponse' '400': description: Invalid request - callbackUrl must be a valid HTTPS URL content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Application not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to create identity token content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/identities: post: summary: Create Identity description: | Creates a new identity for the given source. Credentials are optional. security: - api_key_header: [] tags: - Identities parameters: - name: validateAsync in: query required: false description: Whether to validate the identity asynchronously. Defaults to true. schema: type: boolean default: true requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateIdentityRequest' examples: createEmptyIdentity: summary: Minimal create request (source only, no credentials) value: name: 'My Work Account' source: 'https://example.com/login' createIdentityWithPassword: summary: Create identity with username/password credential value: name: 'My Work Account' source: 'https://example.com/login' credentials: - type: 'username_password' username: 'user@example.com' password: 'securepassword123' metadata: department: 'Engineering' createIdentityWithAuthenticator: summary: Create identity with authenticator value: name: 'Two-Factor Account' source: 'https://secure.example.com/login' credentials: - type: 'username_password' username: 'user@example.com' password: 'securepassword123' - type: 'authenticator' secret: 'JBSWY3DPEHPK3PXP' responses: '201': description: Identity created successfully content: application/json: schema: $ref: '#/components/schemas/CreateIdentityResponse' '400': description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to create identity content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/identities/{identityId}: get: summary: Get Identity description: | Retrieves details of a specific identity by its ID. security: - api_key_header: [] tags: - Identities parameters: - name: identityId in: path required: true description: The ID of the identity to retrieve schema: type: string format: uuid responses: '200': description: Identity details retrieved successfully content: application/json: schema: $ref: '#/components/schemas/GetIdentityResponse' '404': description: Identity not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to get identity content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' put: summary: Update Identity description: | Updates an existing identity's name, metadata, or credentials. security: - api_key_header: [] tags: - Identities parameters: - name: identityId in: path required: true description: The ID of the identity to update schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateIdentityRequest' examples: updateIdentityName: summary: Update identity name value: name: 'Updated Account Name' updateIdentityCredentials: summary: Update identity credentials value: credentials: - type: 'username_password' username: 'newuser@example.com' password: 'newpassword123' responses: '200': description: Identity updated successfully content: application/json: schema: $ref: '#/components/schemas/UpdateIdentityResponse' '404': description: Identity not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to update identity content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' delete: summary: Delete Identity description: | Deletes an existing identity. security: - api_key_header: [] tags: - Identities parameters: - name: identityId in: path required: true description: The ID of the identity to delete schema: type: string format: uuid responses: '200': description: Identity deleted successfully content: application/json: schema: $ref: '#/components/schemas/DeleteIdentityResponse' '404': description: Identity not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to delete identity content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/identities/{identityId}/reauthenticate: post: summary: Reauthenticate Identity description: | Re-authenticates an identity on demand: validates the saved browser profile and runs login if it is no longer signed in, then persists the refreshed profile and tears the temporary session down. Equivalent to a session with `identity_skip_validation: false` that ends after auth. security: - api_key_header: [] tags: - Identities parameters: - name: identityId in: path required: true description: The ID of the identity to reauthenticate schema: type: string format: uuid requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/ReauthenticateIdentityRequest' examples: syncReauthenticate: summary: Wait for authentication to finish (default) value: sync: true asyncReauthenticate: summary: Start authentication in the background value: sync: false responses: '200': description: Identity reauthentication started or completed content: application/json: schema: $ref: '#/components/schemas/ReauthenticateIdentityResponse' '401': description: Missing API key for team content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Identity not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '412': description: Identity has no credentials to authenticate with content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Identity authentication failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to reauthenticate identity content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/identities/dynamic/start/{session_id}: post: summary: Start Dynamic Auth Flow description: | Starts (or restarts) a dynamic auth flow in an existing browser session. `session_id` is required in the path. Advances until the next presentation (`decision`, `form`, `detection_failed`, `authenticated`, or `failed`). If the response is `detection_failed` with `retryable: true`, or the request times out, keep polling `GET /v1/identities/dynamic/state/{session_id}` — some login steps take longer than a single start/resolve call. If `detection_failed` and `retryable` is false, open `live_view_url` to finish signing in. Do not treat a timeout as a hard stop until `view.type` is `failed` or `detection_failed` and `retryable` is false. security: - api_key_header: [] tags: - Identities parameters: - name: session_id in: path required: true description: Active browser session that will drive the login. schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AuthFlowV2StartRequest' examples: startLogin: summary: Start at a login URL value: url: 'https://example.com/login' host: 'example.com' responses: '200': description: First presentation of the auth flow content: application/json: schema: $ref: '#/components/schemas/AuthFlowV2View' examples: decision: summary: Decision — choose one of several sign-in methods value: type: decision session_id: abc-123 host: example.com current_step_label: Sign in step_id: root/login options: - step_id: root/login/password label: Email and password automatable: true - step_id: root/login/google label: Continue with Google automatable: false - step_id: root/login/sso label: Continue with SSO automatable: false form: summary: Form — choose an option, then submit its values value: type: form session_id: abc-123 host: example.com current_step_label: Sign in step_id: root/credentials options: - type: credentials automatable: true inputs: - name: username type: text label: Email - name: password type: password label: Password - type: gmail_one_click_integration automatable: true inputs: - name: gmail_tokens type: text label: Gmail token '400': description: Invalid request or host does not match url hostname content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Session not found or not active content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Auth flow transition already in progress, or navigation/discovery failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to start auth flow content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/identities/dynamic/state/{session_id}: get: summary: Get Dynamic Auth Flow State description: | Read-only snapshot of an in-progress dynamic auth flow. Does not acquire the flow lock or mutate state. Poll this endpoint when: - start/resolve returned `type: detection_failed` with `retryable: true` (the next login step is still being determined and may take longer than the request timeout) - start/resolve timed out or returned 409 while a transition is in flight - you need the current presentation without submitting an answer `view` is that presentation — the same object start/resolve return. Treat it as the live step when `phase` is `settled`. While `phase` is `navigating`, `view` may already describe the next step; `target` is only a progress label for the in-flight transition. Keep polling until `view.type` is `decision`, `form`, `authenticated`, a non-retryable `detection_failed`, or a non-retryable `failed`. Then call `/resolve` only for `decision`/`form`, `/finalize` for `authenticated`, or open `live_view_url` for `detection_failed`. security: - api_key_header: [] tags: - Identities parameters: - name: session_id in: path required: true description: Session whose auth flow state to read. schema: type: string responses: '200': description: Current auth flow state content: application/json: schema: $ref: '#/components/schemas/AuthFlowV2State' '404': description: Auth flow not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to read auth flow state content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/identities/dynamic/resolve/{session_id}: post: summary: Resolve Dynamic Auth Flow Step description: | Advances the flow by answering the current step. The body depends on the last presentation's `type` — do not mix the two shapes: - **`decision`**: send only `choice` (a `step_id` from `options`). Do not send `option_index` or `values`. - **`form`**: send `option_index` (index into `options`) and `values` (field name → string). Do not send `choice`. Do not call `/resolve` for `detection_failed`, `authenticated`, or `failed`. For retryable `detection_failed`, a timeout, or a 409 (another transition still in flight), poll `GET .../state/{session_id}` until a `decision`/`form`/`authenticated` view appears, then continue. If `detection_failed` is not retryable, open `live_view_url` to finish signing in. security: - api_key_header: [] tags: - Identities parameters: - name: session_id in: path required: true description: Session whose auth flow to advance. schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AuthFlowV2ResolveRequest' examples: form: summary: Submit values for a form option description: | Use the same shape for every form option. For an email MFA option, send `gmail_tokens` in `values` instead of username and password. value: option_index: 0 values: username: 'user@example.com' password: 'secret' decision: summary: Choose one option from a decision response value: choice: '' responses: '200': description: Next presentation of the auth flow content: application/json: schema: $ref: '#/components/schemas/AuthFlowV2View' examples: decision: summary: Next step asks you to choose a sign-in method value: type: decision session_id: abc-123 host: example.com current_step_label: Sign in step_id: root/login options: - step_id: root/login/password label: Email and password automatable: true - step_id: root/login/google label: Continue with Google automatable: false - step_id: root/login/sso label: Continue with SSO automatable: false form: summary: Next step asks you to submit form values value: type: form session_id: abc-123 host: example.com current_step_label: Sign in step_id: root/credentials options: - type: credentials automatable: true inputs: - name: username type: text label: Email - name: password type: password label: Password - type: gmail_one_click_integration automatable: true inputs: - name: gmail_tokens type: text label: Gmail token '400': description: Invalid choice, option index, or missing field content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Session, flow, or step not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Auth flow transition already in progress content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to resolve auth flow content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/identities/dynamic/finalize/{session_id}: post: summary: Finalize Dynamic Auth Flow description: | Persists the identity, browser profile, and captured credentials after the flow reaches `authenticated`. The response reports whether the saved login can be replayed unattended (`automatable`). security: - api_key_header: [] tags: - Identities parameters: - name: session_id in: path required: true description: Session whose authenticated flow to persist. schema: type: string requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/AuthFlowV2FinalizeRequest' responses: '200': description: Identity created from the completed flow content: application/json: schema: $ref: '#/components/schemas/AuthFlowV2FinalizeResult' '401': description: Missing team context content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Auth flow or current step not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Flow must be authenticated before finalizing content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to finalize content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/profiles: post: summary: Create Profile description: Creates a new profile from a browser session. A Profile stores cookies, local storage, and cache. security: - api_key_header: [] tags: - Profiles requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ProfileRequestSchema' responses: '200': description: Profile created successfully. content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' '400': description: Invalid request or input. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Session not found or unreachable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Profile name already exists. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '501': description: Feature not implemented. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' get: summary: List Profiles description: Fetches all stored profiles. security: - api_key_header: [] tags: - Profiles responses: '200': description: List of user profiles retrieved successfully. content: application/json: schema: $ref: '#/components/schemas/ProfileListResponse' '500': description: Unable to list user profiles due to an unexpected error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/profiles/{name}: get: summary: Get Profile description: Retrieves details of a specific profile by its name. security: - api_key_header: [] tags: - Profiles parameters: - name: name in: path required: true description: The name of the profile to retrieve. schema: type: string responses: '200': description: Profile details retrieved successfully. content: application/json: schema: $ref: '#/components/schemas/ProfileResponse' '401': description: Invalid API Key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Profile not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Unable to retrieve profile due to an unexpected error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' delete: summary: Delete Profile description: Deletes an existing profile by its name. security: - api_key_header: [] tags: - Profiles parameters: - name: name in: path required: true description: The name of the profile to delete. schema: type: string responses: '200': description: Profile deleted successfully. content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' '404': description: Profile not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Unable to delete the profile due to an unexpected error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/sessions/{sessionId}/screenshot: get: summary: Take Screenshot description: Takes a screenshot of the current browser session and returns it as an image. security: - api_key_header: [] tags: - OS Level Control parameters: - name: sessionId in: path required: true description: The ID of the browser session schema: type: string format: uuid responses: '200': description: Screenshot taken successfully content: image/png: schema: type: string format: binary '404': description: Session not found content: application/json: schema: type: object properties: error: type: string '500': description: Failed to take screenshot content: application/json: schema: type: object properties: error: type: string /v1/sessions/{sessionId}/mouse/click: post: summary: Mouse Click description: Performs a mouse click at the specified coordinates security: - api_key_header: [] tags: - OS Level Control parameters: - name: sessionId in: path required: true description: The ID of the browser session schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MouseSingleClickRequestSchema' responses: '200': description: Click performed successfully content: application/json: schema: type: object properties: status: type: string '400': description: Invalid coordinates or parameters '404': description: Session not found '500': description: Failed to perform click /v1/sessions/{sessionId}/mouse/doubleClick: post: summary: Mouse Double Click description: Performs a double click at the specified coordinates security: - api_key_header: [] tags: - OS Level Control parameters: - name: sessionId in: path required: true description: The ID of the browser session schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MouseClickRequestSchema' responses: '200': description: Double click performed successfully content: application/json: schema: type: object properties: status: type: string '400': description: Invalid coordinates or parameters '404': description: Session not found '500': description: Failed to perform double click /v1/sessions/{sessionId}/mouse/down: post: summary: Mouse Down description: Performs a mouse button down action at the specified coordinates security: - api_key_header: [] tags: - OS Level Control parameters: - name: sessionId in: path required: true description: The ID of the browser session schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MouseClickRequestSchema' responses: '200': description: Mouse down performed successfully content: application/json: schema: type: object properties: status: type: string '400': description: Invalid coordinates or parameters '404': description: Session not found '500': description: Failed to perform mouse down /v1/sessions/{sessionId}/mouse/up: post: summary: Mouse Up description: Performs a mouse button up action at the specified coordinates security: - api_key_header: [] tags: - OS Level Control parameters: - name: sessionId in: path required: true description: The ID of the browser session schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MouseClickRequestSchema' responses: '200': description: Mouse up performed successfully content: application/json: schema: type: object properties: status: type: string '400': description: Invalid coordinates or parameters '404': description: Session not found '500': description: Failed to perform mouse up /v1/sessions/{sessionId}/mouse/move: post: summary: Mouse Move description: Moves the mouse cursor to the specified coordinates security: - api_key_header: [] tags: - OS Level Control parameters: - name: sessionId in: path required: true description: The ID of the browser session schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CoordinatesRequestSchema' responses: '200': description: Mouse move performed successfully content: application/json: schema: type: object properties: status: type: string '400': description: Invalid coordinates '404': description: Session not found '500': description: Failed to perform mouse move /v1/sessions/{sessionId}/drag-and-drop: post: summary: Drag and Drop description: Performs a drag and drop operation from start coordinates to end coordinates security: - api_key_header: [] tags: - OS Level Control parameters: - name: sessionId in: path required: true description: The ID of the browser session schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DragDropRequestSchema' responses: '200': description: Drag and drop performed successfully content: application/json: schema: type: object properties: status: type: string '400': description: Invalid coordinates or parameters '404': description: Session not found '500': description: Failed to perform drag and drop /v1/sessions/{sessionId}/scroll: post: summary: Scroll description: Performs a scroll action at the specified coordinates security: - api_key_header: [] tags: - OS Level Control parameters: - name: sessionId in: path required: true description: The ID of the browser session schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ScrollRequestSchema' responses: '200': description: Scroll performed successfully content: application/json: schema: type: object properties: status: type: string '400': description: Invalid coordinates or parameters '404': description: Session not found '500': description: Failed to perform scroll /v1/sessions/{sessionId}/keyboard/type: post: summary: Type Text description: Types the specified text with optional delay between keystrokes security: - api_key_header: [] tags: - OS Level Control parameters: - name: sessionId in: path required: true description: The ID of the browser session schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TypeTextRequestSchema' responses: '200': description: Text typed successfully content: application/json: schema: type: object properties: status: type: string '400': description: Invalid parameters '404': description: Session not found '500': description: Failed to type text /v1/sessions/{sessionId}/keyboard/shortcut: post: summary: Keyboard Shortcut description: Performs a keyboard shortcut using the specified keys security: - api_key_header: [] tags: - OS Level Control parameters: - name: sessionId in: path required: true description: The ID of the browser session schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/KeyboardShortcutRequestSchema' responses: '200': description: Shortcut performed successfully content: application/json: schema: type: object properties: status: type: string '400': description: Invalid parameters '404': description: Session not found '500': description: Failed to perform shortcut /v1/sessions/{sessionId}/clipboard: get: summary: Get Clipboard Content description: Retrieves the current content of the clipboard security: - api_key_header: [] tags: - OS Level Control parameters: - name: sessionId in: path required: true description: The ID of the browser session schema: type: string format: uuid responses: '200': description: Clipboard content retrieved successfully content: application/json: schema: $ref: '#/components/schemas/ClipboardResponseSchema' '404': description: Session not found '500': description: Failed to get clipboard content post: summary: Set Clipboard Content description: Sets the content of the clipboard security: - api_key_header: [] tags: - OS Level Control parameters: - name: sessionId in: path required: true description: The ID of the browser session schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ClipboardRequestSchema' responses: '200': description: Clipboard content set successfully content: application/json: schema: type: object properties: status: type: string '400': description: Invalid parameters '404': description: Session not found '500': description: Failed to set clipboard content /v1/sessions/{sessionId}/copy: post: summary: Copy Selected Text description: Copies the currently selected text to the clipboard security: - api_key_header: [] tags: - OS Level Control parameters: - name: sessionId in: path required: true description: The ID of the browser session schema: type: string format: uuid responses: '200': description: Text copied successfully content: application/json: schema: $ref: '#/components/schemas/CopyResponseSchema' '404': description: Session not found '500': description: Failed to copy text /v1/sessions/{sessionId}/paste: post: summary: Paste Text description: Pastes text at the current cursor position security: - api_key_header: [] tags: - OS Level Control parameters: - name: sessionId in: path required: true description: The ID of the browser session schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PasteRequestSchema' responses: '200': description: Text pasted successfully content: application/json: schema: type: object properties: status: type: string '400': description: Invalid parameters '404': description: Session not found '500': description: Failed to paste text /v1/sessions/{sessionId}/goto: post: summary: Navigate to URL description: Navigates the browser session to the specified URL security: - api_key_header: [] tags: - OS Level Control parameters: - name: sessionId in: path required: true description: The ID of the browser session schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/NavigateRequestSchema' responses: '200': description: Navigation successful content: application/json: schema: type: object properties: status: type: string '400': description: Invalid URL or parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Session not found content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to navigate to URL content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/ErrorResponse' /v1/sessions/{session_id}/recordings/pause: post: summary: Pause Session Recording description: Pauses the video recording for the specified browser session. tags: - Session Recordings parameters: - in: path name: session_id required: true description: The ID of the browser session for which to pause recording. schema: type: string security: - api_key_header: [] responses: '200': description: Recording paused successfully. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/SuccessResponse' '401': description: Invalid API Key. content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/ErrorResponse' '404': description: Session not found. content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to pause recording. content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/ErrorResponse' /v1/sessions/{session_id}/recordings/resume: post: summary: Resume Session Recording description: Resumes the video recording for the specified browser session. tags: - Session Recordings parameters: - in: path name: session_id required: true description: The ID of the browser session for which to resume recording. schema: type: string security: - api_key_header: [] responses: '200': description: Recording resumed successfully. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/SuccessResponse' '401': description: Invalid API Key. content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/ErrorResponse' '404': description: Session not found. content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to resume recording. content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/ErrorResponse' /v1/sessions/{session_id}/recordings: get: summary: List Session Recordings description: Retrieves the URLs of the browser session's video recordings. Requires a valid API key for authentication. tags: - Session Recordings parameters: - in: path name: session_id required: true description: The ID of the browser session to retrieve recordings for. schema: type: string security: - api_key_header: [] responses: '200': description: A set of recording URLs associated with the browser session. content: application/json: schema: $ref: '#/components/schemas/RecordingListResponse' '401': description: Invalid API Key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Session recordings not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Too many requests, please try again later. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/sessions/{session_id}/recordings/primary/fetch: get: summary: Get Session Recording description: Downloads the primary recording file for the specified browser session. Returns the recording as an MP4 file. tags: - Session Recordings parameters: - in: path name: session_id required: true description: The ID of the browser session to download the recording for. schema: type: string security: - api_key_header: [] responses: '200': description: The browser session recording file content: video/mp4: schema: type: string format: binary '401': description: Invalid API Key - Authentication failed or API key is missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Recording not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/sessions/{session_id}/recordings/{recording_id}: delete: summary: Delete Session Recording description: Deletes a specific recording from a browser session. Use "primary" as the recording_id to delete the primary recording. tags: - Session Recordings parameters: - in: path name: session_id required: true description: The ID of the browser session the recording belongs to. schema: type: string - in: path name: recording_id required: true description: The ID of the recording to delete. Use "primary" to delete the primary recording. schema: type: string security: - api_key_header: [] responses: '200': description: Recording deleted successfully. content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' '400': description: Recording feature is disabled for this session. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Invalid API Key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to delete recording. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/sessions/{sessionId}/agent/files: post: summary: Upload Agent Resources description: | Upload files as agent resources to a browser session using multipart/form-data. If you upload a ZIP file, it will be automatically extracted and the files will be made available as agent resources (pass `extract=false` to keep the archive itself instead). If you upload a single file, it will be saved directly as an agent resource. Resources are then accessible to AI agents for task completion and automation. security: - api_key_header: [] tags: - Agentic capabilities parameters: - name: sessionId in: path required: true description: The browser session ID schema: type: string format: uuid - name: extract in: query required: false description: | Whether a `.zip` upload is unpacked into the uploads directory. Defaults to `true`. Set to `false` to keep the archive itself. Any other value is treated as `true`. Has no effect on non-zip files. schema: type: string enum: - 'true' - 'false' default: 'true' requestBody: required: true content: multipart/form-data: schema: type: object required: - file properties: file: type: string format: binary description: File to upload as agent resource (ZIP files are extracted unless extract=false) responses: '200': description: Agent resources uploaded successfully content: application/json: schema: type: object properties: data: type: object properties: status: type: string message: type: string file_paths: type: array description: Absolute paths of the saved files inside the session (the archive entries when a zip was extracted) items: type: string '400': description: Invalid request (no resource uploaded or file too large) content: application/json: schema: type: object properties: error: type: object properties: code: type: integer message: type: string '404': description: Session not found content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to upload or process agent resources content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/ErrorResponse' get: summary: List Agent Resources description: | List all resources that have been uploaded to the browser session for agent use. Returns resource metadata including name, size, type, and last modified timestamp. security: - api_key_header: [] tags: - Agentic capabilities parameters: - name: sessionId in: path required: true description: The browser session ID schema: type: string format: uuid responses: '200': description: Agent resources listed successfully content: application/json: schema: type: object properties: data: type: object properties: files: type: array items: type: object properties: name: type: string description: The resource name size: type: integer description: Resource size in bytes type: type: string description: Resource extension/type lastModified: type: string format: date-time description: When the resource was last modified '400': description: Session is not running content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/ErrorResponse' '404': description: Session not found content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to list agent resources content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/ErrorResponse' /v1/sessions/{session_id}/agent/pause: post: summary: Pause Agent description: Pauses the AI agent for the specified browser session. security: - api_key_header: [] tags: - Agentic capabilities parameters: - name: session_id in: path required: true description: The ID of the browser session schema: type: string format: uuid responses: '200': description: Agent paused successfully content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' '400': description: Session is not running content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Session not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to pause agent content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/sessions/{session_id}/agent/resume: post: summary: Resume Agent description: Resumes the AI agent for the specified browser session. security: - api_key_header: [] tags: - Agentic capabilities parameters: - name: session_id in: path required: true description: The ID of the browser session schema: type: string format: uuid responses: '200': description: Agent resumed successfully content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' '400': description: Session is not running content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Session not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to resume agent content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/sessions/pending-interventions: get: summary: List Pending Human Interventions description: | Returns all pending human-in-the-loop (HITL) requests across the team's active browser sessions. Each item includes the intervention request plus the session ID and tags for routing responses. security: - api_key_header: [] tags: - Agentic capabilities responses: '200': description: Pending interventions retrieved successfully. content: application/json: schema: $ref: '#/components/schemas/PendingInterventionsResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to get pending interventions content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/sessions/{session_id}/agent/requested-human-intervention: get: summary: Get Requested Human Interventions description: | Retrieves pending human-in-the-loop (HITL) requests for a specific active browser session. Requires `human_intervention: true` on the task that is running in the session. The agent pauses until a response is submitted via `POST /v1/sessions/{session_id}/agent/respond-to-human-intervention`. security: - api_key_header: [] tags: - Agentic capabilities parameters: - name: session_id in: path required: true description: The ID of the browser session schema: type: string format: uuid responses: '200': description: Pending intervention requests retrieved successfully content: application/json: schema: $ref: '#/components/schemas/HumanInterventionRequestsResponse' '400': description: Session is not running content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Session not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to get agent requested human intervention content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/sessions/{session_id}/agent/respond-to-human-intervention: post: summary: Respond to Human Intervention description: | Sends a response to a pending human-in-the-loop (HITL) request for the specified session. Resolving a request unblocks the agent and emits an `intervention.resolved` webhook event when `requestId` is provided. security: - api_key_header: [] tags: - Agentic capabilities parameters: - name: session_id in: path required: true description: The ID of the browser session schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/HumanInterventionResponseRequest' example: requestId: 550e8400-e29b-41d4-a716-446655440000 response: Approve and continue with the current approach. responses: '200': description: Human intervention response submitted successfully content: application/json: schema: $ref: '#/components/schemas/HumanInterventionResponseResponse' '400': description: Session is not running content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Session not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to respond to human intervention content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/extensions: post: summary: Upload Extension description: Upload a new browser extension as a ZIP file. The extension will be validated and stored for use in browser sessions. security: - api_key_header: [] tags: - Extensions requestBody: required: true content: multipart/form-data: schema: type: object required: - name - file properties: name: type: string description: User-friendly name for the extension (1-255 characters) file: type: string format: binary description: ZIP file containing the browser extension responses: '200': description: Extension uploaded successfully content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/ExtensionResponseSchema' '400': description: Invalid request or extension validation failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Unable to upload extension content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' get: summary: List Extensions description: Get all extensions for the authenticated user security: - api_key_header: [] tags: - Extensions responses: '200': description: List of user extensions retrieved successfully content: application/json: schema: $ref: '#/components/schemas/ExtensionListResponse' '500': description: Unable to list extensions content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/extensions/{id}: get: summary: Get Extension Details description: Get details of a specific extension by its ID security: - api_key_header: [] tags: - Extensions parameters: - name: id in: path required: true description: The ID of the extension to retrieve schema: type: string format: uuid responses: '200': description: Extension details retrieved successfully content: application/json: schema: $ref: '#/components/schemas/ExtensionResponseSchema' '404': description: Extension not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Unable to get extension content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' delete: summary: Delete Extension description: Delete an extension and remove it from storage security: - api_key_header: [] tags: - Extensions parameters: - name: id in: path required: true description: The ID of the extension to delete schema: type: string format: uuid responses: '200': description: Extension deleted successfully content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/SuccessResponse' '404': description: Extension not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Unable to delete extension content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/certificates: post: summary: Upload Certificate description: | Upload a CA certificate to trust in browser sessions. Certificates are managed at the team level. Once uploaded, reference the certificate by name when creating sessions to trust services using that CA. See [CA Certificates documentation](/advanced/ca-certificates) for more details. security: - api_key_header: [] tags: - Certificates requestBody: required: true content: multipart/form-data: schema: type: object required: - name - file properties: name: type: string description: Unique identifier for the certificate (alphanumeric, hyphens, underscores only, 1-255 characters) pattern: '^[a-zA-Z0-9\-_]+$' file: type: string format: binary description: Certificate file (.crt, .pem, .cer, or .der format) description: type: string description: Optional description of the certificate (max 1000 characters) maxLength: 1000 responses: '200': description: Certificate uploaded successfully content: application/json: schema: $ref: '#/components/schemas/CertificateResponse' '400': description: Invalid request - missing file, invalid name format, or unsupported file type content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: A certificate with this name already exists for your team content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Unable to upload certificate content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' get: summary: List Certificates description: Get all CA certificates uploaded for the team security: - api_key_header: [] tags: - Certificates responses: '200': description: List of certificates retrieved successfully content: application/json: schema: $ref: '#/components/schemas/CertificateListResponse' '500': description: Unable to list certificates content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/certificates/{name}: delete: summary: Delete Certificate description: Delete a CA certificate by name. The certificate will be removed from storage and can no longer be used in new sessions. security: - api_key_header: [] tags: - Certificates parameters: - name: name in: path required: true description: The name of the certificate to delete schema: type: string responses: '200': description: Certificate deleted successfully content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' '404': description: Certificate not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Unable to delete certificate content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/integrations: post: summary: Create Integration description: | Creates a new integration with a third-party service like 1Password. The integration can then be used in browser sessions to automatically load secrets and credentials. security: - api_key_header: [] tags: - Integrations requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateIntegrationRequest' examples: onePasswordIntegration: summary: Create a 1Password integration value: name: 'My 1Password Integration' type: '1PASSWORD' credentials: type: 'serviceAccount' data: serviceAccount: 'ops_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx' responses: '200': description: Integration created successfully content: application/json: schema: $ref: '#/components/schemas/IntegrationResponse' '400': description: Invalid request or validation failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to create integration content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' get: summary: List Integrations description: Retrieves all integrations for the authenticated team. security: - api_key_header: [] tags: - Integrations responses: '200': description: List of integrations retrieved successfully content: application/json: schema: $ref: '#/components/schemas/IntegrationListResponse' '500': description: Failed to list integrations content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/integrations/{integrationId}: delete: summary: Delete Integration description: Deletes an existing integration and removes its stored credentials. security: - api_key_header: [] tags: - Integrations parameters: - name: integrationId in: path required: true description: The ID of the integration to delete schema: type: string format: uuid example: '550e8400-e29b-41d4-a716-446655440000' responses: '200': description: Integration deleted successfully content: application/json: schema: type: object properties: data: type: object properties: integration: type: object properties: id: type: string format: uuid deleted: type: boolean path: type: string '404': description: Integration not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to delete integration content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/events/{event_name}/wait: post: summary: Wait for Event description: | Waits for a specific event to be signaled by another process, workflow, or session. This endpoint blocks until the event is signaled or the timeout is reached. Useful for coordinating between multiple browser sessions or workflows. security: - api_key_header: [] tags: - Event Coordination parameters: - name: event_name in: path required: true description: The name of the event to wait for schema: type: string requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/WaitForEventRequestSchema' responses: '200': description: Event was signaled successfully content: application/json: schema: $ref: '#/components/schemas/EventResponseSchema' '401': description: Unauthorized - Invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '408': description: Timeout - Event was not signaled within the specified timeout content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to wait for event content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/events/{event_name}: post: summary: Signal Event description: | Signals an event with associated data, unblocking any clients waiting for this event. This enables coordination between different browser sessions, workflows, or external processes. security: - api_key_header: [] tags: - Event Coordination parameters: - name: event_name in: path required: true description: The name of the event to signal schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SignalEventRequestSchema' responses: '200': description: Event signaled successfully content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' '400': description: Invalid request - Event data is required content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized - Invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to signal event content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/batch-sessions: get: summary: List Batch Sessions description: | Lists all batch session requests for the authenticated team, with optional filtering by status and pagination support. security: - api_key_header: [] tags: - Batch Sessions parameters: - name: status in: query required: false description: Filter batches by status schema: type: string enum: [pending, processing, completed, failed, cancelled] - name: page in: query required: false description: Page number (1-based) schema: type: integer minimum: 1 default: 1 - name: limit in: query required: false description: Number of results per page schema: type: integer minimum: 1 maximum: 100 default: 20 - name: created_after in: query required: false description: Filter batches created after this timestamp (ISO 8601) schema: type: string format: date-time - name: created_before in: query required: false description: Filter batches created before this timestamp (ISO 8601) schema: type: string format: date-time responses: '200': description: Batch list retrieved successfully content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/BatchSessionListResponseSchema' '401': description: Invalid API Key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' post: summary: Create Batch Sessions description: | Creates multiple browser sessions in a single batch operation. This endpoint allows you to create up to 5,000 browser sessions simultaneously with the same configuration. The batch will be processed asynchronously, and you can monitor progress using the batch status endpoint. security: - api_key_header: [] tags: - Batch Sessions requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BatchSessionRequestSchema' examples: small_batch: summary: Small batch example value: count: 10 configuration: browser: headless: active: true viewport: width: 1440 height: 900 session: timeout: idle_timeout: 10 max_duration: 300 metadata: project: 'web-scraping' environment: 'production' large_batch: summary: Large batch example (from test snippet) value: count: 2500 configuration: browser: headless: active: true viewport: width: 1440 height: 900 recording: active: true session: timeout: idle_timeout: 10 max_duration: 300 tags: ['batch-test-comprehensive'] metadata: test: true description: 'Comprehensive batch test with 3 sessions' responses: '200': description: Batch created successfully content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/BatchSessionResponseSchema' '400': description: Invalid request parameters or configuration content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_count: summary: Invalid session count value: error: code: 400 message: 'Session count must be between 1 and 1000' invalid_config: summary: Invalid configuration value: error: code: 400 message: 'CAPTCHA solver requires proxy to be active' '402': description: Payment Required - Insufficient credits for batch creation content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Too many requests - Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/batch-sessions/{batch_id}: get: summary: Get Batch Session Status description: | Retrieves detailed status information for a specific batch, including progress, individual session details, and any errors that occurred. security: - api_key_header: [] tags: - Batch Sessions parameters: - name: batch_id in: path required: true description: The unique identifier of the batch schema: type: string format: uuid responses: '200': description: Batch status retrieved successfully content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/BatchSessionStatusResponseSchema' '404': description: Batch not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Invalid API Key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' patch: summary: Update Batch Session description: | Updates a batch session. Supports cancelling a running or pending batch, which terminates all running sessions in the batch. security: - api_key_header: [] tags: - Batch Sessions parameters: - name: batch_id in: path required: true description: The unique identifier of the batch schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BatchSessionUpdateRequestSchema' examples: cancel_batch: summary: Cancel a running batch value: status: cancelled responses: '200': description: Batch updated successfully content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/BatchSessionUpdateResponseSchema' '404': description: Batch not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Invalid state transition (batch already cancelled or completed) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Invalid API Key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' delete: summary: Delete Batch Sessions description: | Deletes all sessions in a batch. Running sessions will be terminated and all session data will be removed. security: - api_key_header: [] tags: - Batch Sessions parameters: - name: batch_id in: path required: true description: The unique identifier of the batch schema: type: string format: uuid responses: '200': description: Batch sessions deleted successfully content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/BatchSessionDeleteResponseSchema' '404': description: Batch not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Invalid API Key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/batch-sessions/{batch_id}/retry: post: summary: Retry Failed Batch Sessions description: | Retries failed sessions in a batch by creating new browser pods for each failed session. The batch status will be set back to 'processing'. security: - api_key_header: [] tags: - Batch Sessions parameters: - name: batch_id in: path required: true description: The unique identifier of the batch schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BatchSessionRetryRequestSchema' examples: retry_defaults: summary: Retry with default settings value: retry_failed_only: true max_retries: 1 retry_multiple: summary: Retry with multiple attempts value: retry_failed_only: true max_retries: 3 responses: '200': description: Retry initiated successfully content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/BatchSessionRetryResponseSchema' '400': description: No failed sessions to retry content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Batch not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Invalid API Key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/task: post: summary: Create Task (Legacy) description: | Creates a new task or updates an existing task with the same name. Tasks are reusable code snippets that can be executed in browser sessions. Tasks support versioning with draft and published versions. If you are using the new Task Builder, see the non-deprecated Tasks endpoints in this API reference. security: - api_key_header: [] tags: - Tasks (Legacy) requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateTaskRequest' examples: createTask: summary: Create a new task value: name: 'web-scraper' language: 'typescript' description: 'A task to scrape product information from e-commerce sites' code: 'Y29uc3QgYW5jaG9yID0gcmVxdWlyZSgnYW5jaG9yYnJvd3NlcicpOwoKYXN5bmMgZnVuY3Rpb24gcnVuKCkgewogIGNvbnN0IHNlc3Npb24gPSBhd2FpdCBhbmNob3IuY3JlYXRlU2Vzc2lvbigpOwogIGF3YWl0IHNlc3Npb24uZ29UbygnaHR0cHM6Ly9leGFtcGxlLmNvbScpOwogIGNvbnN0IHRpdGxlID0gYXdhaXQgc2Vzc2lvbi5nZXRUaXRsZSgpOwogIGNvbnNvbGUubG9nKHRpdGxlKTsKICBhd2FpdCBzZXNzaW9uLmNsb3NlKCk7Cn0KcnVuKCk7' responses: '200': description: Task created or updated successfully content: application/json: schema: $ref: '#/components/schemas/TaskResponse' '400': description: Invalid request or validation failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Task name already exists content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to create task content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' get: summary: List Tasks (Legacy) description: | Retrieves a paginated list of all tasks for the authenticated team. Tasks are returned with their latest version information and metadata. If you are using the new Task Builder, see the non-deprecated Tasks endpoints in this API reference. security: - api_key_header: [] tags: - Tasks (Legacy) parameters: - name: page in: query required: false description: Page number schema: type: string pattern: '^[1-9]\d*$' default: '1' - name: limit in: query required: false description: Number of tasks per page schema: type: string pattern: '^[1-9]\d*$' default: '10' responses: '200': description: List of tasks retrieved successfully content: application/json: schema: $ref: '#/components/schemas/TaskListResponse' '500': description: Failed to list tasks content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/task/run: post: summary: Run Task (Legacy) description: | Executes a task in a browser session. The task can be run with a specific version or the latest version. Optionally, you can provide an existing session ID or let the system create a new one. If you are using the new Task Builder, see the non-deprecated Tasks endpoints in this API reference. security: - api_key_header: [] tags: - Tasks (Legacy) requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RunTaskRequest' examples: runTask: summary: Run a task with specific version value: taskId: '550e8400-e29b-41d4-a716-446655440000' version: '1' inputs: ANCHOR_TARGET_URL: 'https://example.com' ANCHOR_MAX_PAGES: '10' runTaskLatest: summary: Run task with latest version value: taskId: '550e8400-e29b-41d4-a716-446655440000' version: 'latest' responses: '200': description: Task executed successfully content: application/json: schema: $ref: '#/components/schemas/RunTaskResponse' '404': description: Task or session not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Task execution failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/task/run/{taskName}: post: summary: Run Task by Name (Legacy) description: | Executes a task by its name, always using the latest version. This is a convenience endpoint for running tasks without needing to know the task ID. If you are using the new Task Builder, see the non-deprecated Tasks endpoints in this API reference. security: - api_key_header: [] tags: - Tasks (Legacy) parameters: - name: taskName in: path required: true description: The name of the task to run schema: type: string pattern: '^[a-zA-Z0-9_-]+$' example: 'web-scraper' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RunTaskByNameRequest' responses: '200': description: Task executed successfully content: application/json: schema: $ref: '#/components/schemas/RunTaskResponse' '404': description: Task not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Task execution failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/task/{taskId}: get: summary: Get Task Metadata (Legacy) description: | Retrieves task metadata without the code content. Useful for getting task information without downloading the full task code. If you are using the new Task Builder, see the non-deprecated Tasks endpoints in this API reference. security: - api_key_header: [] tags: - Tasks (Legacy) parameters: - name: taskId in: path required: true description: The ID of the task to retrieve schema: type: string format: uuid responses: '200': description: Task metadata retrieved successfully content: application/json: schema: $ref: '#/components/schemas/TaskMetadataResponse' '404': description: Task not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to retrieve task content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' put: summary: Update Task Metadata (Legacy) description: | Updates task metadata (name and description). This does not affect the task code or versions. If you are using the new Task Builder, see the non-deprecated Tasks endpoints in this API reference. security: - api_key_header: [] tags: - Tasks (Legacy) parameters: - name: taskId in: path required: true description: The ID of the task to update schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateTaskMetadataRequest' responses: '200': description: Task metadata updated successfully content: application/json: schema: $ref: '#/components/schemas/TaskMetadataResponse' '404': description: Task not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Task name already exists content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to update task content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' delete: summary: Delete Task (Legacy) description: | Soft deletes a task and all its versions. The task will no longer be accessible but the data is preserved for potential recovery. If you are using the new Task Builder, see the non-deprecated Tasks endpoints in this API reference. security: - api_key_header: [] tags: - Tasks (Legacy) parameters: - name: taskId in: path required: true description: The ID of the task to delete schema: type: string format: uuid responses: '200': description: Task deleted successfully content: application/json: schema: $ref: '#/components/schemas/DeleteTaskResponse' '404': description: Task not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to delete task content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/task/{taskId}/versions: get: summary: List Task Versions (Legacy) description: | Retrieves all versions of a specific task, including draft and published versions. If you are using the new Task Builder, see the non-deprecated Tasks endpoints in this API reference. security: - api_key_header: [] tags: - Tasks (Legacy) parameters: - name: taskId in: path required: true description: The ID of the task schema: type: string format: uuid responses: '200': description: Task versions retrieved successfully content: application/json: schema: $ref: '#/components/schemas/TaskVersionsListResponse' '404': description: Task not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to retrieve task versions content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/task/{taskId}/latest: get: summary: Get Latest Task Version (Legacy) description: | Retrieves the latest version of a task, including the full code content. If you are using the new Task Builder, see the non-deprecated Tasks endpoints in this API reference. security: - api_key_header: [] tags: - Tasks (Legacy) parameters: - name: taskId in: path required: true description: The ID of the task schema: type: string format: uuid responses: '200': description: Latest task version retrieved successfully content: application/json: schema: $ref: '#/components/schemas/TaskVersionResponse' '404': description: Task or version not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to retrieve task version content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/task/{taskId}/draft: get: summary: Get Task Draft (Legacy) description: | Retrieves the draft version of a task, including the full code content. If you are using the new Task Builder, see the non-deprecated Tasks endpoints in this API reference. security: - api_key_header: [] tags: - Tasks (Legacy) parameters: - name: taskId in: path required: true description: The ID of the task schema: type: string format: uuid responses: '200': description: Task draft retrieved successfully content: application/json: schema: $ref: '#/components/schemas/TaskVersionResponse' '404': description: Task or draft not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to retrieve task draft content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' post: summary: Create or Update Task Draft (Legacy) description: | Creates or updates the draft version of a task. Draft versions are used for development and testing before publishing. If you are using the new Task Builder, see the non-deprecated Tasks endpoints in this API reference. security: - api_key_header: [] tags: - Tasks (Legacy) parameters: - name: taskId in: path required: true description: The ID of the task schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DraftTaskRequest' responses: '200': description: Task draft created or updated successfully content: application/json: schema: $ref: '#/components/schemas/TaskVersionResponse' '404': description: Task not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to create or update task draft content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/task/{taskId}/deploy: post: summary: Deploy Task (Legacy) description: | Deploys a task by creating a new version with auto-incremented version number. This is the recommended way to publish task changes. If you are using the new Task Builder, see the non-deprecated Tasks endpoints in this API reference. security: - api_key_header: [] tags: - Tasks (Legacy) parameters: - name: taskId in: path required: true description: The ID of the task schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PublishVersionRequest' responses: '200': description: Task deployed successfully content: application/json: schema: $ref: '#/components/schemas/TaskVersionResponse' '404': description: Task not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to deploy task content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/task/{taskId}/executions: get: summary: List Task Executions (Legacy) description: | Retrieves execution history for a task, including success/failure status, execution times, and outputs. Results can be filtered by version and status. If you are using the new Task Builder, see the Tasks V2 endpoints in this API reference. security: - api_key_header: [] tags: - Tasks (Legacy) parameters: - name: taskId in: path required: true description: The ID of the task schema: type: string format: uuid - name: page in: query required: false description: Page number schema: type: string pattern: '^[1-9]\d*$' default: '1' - name: limit in: query required: false description: Number of results per page schema: type: string pattern: '^[1-9]\d*$' default: '10' - name: status in: query required: false description: Filter by execution status schema: type: string enum: [success, failure, timeout, cancelled, queued, running] - name: version in: query required: false description: Filter by task version schema: type: string responses: '200': description: Task executions retrieved successfully content: application/json: schema: $ref: '#/components/schemas/TaskExecutionResultsListResponse' '404': description: Task not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to retrieve task executions content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/task/{taskId}/executions/{executionId}: get: summary: Get Task Execution Result (Legacy) description: | Retrieves a single execution result by its ID. This endpoint is useful for polling execution status in async mode or retrieving detailed execution information. If you are using the new Task Builder, see the Tasks V2 endpoints in this API reference. security: - api_key_header: [] tags: - Tasks (Legacy) parameters: - name: taskId in: path required: true description: The ID of the task schema: type: string format: uuid - name: executionId in: path required: true description: The ID of the execution result schema: type: string format: uuid responses: '200': description: Execution result retrieved successfully content: application/json: schema: $ref: '#/components/schemas/TaskExecutionResultResponse' '404': description: Task or execution result not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to retrieve execution result content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/task/{taskId}/{taskVersion}: get: summary: Get Task Version (Legacy) description: | Retrieves a specific version of a task, including the full code content. If you are using the new Task Builder, see the Tasks V2 endpoints in this API reference. security: - api_key_header: [] tags: - Tasks (Legacy) parameters: - name: taskId in: path required: true description: The ID of the task schema: type: string format: uuid - name: taskVersion in: path required: true description: The version to retrieve (draft, latest, or version number) schema: type: string pattern: '^(draft|latest|\d+)$' responses: '200': description: Task version retrieved successfully content: application/json: schema: $ref: '#/components/schemas/TaskVersionResponse' '404': description: Task or version not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to retrieve task version content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' post: summary: Publish Task Version (Legacy) description: | Publishes a specific version of a task. This creates a new version if it doesn't exist, or updates an existing version's metadata. If you are using the new Task Builder, see the non-deprecated Tasks endpoints in this API reference. security: - api_key_header: [] tags: - Tasks (Legacy) parameters: - name: taskId in: path required: true description: The ID of the task schema: type: string format: uuid - name: taskVersion in: path required: true description: The version to publish (cannot be draft) schema: type: string pattern: '^\d+$' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PublishVersionRequest' responses: '200': description: Task version published successfully content: application/json: schema: $ref: '#/components/schemas/TaskVersionResponse' '400': description: Cannot publish to draft version content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Task not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to publish task version content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' delete: summary: Delete Task Version (Legacy) description: | Soft deletes a specific version of a task. The version will no longer be accessible but the data is preserved for potential recovery. If you are using the new Task Builder, see the Tasks V2 endpoints in this API reference. security: - api_key_header: [] tags: - Tasks (Legacy) parameters: - name: taskId in: path required: true description: The ID of the task schema: type: string format: uuid - name: taskVersion in: path required: true description: The version to delete schema: type: string pattern: '^(draft|latest|\d+)$' responses: '200': description: Task version deleted successfully content: application/json: schema: $ref: '#/components/schemas/DeleteTaskResponse' '404': description: Task or version not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to delete task version content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/billing: get: summary: Get Billing Info description: >- Retrieves credit balance, current-period credit usage, tier, and billing limits for the authenticated project. Pass `from_date`, `to_date`, or `granularity` to additionally receive a `usage` time series of credits used per period, matching `GET /v1/sessions/history?metrics=credits_used`. security: - api_key_header: [] tags: - Billing parameters: - in: query name: from_date required: false description: >- Start of the usage window (ISO 8601 format, UTC). Passing any of `from_date`, `to_date`, or `granularity` adds a `usage` block to the response. Defaults to 30 days ago. schema: type: string format: date-time - in: query name: to_date required: false description: End of the usage window (ISO 8601 format, UTC). Defaults to now. schema: type: string format: date-time - in: query name: granularity required: false description: Time granularity for the usage time series. schema: type: string enum: [hour, day, week, month] default: day responses: '200': description: Billing information retrieved successfully. content: application/json: schema: $ref: '#/components/schemas/BillingInfoResponse' examples: billingInfo: summary: Example billing info value: data: credits: 42.5 credits_used: 12.5 included_credits: 50 billing_period: '2026-04' tier: monthly_starter gifts_balance: 42.5 max_concurrent_browsers: 25 cost_limit: 100 billingInfoWithUsage: summary: Example billing info with a usage time series (granularity=day) value: data: credits: 42.5 credits_used: 12.5 included_credits: 50 billing_period: '2026-04' tier: monthly_starter gifts_balance: 42.5 max_concurrent_browsers: 25 cost_limit: 100 usage: from_date: '2026-04-01T00:00:00.000Z' to_date: '2026-04-03T23:59:59.000Z' granularity: day total_credits_used: 12.5 data: - date: '2026-04-03T00:00:00.000Z' credits_used: 4.25 - date: '2026-04-02T00:00:00.000Z' credits_used: 5.5 - date: '2026-04-01T00:00:00.000Z' credits_used: 2.75 '400': description: >- Invalid usage query — malformed date, `from_date` after `to_date`, or a date range spanning too many buckets for the requested granularity. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Invalid API Key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' # ============================================================================ # WEBHOOKS — management API for outbound event delivery. # ============================================================================ # Configure HTTPS endpoints to receive Anchor events (task lifecycle, session # lifecycle, batch lifecycle, identity authentication, human intervention). # Each delivery is signed with HMAC-SHA256 (`Anchor-Signature` header). For # the on-the-wire envelope, signature scheme, retry policy, and per-event # data shapes see /docs/webhooks/{overview,events,signature-verification}. /v1/webhooks: post: summary: Create Webhook operationId: createWebhook description: | Register a new HTTPS endpoint to receive events. The response includes a one-time `secret` (HMAC-SHA256 signing key) — store it; Anchor never returns it again. Up to 5 webhooks per project. security: - api_key_header: [] tags: - Webhooks requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookCreateRequest' examples: taskLifecycle: summary: Subscribe to task lifecycle events value: url: https://your-app.example.com/anchor/webhooks description: Production task notifications subscribed_events: - task.completed - task.failed - task.healed slackForwarder: summary: Forward to a Slack incoming webhook value: url: https://hooks.slack.com/services/YOUR/WEBHOOK/URL description: '#ops alerts' subscribed_events: - task.failed - session.failed - identity.authentication_failed responses: '201': description: Webhook created. The `secret` field is returned ONCE — copy it now. content: application/json: schema: $ref: '#/components/schemas/WebhookWithSecret' '400': description: | Validation error. Common causes — non-HTTPS URL, URL targets a private/loopback IP, cloud metadata service, internal-only TLD (`*.local`/`*.internal`), AWS STS/IAM/EKS endpoint, contains basic-auth credentials, exceeds 2048 chars, or `subscribed_events` is empty. content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '409': description: Per-project webhook limit (5) reached. Delete or reuse an existing webhook. content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '500': description: Failed to create webhook. content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' get: summary: List Webhooks operationId: listWebhooks description: List every active webhook for the authenticated project. The signing secret is never included. security: - api_key_header: [] tags: - Webhooks responses: '200': description: All webhooks for this project. content: application/json: schema: $ref: '#/components/schemas/WebhookListResponse' '500': description: Failed to list webhooks. content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' /v1/webhooks/{id}: get: summary: Get Webhook operationId: getWebhook description: Fetch a single webhook config. The signing secret is never returned. security: - api_key_header: [] tags: - Webhooks parameters: - name: id in: path required: true description: Webhook id. schema: type: string responses: '200': description: Webhook config. content: application/json: schema: $ref: '#/components/schemas/WebhookPublic' '404': description: Webhook not found in this project. content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '500': description: Failed to load webhook. content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' patch: summary: Update Webhook operationId: updateWebhook description: | Partial update — pass only the fields you want to change. Setting `enabled: false` immediately stops events from fanning out to this webhook (existing in-flight deliveries finish their attempts). security: - api_key_header: [] tags: - Webhooks parameters: - name: id in: path required: true description: Webhook id. schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookUpdateRequest' examples: changeUrl: summary: Move to a new endpoint URL value: url: https://new-host.example.com/anchor/webhooks addEvents: summary: Add session events to subscriptions value: subscribed_events: - task.completed - task.failed - session.completed - session.failed disable: summary: Pause delivery without losing config value: enabled: false responses: '200': description: Webhook updated. content: application/json: schema: $ref: '#/components/schemas/WebhookPublic' '400': description: Validation error (URL constraints same as create). content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Webhook not found in this project. content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '500': description: Failed to update webhook. content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' delete: summary: Delete Webhook operationId: deleteWebhook description: | Soft-delete a webhook. New events stop fanning out immediately. The events history (`/v1/webhooks/{id}/events`) is still queryable for the retention window even after delete. security: - api_key_header: [] tags: - Webhooks parameters: - name: id in: path required: true description: Webhook id. schema: type: string responses: '200': description: Webhook deleted. content: application/json: schema: $ref: '#/components/schemas/WebhookDeleteResponse' '404': description: Webhook not found in this project. content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '500': description: Failed to delete webhook. content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' /v1/webhooks/{id}/rotate-secret: post: summary: Rotate Webhook Signing Secret operationId: rotateWebhookSecret description: | Mint a new HMAC-SHA256 signing secret. The previous secret remains valid for 24 hours so you can update your verification code at your own pace, then drop the old secret. The new secret is returned exactly once, in the `secret` field. security: - api_key_header: [] tags: - Webhooks parameters: - name: id in: path required: true description: Webhook id. schema: type: string responses: '200': description: New signing secret issued. content: application/json: schema: $ref: '#/components/schemas/WebhookWithSecret' '404': description: Webhook not found in this project. content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '500': description: Failed to rotate secret. content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' /v1/webhooks/{id}/test: post: summary: Send Test Event operationId: sendWebhookTestEvent description: | Fire a synthetic event of the given type through the real signing + retry path. Useful during development for confirming your endpoint can verify the signature and is reachable from Anchor's egress IPs. The synthetic delivery counts toward your delivery log so you can see it in `GET /v1/webhooks/{id}/events`. security: - api_key_header: [] tags: - Webhooks parameters: - name: id in: path required: true description: Webhook id. schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookTestRequest' examples: taskCompleted: summary: Test a task.completed event value: event_type: task.completed sessionRecordingReady: summary: Test a session.recording.ready event value: event_type: session.recording.ready responses: '202': description: Synthetic event accepted and enqueued for delivery. content: application/json: schema: $ref: '#/components/schemas/WebhookTestResponse' '400': description: Unknown event type. content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '404': description: Webhook not found in this project. content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '500': description: Failed to enqueue test event. content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' /v1/webhooks/{id}/events: get: summary: List Webhook Deliveries operationId: listWebhookEvents description: | Paginated history of every delivery attempt for this webhook (succeeded, failed, or dead-lettered). Filter by status, event type, or time range. Retention: 7 days. security: - api_key_header: [] tags: - Webhooks parameters: - name: id in: path required: true description: Webhook id. schema: type: string - name: limit in: query required: false description: Page size, 1–100. Defaults to 25. schema: type: integer minimum: 1 maximum: 100 default: 25 - name: offset in: query required: false description: Number of rows to skip from the beginning of the result set. schema: type: integer minimum: 0 default: 0 - name: status in: query required: false description: Filter by delivery status. schema: type: string enum: - pending - succeeded - failed - dead - name: event_type in: query required: false description: Filter by event type. schema: $ref: '#/components/schemas/WebhookEventType' - name: since in: query required: false description: Only include deliveries scheduled at or after this ISO 8601 timestamp. schema: type: string format: date-time - name: until in: query required: false description: Only include deliveries scheduled at or before this ISO 8601 timestamp. schema: type: string format: date-time - name: include_payload in: query required: false description: > Set to `true` to include each delivery's sanitized event `data` (as delivered to your endpoint) in the `payload` field of every row. schema: type: string enum: - 'true' - 'false' responses: '200': description: Page of delivery rows plus pagination metadata. content: application/json: schema: $ref: '#/components/schemas/WebhookEventsListResponse' '404': description: Webhook not found in this project. content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' '500': description: Failed to load webhook events. content: application/json: schema: $ref: '#/components/schemas/FlatErrorResponse' /v1/volumes: post: summary: Create Volume description: Create a persistent volume for your team. The volume is usually `ready` immediately; if the response says `creating`, poll `GET /v1/volumes/{volume_id}` until it is. Each team can have up to 10 volumes. security: - api_key_header: [] tags: - Volumes requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string description: Volume name, unique within your team. Letters, numbers, `_` and `-`, up to 64 characters. example: customer-reports responses: '200': description: Volume created content: application/json: schema: $ref: '#/components/schemas/VolumeResponse' '400': description: Invalid name content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Volumes are not enabled for this team content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: A volume with this name already exists, or the team reached its volume limit content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' get: summary: List Volumes description: List the volumes of your team. security: - api_key_header: [] tags: - Volumes parameters: - name: include_deleted in: query required: false description: Include deleted volumes. Defaults to `false`. schema: type: string enum: ['true', 'false'] - name: state in: query required: false description: Only return volumes in this state schema: type: string enum: [creating, ready, deleting, deleted, error] responses: '200': description: Volumes retrieved successfully content: application/json: schema: $ref: '#/components/schemas/VolumeListResponse' /v1/volumes/by-name/{name}: get: summary: Get Volume By Name description: Get a volume by its name. security: - api_key_header: [] tags: - Volumes parameters: - name: name in: path required: true schema: type: string responses: '200': description: Volume details content: application/json: schema: $ref: '#/components/schemas/VolumeResponse' '404': description: Volume not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/volumes/{volume_id}: get: summary: Get Volume description: Get a volume by its ID. Deleted volumes return `404`; use `GET /v1/volumes?include_deleted=true` to see them. security: - api_key_header: [] tags: - Volumes parameters: - name: volume_id in: path required: true schema: type: string format: uuid responses: '200': description: Volume details content: application/json: schema: $ref: '#/components/schemas/VolumeResponse' '404': description: Volume not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' delete: summary: Delete Volume description: Delete a volume and every file in it. Refused while a running session has the volume mounted; end those sessions first. security: - api_key_header: [] tags: - Volumes parameters: - name: volume_id in: path required: true schema: type: string format: uuid responses: '200': description: Deletion finished (`deleted`) or still in progress (`deleting`) content: application/json: schema: type: object properties: data: type: object properties: id: type: string format: uuid status: type: string enum: [deleting, deleted] '404': description: Volume not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: The volume is mounted by a running session content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/volumes/{volume_id}/files: get: summary: List Files description: List the contents of a folder in the volume (one level, like `ls`), or the whole tree with `recursive=true`. Files written by a running session appear here about a minute after the session stops writing to them. security: - api_key_header: [] tags: - Volume Files parameters: - name: volume_id in: path required: true schema: type: string format: uuid - name: path in: query required: false description: Folder to list, relative to the volume root. Omit for the root. schema: type: string example: downloads - name: recursive in: query required: false description: List every file under `path` instead of one level schema: type: string enum: ['true', 'false'] - name: cursor in: query required: false description: '`next_cursor` from the previous page' schema: type: string - name: limit in: query required: false description: Page size, 1 to 1000 schema: type: string responses: '200': description: Folder listing content: application/json: schema: $ref: '#/components/schemas/VolumeFileListResponse' '404': description: Volume not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '412': description: The volume is not `ready` content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' post: summary: Upload File description: Upload a file into the volume in one multipart request. For files larger than 10 MB use `POST /v1/volumes/{volume_id}/files/upload-url` instead. security: - api_key_header: [] tags: - Volume Files parameters: - name: volume_id in: path required: true schema: type: string format: uuid requestBody: required: true content: multipart/form-data: schema: type: object required: - file properties: file: type: string format: binary description: The file to upload path: type: string description: Destination path relative to the volume root, e.g. `downloads/report.pdf`. Defaults to the uploaded file's name at the root. overwrite: type: string enum: ['true', 'false'] description: Replace an existing file at `path`. Defaults to `false`. responses: '200': description: File uploaded content: application/json: schema: $ref: '#/components/schemas/VolumeFileInfoResponse' '400': description: Missing file or invalid path content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: A file already exists at `path` and `overwrite` is not set content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '413': description: File too large for a multipart upload; use an upload URL content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' delete: summary: Delete Files description: Delete one file (`path`) or everything under a folder (`prefix` with `recursive=true`). security: - api_key_header: [] tags: - Volume Files parameters: - name: volume_id in: path required: true schema: type: string format: uuid - name: path in: query required: false description: File to delete, relative to the volume root schema: type: string - name: prefix in: query required: false description: Folder to delete recursively; requires `recursive=true` schema: type: string - name: recursive in: query required: false schema: type: string enum: ['true', 'false'] responses: '200': description: Files deleted content: application/json: schema: type: object properties: data: type: object properties: status: type: string enum: [success] deleted_count: type: integer '404': description: Volume or file not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/volumes/{volume_id}/files/upload-url: post: summary: Create Upload URL description: Get a pre-signed URL to upload a file of any size (up to 5 GB) directly to storage. `PUT` the file body to `signed_url` and send the returned `headers` unchanged. security: - api_key_header: [] tags: - Volume Files parameters: - name: volume_id in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object required: - path properties: path: type: string description: Destination path relative to the volume root example: inputs/dataset.csv content_type: type: string description: MIME type of the file. Defaults to `application/octet-stream`. size: type: integer description: Size in bytes, if known responses: '200': description: Upload URL created content: application/json: schema: $ref: '#/components/schemas/VolumeUploadUrlResponse' '400': description: Invalid path or size content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/volumes/{volume_id}/files/stat: get: summary: Get File Info description: Size, type and modification time of one file. security: - api_key_header: [] tags: - Volume Files parameters: - name: volume_id in: path required: true schema: type: string format: uuid - name: path in: query required: true description: File path relative to the volume root schema: type: string example: downloads/report.pdf responses: '200': description: File metadata content: application/json: schema: $ref: '#/components/schemas/VolumeFileInfoResponse' '404': description: Volume or file not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/volumes/{volume_id}/files/download: get: summary: Download File description: Get a pre-signed URL for a file. Pass `redirect=true` to be redirected to the file instead of receiving the URL. security: - api_key_header: [] tags: - Volume Files parameters: - name: volume_id in: path required: true schema: type: string format: uuid - name: path in: query required: true description: File path relative to the volume root schema: type: string example: downloads/report.pdf - name: redirect in: query required: false description: Respond with a `302` to the file instead of JSON schema: type: string enum: ['true', 'false'] responses: '200': description: Download URL content: application/json: schema: $ref: '#/components/schemas/VolumeDownloadUrlResponse' '302': description: Redirect to the file (`redirect=true`) '404': description: Volume or file not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v1/volumes/{volume_id}/paths: get: summary: List All Paths description: Flat list of every path in the volume, optionally under a prefix. Folders appear with a trailing slash (for example `downloads/`). security: - api_key_header: [] tags: - Volume Files parameters: - name: volume_id in: path required: true schema: type: string format: uuid - name: prefix in: query required: false description: Only paths under this folder schema: type: string - name: cursor in: query required: false schema: type: string - name: limit in: query required: false description: Page size, 1 to 1000 schema: type: string responses: '200': description: File paths content: application/json: schema: $ref: '#/components/schemas/VolumePathListResponse' /v1/volumes/{volume_id}/directories: post: summary: Create Directory description: Create an empty folder in the volume. Folders are also created implicitly when a file is uploaded to a path inside them. security: - api_key_header: [] tags: - Volume Files parameters: - name: volume_id in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object required: - path properties: path: type: string example: reports/2026 responses: '200': description: Directory created content: application/json: schema: type: object properties: data: type: object properties: path: type: string type: type: string enum: [directory] '409': description: A file already exists at this path content: application/json: schema: $ref: '#/components/schemas/ErrorResponse'