SerpApi Search API — Search

naftiko: 1.0.0-alpha2
info:
  label: SerpApi Search API — Search
  description: 'SerpApi Search API — Search. 2 operations. Lead operation: Run a search across a supported engine. Self-contained
    Naftiko capability covering one Serpapi business surface.'
  tags:
  - Serpapi
  - Search
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    SERPAPI_API_KEY: SERPAPI_API_KEY
capability:
  consumes:
  - type: http
    namespace: serpapi-search
    baseUri: https://serpapi.com
    description: SerpApi Search API — Search business capability. Self-contained, no shared references.
    resources:
    - name: search
      path: /search
      operations:
      - name: runsearch
        method: GET
        description: Run a search across a supported engine
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: engine
          in: query
          type: string
          description: Search engine identifier (e.g. google, bing, youtube).
          required: true
        - name: q
          in: query
          type: string
          description: Search query (used by most engines except YouTube).
        - name: search_query
          in: query
          type: string
          description: Search query used by the YouTube engine.
        - name: api_key
          in: query
          type: string
          description: SerpApi private key (may also be supplied via the apiKey security scheme).
        - name: location
          in: query
          type: string
          description: Geographic origin for the search.
        - name: gl
          in: query
          type: string
          description: Two-letter country code.
        - name: hl
          in: query
          type: string
          description: Two-letter language code.
        - name: device
          in: query
          type: string
          description: Device type to emulate.
        - name: no_cache
          in: query
          type: boolean
          description: Force fresh (uncached) results.
        - name: async
          in: query
          type: boolean
          description: Submit asynchronously and retrieve results later.
        - name: output
          in: query
          type: string
          description: Response format.
    - name: searches-search_id
      path: /searches/{search_id}
      operations:
      - name: getsearch
        method: GET
        description: Retrieve a previously submitted asynchronous search
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: search_id
          in: path
          type: string
          description: Identifier of the asynchronous search.
          required: true
    authentication:
      type: apikey
      key: api_key
      value: '{{env.SERPAPI_API_KEY}}'
      placement: query
  exposes:
  - type: rest
    namespace: serpapi-search-rest
    port: 8080
    description: REST adapter for SerpApi Search API — Search. One Spectral-compliant resource per consumed operation, prefixed
      with /v1.
    resources:
    - path: /v1/search
      name: search
      description: REST surface for search.
      operations:
      - method: GET
        name: runsearch
        description: Run a search across a supported engine
        call: serpapi-search.runsearch
        with:
          engine: rest.engine
          q: rest.q
          search_query: rest.search_query
          api_key: rest.api_key
          location: rest.location
          gl: rest.gl
          hl: rest.hl
          device: rest.device
          no_cache: rest.no_cache
          async: rest.async
          output: rest.output
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/searches/{search-id}
      name: searches-search-id
      description: REST surface for searches-search_id.
      operations:
      - method: GET
        name: getsearch
        description: Retrieve a previously submitted asynchronous search
        call: serpapi-search.getsearch
        with:
          search_id: rest.search_id
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: serpapi-search-mcp
    port: 9090
    transport: http
    description: MCP adapter for SerpApi Search API — Search. One tool per consumed operation, routed inline through this
      capability's consumes block.
    tools:
    - name: run-search-across-supported-engine
      description: Run a search across a supported engine
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: serpapi-search.runsearch
      with:
        engine: tools.engine
        q: tools.q
        search_query: tools.search_query
        api_key: tools.api_key
        location: tools.location
        gl: tools.gl
        hl: tools.hl
        device: tools.device
        no_cache: tools.no_cache
        async: tools.async
        output: tools.output
      outputParameters:
      - type: object
        mapping: $.
    - name: retrieve-previously-submitted-asynchronous-search
      description: Retrieve a previously submitted asynchronous search
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: serpapi-search.getsearch
      with:
        search_id: tools.search_id
      outputParameters:
      - type: object
        mapping: $.