openapi: 3.0.1
info:
  title: Notte API
  description: >-
    Notte is a REST API for web browser and agent infrastructure for AI. It
    creates cloud browser sessions, runs autonomous web agents from
    natural-language tasks, exposes a perception layer to observe / step /
    scrape live pages, performs one-shot scraping and AI web search, and manages
    personas, vaults, profiles, secrets, file storage, and serverless functions.
    The core framework is open source (SSPL-1.0). This document models the
    primary documented surface; see https://api.notte.cc/openapi.json for the
    full machine-generated specification.
  termsOfService: https://notte.cc/terms
  contact:
    name: Notte
    url: https://notte.cc
  license:
    name: Server Side Public License v1 (SSPL-1.0)
    url: https://www.mongodb.com/licensing/server-side-public-license
  version: 1.4.40
servers:
  - url: https://api.notte.cc
security:
  - BearerAuth: []
tags:
  - name: Sessions
    description: Create and manage remote cloud browser sessions.
  - name: Page
    description: Perception layer - observe, step (execute), and scrape a live session page.
  - name: Agents
    description: Run autonomous web agents from natural-language tasks.
  - name: Scraping
    description: One-shot scraping of a URL or raw HTML, plus AI web search.
  - name: Personas
    description: Disposable digital identities with email, phone, and 2FA.
  - name: Vaults
    description: Secure credential and credit-card storage injected into runs.
  - name: Health
    description: Service health check.
paths:
  /health:
    get:
      operationId: healthCheck
      tags:
        - Health
      summary: Health check
      description: Returns the health status of the Notte API.
      security: []
      responses:
        '200':
          description: Service is healthy.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
  /sessions/start:
    post:
      operationId: sessionStart
      tags:
        - Sessions
      summary: Session Start
      description: Starts a remote cloud browser session.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionStartRequest'
      responses:
        '200':
          description: The started session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionResponse'
  /sessions:
    get:
      operationId: listSessions
      tags:
        - Sessions
      summary: List Sessions
      description: Lists sessions for the authenticated account.
      parameters:
        - name: only_active
          in: query
          required: false
          schema:
            type: boolean
            default: false
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: A paginated list of sessions.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SessionResponse'
  /sessions/{session_id}:
    get:
      operationId: sessionStatus
      tags:
        - Sessions
      summary: Session Status
      description: Returns the current status of a session.
      parameters:
        - $ref: '#/components/parameters/SessionId'
      responses:
        '200':
          description: The session status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionResponse'
  /sessions/{session_id}/stop:
    delete:
      operationId: sessionStop
      tags:
        - Sessions
      summary: Session Stop
      description: Stops and closes a running session.
      parameters:
        - $ref: '#/components/parameters/SessionId'
      responses:
        '200':
          description: The closed session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionResponse'
  /sessions/{session_id}/debug:
    get:
      operationId: sessionDebugInfo
      tags:
        - Sessions
      summary: Session Debug Info
      description: Returns debug information including the live viewer and CDP URLs.
      parameters:
        - $ref: '#/components/parameters/SessionId'
      responses:
        '200':
          description: Debug information for the session.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ws_url:
                    type: string
                  cdp_url:
                    type: string
                  viewer_url:
                    type: string
  /sessions/{session_id}/replay:
    get:
      operationId: sessionReplay
      tags:
        - Sessions
      summary: Session Replay
      description: Returns a replay (WEBP) of the session.
      parameters:
        - $ref: '#/components/parameters/SessionId'
      responses:
        '200':
          description: Session replay binary.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
  /sessions/{session_id}/cookies:
    get:
      operationId: sessionCookiesGet
      tags:
        - Sessions
      summary: Session Cookies Get
      description: Returns the cookies for a session.
      parameters:
        - $ref: '#/components/parameters/SessionId'
      responses:
        '200':
          description: The session cookies.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CookiesResponse'
    post:
      operationId: sessionCookiesSet
      tags:
        - Sessions
      summary: Session Cookies Set
      description: Sets cookies on a session.
      parameters:
        - $ref: '#/components/parameters/SessionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetCookiesRequest'
      responses:
        '200':
          description: Cookies set.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CookiesResponse'
  /sessions/{session_id}/page/observe:
    post:
      operationId: pageObserve
      tags:
        - Page
      summary: Page Observe
      description: >-
        Runs Notte's perception layer on the current page and returns the set of
        available actions a model or human can take next.
      parameters:
        - $ref: '#/components/parameters/SessionId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ObserveRequest'
      responses:
        '200':
          description: The observation including available actions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObserveResponse'
  /sessions/{session_id}/page/execute:
    post:
      operationId: pageExecute
      tags:
        - Page
      summary: Page Execute (Step)
      description: >-
        Executes a single action (a step) on the current page, such as click,
        fill, scroll, navigate, select, upload, or wait.
      parameters:
        - $ref: '#/components/parameters/SessionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StepRequest'
      responses:
        '200':
          description: The result of the executed action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StepResponse'
  /sessions/{session_id}/page/scrape:
    post:
      operationId: pageScrape
      tags:
        - Page
      summary: Page Scrape
      description: Scrapes structured content from the current page of a session.
      parameters:
        - $ref: '#/components/parameters/SessionId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScrapeRequest'
      responses:
        '200':
          description: The scraped content.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScrapeResponse'
  /sessions/{session_id}/page/screenshot:
    post:
      operationId: pageScreenshot
      tags:
        - Page
      summary: Page Screenshot
      description: Captures a screenshot of the current page.
      parameters:
        - $ref: '#/components/parameters/SessionId'
      responses:
        '200':
          description: The screenshot image.
          content:
            image/png:
              schema:
                type: string
                format: binary
  /agents/start:
    post:
      operationId: agentStart
      tags:
        - Agents
      summary: Agent Start
      description: >-
        Starts an autonomous web agent that performs a natural-language task on a
        browser session.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentStartRequest'
      responses:
        '200':
          description: The started agent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
  /agents:
    get:
      operationId: listAgents
      tags:
        - Agents
      summary: List Agents
      description: Lists agents for the authenticated account.
      parameters:
        - name: only_active
          in: query
          required: false
          schema:
            type: boolean
            default: false
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: A list of agents.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgentResponse'
  /agents/{agent_id}:
    get:
      operationId: agentStatus
      tags:
        - Agents
      summary: Agent Status
      description: Returns the status and result of an agent run.
      parameters:
        - $ref: '#/components/parameters/AgentId'
      responses:
        '200':
          description: The agent status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentStatusResponse'
  /agents/{agent_id}/stop:
    delete:
      operationId: agentStop
      tags:
        - Agents
      summary: Agent Stop
      description: Stops a running agent.
      parameters:
        - $ref: '#/components/parameters/AgentId'
      responses:
        '200':
          description: The stopped agent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
  /agents/{agent_id}/workflow/code:
    get:
      operationId: getScript
      tags:
        - Agents
      summary: Get Script
      description: Returns the reproducible workflow script generated from an agent run.
      parameters:
        - $ref: '#/components/parameters/AgentId'
      responses:
        '200':
          description: The generated workflow code.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
  /scrape:
    post:
      operationId: scrapeWebpage
      tags:
        - Scraping
      summary: Scrape Webpage
      description: >-
        One-shot scrape of a URL. Returns main content, links, images, or
        AI-extracted structured data against an optional response format.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GlobalScrapeRequest'
      responses:
        '200':
          description: The scraped content.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScrapeResponse'
  /scrape_from_html:
    post:
      operationId: scrapeFromHtml
      tags:
        - Scraping
      summary: Scrape From HTML
      description: Scrapes structured content from a supplied raw HTML payload.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScrapeFromHtmlRequest'
      responses:
        '200':
          description: The scraped content.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScrapeResponse'
  /search:
    post:
      operationId: searchWeb
      tags:
        - Scraping
      summary: Search Web
      description: Runs an AI web search and returns results.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          description: The search results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
  /personas/create:
    post:
      operationId: personaCreate
      tags:
        - Personas
      summary: Persona Create
      description: >-
        Creates a disposable digital identity, optionally with a phone number
        and a dedicated vault, for account-creation and authentication workflows.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonaCreateRequest'
      responses:
        '200':
          description: The created persona.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonaResponse'
  /personas:
    get:
      operationId: listPersonas
      tags:
        - Personas
      summary: List Personas
      description: Lists personas for the authenticated account.
      responses:
        '200':
          description: A paginated list of personas.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PersonaResponse'
  /personas/{persona_id}:
    get:
      operationId: personaGet
      tags:
        - Personas
      summary: Persona Get
      description: Returns a persona by ID.
      parameters:
        - $ref: '#/components/parameters/PersonaId'
      responses:
        '200':
          description: The persona.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonaResponse'
    delete:
      operationId: personaDelete
      tags:
        - Personas
      summary: Persona Delete
      description: Deletes a persona.
      parameters:
        - $ref: '#/components/parameters/PersonaId'
      responses:
        '200':
          description: The deleted persona.
          content:
            application/json:
              schema:
                type: object
                properties:
                  persona_id:
                    type: string
                  status:
                    type: string
  /personas/{persona_id}/emails:
    get:
      operationId: personaEmailsList
      tags:
        - Personas
      summary: Persona Emails List
      description: Lists emails received by the persona inbox.
      parameters:
        - $ref: '#/components/parameters/PersonaId'
      responses:
        '200':
          description: A list of emails.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
  /personas/{persona_id}/sms:
    get:
      operationId: personaSmsList
      tags:
        - Personas
      summary: Persona SMS List
      description: Lists SMS messages received by the persona phone number.
      parameters:
        - $ref: '#/components/parameters/PersonaId'
      responses:
        '200':
          description: A list of SMS messages.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
  /vaults/create:
    post:
      operationId: vaultCreate
      tags:
        - Vaults
      summary: Vault Create
      description: Creates a secure vault for storing credentials and credit cards.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VaultCreateRequest'
      responses:
        '200':
          description: The created vault.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Vault'
  /vaults:
    get:
      operationId: listVaults
      tags:
        - Vaults
      summary: List Vaults
      description: Lists vaults for the authenticated account.
      responses:
        '200':
          description: A paginated list of vaults.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Vault'
  /vaults/{vault_id}:
    delete:
      operationId: vaultDelete
      tags:
        - Vaults
      summary: Vault Delete
      description: Deletes a vault.
      parameters:
        - $ref: '#/components/parameters/VaultId'
      responses:
        '200':
          description: The deleted vault.
          content:
            application/json:
              schema:
                type: object
                properties:
                  vault_id:
                    type: string
                  status:
                    type: string
  /vaults/{vault_id}/credentials:
    get:
      operationId: vaultCredentialsGet
      tags:
        - Vaults
      summary: Vault Credentials Get
      description: Returns stored credentials for a vault.
      parameters:
        - $ref: '#/components/parameters/VaultId'
        - name: url
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: The credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Credential'
    post:
      operationId: vaultCredentialsAdd
      tags:
        - Vaults
      summary: Vault Credentials Add
      description: Adds credentials to a vault.
      parameters:
        - $ref: '#/components/parameters/VaultId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Credential'
      responses:
        '200':
          description: The added credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Credential'
    delete:
      operationId: vaultCredentialsDelete
      tags:
        - Vaults
      summary: Vault Credentials Delete
      description: Deletes credentials from a vault.
      parameters:
        - $ref: '#/components/parameters/VaultId'
        - name: url
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Deletion result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        Notte API key obtained from the Notte Console (https://console.notte.cc),
        passed as a Bearer token in the Authorization header. The SDK reads the
        NOTTE_API_KEY environment variable automatically.
  parameters:
    SessionId:
      name: session_id
      in: path
      required: true
      schema:
        type: string
    AgentId:
      name: agent_id
      in: path
      required: true
      schema:
        type: string
    PersonaId:
      name: persona_id
      in: path
      required: true
      schema:
        type: string
    VaultId:
      name: vault_id
      in: path
      required: true
      schema:
        type: string
  schemas:
    SessionStartRequest:
      type: object
      properties:
        headless:
          type: boolean
          default: true
          description: Whether to run the session in headless mode.
        solve_captchas:
          type: boolean
          default: false
          description: Whether to automatically attempt to solve captchas.
        max_duration_minutes:
          type: integer
          default: 15
          maximum: 1440
          description: Maximum session lifetime in minutes.
        idle_timeout_minutes:
          type: integer
          default: 3
          maximum: 15
          description: Inactivity timeout in minutes.
        proxies:
          description: Proxy configuration (boolean to enable defaults or an array of proxy objects).
          oneOf:
            - type: boolean
            - type: array
              items:
                type: object
        browser_type:
          type: string
          default: chromium
          enum: [chromium, chrome, firefox, chrome-nightly, chrome-turbo]
        user_agent:
          type: string
          nullable: true
        chrome_args:
          type: array
          items:
            type: string
        viewport_width:
          type: integer
          nullable: true
        viewport_height:
          type: integer
          nullable: true
        aspect_ratio:
          type: string
          enum: ['5:4', '16:9']
          nullable: true
        use_file_storage:
          type: boolean
          default: true
        screenshot_type:
          type: string
          default: last_action
          enum: [raw, full, last_action]
        web_bot_auth:
          type: boolean
          default: false
        extra_http_headers:
          type: object
          additionalProperties:
            type: string
          nullable: true
        vault_id:
          type: string
          nullable: true
    SessionResponse:
      type: object
      properties:
        session_id:
          type: string
        status:
          type: string
          enum: [active, closed, error, timed_out]
        created_at:
          type: string
          format: date-time
        last_accessed_at:
          type: string
          format: date-time
        idle_timeout_minutes:
          type: integer
        max_duration_minutes:
          type: integer
        browser_type:
          type: string
        user_agent:
          type: string
          nullable: true
        viewport_width:
          type: integer
          nullable: true
        viewport_height:
          type: integer
          nullable: true
        network_request_bytes:
          type: integer
        network_response_bytes:
          type: integer
        viewer_url:
          type: string
          nullable: true
        cdp_url:
          type: string
          nullable: true
    ObserveRequest:
      type: object
      properties:
        min_nb_actions:
          type: integer
          nullable: true
          description: Minimum number of actions to surface.
        max_nb_actions:
          type: integer
          nullable: true
          description: Maximum number of actions to surface.
        instructions:
          type: string
          nullable: true
          description: Natural-language guidance for what to look for on the page.
        perception_type:
          type: string
          nullable: true
          description: Perception strategy to apply.
    ObserveResponse:
      type: object
      properties:
        session_id:
          type: string
        title:
          type: string
        url:
          type: string
        screenshot:
          type: string
          nullable: true
        space:
          type: object
          description: The action space - the set of available actions on the page.
          properties:
            actions:
              type: array
              items:
                $ref: '#/components/schemas/Action'
    StepRequest:
      type: object
      required:
        - action
      properties:
        action:
          $ref: '#/components/schemas/Action'
    Action:
      type: object
      description: >-
        A single browser action. Examples include click, fill, check, scroll,
        goto, go_back, go_forward, reload, wait, press_key, select_dropdown_option,
        upload_file, download_file, scrape, and captcha_solve.
      required:
        - type
      properties:
        type:
          type: string
          example: click
        id:
          type: string
          description: The action identifier returned by observe.
          nullable: true
        value:
          type: string
          description: The value for fill / select / press_key style actions.
          nullable: true
        url:
          type: string
          description: The target URL for a goto action.
          nullable: true
    StepResponse:
      type: object
      properties:
        session_id:
          type: string
        success:
          type: boolean
        message:
          type: string
          nullable: true
    ScrapeRequest:
      type: object
      properties:
        selector:
          type: string
          nullable: true
          description: Optional CSS selector to scope extraction.
        scrape_links:
          type: boolean
          default: false
        scrape_images:
          type: boolean
          default: false
        ignored_tags:
          type: array
          items:
            type: string
          nullable: true
        only_main_content:
          type: boolean
          default: true
        only_images:
          type: boolean
          default: false
        response_format:
          type: object
          nullable: true
          description: A JSON schema (e.g. derived from a Pydantic model) for AI-structured extraction.
        instructions:
          type: string
          nullable: true
          description: Natural-language extraction instructions.
        use_link_placeholders:
          type: boolean
          default: false
    GlobalScrapeRequest:
      allOf:
        - $ref: '#/components/schemas/ScrapeRequest'
        - type: object
          required:
            - url
          properties:
            url:
              type: string
              description: The URL to scrape.
            headless:
              type: boolean
              default: true
            solve_captchas:
              type: boolean
              default: false
            proxies:
              oneOf:
                - type: boolean
                - type: array
                  items:
                    type: object
            browser_type:
              type: string
              default: chromium
    ScrapeFromHtmlRequest:
      allOf:
        - $ref: '#/components/schemas/ScrapeRequest'
        - type: object
          properties:
            frames:
              type: array
              description: One or more HTML frames to scrape.
              items:
                type: object
                properties:
                  html:
                    type: string
                  url:
                    type: string
    ScrapeResponse:
      type: object
      properties:
        success:
          type: boolean
        content:
          type: string
          nullable: true
          description: The extracted main content (markdown).
        structured:
          type: object
          nullable: true
          description: AI-extracted structured data matching the response_format.
        links:
          type: array
          items:
            type: string
          nullable: true
        images:
          type: array
          items:
            type: string
          nullable: true
    SearchRequest:
      type: object
      required:
        - q
      properties:
        q:
          type: string
          description: The search query.
        depth:
          type: string
          description: Search depth.
        outputType:
          type: string
          description: Desired output type.
    AgentStartRequest:
      type: object
      required:
        - task
        - session_id
      properties:
        task:
          type: string
          description: The task that the agent should perform.
        session_id:
          type: string
          description: The ID of the session to run the agent on.
        url:
          type: string
          nullable: true
          description: Optional starting URL for the agent.
        response_format:
          type: object
          nullable: true
          description: Desired response schema for structured agent output.
        session_offset:
          type: integer
          nullable: true
          description: Step from which to gather information.
        reasoning_model:
          type: string
          default: vertex_ai/gemini-2.5-flash
          description: The reasoning model to use.
        use_vision:
          type: boolean
          default: true
        max_steps:
          type: integer
          default: 20
          minimum: 1
          maximum: 150
        vault_id:
          type: string
          nullable: true
        persona_id:
          type: string
          nullable: true
        notifier_config:
          type: object
          nullable: true
    AgentResponse:
      type: object
      properties:
        agent_id:
          type: string
        created_at:
          type: string
          format: date-time
        session_id:
          type: string
        status:
          type: string
          enum: [active, closed]
        closed_at:
          type: string
          format: date-time
          nullable: true
        saved:
          type: boolean
          default: false
    AgentStatusResponse:
      allOf:
        - $ref: '#/components/schemas/AgentResponse'
        - type: object
          properties:
            task:
              type: string
            success:
              type: boolean
              nullable: true
            answer:
              type: string
              nullable: true
            steps:
              type: array
              items:
                type: object
    PersonaCreateRequest:
      type: object
      properties:
        create_vault:
          type: boolean
          default: false
          description: Whether to create a dedicated vault for the persona.
        create_phone_number:
          type: boolean
          default: false
          description: Whether to provision a phone number for the persona.
    PersonaResponse:
      type: object
      properties:
        persona_id:
          type: string
        email:
          type: string
          nullable: true
        phone_number:
          type: string
          nullable: true
        vault_id:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
    VaultCreateRequest:
      type: object
      properties:
        name:
          type: string
          description: The vault name.
    Vault:
      type: object
      properties:
        vault_id:
          type: string
        name:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
    Credential:
      type: object
      properties:
        url:
          type: string
        username:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
        password:
          type: string
          nullable: true
        mfa_secret:
          type: string
          nullable: true
    CookiesResponse:
      type: object
      properties:
        cookies:
          type: array
          items:
            $ref: '#/components/schemas/Cookie'
    SetCookiesRequest:
      type: object
      required:
        - cookies
      properties:
        cookies:
          type: array
          items:
            $ref: '#/components/schemas/Cookie'
    Cookie:
      type: object
      properties:
        name:
          type: string
        value:
          type: string
        domain:
          type: string
        path:
          type: string
        expires:
          type: number
        httpOnly:
          type: boolean
        secure:
          type: boolean
        sameSite:
          type: string