Public API

SoMerch exposes a small set of unauthenticated HTTP endpoints for crawlers, AI agents, and uptime monitors. The machine-readable description is available as an OpenAPI 3.1 document and discoverable through the RFC 9727 API catalog.

Endpoints

• GET/api/public/health

  application/json

  Liveness probe

  Returns a small JSON document indicating the application is reachable. Suitable for uptime monitors.

• GET/api/public/openapi.json

  application/json

  OpenAPI 3.1 specification

  Machine-readable description of the public HTTP surface.

• GET/.well-known/api-catalog

  application/linkset+json

  RFC 9727 API catalog

  Linkset (RFC 9264) listing each public API surface with service-desc, service-doc and status link relations.

• GET/.well-known/openid-configuration

  application/json

  OpenID Connect discovery document

  OIDC 1.0 metadata pointing at the Supabase-managed identity provider that issues SoMerch access tokens.

• GET/.well-known/oauth-authorization-server

  application/json

  OAuth 2.0 authorization server metadata

  RFC 8414 metadata describing the OAuth 2.0 endpoints exposed by the upstream identity provider.

• GET/.well-known/oauth-protected-resource

  application/json

  OAuth 2.0 protected resource metadata

  RFC 9728 metadata identifying this resource server, the authorization servers that issue tokens for it, and the supported scopes and bearer methods.

• GET/auth.md

  text/markdown

  Auth.md — agent registration discovery

  Human/agent-readable Markdown document describing supported identity types, credential types, registration URI, and claim/revocation endpoints for AI agents.

• GET/.well-known/mcp/server-card.json

  application/json

  MCP Server Card (SEP-1649)

  Discovery document for SoMerch's Model Context Protocol server. Advertises the streamable-HTTP endpoint, capabilities, and supported protocol version so AI agents can connect automatically.

• POST/api/mcp

  application/json

  MCP server endpoint (Streamable HTTP)

  Model Context Protocol server. Implements the streamable-HTTP transport. Use the server card at /.well-known/mcp/server-card.json to discover capabilities and tools (search_products, get_product, list_categories, list_brands, list_collections, get_header_menu, get_static_page).

• GET/.well-known/agent-skills/index.json

  application/json

  Agent Skills discovery index

  Agent Skills Discovery RFC v0.2.0 index. Lists the SKILL.md artifacts SoMerch publishes (api-catalog, oauth-discovery, oauth-protected-resource, auth-md, mcp-server-card, webmcp), each with a sha256 digest.

• GET/api/protected/meBearer

  application/json

  Current token claims

  Validates the supplied Supabase access token and returns its claims. Requires `Authorization: Bearer <jwt>`.

• GET/sitemap.xml

  application/xml

  XML sitemap index

  Sitemap index of pages, products, catalog and content sitemaps, with locale-aware hreflang alternates.

• GET/sitemap-index.xml

  application/xml

  Sitemap index redirect

  Permanent redirect to /sitemap.xml, the canonical sitemap index.

• GET/llms.txt

  text/plain

  LLM index

  Short index of the site curated for large language models.

• GET/llms-full.txt

  text/plain

  Full LLM corpus

  Concatenated machine-readable copy of the public site content.

• GET/api/public/v1/providersBearer

  application/json

  List integration providers

  Catalog of provider slugs the platform knows about (hubspot, slack, salesforce, chatgpt-mcp, zapier, generic-webhook, …) with status and supported triggers/actions.

• GET/api/public/v1/connectionsBearer

  application/json

  List integration connections for the caller's org

  Sanitized view of `integration_connections` for the caller's organization. Never returns credential material.

• POST/api/public/v1/connectionsBearer

  application/json

  Create or update an integration connection

  Attach a provider connection to the caller's organization. Use the OAuth flow for hosted providers (see /oauth/{providerSlug}/authorize).

• POST/api/public/v1/oauth/{providerSlug}/authorizeBearer

  application/json

  Begin per-tenant OAuth flow

  Mints a one-shot state + PKCE verifier and returns the provider's authorization URL. Redirect the user to that URL; the provider will redirect back to /api/public/v1/oauth/{providerSlug}/callback.

• GET/api/public/v1/oauth/{providerSlug}/callback

  text/html

  OAuth callback

  Public callback route the provider redirects to. Validates state, exchanges the code, and upserts the connection.

• POST/api/public/v1/actions/{actionKey}Bearer

  application/json

  Invoke a central action

  Central action dispatcher. Supports `Idempotency-Key` header. Built-in actions: system.ping, orders.list, orders.get, quotes.submit, hubspot.contacts.upsert, slack.messages.post, salesforce.leads.create, …

• GET/api/public/v1/eventsBearer

  application/json

  List integration events

  Normalized event log for the caller's organization. Filter by provider slug, event type, correlation id, resource, or time range.

• GET/api/public/v1/webhooksBearer

  application/json

  List outgoing webhook subscriptions

  Enumerate the org's outgoing webhook subscriptions.

• POST/api/public/v1/webhooksBearer

  application/json

  Create an outgoing webhook subscription

  Register a URL to receive HMAC-SHA256 signed deliveries for the requested event types. The signing secret is returned once at creation time.

• GET/api/public/v1/jobsBearer

  application/json

  List queued integration jobs

  Inspect background jobs (webhook deliveries, retries, dead-letter).

• GET/api/public/v1/audit-logsBearer

  application/json

  Sanitized integration audit logs

  Cross-provider audit trail. Credentials, tokens, and PII are redacted server-side before writing.

• POST/api/public/webhooks/{providerSlug}/{connectionId}

  application/json

  Incoming provider webhook

  Verifies the provider signature, normalizes the payload, enqueues a job, and returns 2xx. Configure this URL on the provider side.

• POST/api/public/cron/dispatch-webhooks

  application/json

  Cron: dispatch pending outgoing webhooks

  Secret-gated cron entry point. Called by pg_cron on a fixed schedule to drain `integration_webhook_deliveries` (exponential backoff, dead-letter). Not for direct external use.