{ "openapi": "3.1.0", "info": { "title": "SoMerch Public API", "version": "1.0.0", "description": "Public HTTP endpoints exposed by SoMerch for crawlers, AI agents, and uptime monitors. Authenticated endpoints accept Supabase-issued access tokens; see /.well-known/openid-configuration for discovery.", "contact": { "name": "SoMerch", "url": "https://somerch.co" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://somerch.co" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Supabase-issued access token. Discover the token endpoint via /.well-known/openid-configuration." }, "oauth2": { "type": "oauth2", "description": "Authorization Code + PKCE against the Supabase-managed identity provider.", "flows": { "authorizationCode": { "authorizationUrl": "https://icgeebswaukzsuazxqcj.supabase.co/auth/v1/authorize", "tokenUrl": "https://icgeebswaukzsuazxqcj.supabase.co/auth/v1/token", "refreshUrl": "https://icgeebswaukzsuazxqcj.supabase.co/auth/v1/token", "scopes": { "openid": "OpenID Connect sign-in", "email": "User email address", "profile": "User profile claims" } } } } } }, "paths": { "/api/public/health": { "get": { "summary": "Liveness probe", "description": "Returns a small JSON document indicating the application is reachable. Suitable for uptime monitors.", "responses": { "200": { "description": "Success", "content": { "application/json": {} } } } } }, "/api/public/openapi.json": { "get": { "summary": "OpenAPI 3.1 specification", "description": "Machine-readable description of the public HTTP surface.", "responses": { "200": { "description": "Success", "content": { "application/json": {} } } } } }, "/.well-known/api-catalog": { "get": { "summary": "RFC 9727 API catalog", "description": "Linkset (RFC 9264) listing each public API surface with service-desc, service-doc and status link relations.", "responses": { "200": { "description": "Success", "content": { "application/linkset+json": {} } } } } }, "/.well-known/openid-configuration": { "get": { "summary": "OpenID Connect discovery document", "description": "OIDC 1.0 metadata pointing at the Supabase-managed identity provider that issues SoMerch access tokens.", "responses": { "200": { "description": "Success", "content": { "application/json": {} } } } } }, "/.well-known/oauth-authorization-server": { "get": { "summary": "OAuth 2.0 authorization server metadata", "description": "RFC 8414 metadata describing the OAuth 2.0 endpoints exposed by the upstream identity provider.", "responses": { "200": { "description": "Success", "content": { "application/json": {} } } } } }, "/.well-known/oauth-protected-resource": { "get": { "summary": "OAuth 2.0 protected resource metadata", "description": "RFC 9728 metadata identifying this resource server, the authorization servers that issue tokens for it, and the supported scopes and bearer methods.", "responses": { "200": { "description": "Success", "content": { "application/json": {} } } } } }, "/auth.md": { "get": { "summary": "Auth.md — agent registration discovery", "description": "Human/agent-readable Markdown document describing supported identity types, credential types, registration URI, and claim/revocation endpoints for AI agents.", "responses": { "200": { "description": "Success", "content": { "text/markdown": {} } } } } }, "/.well-known/mcp/server-card.json": { "get": { "summary": "MCP Server Card (SEP-1649)", "description": "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.", "responses": { "200": { "description": "Success", "content": { "application/json": {} } } } } }, "/api/mcp": { "post": { "summary": "MCP server endpoint (Streamable HTTP)", "description": "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).", "responses": { "200": { "description": "Success", "content": { "application/json": {} } } } } }, "/.well-known/agent-skills/index.json": { "get": { "summary": "Agent Skills discovery index", "description": "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.", "responses": { "200": { "description": "Success", "content": { "application/json": {} } } } } }, "/api/protected/me": { "get": { "summary": "Current token claims", "description": "Validates the supplied Supabase access token and returns its claims. Requires `Authorization: Bearer `.", "responses": { "200": { "description": "Success", "content": { "application/json": {} } }, "401": { "description": "Missing or invalid Bearer token.", "content": { "application/json": {} } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "openid", "email" ] } ] } }, "/sitemap.xml": { "get": { "summary": "XML sitemap", "description": "Localized URL set for the public site, with hreflang alternates per RFC compliant sitemaps.", "responses": { "200": { "description": "Success", "content": { "application/xml": {} } } } } }, "/sitemap-index.xml": { "get": { "summary": "Sitemap index", "description": "Index of all available sitemaps for the public site.", "responses": { "200": { "description": "Success", "content": { "application/xml": {} } } } } }, "/llms.txt": { "get": { "summary": "LLM index", "description": "Short index of the site curated for large language models.", "responses": { "200": { "description": "Success", "content": { "text/plain": {} } } } } }, "/llms-full.txt": { "get": { "summary": "Full LLM corpus", "description": "Concatenated machine-readable copy of the public site content.", "responses": { "200": { "description": "Success", "content": { "text/plain": {} } } } } }, "/api/public/v1/providers": { "get": { "summary": "List integration providers", "description": "Catalog of provider slugs the platform knows about (hubspot, slack, salesforce, chatgpt-mcp, zapier, generic-webhook, …) with status and supported triggers/actions.", "responses": { "200": { "description": "Success", "content": { "application/json": {} } }, "401": { "description": "Missing or invalid Bearer token.", "content": { "application/json": {} } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "openid", "email" ] } ] } }, "/api/public/v1/connections": { "get": { "summary": "List integration connections for the caller's org", "description": "Sanitized view of `integration_connections` for the caller's organization. Never returns credential material.", "responses": { "200": { "description": "Success", "content": { "application/json": {} } }, "401": { "description": "Missing or invalid Bearer token.", "content": { "application/json": {} } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "openid", "email" ] } ] }, "post": { "summary": "Create or update an integration connection", "description": "Attach a provider connection to the caller's organization. Use the OAuth flow for hosted providers (see /oauth/{providerSlug}/authorize).", "responses": { "200": { "description": "Success", "content": { "application/json": {} } }, "401": { "description": "Missing or invalid Bearer token.", "content": { "application/json": {} } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "openid", "email" ] } ] } }, "/api/public/v1/oauth/{providerSlug}/authorize": { "post": { "summary": "Begin per-tenant OAuth flow", "description": "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.", "responses": { "200": { "description": "Success", "content": { "application/json": {} } }, "401": { "description": "Missing or invalid Bearer token.", "content": { "application/json": {} } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "openid", "email" ] } ] } }, "/api/public/v1/oauth/{providerSlug}/callback": { "get": { "summary": "OAuth callback", "description": "Public callback route the provider redirects to. Validates state, exchanges the code, and upserts the connection.", "responses": { "200": { "description": "Success", "content": { "text/html": {} } } } } }, "/api/public/v1/actions/{actionKey}": { "post": { "summary": "Invoke a central action", "description": "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, …", "responses": { "200": { "description": "Success", "content": { "application/json": {} } }, "401": { "description": "Missing or invalid Bearer token.", "content": { "application/json": {} } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "openid", "email" ] } ] } }, "/api/public/v1/events": { "get": { "summary": "List integration events", "description": "Normalized event log for the caller's organization. Filter by provider slug, event type, correlation id, resource, or time range.", "responses": { "200": { "description": "Success", "content": { "application/json": {} } }, "401": { "description": "Missing or invalid Bearer token.", "content": { "application/json": {} } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "openid", "email" ] } ] } }, "/api/public/v1/webhooks": { "get": { "summary": "List outgoing webhook subscriptions", "description": "Enumerate the org's outgoing webhook subscriptions.", "responses": { "200": { "description": "Success", "content": { "application/json": {} } }, "401": { "description": "Missing or invalid Bearer token.", "content": { "application/json": {} } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "openid", "email" ] } ] }, "post": { "summary": "Create an outgoing webhook subscription", "description": "Register a URL to receive HMAC-SHA256 signed deliveries for the requested event types. The signing secret is returned once at creation time.", "responses": { "200": { "description": "Success", "content": { "application/json": {} } }, "401": { "description": "Missing or invalid Bearer token.", "content": { "application/json": {} } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "openid", "email" ] } ] } }, "/api/public/v1/jobs": { "get": { "summary": "List queued integration jobs", "description": "Inspect background jobs (webhook deliveries, retries, dead-letter).", "responses": { "200": { "description": "Success", "content": { "application/json": {} } }, "401": { "description": "Missing or invalid Bearer token.", "content": { "application/json": {} } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "openid", "email" ] } ] } }, "/api/public/v1/audit-logs": { "get": { "summary": "Sanitized integration audit logs", "description": "Cross-provider audit trail. Credentials, tokens, and PII are redacted server-side before writing.", "responses": { "200": { "description": "Success", "content": { "application/json": {} } }, "401": { "description": "Missing or invalid Bearer token.", "content": { "application/json": {} } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "openid", "email" ] } ] } }, "/api/public/webhooks/{providerSlug}/{connectionId}": { "post": { "summary": "Incoming provider webhook", "description": "Verifies the provider signature, normalizes the payload, enqueues a job, and returns 2xx. Configure this URL on the provider side.", "responses": { "200": { "description": "Success", "content": { "application/json": {} } } } } }, "/api/public/cron/dispatch-webhooks": { "post": { "summary": "Cron: dispatch pending outgoing webhooks", "description": "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.", "responses": { "200": { "description": "Success", "content": { "application/json": {} } } } } } } }