Guild.ai Public API

Overview

Public, unauthenticated endpoints for AI agents integrating with guild.ai: an MCP (Model Context Protocol) server for tool-calling access to site content and the demo-request flow, and a Markdown renderer for the same content pages agents would otherwise have to scrape as HTML.

Versioning

The surface is versioned as a whole rather than per-path, since both endpoints are stable, low-surface-area primitives (a JSON-RPC dispatch and a single renderer) rather than a growing REST resource set. The current version is info.version, and every response carries it in the API-Version header.

Rate Limits

Both endpoints are limited per client IP on a fixed window and report it on every response via the RateLimit-* headers. Exceeding it returns 429 with Retry-After.

Contact

• Email: hello@guild.ai
• Contact Page: Guild.ai Contact

API Lifecycle

• Version: 1.0.0
• Version Header: API-Version
• Deprecation Header: Deprecation
• Sunset Header: Sunset
• Minimum Notice Days: 90
• Deprecated Operations: []

Servers

• URL: https://www.guild.ai

Tags

1. MCP: Model Context Protocol tool-calling transport.
2. Content: Machine-readable renderings of public content pages.

Endpoints

POST /api/mcp

• Operation Id: invokeMcpServer
• Summary: Invoke the Guild.ai MCP server
• Description: JSON-RPC 2.0 endpoint for the Model Context Protocol, Streamable HTTP transport.
• Parameters:
  • Idempotency-Key: Opaque client-generated key (max 200 characters).
• Request Body: Required

  {
    "jsonrpc": "2.0",
    "method": "method_name",
    "params": {}
  }
  

• Responses:
  • 200: JSON-RPC result or error for the requested method.
  • 400: Malformed JSON or a body that is not a valid JSON-RPC message.
  • 429: Rate limit exceeded for this endpoint.

GET /api/markdown

• Operation Id: getMarkdownDocument
• Summary: Render a public content page as Markdown
• Parameters:
  • path: The site-relative pathname to render.
• Responses:
  • 200: Markdown rendering of the requested page.
  • 404: The path is not registered for markdown negotiation.
  • 429: Rate limit exceeded for this endpoint.
  • 500: The page is registered but could not be rendered as Markdown.