Search docs ⌘K
esc
Type to search across all documentation pages
Meta

Meta & Health

Public discovery routes for humans, agents, SDKs, and operators. This page covers the API landing page, the canonical SaaSignal agent skill, OpenAPI and AI docs, health probes, OAuth protected-resource metadata, and the MCP transport endpoint.

These routes are especially useful when you are integrating SaaSignal from a browser, CLI, SDK, or agent runtime. Most are public; the MCP transport itself still requires OAuth or an API key.

Discovery & Docs

Landing pages and machine-readable specs for humans, SDKs, and AI agents.

API Landing Page

GET
/

Returns an AI-first landing page. Serves semantic HTML to browsers and markdown documentation to agents that send Accept: text/markdown.

curl
curl https://api.saasignal.saastemly.com/ \
  -H "Authorization: Bearer <session_token>"
json — 200 OK
{ "status": "ok" }
typescript
const markdown = await ss.meta.landing()
  1. Open Dashboard → API Console
  2. Select GET / and run it to inspect the public discovery response from Chrome
  3. Open the API host directly in a new tab when you want the full HTML landing page instead of markdown

SaaSignal Agent Skill

GET
/skills/saasignal

Returns the canonical SaaSignal agent skill as markdown. Use this when an agent needs a guided playbook for choosing between MCP, REST, the SDK, and the CLI, including current MCP coverage and common scope boundaries. Supports HEAD requests to inspect X-Markdown-Tokens before downloading the body. Responses include ETag for conditional requests (If-None-Match → 304).

curl
curl https://api.saasignal.saastemly.com/skills/saasignal \
  -H "Authorization: Bearer <session_token>"
json — 200 OK
{ "status": "ok" }
typescript
const skill = await ss.meta.saasignalSkill()
  1. Open Dashboard → API Console
  2. Select GET /skills/saasignal and run it to inspect the canonical agent onboarding guide
  3. Use this route when you want an AI agent to choose between MCP, REST, the SDK, and the CLI without guessing
This route is the single-source SaaSignal skill document used by the public API, SDK helpers, and the MCP helper tool.

LLM Docs Index

GET
/llms.txt

Returns a spec-compliant llmstxt.org index linking to deeper resources: the full LLM-optimized API reference (/llms-full.txt), agent skill, OpenAPI spec, human-readable docs, MCP endpoint, and SDK/CLI references. Responses include ETag for conditional requests (If-None-Match → 304).

curl
curl https://api.saasignal.saastemly.com/llms.txt \
  -H "Authorization: Bearer <session_token>"
json — 200 OK
{ "status": "ok" }
typescript
const llms = await ss.meta.llmsTxt()
  1. Open Dashboard → API Console
  2. Select GET /llms.txt and run it to inspect the llmstxt.org-compliant index
  3. Use the response headers pane to confirm caching metadata like ETag

Full LLM-Optimized Docs

GET
/llms-full.txt

Returns a token-optimized compact representation of the API (~60-75% smaller than raw OpenAPI JSON). Designed for LLM agents and AI tools. Supports HEAD requests to check token cost via X-Markdown-Tokens response header before downloading the full body. Responses include ETag for conditional requests (If-None-Match → 304).

curl
curl https://api.saasignal.saastemly.com/llms-full.txt \
  -H "Authorization: Bearer <session_token>"
json — 200 OK
{ "status": "ok" }
typescript
const llmsFull = await ss.meta.llmsFullTxt()
  1. Open Dashboard → API Console
  2. Select GET /llms-full.txt and run it to inspect the AI-focused docs payload
  3. Use the response headers pane to confirm caching metadata like ETag and X-Markdown-Tokens

Human Markdown Docs

GET
/to-humans.md

Returns comprehensive markdown documentation with table of contents, authentication guide, parameter tables, and response schemas. Suitable for rendering in any markdown viewer or importing into documentation platforms. Responses include ETag for conditional requests (If-None-Match → 304).

curl
curl https://api.saasignal.saastemly.com/to-humans.md \
  -H "Authorization: Bearer <session_token>"
json — 200 OK
{ "status": "ok" }
typescript
const docs = await ss.meta.humanDocs()
  1. Open Dashboard → API Console
  2. Select GET /to-humans.md and run it to preview the markdown reference in Chrome
  3. Use this route when you want an agent-friendly but still human-readable export of the full API surface

OpenAPI Spec

GET
/api/openapi.json

Returns the full OpenAPI 3.1.0 JSON specification for the SaaSignal API. Includes all route definitions, request/response schemas, authentication requirements, and tag descriptions. Use this spec to generate client SDKs, import into tools like Postman or Insomnia, or feed into code-generation pipelines.

curl
curl https://api.saasignal.saastemly.com/api/openapi.json \
  -H "Authorization: Bearer <session_token>"
json — 200 OK
{ "status": "ok" }
typescript
const spec = await ss.meta.openApiSpec()
  1. Open Dashboard → API Console
  2. Select GET /api/openapi.json and run it to inspect the raw OpenAPI document
  3. Use the JSON response directly in code generators, Postman imports, or contract diff tooling

Scalar API Reference

GET
/scalar

Interactive API reference powered by Scalar. Renders the OpenAPI specification as a browsable UI.

curl
curl https://api.saasignal.saastemly.com/scalar \
  -H "Authorization: Bearer <session_token>"
json — 200 OK
{ "status": "ok" }
typescript
const scalarUrl = ss.meta.scalarUrl()
window.open(scalarUrl, '_blank')
  1. Open Dashboard → API Console
  2. Click Open Scalar in the header to launch the hosted interactive reference
  3. Or call GET /scalar directly from the console if you want to inspect the HTML response itself

robots.txt

GET
/robots.txt

Robots exclusion protocol file. Serves a permissive policy that allows all user-agents to crawl public meta endpoints. Includes a Sitemap directive pointing to /sitemap.xml for automated URL discovery.

curl
curl https://api.saasignal.saastemly.com/robots.txt \
  -H "Authorization: Bearer <session_token>"
json — 200 OK
{ "status": "ok" }
typescript
const robots = await ss.meta.robotsTxt()
  1. Open Dashboard → API Console
  2. Select GET /robots.txt and run it to inspect crawler directives
  3. Validate that the file points crawlers to the public meta surfaces and sitemap

XML Sitemap

GET
/sitemap.xml

Sitemaps protocol file listing all publicly accessible meta endpoints with changefreq and priority hints. Referenced by the Sitemap directive in /robots.txt.

curl
curl https://api.saasignal.saastemly.com/sitemap.xml \
  -H "Authorization: Bearer <session_token>"
json — 200 OK
{ "status": "ok" }
typescript
const sitemap = await ss.meta.sitemapXml()
  1. Open Dashboard → API Console
  2. Select GET /sitemap.xml and run it to inspect the public route inventory
  3. Use the XML response to verify that public docs and health surfaces stay discoverable

Health & Readiness

Operational probes for uptime checks, orchestration, and monitoring.

Liveness Probe

GET
/livez

Liveness check — returns 200 if the worker is alive and accepting HTTP requests. Does not verify downstream dependencies. Use /readyz for a deeper check.

curl
curl https://api.saasignal.saastemly.com/livez \
  -H "Authorization: Bearer <session_token>"
json — 200 OK
{ "status": "ok" }
typescript
const result = await ss.meta.livez()
  1. Open Dashboard → API Console
  2. Select GET /livez and run it for a fast process-level health check
  3. Use this endpoint for shallow uptime monitors that only need to know the worker is answering requests

Readiness Probe

GET
/readyz

Readiness check — verifies the worker can reach its database (D1). Returns 200 when all dependencies are healthy, or 503 when degraded. Use /livez for a lightweight liveness-only check.

curl
curl https://api.saasignal.saastemly.com/readyz \
  -H "Authorization: Bearer <session_token>"
json — 200 OK
{ "status": "ok" }
typescript
const result = await ss.meta.readyz()
  1. Open Dashboard → API Console
  2. Select GET /readyz and run it to verify the worker can reach dependencies like D1
  3. Inspect the JSON checks object when you are debugging a degraded deployment
Error responses
503 Service is not ready

Combined Health Probe

GET
/healthz

Combined health endpoint — returns liveness status together with dependency checks (database connectivity). Responds 200 when all systems are healthy, 503 when any dependency is degraded. Equivalent to running both /livez and /readyz in a single call.

curl
curl https://api.saasignal.saastemly.com/healthz \
  -H "Authorization: Bearer <session_token>"
json — 200 OK
{ "status": "ok" }
typescript
const result = await ss.meta.healthz()
  1. Open Dashboard → API Console
  2. Select GET /healthz and run it for the combined liveness and readiness view
  3. Use this route when you want one browser-checkable JSON response with status, uptime, version, and dependency checks
Error responses
503 One or more dependencies are unhealthy

OAuth Metadata & MCP

Protected-resource discovery documents and the Streamable HTTP MCP entrypoint.

API Protected Resource Metadata

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

Publishes RFC 9728 protected resource metadata for the SaaSignal HTTP API. OAuth-capable SDKs and CLIs use this document to discover the frontend authorization server, supported scopes, and the primary API setup guide.

curl
curl https://api.saasignal.saastemly.com/.well-known/oauth-protected-resource \
  -H "Authorization: Bearer <session_token>"
json — 200 OK
{ "status": "ok" }
typescript
const metadata = await ss.meta.apiProtectedResourceMetadata()
  1. Open Dashboard → API Console
  2. Select GET /.well-known/oauth-protected-resource and run it to inspect API OAuth discovery data
  3. Use this document when wiring CLI or SDK OAuth flows against the regular SaaSignal HTTP API

MCP Protected Resource Metadata

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

Publishes RFC 9728 protected resource metadata for the SaaSignal MCP endpoint. OAuth-capable MCP clients use this document to discover the frontend authorization server, supported scopes, and the MCP setup guide.

curl
curl https://api.saasignal.saastemly.com/.well-known/oauth-protected-resource/mcp \
  -H "Authorization: Bearer <session_token>"
json — 200 OK
{ "status": "ok" }
typescript
const metadata = await ss.meta.mcpProtectedResourceMetadata()
  1. Open Dashboard → API Console
  2. Select GET /.well-known/oauth-protected-resource/mcp and run it to inspect MCP OAuth discovery data
  3. Use the response when configuring MCP clients that support the browser authorization flow

MCP JSON-RPC Transport

POST
/mcp

Stateless MCP (Model Context Protocol) server over Streamable HTTP. This deployment is POST-only: clients send JSON-RPC 2.0 requests (initialize, tools/list, tools/call) to POST /mcp, and GET /mcp / DELETE /mcp return 405 Method Not Allowed because SaaSignal does not provide a standalone SSE session transport. Primary authentication: Browser-based OAuth 2.1 / MCP authorization flow. OAuth-capable MCP clients can connect with just the server URL, discover /.well-known/oauth-protected-resource/mcp, open the frontend authorization flow in a browser, and then call /mcp with the JWT bearer token. OAuth tokens are user-level and grant access across all organizations the user belongs to. Manual fallback: Existing project API keys (sk_live_…) still work in the Authorization: Bearer header for clients that do not support browser authorization. If X-Project-Id is provided, it is enforced for all tool calls. Otherwise, each tool call must include project_id unless the credential is already project-scoped. Agent onboarding: Call saasignal_surface_map or saasignal_skill first when you want the broader platform map before planning. Automatic route exposure: MCP now auto-registers a tool for each documented HTTP operation using its OpenAPI operationId. If you add a new Hono route with describeRoute(...) and a stable operationId, it becomes available through tools/list automatically after deploy. Legacy aliases: Existing operational aliases like kv_get, channel_publish, and job_create remain available for compatibility, but the canonical generated tool names follow the HTTP operationId values such as listProjects, storageListBuckets, or logisticsGeoCreate. Response model: Generated MCP route tools proxy the real HTTP handlers. They return the HTTP status, response headers, content type, and parsed body so validation, billing, side effects, and auth stay aligned with the underlying route. Streaming responses are returned as previews or connection metadata instead of long-lived sockets. All write operations are metered via token-based billing. Rate limits apply per organization plan.

curl
curl -X POST https://api.saasignal.saastemly.com/mcp \
  -H "Authorization: Bearer sk_live_..."
json — 200 OK
{ "status": "ok" }
typescript
const tools = await ss.meta.mcp({ method: 'tools/list', params: {} })
  1. Open Dashboard → API Console and select an organization plus project
  2. Choose POST /mcp from the route list, then edit the JSON-RPC body in the request builder
  3. Run the request to proxy it through the dashboard session and inspect the MCP response directly from Chrome
The dashboard proxy handles authentication for browser testing, while production MCP clients should use OAuth discovery or an API key fallback.
Error responses
400 Bad request — conflicting or missing project selection
401 Unauthorized — missing or invalid MCP bearer credential. Includes an OAuth Bearer challenge with resource metadata.
403 Forbidden — token does not have access to the specified project or lacks the required OAuth scope.