{
 "openapi": "3.1.0",
 "info": {
  "title": "DouxProcess Directory API",
  "version": "1.2.0",
  "summary": "US businesses checked against the issuer's record, for AI assistants and apps. Free, no key.",
  "description": "The only directory where every listing links to the issuer's record, any AI can call it free, a request reaches the business with consent, and nobody can pay to rank. Results follow one published order: 1. What you asked for: the category you named before a related one, and inside it a business whose name holds the other words you typed. With no category, the name you typed: exact, then every word, then a close spelling. 2. Your area: only businesses that serve your state, those in your city first, then nearer before farther in 5-mile steps. 3. A license checked against the issuing board and active, before one not checked. 4. More facts on the listing: phone, website, hours, a description, a quote or booking link, an MCP address. 5. Name, A to Z. A claimed listing only breaks a tie, and never for a business affiliated with DouxProcess's owner. Nobody can pay to rank, and there are no reviews or star ratings. Requests to a business go through the MCP tool request_contact or the A2A agent, only with the person's consent.",
  "termsOfService": "https://douxprocess.directory/terms",
  "contact": {
   "name": "DouxProcess",
   "email": "admin@douxprocess.com",
   "url": "https://douxprocess.directory/for-ai"
  }
 },
 "servers": [
  {
   "url": "https://douxprocess.directory"
  }
 ],
 "externalDocs": {
  "description": "llms.txt",
  "url": "https://douxprocess.directory/llms.txt"
 },
 "paths": {
  "/v1/search": {
   "get": {
    "operationId": "searchBusinesses",
    "summary": "Find businesses by need and place",
    "description": "The find_businesses MCP tool over HTTP. covered=false with a note means the directory does not hold that kind of business or place yet.",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "required": false,
      "description": "What the person needs, in their words.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "where",
      "in": "query",
      "required": false,
      "description": "City and state, a 5-digit ZIP, or a state.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "category",
      "in": "query",
      "required": false,
      "description": "A category id (see /categories).",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "state",
      "in": "query",
      "required": false,
      "description": "Two-letter state.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "city",
      "in": "query",
      "required": false,
      "description": "City.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "postal_code",
      "in": "query",
      "required": false,
      "description": "5-digit ZIP.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "cursor",
      "in": "query",
      "required": false,
      "description": "next_cursor from the previous page.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "1 to 25.",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 25
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SearchResult"
        }
       }
      }
     },
     "429": {
      "description": "Too many requests from this connection",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "The directory is unavailable for a moment; retry after Retry-After"
     }
    }
   }
  },
  "/v1/businesses/{id}": {
   "get": {
    "operationId": "getBusiness",
    "summary": "One listing",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "description": "The listing's slug.",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Listing"
        }
       }
      }
     },
     "301": {
      "description": "A former slug; Location has the current one"
     },
     "404": {
      "description": "No listing at that id",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "The directory is unavailable for a moment; retry after Retry-After"
     }
    }
   }
  },
  "/v1/businesses": {
   "get": {
    "operationId": "listBusinesses",
    "summary": "The local-services feed",
    "description": "Keyset pages in slug order. By default only listings with coordinates (geo=only); geo=any includes the rest.",
    "parameters": [
     {
      "name": "page_size",
      "in": "query",
      "required": false,
      "description": "1 to 500, default 100.",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 500
      }
     },
     {
      "name": "page_token",
      "in": "query",
      "required": false,
      "description": "next_page_token from the previous page.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "geo",
      "in": "query",
      "required": false,
      "description": "only (default) or any.",
      "schema": {
       "type": "string",
       "enum": [
        "only",
        "any"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Feed"
        }
       }
      }
     },
     "429": {
      "description": "Too many requests from this connection",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "The directory is unavailable for a moment; retry after Retry-After"
     }
    }
   }
  },
  "/mcp": {
   "post": {
    "operationId": "mcp",
    "summary": "MCP server (streamable HTTP, JSON responses)",
    "description": "JSON-RPC 2.0. Server card: https://douxprocess.directory/mcp/server-card. Every listing has its own at /b/{slug}/mcp.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "A JSON-RPC response",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "202": {
      "description": "A notification was accepted"
     }
    }
   }
  },
  "/a2a": {
   "post": {
    "operationId": "a2a",
    "summary": "A2A JSON-RPC (1.0 SendMessage, 0.3 message/send)",
    "description": "Agent card: https://douxprocess.directory/.well-known/agent-card.json. Every listing has its own at /b/{slug}/a2a.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "A JSON-RPC response",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "License": {
    "type": "object",
    "properties": {
     "issuer": {
      "type": "string"
     },
     "number": {
      "type": "string"
     },
     "classification": {
      "type": [
       "string",
       "null"
      ]
     },
     "status": {
      "type": [
       "string",
       "null"
      ]
     },
     "expires": {
      "type": [
       "string",
       "null"
      ]
     },
     "source_url": {
      "type": [
       "string",
       "null"
      ]
     },
     "checked_at": {
      "type": [
       "string",
       "null"
      ]
     },
     "basis": {
      "type": "string",
      "enum": [
       "issuer_file",
       "stated"
      ]
     }
    },
    "required": [
     "issuer",
     "number"
    ]
   },
   "Business": {
    "type": "object",
    "required": [
     "slug",
     "name",
     "page"
    ],
    "properties": {
     "slug": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "page": {
      "type": "string"
     },
     "about": {
      "type": "string"
     },
     "website": {
      "type": "string"
     },
     "phone": {
      "type": "string"
     },
     "quote_link": {
      "type": "string"
     },
     "booking_link": {
      "type": "string"
     },
     "mcp_url": {
      "type": "string"
     },
     "street": {
      "type": "string"
     },
     "city": {
      "type": "string"
     },
     "region": {
      "type": "string"
     },
     "postal": {
      "type": "string"
     },
     "service_area": {
      "type": "object"
     },
     "languages": {
      "type": "array"
     },
     "licenses": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/License"
      }
     },
     "status": {
      "type": "string",
      "enum": [
       "seeded",
       "claimed",
       "verified"
      ]
     },
     "categories": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "disclosure": {
      "type": "string"
     },
     "note": {
      "type": "string"
     },
     "request_contact": {
      "type": "string"
     },
     "can_take_requests": {
      "type": "boolean"
     },
     "agent": {
      "type": "object",
      "properties": {
       "mcp": {
        "type": "string"
       },
       "a2a": {
        "type": "string"
       },
       "agent_card": {
        "type": "string"
       },
       "json": {
        "type": "string"
       },
       "markdown": {
        "type": "string"
       }
      }
     },
     "luma": {
      "type": "object",
      "properties": {
       "books_online": {
        "type": "boolean"
       },
       "site_url": {
        "type": "string"
       },
       "site": {
        "type": "string"
       }
      }
     }
    }
   },
   "SearchResult": {
    "type": "object",
    "required": [
     "businesses",
     "count",
     "has_more",
     "covered",
     "ranking"
    ],
    "properties": {
     "intent": {
      "type": "object"
     },
     "covered": {
      "type": "boolean"
     },
     "note": {
      "type": "string"
     },
     "total": {
      "type": [
       "integer",
       "null"
      ]
     },
     "count": {
      "type": "integer"
     },
     "has_more": {
      "type": "boolean"
     },
     "next_cursor": {
      "type": [
       "string",
       "null"
      ]
     },
     "ranking": {
      "type": "string"
     },
     "businesses": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Business"
      }
     }
    }
   },
   "ServiceProvider": {
    "type": "object",
    "required": [
     "provider",
     "provider_business_id",
     "action_type",
     "provider_action_url"
    ],
    "properties": {
     "provider": {
      "type": "string"
     },
     "provider_business_id": {
      "type": "string"
     },
     "action_type": {
      "type": "string",
      "enum": [
       "request_a_quote"
      ]
     },
     "provider_action_url": {
      "type": "string",
      "format": "uri"
     }
    }
   },
   "FeedBusiness": {
    "type": "object",
    "required": [
     "id",
     "name",
     "address",
     "platform_url",
     "service_providers"
    ],
    "properties": {
     "id": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "address": {
      "type": "object",
      "properties": {
       "line1": {
        "type": "string"
       },
       "locality": {
        "type": "string"
       },
       "region": {
        "type": "string"
       },
       "postal_code": {
        "type": "string"
       },
       "country": {
        "type": "string"
       },
       "formatted": {
        "type": "string"
       }
      }
     },
     "location": {
      "type": [
       "object",
       "null"
      ],
      "properties": {
       "latitude": {
        "type": "number"
       },
       "longitude": {
        "type": "number"
       }
      }
     },
     "phone_number": {
      "type": [
       "string",
       "null"
      ],
      "description": "E.164"
     },
     "website_url": {
      "type": [
       "string",
       "null"
      ]
     },
     "platform_url": {
      "type": "string"
     },
     "categories": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "licenses": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/License"
      }
     },
     "service_area": {
      "type": "object"
     },
     "disclosure": {
      "type": "string"
     },
     "can_take_requests": {
      "type": "boolean"
     },
     "service_providers": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ServiceProvider"
      }
     },
     "updated_at": {
      "type": "string"
     }
    }
   },
   "Feed": {
    "type": "object",
    "required": [
     "businesses",
     "page_size",
     "checksum"
    ],
    "properties": {
     "businesses": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/FeedBusiness"
      }
     },
     "next_page_token": {
      "type": [
       "string",
       "null"
      ]
     },
     "page_size": {
      "type": "integer"
     },
     "count": {
      "type": "integer"
     },
     "geo": {
      "type": "string"
     },
     "generated_at": {
      "type": "string"
     },
     "checksum": {
      "type": "string",
      "description": "sha256 of the businesses array as compact JSON"
     },
     "ranking": {
      "type": "string"
     }
    }
   },
   "Listing": {
    "type": "object",
    "required": [
     "business"
    ],
    "properties": {
     "business": {
      "$ref": "#/components/schemas/Business"
     },
     "jsonld": {
      "type": "object"
     },
     "actions": {
      "type": "array"
     },
     "agent": {
      "type": "object"
     }
    }
   },
   "Error": {
    "type": "object",
    "required": [
     "error"
    ],
    "properties": {
     "error": {
      "type": "string"
     },
     "why": {
      "type": "string"
     }
    }
   }
  }
 }
}