usestring-ai Browser API

openapi: 3.2.0
info:
  title: String Web Access Browser API
  version: 1.0.0
  description: 'Fetch any http or https URL, search the web, discover a site''s URLs, and run a remote browser over CDP. Fetch and search are billed per request; remote browser sessions are billed by bandwidth and session time. Failed requests are not billed. See https://portal.usestring.ai/docs for guides and pricing. Versioning and deprecation policy: https://portal.usestring.ai/docs/api-reference/versioning (at least 90 days'' notice before removal, with Deprecation and Sunset headers).'
  termsOfService: https://usestring.ai/terms
  contact:
    name: String support
    email: support@usestring.ai
    url: https://portal.usestring.ai/docs
servers:
- url: https://request.usestring.ai/v1
security:
- bearerAuth: []
tags:
- name: Browser
  description: Remote CDP browser over WebSocket and reusable browser profiles (contexts).
paths:
  /contexts:
    post:
      operationId: createBrowserContext
      summary: Create a browser profile
      description: Create a reusable browser profile (context) that saves logins, cookies and site storage between remote browser sessions. Pass the returned `id` as `contextId` when connecting to GET /wss; closing that session saves the profile.
      tags:
      - Browser
      externalDocs:
        url: https://portal.usestring.ai/docs/browser/contexts#create-a-profile
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        description: Retry a create without making a second profile. Scoped to your organization for 24 hours. A retry while creation is in progress returns 409; a malformed or repeated header returns 400.
        schema:
          type: string
          pattern: ^[A-Za-z0-9._:-]{1,255}$
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateContextRequest'
      responses:
        '201':
          description: Profile created, or an idempotent create replayed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Context'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: Insufficient balance for creation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Duplicate name, or a create with the same Idempotency-Key is still in progress (retry with backoff).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Profile limit (25 per organization), storage limit (1 GiB per organization), or request-rate limit reached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalError'
    get:
      operationId: listBrowserContexts
      summary: List browser profiles
      description: List your organization's browser profiles, newest first, without deleted profiles. Use it to find a `contextId`.
      tags:
      - Browser
      externalDocs:
        url: https://portal.usestring.ai/docs/browser/contexts#list-profiles
      parameters:
      - name: limit
        in: query
        required: false
        description: Page size. Invalid values use the default. Stop when a page comes back short.
        schema:
          type: integer
          default: 50
          minimum: 1
          maximum: 200
      - name: offset
        in: query
        required: false
        description: Number of profiles to skip.
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: Profiles returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
  /contexts/{contextId}:
    parameters:
    - name: contextId
      in: path
      required: true
      description: The browser profile's UUID.
      schema:
        type: string
        format: uuid
    get:
      operationId: getBrowserContext
      summary: Inspect a browser profile
      description: Return one browser profile with its status and latest save. Use it to check whether a profile is busy (`IN_USE` or `UPLOADING`) or to confirm that a session's changes were saved.
      tags:
      - Browser
      externalDocs:
        url: https://portal.usestring.ai/docs/browser/contexts#inspect-a-profile
      responses:
        '200':
          description: Profile returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Context'
        '400':
          description: Malformed profile ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: 'Unknown, foreign-owned, or deleted profile (`error: Context not found`).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteBrowserContext
      summary: Delete a browser profile
      description: Delete a browser profile. It becomes unusable at once and its name and slot are free; stored data is removed in the background. Repeating the request returns 202 until the data is gone, then 404.
      tags:
      - Browser
      externalDocs:
        url: https://portal.usestring.ai/docs/browser/contexts#delete-a-profile
      responses:
        '202':
          description: Deletion accepted; stored data is being removed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextDeleteAccepted'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Profile not found for this organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: A saving session is open on the profile. Read-only sessions do not block deletion.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
  /wss:
    get:
      operationId: connectBrowser
      summary: Connect to a remote CDP browser (WebSocket)
      description: 'Open a WebSocket to a remote Chrome DevTools Protocol (CDP) browser for Playwright, Puppeteer or another CDP client, at `wss://request.usestring.ai/v1/wss`. This is a WebSocket upgrade, not a JSON endpoint, so a function-calling layer cannot call it as a plain HTTP request. Send the same `Authorization: Bearer` header when connecting. Failures arrive after the upgrade as WebSocket close frames: `1000` normal close (with persistence on, the profile saves in the background); `1008` authentication, request, quota or access refusal, including an invalid or unrecognized query parameter or a busy profile; `1011` connection failure or session limit reached (retry with backoff); `4008` session bandwidth limit reached (reconnect to continue). Sessions close after 30 minutes, or 5 minutes without traffic. Billed by bandwidth and session time.'
      tags:
      - Browser
      externalDocs:
        url: https://portal.usestring.ai/docs/api-reference/browser-websocket
      servers:
      - url: wss://request.usestring.ai/v1
        description: WebSocket endpoint.
      parameters:
      - name: proxy
        in: query
        required: false
        description: 'Proxy tier for the session''s traffic: `premium` (residential) or `standard` (datacenter, half the premium bandwidth rate).'
        schema:
          type: string
          enum:
          - premium
          - standard
          default: premium
      - name: countryCode
        in: query
        required: false
        description: ISO 3166-1 alpha-2 country the session's traffic exits from. Normalized to uppercase. Profiles do not remember it, so send the same value on every connection that uses a `contextId`.
        schema:
          type: string
          default: US
      - name: contextId
        in: query
        required: false
        description: UUID of a browser profile to restore into the session. Only one saving session can use a profile at a time.
        schema:
          type: string
          format: uuid
      - name: persist
        in: query
        required: false
        description: With `contextId`, save the profile when the session closes. `false` restores it and discards changes; any number of read-only sessions can run at once. Requires `contextId`; a profile that has never been saved cannot be used with `persist=false`.
        schema:
          type: boolean
          default: true
      responses:
        '101':
          description: 'WebSocket upgrade accepted. This alone does not mean authentication succeeded: check for a close frame (code 1008) before assuming the session is ready.'
components:
  schemas:
    RateLimitError:
      description: 429 body. See https://portal.usestring.ai/docs/api-reference/rate-limits
      allOf:
      - $ref: '#/components/schemas/ErrorResponse'
      - type: object
        properties:
          limitRequestsPerSecond:
            type: integer
            description: Your organization's allowed average requests per second.
    ContextList:
      type: object
      required:
      - contexts
      properties:
        contexts:
          type: array
          items:
            $ref: '#/components/schemas/Context'
          description: Newest first, without deleted profiles.
    ErrorResponse:
      type: object
      description: Error body used by most error responses. Errors are always JSON, whatever `format` the request asked for. Key off `statusCode` and `errorType`, not the HTTP status alone. See https://portal.usestring.ai/docs/api-reference/errors
      required:
      - error
      properties:
        error:
          type: string
          description: Error type identifier, for example `Validation error` or `Request failed`.
        message:
          type: string
          description: Human-readable error message.
        statusCode:
          type: integer
          description: The status the destination returned, when the request reached it. Not the HTTP status of this response. Absent when no response came back from the destination (absent means no response, not 0). Can be a success status, for example an anti-bot challenge served as 200 and reported on a 502.
        errorType:
          type: string
          description: 'Machine-readable failure class, sent when the upstream failure can be identified. `TargetCertificateError`: the destination''s TLS certificate cannot be verified (only with `ignoreCertificateErrors: false`). `TooManyRedirectsError`: the redirect chain does not terminate; do not retry. `TerminalOriginError`: the destination''s own configuration produced the answer; do not retry, read `data`. `TargetTimeoutError`: the destination did not respond in time (HTTP 504); retry later. `TargetUnreachableError`: could not connect, or the connection dropped before an answer. `TargetHostNotFoundError`: the hostname has no DNS record (HTTP 502); do not retry until it resolves.'
          enum:
          - TargetCertificateError
          - TooManyRedirectsError
          - TerminalOriginError
          - TargetTimeoutError
          - TargetUnreachableError
          - TargetHostNotFoundError
        traceId:
          type: string
          description: Optional trace identifier.
        issues:
          type: array
          description: Per-field validation issues.
          items:
            type: object
            properties:
              field:
                type: string
                description: The request field the issue is about.
              message:
                type: string
                description: What is wrong with the field.
        data:
          description: The destination's own response body. Present only on a `TerminalOriginError`, where that body is the answer.
        headers:
          type: object
          description: The destination's own response headers. Present exactly when `data` is.
        finalUrl:
          type: string
          description: '`/fetch` only: the URL the response was served from after any redirects, or the requested URL. Sent on `/fetch` error responses too, except when the request body has no valid `url`.'
    Context:
      type: object
      description: A saved browser profile. See https://portal.usestring.ai/docs/browser/contexts#the-profile-object
      required:
      - id
      - name
      - status
      - sizeBytes
      - failureReason
      - latestSaveOperation
      - lastSavedAt
      - lastUsedAt
      - createdAt
      - updatedAt
      properties:
        id:
          type: string
          format: uuid
          description: Opaque UUID used to reconnect (`/wss?contextId=`), inspect, or delete.
        name:
          type:
          - string
          - 'null'
          description: Optional label.
        status:
          $ref: '#/components/schemas/ContextStatus'
        sizeBytes:
          type:
          - integer
          - 'null'
          description: Compressed size of the saved profile. Null before the first successful save.
        failureReason:
          type:
          - string
          - 'null'
          description: Most recent save failure, cleared by a successful save.
        latestSaveOperation:
          oneOf:
          - $ref: '#/components/schemas/ContextSaveOperation'
          - type: 'null'
        lastSavedAt:
          type:
          - string
          - 'null'
          format: date-time
          description: Time of the last successful save.
        lastUsedAt:
          type:
          - string
          - 'null'
          format: date-time
          description: Last connection, saving or read-only. Reading status does not update it.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ContextSaveOperation:
      type: object
      description: The most recent save.
      properties:
        id:
          type: string
        status:
          type: string
          enum:
          - PENDING
          - COMMITTED
          - FAILED
          - EXPIRED
          - SUPERSEDED
          description: '`PENDING`: not finished. `COMMITTED`: succeeded. `FAILED`: failed; read `failureReason`. `EXPIRED`: the session ended before anything was saved. `SUPERSEDED`: another session saved first; not a success.'
        failureReason:
          type:
          - string
          - 'null'
        completedAt:
          type:
          - string
          - 'null'
    ContextStatus:
      type: string
      enum:
      - EMPTY
      - IN_USE
      - UPLOADING
      - READY
      - FAILED
      - DELETING
      description: '`EMPTY`: no saved data. `IN_USE`: a saving session is using the profile. `UPLOADING`: a save is finishing. `READY`: saved data is available. `FAILED`: a save failed; earlier saved data remains. `DELETING`: returned only by DELETE.'
    ContextDeleteAccepted:
      type: object
      required:
      - id
      - status
      - deleted
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - DELETING
        deleted:
          type: boolean
          description: '`false` while stored data is still being removed.'
    CreateContextRequest:
      type: object
      description: Request body for POST /contexts. Unknown fields return 400.
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 200
          description: Optional label, 1-200 characters after trimming, unique among your live profiles. A duplicate returns 409.
  responses:
    InternalError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    TooManyRequests:
      description: Rate limit exceeded. The default limit is 60 requests per second per organization, averaged over a rolling window. Back off and retry with exponential backoff and jitter.
      headers:
        X-RateLimit-Limit-Rps:
          $ref: '#/components/headers/XRateLimitLimitRps'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitError'
    Unauthorized:
      description: Missing or invalid Authorization header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: 'Validation error: invalid input or an unrecognized field. `issues` lists per-field problems.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  headers:
    XRateLimitLimitRps:
      description: Your allowed average requests per second.
      schema:
        type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: 'Send `Authorization: Bearer YOUR_API_KEY`. Get an API key at https://portal.usestring.ai/settings. The same header authenticates the /wss WebSocket.'
externalDocs:
  description: String Web Access API documentation
  url: https://portal.usestring.ai/docs