unbrowse-ai Account API

openapi: 3.2.0
info:
  title: Unbrowse Ai Account API
  version: 1.0.0
  contact:
    name: Unbrowse
    email: hello@unbrowse.ai
    url: https://unbrowse.ai
  termsOfService: https://unbrowse.ai/terms
  description: 'Operations tagged Account across 2 of this provider''s published API definitions: unbrowse-ai-openapi.json, unbrowse-ai-openapi2.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.unbrowse.ai
  description: Unbrowse
- url: https://unbrowse.ai
  description: Unbrowse
security:
- oauth2:
  - unbrowse
- apiKey: []
tags:
- name: Account
  description: Who is signed in and what they have used.
paths:
  /api/v1/memory/requests:
    get:
      tags:
      - Account
      operationId: browserRequestMemory
      summary: Search or read your private browser request receipts
      description: Dated metadata only; does not replay requests. Search window and bounded storage policy are returned. Headers, payloads and URL paths/query values are omitted.
      parameters:
      - name: query
        in: query
        schema:
          type: string
      - name: pointer
        in: query
        schema:
          type: string
      - name: cursor
        in: query
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      responses:
        '200':
          description: Private request receipts and retention policy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Object'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
    servers:
    - url: https://api.unbrowse.ai
      description: Unbrowse
  /api/v1/cookies:
    post:
      tags:
      - Account
      operationId: importCookies
      summary: Import browser cookies as kept sessions
      description: Takes cookies exported from the user's own browser (the CLI's `unbrowse cookies sync`, or the browser extension's sync) and keeps them as a signed-in session per site, sealed in the vault, so later runs act as the signed-in user. Values are stored, never returned.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - cookies
              properties:
                source:
                  type: string
                  enum:
                  - extension
                  - cli
                  description: Where the cookies came from; recorded on the site's session.
                cookies:
                  type: array
                  items:
                    type: object
                    required:
                    - domain
                    - name
                    - value
                    properties:
                      domain:
                        type: string
                        description: The cookie's domain, e.g. .example.com
                      name:
                        type: string
                      value:
                        type: string
                      path:
                        type: string
                      secure:
                        type: boolean
                      httpOnly:
                        type: boolean
                      expires:
                        type: integer
                        description: Unix seconds; 0 = session cookie.
      responses:
        '200':
          description: How many sites and cookies were kept
          content:
            application/json:
              schema:
                type: object
                properties:
                  sites:
                    type: integer
                  cookies:
                    type: integer
                  origins:
                    type: array
                    items:
                      $ref: '#/components/schemas/Object'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
    servers:
    - url: https://api.unbrowse.ai
      description: Unbrowse
  /api/v1/cookies/{site}:
    delete:
      tags:
      - Account
      operationId: forgetSiteSession
      summary: Forget a site's kept session
      description: Deletes the signed-in session kept for a site (every origin of it) from the vault, as revoking the site in the browser extension does. The next run on that site signs in again, or asks.
      parameters:
      - name: site
        in: path
        required: true
        schema:
          type: string
        description: The site, e.g. linkedin.com (an origin or a subdomain names its site).
      responses:
        '200':
          description: Whether a session was kept and is now gone
          content:
            application/json:
              schema:
                type: object
                properties:
                  site:
                    type: string
                  dropped:
                    type: boolean
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
    servers:
    - url: https://api.unbrowse.ai
      description: Unbrowse
  /api/v1/relay/status:
    get:
      tags:
      - Account
      operationId: browserRelayStatus
      summary: The browser extension's relay status
      description: Whether the workspace's Unbrowse browser extension is connected, the device, which sites it syncs or relays, and whether it is paused. Offline with no sites when the relay is not enabled.
      responses:
        '200':
          description: Relay status
          content:
            application/json:
              schema:
                type: object
                properties:
                  online:
                    type: boolean
                  paused:
                    type: boolean
                  device:
                    $ref: '#/components/schemas/Object'
                  sites:
                    type: array
                    items:
                      type: object
                      properties:
                        site:
                          type: string
                        sync:
                          type: boolean
                        relay:
                          type: boolean
                        writes:
                          type: boolean
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
    servers:
    - url: https://api.unbrowse.ai
      description: Unbrowse
  /api/v1/relay/revoke:
    post:
      tags:
      - Account
      operationId: revokeBrowserRelay
      summary: Disconnect the browser extension
      description: Closes the extension's relay connection; runs stop using the person's browser until it connects again.
      responses:
        '200':
          description: Disconnected
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
    servers:
    - url: https://api.unbrowse.ai
      description: Unbrowse
  /api/v1/workspace/sharing:
    get:
      tags:
      - Account
      operationId: getSharing
      summary: Whether this workspace's learned routes are shared to the public registry, and…
      description: Acts on the workspace of the API key (or sign-in) making the call. Free workspaces share by default; a workspace that has ever paid is private by default and shares only after opting in. Run results and inputs are never published.
      responses:
        '200':
          description: The effective setting
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sharing'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
    put:
      tags:
      - Account
      operationId: setSharing
      summary: Opt in to or out of sharing learned routes to the public registry
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - shareLearned
              properties:
                shareLearned:
                  type: boolean
              additionalProperties: false
      responses:
        '200':
          description: The effective setting
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sharing'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
    servers:
    - url: https://api.unbrowse.ai
      description: Unbrowse
  /api/v1/workspace/session-reuse:
    get:
      tags:
      - Account
      operationId: getSessionReuse
      summary: Whether runs reuse this workspace's kept signed-in sessions automatically, and…
      description: 'Acts on the workspace of the API key (or sign-in) making the call. On by default: a site you are signed in to (a kept session, sealed in the vault) is reused by runs, scrapes and browse sessions without asking. A site set to Never in the password manager is never reused; one set to Ask me asks first. Turning it off refuses every site and asks no one.'
      responses:
        '200':
          description: The effective setting
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionReuse'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
    put:
      tags:
      - Account
      operationId: setSessionReuse
      summary: Turn automatic reuse of kept sign-ins off (or back on) for this workspace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - reuse
              properties:
                reuse:
                  type: boolean
              additionalProperties: false
      responses:
        '200':
          description: The effective setting
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionReuse'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
    servers:
    - url: https://api.unbrowse.ai
      description: Unbrowse
  /api/v1/usage:
    get:
      tags:
      - Account
      operationId: getUsage
      summary: This month's metered usage
      responses:
        '200':
          description: Verified calls, quota and what remains
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Object'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
    servers:
    - url: https://api.unbrowse.ai
      description: Unbrowse
  /api/v1/me:
    get:
      tags:
      - Account
      operationId: getMe
      summary: The signed-in user and workspace
      responses:
        '200':
          description: The principal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Object'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
    servers:
    - url: https://api.unbrowse.ai
      description: Unbrowse
components:
  responses:
    Unauthorized:
      description: Missing or invalid credentials. The WWW-Authenticate header names the protected-resource metadata.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error:
      description: An error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    SessionReuse:
      type: object
      required:
      - workspaceId
      - reuse
      - reason
      properties:
        workspaceId:
          type: string
        reuse:
          type: boolean
          description: 'Effective: whether kept signed-in sessions are reused automatically (sites set to Never or Ask me excepted).'
        explicit:
          type:
          - boolean
          - 'null'
          description: What the workspace set; null when it never chose (on by default).
        reason:
          type: string
          examples:
          - 'on by default: kept sign-ins are reused automatically'
          - 'turned off for this workspace: no kept sign-in is reused, and no one is asked'
        never:
          type: array
          items:
            type: string
          description: 'Sites set to Never: their kept sign-in is never reused.'
        ask:
          type: array
          items:
            type: string
          description: 'Sites set to Ask me: each reuse needs your approval.'
        change:
          type: string
    Object:
      type: object
      additionalProperties: true
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
          additionalProperties: true
      additionalProperties: true
    Sharing:
      type: object
      required:
      - workspaceId
      - shareLearned
      - paid
      - reason
      properties:
        workspaceId:
          type: string
        shareLearned:
          type: boolean
          description: 'Effective: whether a learned public read-only route is shared after its first verified run.'
        explicit:
          type:
          - boolean
          - 'null'
          description: What the workspace set; null when it never chose (the plan default applies).
        paid:
          type: boolean
          description: The workspace has paid credits or a completed purchase.
        reason:
          type: string
          examples:
          - 'paid workspace: private by default'
          - 'free workspace: shared by default (turn it off any time)'
        shared:
          type: integer
          description: Routes this workspace has shared so far.
        published:
          type: string
          description: 'What sharing publishes: the scrubbed route only, never run results or inputs.'
  securitySchemes:
    oauth2:
      type: oauth2
      description: 'Authorization code with PKCE (S256). Clients may register dynamically at /oauth/register. Discovery: /.well-known/oauth-authorization-server; the REST API''s protected-resource metadata is /.well-known/oauth-protected-resource/api.'
      flows:
        authorizationCode:
          authorizationUrl: https://api.unbrowse.ai/authorize
          tokenUrl: https://api.unbrowse.ai/oauth/token
          refreshUrl: https://api.unbrowse.ai/oauth/token
          scopes:
            unbrowse: Run tasks and read results on the user's behalf, with their kept logins.
    apiKey:
      type: http
      scheme: bearer
      description: An Unbrowse API key (create one in the console at https://unbrowse.ai/app).
externalDocs:
  description: Docs
  url: https://docs.unbrowse.ai
x-refined-from:
- unbrowse-ai-openapi.json
- unbrowse-ai-openapi2.json