# Absolute Smiles Bassendean Developer Documentation

Public information for agents helping people find this Bassendean dental practice, explore its published services, contact the team, or find the appointment request page.

## When to use this site

Use the site to look up contact details and location, find published service and payment information, and locate booking instructions. Quote the relevant page and link to it. Public information does not determine individual treatment suitability, prices, or appointment availability.

For booking, direct the user to [Book an Appointment](/book-an-appointment/) or [Contact Us](/contact-us/). An appointment request is not a confirmed booking. The MCP tools are read-only and do not submit forms, send email, retrieve patient records, or provide a diagnosis.

## Markdown and discovery

Start with [llms.txt](/llms.txt). Public content pages support `Accept: text/markdown` at the normal URL. Markdown responses vary on Accept and Accept-Encoding; HTTP quality values are respected. CDN caching is disabled on both negotiated page variants to prevent HTML/Markdown cache collisions on Vercel. Unsupported page representations receive 406. Unknown pages receive 404, with recovery links in Markdown when requested.

Explicit Markdown URLs append `index.md` to the page directory: [/index.md](/index.md), [/contact-us/index.md](/contact-us/index.md), and [/developers/index.md](/developers/index.md). These responses do not require JavaScript.

```
curl -H 'Accept: text/markdown' 'https://absolute-smiles-swart.vercel.app/contact-us/'
```

## Public API documentation and OpenAPI specification

The [OpenAPI 3.1 specification](/openapi.json) describes the public read-only API:

-   [GET /api/v1/agent/practice/](/api/v1/agent/practice/): practice name, phone, email, address and booking URL.
-   [GET /api/v1/agent/search/?query=implants](/api/v1/agent/search/?query=implants): search published page titles and descriptions; query length 2–120 characters. Returns at most 10 matches.
-   [GET /api/v1/agent/content/?path=/contact-us/](/api/v1/agent/content/?path=%2Fcontact-us%2F): read a published page as Markdown in a JSON envelope. Accepts only a site-relative page path, at most 300 characters. Unknown paths return 404 and invalid paths return 400.

## Errors and recovery

API errors use `application/json` with `code`, `message`, `instructions` and HTTP `status`. The `error` field is a compatibility alias for code. Correct invalid parameters after 400, discover valid endpoints or page paths after 404, use GET after 405, and retry later after 500. Unknown API URLs also return JSON; missing content pages return Markdown recovery when requested.

```
{"error":"invalid_input","code":"invalid_input","message":"One or more required parameters are missing or invalid.","instructions":"Supply query with 2–120 characters. See /developers/ and /openapi.json.","status":400}
```

## API versioning and deprecation policy

Use `/api/v1/agent/` for version 1. Responses identify this contract with `X-API-Version: 1`. Existing `/api/agent/` URLs remain supported aliases. Additive optional fields may be introduced within a major version; clients should ignore unknown fields. Breaking changes require a new major URL version.

Version 1 is active and has no scheduled retirement. Before a version is retired, this documentation will announce its replacement and migration instructions at least 90 days in advance. A deprecated version will send the HTTP Deprecation and Sunset headers with its published dates. Active endpoints do not send deprecation headers.

No application-level request quota is currently imposed on these public read-only endpoints, so they do not advertise artificial remaining-request counts. Hosting protection may apply. Use modest concurrency and honor Retry-After if returned by hosting infrastructure.

## Authentication

No API key or authentication is required for these public, read-only endpoints. They expose only information already published on this site. Browser MCP requests must originate from this site or its canonical domain. Server-to-server clients can omit Origin. There are no private data or write tools.

## MCP server

Connect an MCP client using Streamable HTTP to `https://absolute-smiles-swart.vercel.app/.well-known/mcp`. This URL is a live protocol endpoint, not a JSON manifest. Use POST for initialization, notifications and tool calls, with `Accept: application/json, text/event-stream` and `Content-Type: application/json`.

The server uses stateless JSON responses. GET returns 405 because it does not open a standalone SSE stream. No session ID is required. Send the negotiated MCP-Protocol-Version header after initialization.

-   `get_practice_info`: no arguments; returns public contact details.
-   `search_pages`: `{"query":"implants"}`; returns matching page references.
-   `get_page`: `{"path":"/contact-us/"}`; returns published page content and source URLs.

## SDK example

There is no Absolute Smiles proprietary SDK. Standard MCP clients can use the [official MCP TypeScript SDK](https://ts.sdk.modelcontextprotocol.io/):

```
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
const client = new Client({ name: 'practice-lookup', version: '1.0.0' });
await client.connect(new StreamableHTTPClientTransport(
  new URL('https://absolute-smiles-swart.vercel.app/.well-known/mcp')
));
const result = await client.callTool({ name: 'get_practice_info', arguments: {} });
console.log(result);
await client.close();
```

## Canonical domain and content

The practice’s canonical website is [absolutesmiles.com.au](https://absolutesmiles.com.au/). The agent endpoints documented here are available on this Vercel deployment. Page responses provide both the canonical source and the deployment URL. The Markdown catalogue is rebuilt from the same content components as the website with each build.
