Public API Documentation

Authentication and Access

These website endpoints require no API key or login. The base URL is https://brownsmithdynamics.com. Public GET requests read website data. The contact endpoint accepts enquiries initiated by a person. Browser JavaScript on other origins has no CORS access guarantee.

The website serves Markdown for registered public content pages when an Accept header explicitly prefers text/markdown, including a tie with HTML. The server generates it from the page's rendered HTML and revalidates its server cache after five minutes. Default requests receive HTML. Both representations use Vary: Accept. Interactive search, requests with content-changing query parameters, and browser navigation retain their usual format.

Clients that cannot set request headers can use /agent-markdown?path=/ with a registered public page path. Each Markdown response links to the original page as its canonical source. These are public page representations; they do not accept an external source URL.

Endpoints

• GET /api/public-business-information

  Read public business information.

• GET /api/ai-instructions

  Read agent usage instructions.

• GET /api/blogs

  List public blog summaries.

• GET /api/coding-tools

  List open-source coding tools.

• GET /api/coding-tools.csv

  Download coding tools as CSV.

• GET /api/consent-region

  Check whether analytics consent is required.

• POST /api/contact

  Submit an intentional contact request.

The coding-tools CSV contains name, description, github_url, and website_url columns. Upstream projects retain their own licenses. The consent-region endpoint returns whether analytics opt-in is required and treats unknown regions conservatively.

Example Requests and Pagination

Blog pages contain up to ten summaries in date order. Offset defaults to 0 and must be a non-negative integer. Limit defaults to 10 and only accepts 10. Continue using nextOffset while hasMore is true.

curl -sS 'https://brownsmithdynamics.com/api/public-business-information'
curl -sS 'https://brownsmithdynamics.com/api/blogs?offset=0&limit=10'
curl -sS -H 'Accept: text/markdown' 'https://brownsmithdynamics.com/'

Contact Requests and Rate Limits

Use the contact page to send an enquiry. Integrations may POST JSON with Content-Type: application/json. When supplied, Origin must match the request origin. The complete UTF-8 body must be at most 8192 bytes.

General requests require email. Requests with source set to service-scoping or building-with-ai require a message and either an email or an international phone number starting with +. Name is limited to 100 characters, email to 254, phone to 32, and message to 2000. Leave the website honeypot field empty.

POST /api/contact
Content-Type: application/json

{"email":"asha@example.com","message":"Please contact me about workflow automation."}

200 OK
{"ok":true}

Delivery must be configured on the server. Best-effort limits are three requests per 15 minutes per normalized email or phone key and 20 per minute per running process. These in-memory limits apply independently to each process. HTTP 429 includes Retry-After in seconds.

JSON Errors and Recovery

Handled API errors include a stable code, message, resolution hint, and documentation URL. The error field preserves the existing message for form clients. Unknown API paths return HTTP 404 with code NOT_FOUND. Unsupported methods return HTTP 405 with code METHOD_NOT_ALLOWED and an Allow header.

{
  "ok": false,
  "error": "offset must be non-negative and limit must be 10",
  "code": "INVALID_QUERY",
  "message": "offset must be non-negative and limit must be 10",
  "hint": "Use a non-negative integer offset and limit=10.",
  "documentation": "https://brownsmithdynamics.com/docs"
}

Correct invalid JSON or fields (400), use the website origin (403), shorten oversized bodies (413), or send application/json (415). Wait for Retry-After on 429. For delivery failures (502) or an unavailable contact service (503), use the email or WhatsApp options on the contact page.

Agent Discovery

Start with llms.txt, structured business data, and the sitemap. Missing website addresses can return a Markdown 404 with current discovery links when Markdown is requested.