surfingdog-ai Owners API
For a business's owner and its AI: whether agents find its inbox from its domain.
For a business's owner and its AI: whether agents find its inbox from its domain.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/surfingdog-ai:surfingdog-ai-owners-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
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