> ## Documentation Index
> Fetch the complete documentation index at: https://docs.surfsky.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Start one-time session

> Start a browser without a saved profile. The response returns connection fields at the top level. Use the returned internal_uuid to stop the session. Supply a proxy or VPN, or use a pool available to your account. Shared HTTP cache can be enabled separately from profile storage. See [the session guide](/sessions).



## OpenAPI

````yaml /api-reference/openapi.json post /profiles/one_time
openapi: 3.1.0
info:
  title: Surfsky API
  version: 0.1.0
  description: >-
    Start cloud browsers, control them through CDP, and manage the profiles,
    proxies, and fingerprints they run with.
servers:
  - url: '{baseUrl}'
    variables:
      baseUrl:
        default: https://YOUR_API_HOST
        description: API base URL from your Surfsky dashboard, including https://.
security:
  - ApiToken: []
tags:
  - name: profiles
    description: >-
      Start, stop, and manage browsers. A one-time profile is discarded when it
      stops; a persistent profile keeps its cookies, storage, and fingerprint
      according to its storage settings.
  - name: proxies
    description: >-
      Look up what the premium and shared pools can offer before you pin a
      location, and read your traffic quota.
  - name: fingerprints
    description: >-
      The value sets a fingerprint field accepts. Use these to pin a renderer,
      screen, or device model instead of guessing at a string.
  - name: extensions
    description: Upload Chrome extensions once and load them into any browser you start.
  - name: captcha
    description: Balance on the CAPTCHA solver behind your account.
paths:
  /profiles/one_time:
    post:
      tags:
        - profiles
      summary: Start one-time session
      description: >-
        Start a browser without a saved profile. The response returns connection
        fields at the top level. Use the returned internal_uuid to stop the
        session. Supply a proxy or VPN, or use a pool available to your account.
        Shared HTTP cache can be enabled separately from profile storage. See
        [the session guide](/sessions).
      operationId: start_one_time_profile_profiles_one_time_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartOneTimeProfileIn'
            example: {}
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionStarted'
              example:
                success: true
                internal_uuid: a8fb62f90611456aa75422b01c385a62
                ws_url: wss://YOUR_API_HOST/proxy/a8fb62f90611456aa75422b01c385a62
                inspector:
                  list: >-
                    https://YOUR_API_HOST/proxy/a8fb62f90611456aa75422b01c385a62/inspector
                  pages: []
                  screencast: >-
                    wss://YOUR_API_HOST/screencast/a8fb62f90611456aa75422b01c385a62/devtools/page/PAGE_ID
        '401':
          description: Missing or invalid API token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Account or feature access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: Request validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Request, browser, session, or traffic limit reached; inspect code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
components:
  schemas:
    StartOneTimeProfileIn:
      properties:
        proxy_blacklist:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Proxy Blacklist
        domain_routes:
          anyOf:
            - items:
                $ref: '#/components/schemas/DomainRouteConfig'
              type: array
            - type: 'null'
          title: Domain Routes
        proxy:
          anyOf:
            - type: string
              minLength: 1
              format: uri
            - $ref: '#/components/schemas/ProxyConfig'
          title: Proxy
          description: >-
            Proxy URL or pool selection. Choose tier explicitly to require
            shared or premium. See the [proxy guide](/proxies) for targeting
            rules.
        open_vpn:
          $ref: '#/components/schemas/OpenVPNConfig'
        wireguard:
          $ref: '#/components/schemas/WireGuardConfig'
        anti_captcha:
          $ref: '#/components/schemas/AntiCaptchaIn'
        enable_chromedriver:
          type: boolean
          title: Enable Chromedriver
          default: false
        extensions:
          items:
            type: string
          type: array
          maxItems: 5
          title: Extensions
        browser_settings:
          $ref: '#/components/schemas/BrowserSettings'
        fingerprint:
          $ref: '#/components/schemas/OneTimeProfileFingerprint'
        cookies:
          items:
            $ref: '#/components/schemas/JsonCookie'
          type: array
          minItems: 1
          title: Cookies
        show_config:
          type: boolean
          title: Show Config
          default: false
      additionalProperties: false
      type: object
      title: StartOneTimeProfileIn
    SessionStarted:
      type: object
      properties:
        success:
          type: boolean
          const: true
        internal_uuid:
          type: string
          description: >-
            Identifier to use for stop, scrape, and live connections. May equal
            profile_uuid.
        ws_url:
          type: string
          description: Live CDP connection URL. Keep private.
        inspector:
          type: object
          properties:
            list:
              type: string
            pages:
              type: array
              items:
                type: object
                properties:
                  page_url:
                    type: string
                  devtools_url:
                    type: string
            screencast:
              type: string
          required:
            - list
            - pages
            - screencast
      required:
        - success
        - internal_uuid
        - ws_url
        - inspector
    ApiError:
      type: object
      properties:
        success:
          type: boolean
          const: false
        msg:
          type: string
        code:
          type: string
        data: {}
        detail: {}
        error: {}
      description: >-
        Error fields vary for forwarded responses. Check HTTP status and code
        when present.
    DomainRouteConfig:
      properties:
        proxy:
          type: string
          minLength: 1
          format: uri
          title: Proxy
        domain:
          items:
            type: string
          type: array
          title: Domain
        domain_suffix:
          items:
            type: string
          type: array
          title: Domain Suffix
        domain_keyword:
          items:
            type: string
          type: array
          title: Domain Keyword
        domain_regex:
          items:
            type: string
          type: array
          title: Domain Regex
      type: object
      required:
        - proxy
      title: DomainRouteConfig
      description: >-
        Route specific domains through a different proxy.


        - domain: exact domain match (e.g., ["google.com"])

        - domain_suffix: suffix match (e.g., [".google.com"] matches
        *.google.com)

        - domain_keyword: keyword match (e.g., ["google"] matches any domain
        containing "google")

        - domain_regex: regex match (e.g., ["^stun\\..+"] matches
        stun.example.com)
    ProxyConfig:
      properties:
        tier:
          anyOf:
            - $ref: '#/components/schemas/ProxyTier'
            - type: 'null'
        type:
          anyOf:
            - $ref: '#/components/schemas/ProxyType'
            - type: 'null'
        country:
          anyOf:
            - type: string
              pattern: ^[A-Za-z]{2}$
            - type: 'null'
          title: Country
        region:
          anyOf:
            - type: string
              pattern: ^[\w \-]{1,64}$
            - type: 'null'
          title: Region
        city:
          anyOf:
            - type: string
              pattern: ^[\w \-]{1,64}$
            - type: 'null'
          title: City
        pool:
          anyOf:
            - $ref: '#/components/schemas/RegionalPool'
            - type: 'null'
        asn:
          anyOf:
            - type: integer
              maximum: 4294967295
              minimum: 1
            - type: 'null'
          title: Asn
        lat:
          anyOf:
            - type: number
              maximum: 90
              minimum: -90
            - type: 'null'
          title: Lat
        lon:
          anyOf:
            - type: number
              maximum: 180
              minimum: -180
            - type: 'null'
          title: Lon
        session_minutes:
          anyOf:
            - type: integer
              maximum: 10080
              minimum: 1
            - type: 'null'
          title: Session Minutes
        unique_ip:
          type: boolean
          title: Unique Ip
          default: false
        keep_asn:
          type: boolean
          title: Keep Asn
          default: false
        keep_ip:
          type: boolean
          title: Keep Ip
          default: false
      additionalProperties: false
      type: object
      title: ProxyConfig
    OpenVPNConfig:
      properties:
        config:
          type: string
          title: Config
        username:
          type: string
          title: Username
          default: ''
        password:
          type: string
          title: Password
          default: ''
      type: object
      required:
        - config
      title: OpenVPNConfig
    WireGuardConfig:
      properties:
        private_key:
          type: string
          title: Private Key
        address:
          items:
            type: string
          type: array
          title: Address
        peers:
          items:
            $ref: '#/components/schemas/WireGuardPeerConfig'
          type: array
          title: Peers
        mtu:
          type: integer
          title: Mtu
          default: 1408
      type: object
      required:
        - private_key
        - address
        - peers
      title: WireGuardConfig
    AntiCaptchaIn:
      properties:
        enabled:
          type: boolean
          title: Enabled
          default: false
        gemini_api_key:
          anyOf:
            - type: string
            - type: 'null'
          title: Gemini Api Key
        disable_external_providers:
          type: boolean
          title: Disable External Providers
          default: false
        external_providers_initially_enabled:
          type: boolean
          title: External Providers Initially Enabled
          default: true
        auto_captcha_types:
          items:
            type: string
          type: array
          title: Auto Captcha Types
          default:
            - recaptcha
            - hcaptcha
            - geetest
            - turnstile
            - bls
            - perimeterx
            - datadome
            - datadome_audio
      type: object
      title: AntiCaptchaIn
    BrowserSettings:
      properties:
        inactive_kill_timeout:
          type: integer
          maximum: 3600
          minimum: 1
          title: Inactive Kill Timeout
          default: 30
          description: >-
            Seconds without browser activity before automatic stop. An idle
            WebSocket alone does not keep the session active.
        cache_enabled:
          type: boolean
          title: Cache Enabled
          default: false
        cache_key:
          anyOf:
            - type: string
              maxLength: 255
              pattern: ^[A-Za-z0-9_-][A-Za-z0-9._-]*$
            - type: 'null'
          title: Cache Key
          description: >-
            Required when cache_enabled is true. See [shared
            cache](/shared-cache) for sharing behavior.
      type: object
      title: BrowserSettings
    OneTimeProfileFingerprint:
      properties:
        user_agent:
          type: string
          title: User Agent
        screen:
          type: string
          title: Screen
        languages:
          items:
            type: string
          type: array
          title: Languages
        timezone:
          type: string
          title: Timezone
        geolocation:
          $ref: '#/components/schemas/Geolocation'
        cpu:
          type: integer
          title: Cpu
        ram:
          type: integer
          title: Ram
        renderer:
          type: string
          title: Renderer
        noise:
          additionalProperties: true
          type: object
          title: Noise
        dns:
          anyOf:
            - type: string
            - type: 'null'
          title: Dns
        media_devices:
          additionalProperties: true
          type: object
          title: Media Devices
        webrtc:
          additionalProperties: true
          type: object
          title: Webrtc
          default:
            type: real
        os:
          $ref: '#/components/schemas/OSTypeIn'
          default: win
        os_arch:
          type: string
          title: Os Arch
        os_version:
          type: string
          title: Os Version
        device_model:
          type: string
          title: Device Model
        device_type:
          type: string
          title: Device Type
      additionalProperties: false
      type: object
      title: OneTimeProfileFingerprint
    JsonCookie:
      properties:
        domain:
          type: string
          title: Domain
        path:
          type: string
          title: Path
        expirationDate:
          type: integer
          title: Expirationdate
        sameSite:
          type: string
          title: Samesite
        name:
          type: string
          title: Name
        value:
          type: string
          title: Value
        hostOnly:
          type: boolean
          title: Hostonly
        httpOnly:
          type: boolean
          title: Httponly
        secure:
          type: boolean
          title: Secure
        session:
          type: boolean
          title: Session
      additionalProperties: false
      type: object
      required:
        - domain
        - path
        - expirationDate
        - sameSite
        - name
        - value
        - hostOnly
        - httpOnly
        - secure
        - session
      title: JsonCookie
    ProxyTier:
      type: string
      enum:
        - shared
        - premium
      title: ProxyTier
    ProxyType:
      type: string
      enum:
        - residential
        - mobile
      title: ProxyType
    RegionalPool:
      type: string
      enum:
        - western
        - europe
        - westeurope
        - northamerica
        - southamerica
        - asia
        - centralasia
        - southasia
        - eastasia
        - sea
        - oceania
        - mena
        - middleeast
        - africa
        - northafrica
        - westafrica
        - eastafrica
        - centralafrica
        - southernafrica
      title: RegionalPool
    WireGuardPeerConfig:
      properties:
        public_key:
          type: string
          title: Public Key
        endpoint:
          type: string
          title: Endpoint
        allowed_ips:
          items:
            type: string
          type: array
          title: Allowed Ips
        pre_shared_key:
          anyOf:
            - type: string
            - type: 'null'
          title: Pre Shared Key
        persistent_keepalive_interval:
          anyOf:
            - type: integer
            - type: 'null'
          title: Persistent Keepalive Interval
        reserved:
          anyOf:
            - items:
                type: integer
              type: array
            - type: 'null'
          title: Reserved
      type: object
      required:
        - public_key
        - endpoint
      title: WireGuardPeerConfig
    Geolocation:
      properties:
        latitude:
          type: number
          maximum: 90
          minimum: -90
          title: Latitude
        longitude:
          type: number
          maximum: 180
          minimum: -180
          title: Longitude
        accuracy:
          type: integer
          maximum: 999
          minimum: 1
          title: Accuracy
      type: object
      required:
        - latitude
        - longitude
        - accuracy
      title: Geolocation
    OSTypeIn:
      type: string
      enum:
        - win
        - mac
        - android
      title: OSTypeIn
  securitySchemes:
    ApiToken:
      type: apiKey
      in: header
      name: X-Cloud-Api-Token
      description: API token from your dashboard.

````