surfingdog-ai Owners API

openapi: 3.2.0
info:
  title: Surfing Dog Search Owners 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: Owners
  description: 'For a business''s owner and its AI: whether agents find its inbox from its domain.'
paths:
  /v1/discovery/{domain}:
    get:
      operationId: checkDiscovery
      tags:
      - Owners
      summary: Whether agents find a business's inbox from its domain
      description: 'Checks the inbox''s DNS record at its host (inbox. unless host is given; against target when given), its manifest, the domain''s robots.txt (no AI assistant kept out), and five ways the domain can lead an agent to the inbox: four on the website (its own /.well-known/agent-inbox.json, a line in llms.txt, , a schema.org potentialAction) and an _agent-inbox TXT record. ready needs the inbox reached, no assistant kept out, and one of the four on the website: the DNS record alone is state dns_only. Every item not in place carries the exact fix (fix_lines: the text to paste). Reads the site as a browser would, nothing robots.txt keeps SurfingDogBot off, and nothing at all while robots.txt answers 5xx or 429 or does not answer. What it read is kept for a minute (a site''s documents by its domain, a host by its name), and a site is read at most twelve times a minute whoever asks; six checks a minute from one address, thirty from a wider network. The same as the MCP tool check_dns.'
      parameters:
      - name: domain
        in: path
        required: true
        description: The business's own domain, such as salon.example.
        schema:
          type: string
          maxLength: 253
      - name: host
        in: query
        description: 'Where the inbox answers, when not inbox.<domain>: the domain itself or a name under it.'
        schema:
          type: string
          maxLength: 253
      - name: target
        in: query
        description: The CNAME target the host must point to, when known.
        schema:
          type: string
          maxLength: 253
      responses:
        '200':
          description: The check.
          content:
            application/json:
              schema:
                type: object
                externalDocs:
                  description: Its JSON Schema
                  url: https://github.com/surfingdogai/inbox/blob/main/packages/spec/schemas/discovery-result.json
                required:
                - domain
                - host
                - manifest
                - checked_at
                - ready
                - state
                - ways
                - site_ways
                - next
                - items
                properties:
                  domain:
                    type: string
                  host:
                    type: string
                  manifest:
                    type: string
                    format: uri
                  checked_at:
                    type: string
                    format: date-time
                  ready:
                    type: boolean
                  state:
                    type: string
                    enum:
                    - ready
                    - unreachable
                    - blocked
                    - robots_unreadable
                    - dns_only
                    - no_way
                    description: 'ready; unreachable: the inbox does not answer at its host; blocked: robots.txt keeps AI assistants out; robots_unreadable: robots.txt cannot be read, so crawlers read nothing; dns_only: only the DNS record leads to the inbox; no_way: nothing does. New states may be added: read an unknown one as not ready.'
                  ways:
                    type: integer
                    minimum: 0
                    description: Ways in place, the DNS record included (five today).
                  site_ways:
                    type: integer
                    minimum: 0
                    description: Ways in place on the website.
                  platform:
                    type: string
                    enum:
                    - wordpress
                    - shopify
                    - wix
                    - squarespace
                    description: The site's platform, when its homepage (or this network's last read of it) shows one of these.
                  next:
                    type: string
                  items:
                    type: array
                    items:
                      type: object
                      required:
                      - id
                      - need
                      - state
                      - detail
                      properties:
                        id:
                          type: string
                          enum:
                          - cname
                          - manifest
                          - robots
                          - well_known
                          - llms_txt
                          - link
                          - schema_org
                          - dns_txt
                        need:
                          type: string
                          enum:
                          - required
                          - recommended
                          - optional
                        state:
                          type: string
                          enum:
                          - ok
                          - missing
                          - wrong
                          - blocked
                          - unreadable
                        detail:
                          type: string
                        fix:
                          type: string
                        fix_lines:
                          type: string
                          description: The text to paste, alone, when the fix is one.
        '422':
          $ref: '#/components/responses/Problem'
        '429':
          $ref: '#/components/responses/Problem'
        '503':
          $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