surfingdog-ai Rules API

openapi: 3.2.0
info:
  title: Surfing Dog Search Rules API
  version: '1'
  license:
    name: ODbL-1.0 (the directory data; town names and centres © GeoNames, CC BY 4.0)
    url: https://opendatacommons.org/licenses/odbl/1-0/
  summary: A public directory of businesses an AI can ask, book or buy from, through their own inboxes and other agent doors.
  description: 'Everything here is a public read, no sign-in, the same answer for everyone (a free directory key only lets a list page deeper than 200 places), except two calls about door reports: POST /v1/door-reports, where an agent says how a business''s door went, and GET /v1/door-reports/me, signed, which answers the signer''s own reporting credit. Signed reads may count against a contributor''s own allowance; the answers are the same. The directory''s order is published at GET /v1/ranking and cannot be bought; every query parameter only leaves businesses out. This API takes no orders or payments and books nothing itself; each result lists the business''s own doors (a listing''s doors, or a member''s protocols). A business this network found on its own website is marked as found, with the date it was checked; only facts it published itself are shown, never a phone or an email. Errors are RFC 9457 problem documents. The protocol behind this API, with its JSON Schemas and test vectors, is public; the MCP server at /mcp offers the same reads as tools, and can carry a person''s request to a business''s own inbox when the business allows it.'
servers:
- url: https://network.surfingdog.ai
tags:
- name: Rules
  description: How the directory is ordered.
paths:
  /v1/ranking:
    get:
      operationId: getRules
      tags:
      - Rules
      summary: The rules that order the directory
      description: The version in force, or any version ever published. Every number the rules use is here, with the changelog and the next version when one is announced.
      parameters:
      - name: version
        in: query
        schema:
          type: integer
          minimum: 1
      responses:
        '200':
          description: The rules.
          content:
            application/json:
              schema:
                type: object
                description: The rules document.
                externalDocs:
                  description: Its JSON Schema
                  url: https://github.com/surfingdogai/inbox/blob/main/packages/spec/schemas/ranking.json
                required:
                - version
                - status
                properties:
                  version:
                    type: integer
                    minimum: 1
                  status:
                    type: string
        '404':
          $ref: '#/components/responses/Problem'
components:
  schemas:
    Problem:
      type: object
      required:
      - type
      - title
      - status
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
        code:
          type: string
          description: 'What to do differently, when a status alone does not say: cursor_expired, not_found, too_large, rate_limited, category_unresolved, page_too_deep.'
        detail:
          type: string
        instance:
          type: string
        candidates:
          type: array
          items:
            type: string
          description: 'category_unresolved: up to 5 categories to try.'
  responses:
    Problem:
      description: An RFC 9457 problem document.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
externalDocs:
  description: The network protocol
  url: https://github.com/surfingdogai/inbox/blob/main/docs/protocol/network.md