Surf Web API

openapi: 3.2.0
info:
  contact:
    email: backend@cybertinolab.com
    name: Cyber team
  description: Surf data API gateway providing typed endpoints for crypto market data, project analytics, social signals, on-chain queries, and more.
  title: Hermod Web API
  version: sha-80d3407
servers:
- url: /
tags:
- description: Fetch and search web content. Retrieve any URL and convert it to clean, LLM-friendly markdown, or search the internet for crypto-related articles, reports, and resources.
  name: Web
paths:
  /gateway/v1/web/fetch:
    get:
      description: 'Fetches a web page and converts it to clean, LLM-friendly markdown.


        **Options:**

        - `target_selector` — extract specific page sections

        - `remove_selector` — strip unwanted elements


        Returns 400 if the URL is invalid or unreachable.'
      operationId: web-fetch
      parameters:
      - description: URL to fetch and parse
        explode: false
        in: query
        name: url
        required: true
        schema:
          description: URL to fetch and parse
          examples:
          - https://ethereum.org
          type: string
      - description: CSS selector to extract specific content
        explode: false
        in: query
        name: target_selector
        schema:
          description: CSS selector to extract specific content
          examples:
          - article.main-content
          type: string
      - description: CSS selector to remove unwanted elements
        explode: false
        in: query
        name: remove_selector
        schema:
          description: CSS selector to remove unwanted elements
          examples:
          - nav,footer,.ads
          type: string
      - description: CSS selector to wait for before extracting
        explode: false
        in: query
        name: wait_for_selector
        schema:
          description: CSS selector to wait for before extracting
          examples:
          - .content-loaded
          type: string
      - description: Request timeout in milliseconds
        explode: false
        in: query
        name: timeout
        schema:
          default: 30000
          description: Request timeout in milliseconds
          examples:
          - 5000
          format: int64
          maximum: 60000
          minimum: 1000
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataObjectResponseWebFetchResultItem'
          description: OK
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataAPIError'
          description: Error
      security:
      - AccessToken: []
      summary: Web Page Fetch
      tags:
      - Web
components:
  schemas:
    DataObjectResponseWebFetchResultItem:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
          - https://example.com/schemas/DataObjectResponseWebFetchResultItem.json
          format: uri
          readOnly: true
          type: string
        data:
          $ref: '#/components/schemas/WebFetchResultItem'
        meta:
          $ref: '#/components/schemas/ObjectResponseMeta'
      required:
      - data
      - meta
      type: object
    ObjectResponseMeta:
      additionalProperties: false
      properties:
        cached:
          description: Whether this response was served from cache
          type: boolean
        credits_used:
          description: Credits deducted for this request
          format: int64
          type: integer
        empty_reason:
          description: Hint explaining why the data array is empty, when applicable
          type: string
      required:
      - credits_used
      - cached
      type: object
    DataAPIError:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
          - https://example.com/schemas/DataAPIError.json
          format: uri
          readOnly: true
          type: string
        error:
          $ref: '#/components/schemas/DataAPIErrorDetail'
      required:
      - error
      type: object
    DataAPIErrorDetail:
      additionalProperties: false
      properties:
        code:
          type: string
        message:
          type: string
      required:
      - code
      - message
      type: object
    WebFetchResultItem:
      additionalProperties: false
      properties:
        content:
          description: Full page content converted to clean markdown text
          type: string
        title:
          description: Page title extracted from the HTML
          type: string
        url:
          description: The URL that was fetched
          type: string
      required:
      - url
      - content
      type: object
  securitySchemes:
    AccessToken:
      bearerFormat: JWT
      scheme: bearer
      type: http
    AdminToken:
      in: header
      name: X-Admin-Token
      type: apiKey
    InternalKey:
      in: header
      name: X-Internal-Key
      type: apiKey