usestring-ai Contexts API

openapi: 3.2.0
info:
  title: String Web Access Contexts 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: Contexts
  description: Browser profiles that persist logins and cookies between sessions.
paths:
  /contexts:
    post:
      tags:
      - Contexts
      operationId: createBrowserContext
      summary: Create a browser context
      description: Creates an empty profile that a later `/wss` session can attach to, so logins and cookies survive between sessions.
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        description: Retry-safe creation. Replaying a completed key returns the context it created rather than a second one.
        schema:
          type: string
          pattern: ^[A-Za-z0-9._:-]{1,255}$
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BrowserContextCreateRequest'
      responses:
        '201':
          description: The created context, or the one a replayed Idempotency-Key already created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrowserContext'
        '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'
        '409':
          description: The name is taken, or a create with this Idempotency-Key is still in flight.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '429':
          description: The organization's context count or storage limit is reached, or its rate limit is.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
    get:
      tags:
      - Contexts
      operationId: listBrowserContexts
      summary: List browser contexts
      description: 'Credit-free: an organization whose balance ran out must still be able to see what it has.'
      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: The organization's contexts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrowserContextList'
        '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'
  /contexts/{contextId}:
    get:
      tags:
      - Contexts
      operationId: getBrowserContext
      summary: Read a browser context
      description: Credit-free.
      parameters:
      - name: contextId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The context.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrowserContext'
        '400':
          description: '`contextId` is not a context UUID.'
          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 context 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'
    delete:
      tags:
      - Contexts
      operationId: deleteBrowserContext
      summary: Delete a browser context
      description: 202 is the normal answer and 200 the exception. Accepting the deletion is immediate and irreversible — the profile is never attachable again from the moment this returns — but its stored data may take a moment to be removed, so 200 is reserved for when nothing is left. A client that wants to know when that is repeats the same call.
      parameters:
      - name: contextId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Deleted; nothing remains in storage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrowserContextDeleted'
        '202':
          description: Accepted and irreversible; the stored objects are not gone yet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrowserContextDeleteAccepted'
        '400':
          description: '`contextId` is not a context UUID.'
          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 context in the caller's organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '409':
          description: The context is attached to a running session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '429':
          description: Rate limit or plan quota exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
components:
  schemas:
    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
    BrowserContextList:
      type: object
      required:
      - contexts
      properties:
        contexts:
          type: array
          items:
            $ref: '#/components/schemas/BrowserContext'
    BrowserContextDeleted:
      type: object
      required:
      - id
      - deleted
      properties:
        id:
          type: string
          format: uuid
        deleted:
          const: true
    BrowserContext:
      type: object
      required:
      - id
      - name
      - status
      - sizeBytes
      - failureReason
      - latestSaveOperation
      - lastSavedAt
      - lastUsedAt
      - createdAt
      - updatedAt
      properties:
        id:
          type: string
          format: uuid
        name:
          type:
          - string
          - 'null'
        status:
          type: string
          enum:
          - EMPTY
          - IN_USE
          - UPLOADING
          - READY
          - FAILED
        sizeBytes:
          type:
          - integer
          - 'null'
          description: Size of the stored profile archive.
        failureReason:
          type:
          - string
          - 'null'
        latestSaveOperation:
          type:
          - object
          - 'null'
          required:
          - id
          - status
          - failureReason
          - completedAt
          properties:
            id:
              type: string
            status:
              type: string
              enum:
              - PENDING
              - COMMITTED
              - FAILED
              - EXPIRED
              - SUPERSEDED
            failureReason:
              type:
              - string
              - 'null'
            completedAt:
              type:
              - string
              - 'null'
              format: date-time
        lastSavedAt:
          type:
          - string
          - 'null'
          format: date-time
          description: When the profile data was last durable, as against `lastUsedAt`, which is activity.
        lastUsedAt:
          type:
          - string
          - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    BrowserContextCreateRequest:
      $schema: https://json-schema.org/draft/2020-12/schema
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 200
      additionalProperties: false
    SimpleError:
      type: object
      required:
      - error
      properties:
        error:
          type: string
    BrowserContextDeleteAccepted:
      type: object
      required:
      - id
      - status
      - deleted
      properties:
        id:
          type: string
          format: uuid
        status:
          const: DELETING
        deleted:
          const: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'A String API key, sent as `Authorization: Bearer <key>`. Keys are issued in the portal.'