---
title: "API Documentation"
source: "https://samcarlton.com/api-docs/"
---

# API Documentation

This site publishes a small public agent surface for reading public content, exploring portfolio projects, and sending reviewed contact inquiries.

## Discovery

-   API catalog: [/.well-known/api-catalog](/.well-known/api-catalog)
-   OpenAPI description: [/openapi.json](/openapi.json)
-   MCP server card: [/.well-known/mcp/server-card.json](/.well-known/mcp/server-card.json)
-   MCP endpoint: [/mcp](/mcp)
-   Agent Skills index: [/.well-known/agent-skills/index.json](/.well-known/agent-skills/index.json)
-   Health endpoint: [/api/health](/api/health)

## Article endpoints

`GET /api/articles.json`

Lists public articles with canonical HTML URLs, Markdown alternate URLs, and per-article JSON URLs.

`GET /api/articles/{slug}.json`

Returns a public article by slug, including the source MDX body. Example:

`/api/articles/how-i-like-to-keep-ai-honest.json`

## Project endpoints

`GET /api/projects.json`

Lists public projects and portfolio items with canonical HTML URLs, Markdown alternate URLs, and per-project JSON URLs.

`GET /api/projects/{slug}.json`

Returns a public project by slug, including the source MDX body. Example:

`/api/projects/church-on-the-move-messages-platform.json`

## Contact form endpoint

`POST /api/contact`

The contact endpoint accepts the same form fields used by the public contact page:

-   `name`
-   `email`
-   `message`
-   `source`
-   `g-recaptcha-response`
-   `page_url`
-   `referrer_url`
-   `utm_source`
-   `utm_medium`
-   `utm_campaign`
-   `utm_content`
-   `utm_term`
-   `self_reported_source`
-   `referral_person_or_org`
-   `company`
-   `website`
-   `project_type`
-   `budget_range`
-   `timeline`
-   `preferred_contact_method`
-   `phone`
-   `asset_urls`

Submissions are validated server-side with reCAPTCHA before email forwarding. Automated clients should only submit after the user has reviewed the exact message and the client has a valid `g-recaptcha-response` token from the public contact page.

## MCP endpoint

`POST /mcp`

The MCP endpoint supports JSON-RPC requests for:

-   `initialize`
-   `ping`
-   `tools/list`
-   `tools/call`

Published tools:

-   `list_articles`
-   `read_article`
-   `list_projects`
-   `read_project`
-   `submit_contact_form`

The contact submission tool requires `confirm_user_reviewed: true` and a valid `g_recaptcha_response`. It is intentionally guarded so agents can prepare and submit reviewed inquiries without bypassing the site’s existing spam protection.

## Health endpoint

`GET /api/health`

Returns a small JSON status response so automated clients can verify that the public API surface is reachable.