{
"openapi": "3.1.0",
"info": {
"title": "surrealdb.com website API",
"version": "1.0.0",
"summary": "The machine-readable surface of the SurrealDB website: pricing data, course outlines, markdown renderings of every page, and the agent-discovery documents.",
"description": "This description covers what the surrealdb.com **website** origin serves to programmatic clients. It is not the SurrealDB product API.\n\nThree other surfaces exist, and an agent usually wants one of them instead:\n\n- **SurrealDB Cloud platform API** - accounts, organisations, instances, billing. Origin `https://api.surrealdb.com`, described at `https://api.surrealdb.com/openapi/public.yaml`, documented at `https://api.surrealdb.com/docs`.\n- **SurrealDB HTTP API** - the database engine's own endpoints (`/sql`, `/key/:table`, import, export), served by whatever SurrealDB instance you are talking to. Described at `https://raw.githubusercontent.com/surrealdb/openapi/main/openapi.yml`.\n- **SurrealDB MCP server** - the same Cloud capabilities as MCP tools over streamable HTTP at `https://mcp.surrealdb.com`. Start at `https://surrealdb.com/.well-known/mcp/server-card.json`.\n\nEverything described below is public and unauthenticated. Errors are RFC 9457 `application/problem+json` documents carrying a stable `code` and a `resolution` naming the next request to make.\n\nTwo endpoints on this origin are deliberately absent from `paths`.\n\n`GET /api/docs/search` is a rewrite to the documentation search service, owned by the docs project. It answers with JSON, but its required query parameters are not defined here, and a generated call would be wrong. Search the docs through https://surrealdb.com/docs, or use the `search_documentation` tool on the MCP server.\n\n`GET /api/learn/{course}.json` responds 200 with an empty array for every course, because the course map it reads from has not been wired to the content collections. The courses themselves are published as ordinary pages under `/learn`, so read those as markdown instead. The operation will be described here once the endpoint returns real outlines.",
"contact": {
"name": "SurrealDB",
"url": "https://surrealdb.com/contact",
"email": "support@surrealdb.com"
},
"license": {
"name": "Content licence",
"url": "https://surrealdb.com/legal/website-terms"
}
},
"servers": [
{
"url": "https://surrealdb.com",
"description": "Production website origin."
}
],
"security": [],
"externalDocs": {
"description": "SurrealDB documentation",
"url": "https://surrealdb.com/docs"
},
"tags": [
{
"name": "content",
"description": "Markdown renderings of the site's pages, for agents that would rather read a document than an HTML app shell."
},
{
"name": "data",
"description": "Structured data the site publishes as JSON: the pricing catalogue and the interactive course outlines."
},
{
"name": "discovery",
"description": "The well-known documents an agent reads to work out what SurrealDB offers and how to connect to it."
}
],
"paths": {
"/api/cloud/pricing.json": {
"get": {
"operationId": "getCloudPricing",
"tags": [
"data"
],
"summary": "Get the SurrealDB Cloud pricing catalogue",
"description": "Returns every published plan - SurrealDB Cloud tiers, the self-hosted tier, and the support tiers - with prices, included features, and resource limits. This is the same data that renders https://surrealdb.com/pricing, so an agent comparing costs does not have to scrape the pricing page.",
"responses": {
"200": {
"description": "The full pricing catalogue.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PricingCatalogue"
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/index.md": {
"get": {
"operationId": "getHomepageMarkdown",
"tags": [
"content"
],
"summary": "Get the homepage as markdown",
"description": "The homepage rendered as markdown. The `.md` suffix is reserved on the homepage because `/.md` is not a URL, so the homepage alone uses this spelling; every other page follows the pattern in getPageMarkdown.",
"responses": {
"200": {
"$ref": "#/components/responses/PageMarkdown"
},
"404": {
"$ref": "#/components/responses/NotFoundMarkdown"
}
}
}
},
"/{page}.md": {
"get": {
"operationId": "getPageMarkdown",
"tags": [
"content"
],
"summary": "Get a top-level page as markdown",
"description": "Every page on this site has a markdown twin: append `.md` to its path. `/pricing` becomes `/pricing.md`. Blog posts are served from their authored markdown source; every other page is rendered and converted. The response carries `x-markdown-tokens` and `x-original-tokens` so an agent can budget before reading.\n\nSending `Accept: text/markdown` to the page's ordinary URL returns the same document, and each page's HTML `` advertises its twin with ``.\n\nEach path segment is a separate parameter on purpose: the separating slashes are part of the URL, and a client that percent-encodes one gets a 404. There is one operation per URL depth, and four segments is the deepest this site goes.",
"parameters": [
{
"name": "page",
"in": "path",
"required": true,
"description": "The page's single path segment, without the leading slash.",
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9._~@-]+$",
"examples": [
"pricing"
]
},
"example": "pricing"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/PageMarkdown"
},
"404": {
"description": "No page exists at that path. The body is a short markdown document naming the site's indexes.",
"content": {
"text/markdown": {
"schema": {
"type": "string"
}
}
}
}
}
}
},
"/llms.txt": {
"get": {
"operationId": "getLlmsIndex",
"tags": [
"discovery"
],
"summary": "Get the agent navigation index",
"description": "A markdown index of the site written for language models: what SurrealDB is, when to reach for it, and a linked map of the pages worth reading. Start here when you know nothing about this domain.",
"responses": {
"200": {
"description": "The navigation index.",
"content": {
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFoundMarkdown"
}
}
}
},
"/llms-full.txt": {
"get": {
"operationId": "getLlmsFull",
"tags": [
"discovery"
],
"summary": "Get the long-form agent index",
"description": "The expanded companion to llms.txt: the same map with the prose that llms.txt summarises. Fetch it when the index alone does not answer the question.",
"responses": {
"200": {
"description": "The long-form index.",
"content": {
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFoundMarkdown"
}
}
}
},
"/sitemap.xml": {
"get": {
"operationId": "getSitemapIndex",
"tags": [
"discovery"
],
"summary": "Get the sitemap index",
"description": "A sitemap index pointing at the per-section sitemaps. Every indexable URL on this origin appears in one of them, each with a lastmod date.",
"responses": {
"200": {
"description": "A urlset or sitemapindex document.",
"content": {
"application/xml": {
"schema": {
"type": "string"
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFoundMarkdown"
}
}
}
},
"/openapi.json": {
"get": {
"operationId": "getOpenApiDescription",
"tags": [
"discovery"
],
"summary": "Get this description",
"description": "This document. It is also advertised as `rel=\"service-desc\"` in the Link response header of every page, and listed in the RFC 9727 catalogue at /.well-known/api-catalog.",
"responses": {
"200": {
"description": "This OpenAPI description.",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFoundMarkdown"
}
}
}
},
"/.well-known/mcp/server-card.json": {
"get": {
"operationId": "getMcpServerCard",
"tags": [
"discovery"
],
"summary": "Get the MCP server card",
"description": "Describes the SurrealDB MCP server - transport, endpoint, and documentation - so an MCP client can connect to https://mcp.surrealdb.com without being told the URL. The server exposes SurrealDB Cloud as tools and requires a SurrealDB account or personal access token.",
"responses": {
"200": {
"description": "The MCP server card.",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFoundMarkdown"
}
}
}
},
"/.well-known/agent-card.json": {
"get": {
"operationId": "getAgentCard",
"tags": [
"discovery"
],
"summary": "Get the A2A agent card",
"description": "The Agent-to-Agent card for the SurrealDB MCP server: its skills, supported interfaces, and security schemes.",
"responses": {
"200": {
"description": "The A2A agent card.",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFoundMarkdown"
}
}
}
},
"/.well-known/ai-catalog.json": {
"get": {
"operationId": "getAiCatalog",
"tags": [
"discovery"
],
"summary": "Get the ARD capability catalogue",
"description": "The Agentic Resource Discovery catalogue: every machine-consumable resource this organisation publishes, each with a domain-anchored urn:air identifier and a media type.",
"responses": {
"200": {
"description": "The ARD catalogue.",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFoundMarkdown"
}
}
}
},
"/.well-known/agent-skills/index.json": {
"get": {
"operationId": "getAgentSkillsIndex",
"tags": [
"discovery"
],
"summary": "Get the Agent Skills index",
"description": "Lists the SurrealDB agent skills published at this origin - SurrealQL, the CLI, the JavaScript and Python SDKs, vector search, and performance - each with a URL and a SHA-256 digest so a client can verify what it installs.",
"responses": {
"200": {
"description": "The Agent Skills index.",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFoundMarkdown"
}
}
}
},
"/auth.md": {
"get": {
"operationId": "getAuthGuide",
"tags": [
"discovery"
],
"summary": "Get the agent authentication guide",
"description": "How an agent obtains and uses a SurrealDB credential: where the OAuth 2.0 endpoints live, which scopes exist, and what to do when a request comes back unauthorised.",
"responses": {
"200": {
"description": "The authentication guide, as markdown.",
"content": {
"text/markdown": {
"schema": {
"type": "string"
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFoundMarkdown"
}
}
}
},
"/{section}/{page}.md": {
"get": {
"operationId": "getSectionPageMarkdown",
"tags": [
"content"
],
"summary": "Get a nested page as markdown",
"description": "The markdown twin of a page one level down. `/why/vs-vector-databases` becomes `/why/vs-vector-databases.md`, `/blog/some-post` becomes `/blog/some-post.md`. Blog posts are served from their authored markdown source; every other page is rendered and converted. The response carries `x-markdown-tokens` and `x-original-tokens` so an agent can budget before reading.\n\nSending `Accept: text/markdown` to the page's ordinary URL returns the same document, and each page's HTML `` advertises its twin with ``.\n\nEach path segment is a separate parameter on purpose: the separating slashes are part of the URL, and a client that percent-encodes one gets a 404. There is one operation per URL depth, and four segments is the deepest this site goes.",
"parameters": [
{
"name": "section",
"in": "path",
"required": true,
"description": "The first path segment.",
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9._~@-]+$",
"examples": [
"why",
"blog",
"solutions",
"use-cases"
]
},
"example": "why"
},
{
"name": "page",
"in": "path",
"required": true,
"description": "The second path segment.",
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9._~@-]+$",
"examples": [
"vs-vector-databases"
]
},
"example": "vs-vector-databases"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/PageMarkdown"
},
"404": {
"description": "No page exists at that path. The body is a short markdown document naming the site's indexes.",
"content": {
"text/markdown": {
"schema": {
"type": "string"
}
}
}
}
}
}
},
"/{section}/{subsection}/{page}.md": {
"get": {
"operationId": "getSubsectionPageMarkdown",
"tags": [
"content"
],
"summary": "Get a three-segment page as markdown",
"description": "The markdown twin of a page three segments deep. `/legal/category/privacy` becomes `/legal/category/privacy.md`. Blog posts are served from their authored markdown source; every other page is rendered and converted. The response carries `x-markdown-tokens` and `x-original-tokens` so an agent can budget before reading.\n\nSending `Accept: text/markdown` to the page's ordinary URL returns the same document, and each page's HTML `` advertises its twin with ``.\n\nEach path segment is a separate parameter on purpose: the separating slashes are part of the URL, and a client that percent-encodes one gets a 404. There is one operation per URL depth, and four segments is the deepest this site goes.",
"parameters": [
{
"name": "section",
"in": "path",
"required": true,
"description": "The first path segment.",
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9._~@-]+$",
"examples": [
"legal",
"learn"
]
},
"example": "legal"
},
{
"name": "subsection",
"in": "path",
"required": true,
"description": "The second path segment.",
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9._~@-]+$",
"examples": [
"category",
"fundamentals"
]
},
"example": "category"
},
{
"name": "page",
"in": "path",
"required": true,
"description": "The third path segment.",
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9._~@-]+$",
"examples": [
"privacy"
]
},
"example": "privacy"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/PageMarkdown"
},
"404": {
"description": "No page exists at that path. The body is a short markdown document naming the site's indexes.",
"content": {
"text/markdown": {
"schema": {
"type": "string"
}
}
}
}
}
}
},
"/{section}/{subsection}/{subsubsection}/{page}.md": {
"get": {
"operationId": "getDeepPageMarkdown",
"tags": [
"content"
],
"summary": "Get a four-segment page as markdown",
"description": "The markdown twin of a page four segments deep, the deepest this site goes. `/learn/fundamentals/intro/surrealdb` becomes `/learn/fundamentals/intro/surrealdb.md`. Blog posts are served from their authored markdown source; every other page is rendered and converted. The response carries `x-markdown-tokens` and `x-original-tokens` so an agent can budget before reading.\n\nSending `Accept: text/markdown` to the page's ordinary URL returns the same document, and each page's HTML `` advertises its twin with ``.\n\nEach path segment is a separate parameter on purpose: the separating slashes are part of the URL, and a client that percent-encodes one gets a 404. There is one operation per URL depth, and four segments is the deepest this site goes.",
"parameters": [
{
"name": "section",
"in": "path",
"required": true,
"description": "The first path segment.",
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9._~@-]+$",
"examples": [
"learn"
]
},
"example": "learn"
},
{
"name": "subsection",
"in": "path",
"required": true,
"description": "The second path segment.",
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9._~@-]+$",
"examples": [
"fundamentals",
"book"
]
},
"example": "fundamentals"
},
{
"name": "subsubsection",
"in": "path",
"required": true,
"description": "The third path segment.",
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9._~@-]+$",
"examples": [
"intro",
"welcome"
]
},
"example": "intro"
},
{
"name": "page",
"in": "path",
"required": true,
"description": "The fourth path segment.",
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9._~@-]+$",
"examples": [
"surrealdb"
]
},
"example": "surrealdb"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/PageMarkdown"
},
"404": {
"description": "No page exists at that path. The body is a short markdown document naming the site's indexes.",
"content": {
"text/markdown": {
"schema": {
"type": "string"
}
}
}
}
}
}
}
},
"components": {
"responses": {
"PageMarkdown": {
"description": "The page as markdown.",
"headers": {
"x-markdown-tokens": {
"description": "Estimated token count of this markdown document.",
"schema": {
"type": "integer"
}
},
"x-original-tokens": {
"description": "Estimated token count of the equivalent HTML page, for comparison.",
"schema": {
"type": "integer"
}
}
},
"content": {
"text/markdown": {
"schema": {
"type": "string",
"description": "A CommonMark document beginning with a level-one heading."
}
}
}
},
"NotFound": {
"description": "No resource is served at that path.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"NotFoundMarkdown": {
"description": "The document is not served at this path. The body is a short markdown document naming the site's indexes.",
"content": {
"text/markdown": {
"schema": {
"type": "string"
}
}
}
}
},
"schemas": {
"Problem": {
"type": "object",
"description": "An RFC 9457 problem detail. Every `/api` failure uses this shape.",
"required": [
"type",
"title",
"status",
"code",
"resolution"
],
"properties": {
"type": {
"type": "string",
"format": "uri",
"description": "A URI identifying this problem type."
},
"title": {
"type": "string",
"description": "A short, human-readable summary of the problem type."
},
"status": {
"type": "integer",
"description": "The HTTP status code, repeated in the body.",
"examples": [
404
]
},
"detail": {
"type": "string",
"description": "What went wrong with this specific request."
},
"instance": {
"type": "string",
"format": "uri",
"description": "The URL that produced the problem."
},
"code": {
"type": "string",
"description": "A stable machine-readable error code. Match on this, not on the prose.",
"examples": [
"resource_not_found"
]
},
"resolution": {
"type": "string",
"description": "The next request to make, or the change to the current one, that would succeed."
},
"documentation_url": {
"type": "string",
"format": "uri",
"description": "Where the resources this origin serves are described."
}
}
},
"PricingCatalogue": {
"type": "object",
"description": "Every published SurrealDB plan, grouped by how it is run and supported.",
"properties": {
"cloud": {
"type": "array",
"description": "Managed SurrealDB Cloud tiers.",
"items": {
"$ref": "#/components/schemas/PricingPlan"
}
},
"selfHosted": {
"type": "array",
"description": "Self-hosted tiers.",
"items": {
"$ref": "#/components/schemas/PricingPlan"
}
},
"support": {
"type": "array",
"description": "Support tiers, purchased alongside a plan.",
"items": {
"$ref": "#/components/schemas/PricingPlan"
}
},
"page": {
"type": "object",
"description": "Copy used to render the pricing page itself. Not part of the commercial data.",
"additionalProperties": true
},
"calculator": {
"type": "object",
"description": "Rates and units behind the cost calculator on the pricing page.",
"additionalProperties": true
}
}
},
"PricingPlan": {
"type": "object",
"description": "One purchasable plan. Mirrors PricingConfigBase in src/lib/api/pricing.ts; the cloud tiers add `resources`, `dataset` and `surrealist`.",
"required": [
"id",
"name",
"description",
"price",
"features",
"featuresTitle",
"cta"
],
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for the plan. Match on this, not on the display name.",
"enum": [
"cloud-free",
"cloud-start",
"cloud-scale",
"self-hosted-enterprise",
"support-pro",
"support-priority",
"support-premium"
]
},
"name": {
"type": "string",
"description": "Display name.",
"examples": [
"Free"
]
},
"description": {
"type": "string",
"description": "Who the plan is for."
},
"price": {
"description": "The headline price as displayed. A string when the plan is quoted or free rather than a listed number.",
"anyOf": [
{
"type": "string"
},
{
"type": "number"
}
],
"examples": [
"Free"
]
},
"featuresTitle": {
"type": "string",
"description": "Heading introducing the feature list."
},
"features": {
"type": "array",
"description": "What the plan includes. Each entry is an object, not a string.",
"items": {
"$ref": "#/components/schemas/PricingFeature"
}
},
"plus": {
"type": "array",
"description": "What this plan adds on top of the tier below it.",
"items": {
"type": "string"
},
"examples": [
[
"Community support"
]
]
},
"resources": {
"type": "array",
"description": "Compute, memory and storage allowances, as displayed. Present on the SurrealDB Cloud tiers only.",
"items": {
"type": "string"
},
"examples": [
[
"1 GB storage",
"0.25 vCPU",
"1 GB Memory"
]
]
},
"dataset": {
"description": "The demo dataset preloaded for this tier, or null when there is none.",
"oneOf": [
{
"$ref": "#/components/schemas/PricingDataset"
},
{
"type": "null"
}
]
},
"surrealist": {
"$ref": "#/components/schemas/PricingStudioPlan"
},
"cta": {
"$ref": "#/components/schemas/PricingCta"
},
"computePrice": {
"type": "array",
"description": "Per-node compute rates available on this plan.",
"items": {
"$ref": "#/components/schemas/PricingComputeRate"
}
},
"storagePrice": {
"type": "array",
"description": "Storage rates available on this plan.",
"items": {
"$ref": "#/components/schemas/PricingUnitRate"
}
},
"transferPrice": {
"type": "array",
"description": "Data transfer rates available on this plan.",
"items": {
"$ref": "#/components/schemas/PricingUnitRate"
}
}
}
},
"PricingFeature": {
"type": "object",
"description": "One line item in a plan's feature list.",
"required": [
"name",
"comingSoon"
],
"properties": {
"name": {
"type": "string",
"description": "The feature, as displayed.",
"examples": [
"Social authentication"
]
},
"comingSoon": {
"type": "boolean",
"description": "True when the feature is announced but not yet shipped on this plan."
}
}
},
"PricingDataset": {
"type": "object",
"description": "A demo dataset preloaded on the instance.",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "Dataset identifier."
},
"version": {
"type": "string",
"description": "Dataset version, when pinned."
},
"size": {
"type": "string",
"description": "Approximate on-disk size, as displayed."
}
}
},
"PricingCta": {
"type": "object",
"description": "The action offered for this plan on the pricing page. A disabled CTA carries no href.",
"required": [
"variant",
"text"
],
"properties": {
"variant": {
"type": "string",
"enum": [
"reversed",
"gradient",
"disabled"
],
"description": "How the button is rendered."
},
"text": {
"type": "string",
"description": "Button label.",
"examples": [
"Start for free"
]
},
"href": {
"type": "string",
"format": "uri-reference",
"description": "Where the button goes. Either an absolute URL or a root-relative path to resolve against https://surrealdb.com. Absent when variant is \"disabled\".",
"examples": [
"https://studio.surrealdb.com/current/instances/deploy",
"/contact/pricing"
]
}
}
},
"PricingComputeRate": {
"type": "object",
"description": "The hourly rate for one compute node size. Mirrors PricingComputePriceEntry in src/lib/api/pricing.ts.",
"required": [
"slug",
"displayName",
"node",
"type",
"category",
"cpu",
"memory",
"compute_price"
],
"properties": {
"slug": {
"type": "string",
"description": "Stable identifier for the node size.",
"examples": [
"free"
]
},
"displayName": {
"type": "string",
"description": "Name shown in the cost calculator.",
"examples": [
"free"
]
},
"node": {
"type": "string",
"description": "Node size name as printed in the pricing table.",
"examples": [
"Free"
]
},
"type": {
"type": "string",
"enum": [
"Burstable",
"General purpose",
"Scale"
],
"description": "Node family."
},
"category": {
"type": "string",
"enum": [
"free",
"development",
"production",
"scale"
],
"description": "Which group of the cost calculator this node size belongs to."
},
"cpu": {
"type": "string",
"description": "vCPU allowance, as displayed.",
"examples": [
"0.25 vCPU"
]
},
"memory": {
"type": "string",
"description": "Memory allowance, as displayed.",
"examples": [
"1 GB memory"
]
},
"compute_price": {
"type": "string",
"description": "Price per hour, as displayed.",
"examples": [
"$0"
]
}
}
},
"PricingUnitRate": {
"type": "object",
"description": "A metered rate: the unit it is charged against, and the price.",
"properties": {
"storage": {
"type": "string",
"description": "The storage unit charged against. Present on storage rates."
},
"transfer": {
"type": "string",
"description": "The transfer unit charged against. Present on transfer rates."
},
"price": {
"type": "string",
"description": "Price for that unit, as displayed."
}
}
},
"PricingStudioPlan": {
"type": "object",
"description": "How this tier maps onto SurrealDB Studio. The JSON key is `surrealist`, the tool's former name, kept for compatibility with existing consumers.",
"required": [
"plan"
],
"properties": {
"plan": {
"type": "string",
"enum": [
"free",
"start",
"scale",
"enterprise"
],
"description": "The Studio plan this tier grants."
},
"defaultType": {
"type": "string",
"description": "The instance type Studio preselects when deploying on this tier, when it pins one.",
"examples": [
"free"
]
}
}
}
}
}
}