surfingdog-ai Census API

openapi: 3.2.0
info:
  title: Surfing Dog Search Census 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: census
  description: 'Once a month, what AI agents can do at the websites checked: counts only, open data under CC BY 4.0 (credit "Surfing Dog census, surfingdog.ai, CC BY 4.0").'
paths:
  /v1/census:
    get:
      operationId: listCensusEditions
      tags:
      - census
      summary: The census's published editions
      description: 'Each month, how many of the websites checked an AI agent can message, book, order from, pay and the rest: counts only, never a website''s name. Newest first; a withdrawn edition is listed with its status.'
      responses:
        '200':
          description: The published and withdrawn editions.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                type: object
                externalDocs:
                  description: Its JSON Schema
                  url: https://surfingdog.ai/spec/schemas/census-editions.json
                required:
                - title
                - licence
                - editions
                properties:
                  title:
                    type: string
                  licence:
                    type: object
                  editions:
                    type: array
                    items:
                      type: object
                      required:
                      - edition
                      - title
                      - status
                      - as_of
                      - published_at
                      - url
                      - json
                      - csv
                      properties:
                        edition:
                          type: string
                          pattern: ^20[0-9]{2}-(0[1-9]|1[0-2])$
                        title:
                          type: string
                        status:
                          type: string
                          enum:
                          - published
                          - withdrawn
                        as_of:
                          type: string
                          format: date-time
                        published_at:
                          type: string
                          format: date-time
                        url:
                          type: string
                          format: uri
                        json:
                          type: string
                          format: uri
                        csv:
                          type: string
                          format: uri
  /v1/census/{edition}:
    get:
      operationId: getCensusEdition
      tags:
      - census
      summary: One edition of the census
      description: 'Its counts as long rows (scope, key, metric, value): the whole, and each country, kind of business, platform, source and city with at least min_sample sites checked. The same rows as CSV are at /census/{edition}.csv on the site. A reader skips a scope or a metric it does not know: both are added to, never renamed.'
      parameters:
      - name: edition
        in: path
        required: true
        schema:
          type: string
          pattern: ^20[0-9]{2}-(0[1-9]|1[0-2])$
        example: 2026-11
      responses:
        '200':
          description: The edition.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                type: object
                externalDocs:
                  description: Its JSON Schema
                  url: https://surfingdog.ai/spec/schemas/census-edition.json
                required:
                - edition
                - status
                - as_of
                - method
                - vocabulary
                - score_rules
                - licence
                - rows
                properties:
                  edition:
                    type: string
                  status:
                    type: string
                    enum:
                    - published
                    - withdrawn
                  as_of:
                    type: string
                    format: date-time
                  method:
                    type: object
                  vocabulary:
                    type: object
                  score_rules:
                    type: object
                    required:
                    - version
                    - revised
                    - url
                    properties:
                      version:
                        type: integer
                        minimum: 1
                      revised:
                        type:
                        - string
                        - 'null'
                        format: date
                      url:
                        type: string
                        format: uri
                  licence:
                    type: object
                  rows:
                    type: array
                    items:
                      type: object
                      required:
                      - scope
                      - key
                      - metric
                      - value
                      properties:
                        scope:
                          type: string
                          pattern: ^[a-z][a-z0-9_]{0,31}$
                          description: all, country, group, platform, source or city.
                        key:
                          type: string
                        metric:
                          type: string
                        value:
                          type: integer
                          minimum: 0
        '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.'
  headers:
    ETag:
      description: Send it back in If-None-Match for a 304 while the answer holds.
      schema:
        type: string
  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