usestring-ai Sessions API

openapi: 3.2.0
info:
  title: String Web Access Sessions API
  version: 1.0.0
  description: 'Fetch, search, and map the public web through String. Requests egress through rotating proxies with anti-bot handling, so pages that refuse ordinary automated traffic still return content. Full documentation: https://portal.usestring.ai/docs'
  contact:
    name: String
    url: https://usestring.ai
servers:
- url: https://request.usestring.ai/v1
  description: Production
security:
- bearerAuth: []
tags:
- name: Sessions
  description: 'Hosted-browser (`/wss`) sessions as API objects: ids, status, replays, live view and files. Every `/wss` connection gets an id, returned in its `x-session-id` upgrade response header.'
paths:
  /sessions:
    post:
      tags:
      - Sessions
      operationId: createBrowserSession
      summary: Create a browser session
      description: 'Takes the same options as the `/wss` query string and returns a session to connect at `connectUrl` within ten minutes. `record: true` stores a screencast replay.'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BrowserSessionCreateRequest'
      responses:
        '201':
          description: The pending session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrowserSession'
        '400':
          description: The request failed validation. `issues` names the offending fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '403':
          description: Browser contexts are not enabled for this organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '429':
          description: Rate limit or plan quota exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '503':
          description: Session storage is not configured on this deployment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
    get:
      tags:
      - Sessions
      operationId: listBrowserSessions
      summary: List browser sessions
      description: Newest first. Credit-free. Lists sessions made through `POST /sessions`, recorded, or given a file; any other `/wss` session is readable by its `x-session-id` for a week.
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
      - name: offset
        in: query
        schema:
          type: integer
          minimum: 0
          default: 0
      responses:
        '200':
          description: A page of the organization's sessions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrowserSessionList'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '429':
          description: Rate limit or plan quota exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
  /sessions/{sessionId}:
    get:
      tags:
      - Sessions
      operationId: getBrowserSession
      summary: Read a browser session
      description: Status, proxy route and file list. Watch a running session live by opening a WebSocket to `/sessions/{sessionId}/live` with the same `Authorization` header.
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
          pattern: ^ses_[0-9a-f]{32}$
      responses:
        '200':
          description: The session and its files.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrowserSessionDetail'
        '400':
          description: '`sessionId` is not a session id.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '404':
          description: No such session in the caller's organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '429':
          description: Rate limit or plan quota exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
  /sessions/{sessionId}/replay:
    get:
      tags:
      - Sessions
      operationId: getBrowserSessionReplay
      summary: Read a session replay
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
          pattern: ^ses_[0-9a-f]{32}$
      responses:
        '200':
          description: Short-lived URLs for the replay's frame chunks, in order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrowserSessionReplay'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '404':
          description: No such session, or it was not recorded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '429':
          description: Rate limit or plan quota exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '503':
          description: Session storage is not configured on this deployment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
  /sessions/{sessionId}/files:
    get:
      tags:
      - Sessions
      operationId: listBrowserSessionFiles
      summary: List a session's files
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
          pattern: ^ses_[0-9a-f]{32}$
      responses:
        '200':
          description: The session's files with short-lived download URLs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrowserSessionFileList'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '404':
          description: No such session in the caller's organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '429':
          description: Rate limit or plan quota exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
  /sessions/{sessionId}/files/{name}:
    put:
      tags:
      - Sessions
      operationId: putBrowserSessionFile
      summary: Store a file on a session
      description: Stores the request body as one of the session's files, such as a receipt, replacing any file of that name. At most 26214400 bytes and 50 files per session.
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
          pattern: ^ses_[0-9a-f]{32}$
      - name: name
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$
      requestBody:
        required: true
        content:
          '*/*':
            schema:
              type: string
              format: binary
      responses:
        '201':
          description: The stored file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrowserSessionFile'
        '400':
          description: The request failed validation. `issues` names the offending fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '404':
          description: No such session in the caller's organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '409':
          description: The session already holds 50 files.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '413':
          description: The file is too large.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '429':
          description: Rate limit or plan quota exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '503':
          description: Session storage is not configured on this deployment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
    get:
      tags:
      - Sessions
      operationId: getBrowserSessionFile
      summary: Download a session file
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
          pattern: ^ses_[0-9a-f]{32}$
      - name: name
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$
      responses:
        '302':
          description: Redirects to a short-lived download URL.
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '404':
          description: No such session or file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '429':
          description: Rate limit or plan quota exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '503':
          description: Session storage is not configured on this deployment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
components:
  schemas:
    BrowserSessionCreateRequest:
      $schema: https://json-schema.org/draft/2020-12/schema
      type: object
      properties:
        proxy:
          type: string
          enum:
          - standard
          - premium
        countryCode:
          type: string
          minLength: 2
          maxLength: 2
        contextId:
          type: string
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
        persist:
          type: boolean
        record:
          type: boolean
      additionalProperties: false
    ErrorResponse:
      $schema: https://json-schema.org/draft/2020-12/schema
      type: object
      properties:
        error:
          type: string
        statusCode:
          type: number
        message:
          type: string
        traceId:
          type: string
        issues:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
            required:
            - field
            - message
            additionalProperties: false
        errorType:
          type: string
        data: {}
        headers:
          type: object
          propertyNames:
            type: string
          additionalProperties:
            anyOf:
            - type: string
            - type: array
              items:
                type: string
        finalUrl:
          type: string
      required:
      - error
      - message
      additionalProperties: false
    BrowserSessionReplay:
      type: object
      required:
      - id
      - status
      - frameCount
      - format
      - chunks
      - expiresAt
      properties:
        id:
          type: string
        status:
          type: string
        frameCount:
          type: integer
        format:
          const: ndjson
          description: 'Each chunk is newline-delimited JSON, one frame per line: `{t, target, data, width, height}`, where `t` is epoch ms, `target` names the tab, and `data` is a base64 JPEG.'
        chunks:
          type: array
          items:
            type: object
            required:
            - tabId
            - index
            - url
            properties:
              tabId:
                type: string
                description: The recorded tab; each tab has its own chunks.
              index:
                type: integer
                description: Chunk k covers 10 s from the session's first recorded frame plus k·10 s.
              url:
                type: string
        expiresAt:
          type: string
          format: date-time
          description: When the chunk URLs stop working.
    BrowserSession:
      type: object
      required:
      - id
      - status
      - contextId
      - persist
      - proxy
      - record
      - frameCount
      - attempts
      - closeCode
      - closeReason
      - createdAt
      - startedAt
      - endedAt
      properties:
        id:
          type: string
          pattern: ^ses_[0-9a-f]{32}$
        status:
          type: string
          enum:
          - pending
          - connecting
          - running
          - ended
          - failed
          - expired
          description: '`expired` is a created session that was never connected within its ten minutes.'
        connectUrl:
          type: string
          description: 'Present while `pending`: the `/wss` URL that connects this session, once. Send the API key as the `Authorization` header.'
        connectBy:
          type: string
          format: date-time
          description: 'Present while `pending`: the session expires unconnected after this.'
        contextId:
          type:
          - string
          - 'null'
          format: uuid
        persist:
          type:
          - boolean
          - 'null'
        proxy:
          type: object
          required:
          - tier
          - countryCode
          - provider
          - zone
          properties:
            tier:
              type: string
              enum:
              - standard
              - premium
            countryCode:
              type:
              - string
              - 'null'
            provider:
              type:
              - string
              - 'null'
              description: The exit provider the session was routed through, once it connected.
            zone:
              type:
              - string
              - 'null'
        record:
          type: boolean
          description: Whether a screencast replay is recorded.
        frameCount:
          type: integer
          description: Replay frames stored so far.
        attempts:
          type: integer
          description: Browser launches it took to connect; capacity retries add one each.
        closeCode:
          type:
          - integer
          - 'null'
        closeReason:
          type:
          - string
          - 'null'
        createdAt:
          type: string
          format: date-time
        startedAt:
          type:
          - string
          - 'null'
          format: date-time
        endedAt:
          type:
          - string
          - 'null'
          format: date-time
    BrowserSessionList:
      type: object
      required:
      - sessions
      - limit
      - offset
      properties:
        sessions:
          type: array
          items:
            $ref: '#/components/schemas/BrowserSession'
        limit:
          type: integer
        offset:
          type: integer
    BrowserSessionFileList:
      type: object
      required:
      - files
      - expiresAt
      properties:
        files:
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/BrowserSessionFile'
            - type: object
              required:
              - url
              properties:
                url:
                  type:
                  - string
                  - 'null'
                  description: Short-lived download URL.
        expiresAt:
          type: string
          format: date-time
          description: When the download URLs stop working.
    SimpleError:
      type: object
      required:
      - error
      properties:
        error:
          type: string
    BrowserSessionDetail:
      allOf:
      - $ref: '#/components/schemas/BrowserSession'
      - type: object
        required:
        - files
        properties:
          files:
            type: array
            items:
              $ref: '#/components/schemas/BrowserSessionFile'
    BrowserSessionFile:
      type: object
      required:
      - name
      - sizeBytes
      - contentType
      - sha256
      - createdAt
      properties:
        name:
          type: string
        sizeBytes:
          type: integer
        contentType:
          type: string
        sha256:
          type: string
        createdAt:
          type: string
          format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'A String API key, sent as `Authorization: Bearer <key>`. Keys are issued in the portal.'