openapi: 3.0.1
info:
  title: Steel Files Session Actions API
  description: Steel is the open-source browser API for AI agents and apps. The Steel Cloud REST API launches and manages cloud browser sessions, runs stateless quick actions (scrape, screenshot, pdf, search), and exposes a live session viewer. Long-running automation connects to the per-session Chrome DevTools Protocol (CDP) WebSocket returned as `websocketUrl`, which is driven with Playwright, Puppeteer, or Selenium. The same surface is available self-hosted (Apache-2.0) from the steel-browser server, where the default base path is http://localhost:3000/v1.
  termsOfService: https://steel.dev/terms-of-service
  contact:
    name: Steel Support
    url: https://docs.steel.dev
  license:
    name: Apache 2.0
    url: https://github.com/steel-dev/steel-browser/blob/main/LICENSE
  version: '1.0'
servers:
- url: https://api.steel.dev/v1
  description: Steel Cloud
- url: http://localhost:3000/v1
  description: Self-hosted steel-browser
security:
- SteelApiKey: []
tags:
- name: Session Actions
  description: Scrape, screenshot, and PDF the page in a running session.
paths:
  /sessions/scrape:
    post:
      operationId: scrapeSession
      tags:
      - Session Actions
      summary: Scrape the current session page
      description: Extracts content from the page currently loaded in the session.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionScrapeRequest'
      responses:
        '200':
          description: Scrape result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScrapeResponse'
  /sessions/screenshot:
    post:
      operationId: screenshotSession
      tags:
      - Session Actions
      summary: Screenshot the current session page
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionScreenshotRequest'
      responses:
        '200':
          description: PNG screenshot
          content:
            image/png:
              schema:
                type: string
                format: binary
  /sessions/pdf:
    post:
      operationId: pdfSession
      tags:
      - Session Actions
      summary: Generate a PDF of the current session page
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionPDFRequest'
      responses:
        '200':
          description: PDF document
          content:
            application/pdf:
              schema:
                type: string
                format: binary
components:
  schemas:
    ScrapeResponse:
      type: object
      properties:
        content:
          type: object
          description: Map of requested format to extracted content.
          additionalProperties: true
        metadata:
          type: object
          properties:
            title:
              type: string
            language:
              type: string
            urlSource:
              type: string
            timestamp:
              type: string
              format: date-time
            description:
              type: string
            statusCode:
              type: integer
            wordCount:
              type: number
            canonical:
              type: string
            favicon:
              type: string
        links:
          type: array
          items:
            type: object
            properties:
              url:
                type: string
              text:
                type: string
        screenshot:
          type: string
          description: Base64 screenshot, present when screenshot=true.
        pdf:
          type: string
          description: Base64 PDF, present when pdf=true.
    SessionScrapeRequest:
      type: object
      description: Scrape request for the current session page (no url).
      properties:
        format:
          type: array
          items:
            $ref: '#/components/schemas/ScrapeFormat'
        screenshot:
          type: boolean
        pdf:
          type: boolean
        removeBase64Images:
          type: boolean
        proxyUrl:
          type: string
          nullable: true
        delay:
          type: number
    SessionPDFRequest:
      type: object
      properties:
        proxyUrl:
          type: string
          nullable: true
        delay:
          type: number
    ScrapeFormat:
      type: string
      enum:
      - html
      - readability
      - cleaned_html
      - markdown
    SessionScreenshotRequest:
      type: object
      properties:
        fullPage:
          type: boolean
        proxyUrl:
          type: string
          nullable: true
        delay:
          type: number
  securitySchemes:
    SteelApiKey:
      type: apiKey
      in: header
      name: Steel-Api-Key
      description: API key issued from app.steel.dev. Pass it in the `Steel-Api-Key` request header. Self-hosted instances may run without auth.