{ "openapi": "3.1.0", "info": { "title": "BookVisit public content API", "version": "1.2.1", "summary": "Read-only JSON access to the public content of bookvisit.com.", "description": "Read-only access to the public content of bookvisit.com: products, solutions, contact routes, pages, customer stories and articles, in English, Swedish, Norwegian, Danish, Finnish and Icelandic. No key, token or account is needed, and there are no write operations, so Idempotency-Key does not apply.\n\nRate limit: 300 requests per 60 seconds, shared by all clients. Every response carries the IETF RateLimit-Policy and RateLimit headers (plus RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset for older clients). A 429 response carries Retry-After.\n\nErrors: every 4xx and 5xx response is an RFC 9457 problem details document (application/problem+json) with a stable code, a human-readable detail and a resolution hint.\n\nVersioning and deprecation: The major version is part of the path (/api/v1). Fields may be added within v1. Breaking changes get a new path (/api/v2). A version that is going to be removed is announced first with Deprecation and Sunset response headers (RFC 9745, RFC 8594).\n\nSeparate from this API, the BookVisit help centre runs an MCP server at https://help.bookvisit.com/mcp. It is hosted by Zendesk and protected by OAuth 2.0; the operation callHelpCentreMcp and the helpCentreOAuth security scheme below describe it with the scopes that its authorization server publishes.", "contact": { "name": "BookVisit", "url": "https://bookvisit.com/contact-and-support/" } }, "externalDocs": { "description": "Instructions for AI agents", "url": "https://bookvisit.com/agents.md" }, "x-api-lifecycle": { "current_major_version": "v1", "status": "active", "breaking_changes": "new major version in the path (/api/v2)", "deprecation_headers": [ "Deprecation (RFC 9745)", "Sunset (RFC 8594)" ], "deprecation_policy_url": "https://bookvisit.com/agents.md#rate-limits-and-versions" }, "servers": [ { "url": "https://bookvisit.com/api/v1", "description": "Production" } ], "tags": [ { "name": "Discovery", "description": "Index and documentation of the API." }, { "name": "Company", "description": "Products, solutions and contact routes." }, { "name": "Content", "description": "Published pages, customer stories and articles." }, { "name": "Help centre", "description": "The help centre MCP server, hosted by Zendesk (OAuth 2.0)." } ], "paths": { "/": { "get": { "operationId": "getApiIndex", "summary": "Get the API index", "description": "Returns the endpoints, supported languages, pagination rules, rate limit, error format and documentation links.", "tags": [ "Discovery" ], "security": [], "responses": { "200": { "description": "The API index.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiIndex" } } } }, "405": { "description": "Only GET, HEAD and OPTIONS are allowed.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "The shared rate limit is exhausted.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected error.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/products": { "get": { "operationId": "listProducts", "summary": "List BookVisit products", "description": "Returns every BookVisit product with a short description and the address of its page on bookvisit.com.", "tags": [ "Company" ], "security": [], "responses": { "200": { "description": "The products.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductList" } } } }, "405": { "description": "Only GET, HEAD and OPTIONS are allowed.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "The shared rate limit is exhausted.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected error.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/solutions": { "get": { "operationId": "listSolutions", "summary": "List solutions by type of business", "description": "Returns the BookVisit solutions for each type of accommodation business, with a short description and page address.", "tags": [ "Company" ], "security": [], "responses": { "200": { "description": "The solutions.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolutionList" } } } }, "405": { "description": "Only GET, HEAD and OPTIONS are allowed.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "The shared rate limit is exhausted.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected error.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/contact": { "get": { "operationId": "getContact", "summary": "Get public contact routes", "description": "Returns the sales and support contact routes, the demo page, the pricing page and the headquarters address. Use these instead of submitting forms for a user.", "tags": [ "Company" ], "security": [], "responses": { "200": { "description": "The contact routes.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "405": { "description": "Only GET, HEAD and OPTIONS are allowed.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "The shared rate limit is exhausted.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected error.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/pages": { "get": { "operationId": "listPages", "summary": "List published pages", "description": "Returns published, indexable pages in the requested language, ordered by menu order and title.", "tags": [ "Content" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/lang" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" } ], "responses": { "200": { "description": "A page of results with pagination details.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/Link" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentList" } } } }, "400": { "description": "A query parameter is invalid.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Only GET, HEAD and OPTIONS are allowed.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "The shared rate limit is exhausted.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected error.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/pages/{id}": { "get": { "operationId": "getPage", "summary": "Get one page", "description": "Returns one published page by ID, with its content converted to Markdown.", "tags": [ "Content" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "The item, including its content as Markdown.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentItem" } } } }, "404": { "description": "The item or route does not exist.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Only GET, HEAD and OPTIONS are allowed.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "The shared rate limit is exhausted.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected error.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/case-studies": { "get": { "operationId": "listCaseStudies", "summary": "List customer stories", "description": "Returns published customer stories in the requested language, newest first, with their categories.", "tags": [ "Content" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/lang" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" } ], "responses": { "200": { "description": "A page of results with pagination details.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/Link" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentList" } } } }, "400": { "description": "A query parameter is invalid.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Only GET, HEAD and OPTIONS are allowed.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "The shared rate limit is exhausted.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected error.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/case-studies/{id}": { "get": { "operationId": "getCaseStudy", "summary": "Get one customer story", "description": "Returns one customer story by ID, with its content converted to Markdown.", "tags": [ "Content" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "The item, including its content as Markdown.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentItem" } } } }, "404": { "description": "The item or route does not exist.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Only GET, HEAD and OPTIONS are allowed.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "The shared rate limit is exhausted.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected error.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/articles": { "get": { "operationId": "listArticles", "summary": "List articles", "description": "Returns published news and insight articles in the requested language, newest first.", "tags": [ "Content" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/lang" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" } ], "responses": { "200": { "description": "A page of results with pagination details.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/Link" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentList" } } } }, "400": { "description": "A query parameter is invalid.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Only GET, HEAD and OPTIONS are allowed.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "The shared rate limit is exhausted.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected error.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/articles/{id}": { "get": { "operationId": "getArticle", "summary": "Get one article", "description": "Returns one article by ID, with its content converted to Markdown.", "tags": [ "Content" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "The item, including its content as Markdown.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentItem" } } } }, "404": { "description": "The item or route does not exist.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Only GET, HEAD and OPTIONS are allowed.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "The shared rate limit is exhausted.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected error.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/mcp": { "servers": [ { "url": "https://help.bookvisit.com", "description": "BookVisit help centre, hosted by Zendesk" } ], "post": { "operationId": "callHelpCentreMcp", "summary": "Call the help centre MCP server", "description": "Sends a JSON-RPC 2.0 message to the BookVisit help centre MCP server (Streamable HTTP transport). The server is hosted by Zendesk and needs an OAuth 2.0 access token; see https://bookvisit.com/auth.md. Protected resource metadata: https://help.bookvisit.com/.well-known/oauth-protected-resource/mcp.", "tags": [ "Help centre" ], "security": [ { "helpCentreOAuth": [ "read" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcRequest" } } } }, "responses": { "200": { "description": "A JSON-RPC 2.0 response. The server may also stream responses as text/event-stream.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } } } }, "401": { "description": "Missing or invalid access token. Obtain a token through the help centre authorization server. The body is Zendesk's own JSON error format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HelpCentreError" } } } } } } } }, "components": { "securitySchemes": { "helpCentreOAuth": { "type": "oauth2", "description": "OAuth 2.0 for the BookVisit help centre MCP server, hosted by Zendesk. Authorization code flow with PKCE (S256). Authorization server metadata: https://help.bookvisit.com/.well-known/oauth-authorization-server/mcp/oauth. The public content API needs no authentication.", "flows": { "authorizationCode": { "authorizationUrl": "https://help.bookvisit.com/oauth/authorizations/new", "tokenUrl": "https://help.bookvisit.com/oauth/tokens", "refreshUrl": "https://help.bookvisit.com/oauth/tokens", "scopes": { "read": "Read access, as published by the help centre authorization server.", "write": "Write access, as published by the help centre authorization server." } } } } }, "parameters": { "lang": { "name": "lang", "in": "query", "required": false, "description": "Language of the content. Defaults to en.", "schema": { "type": "string", "enum": [ "en", "sv", "no", "da", "fi", "is" ], "default": "en" } }, "page": { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1 } }, "per_page": { "name": "per_page", "in": "query", "required": false, "description": "Items per page, from 1 to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, "id": { "name": "id", "in": "path", "required": true, "description": "Numeric ID of the item, as returned by the list endpoint.", "schema": { "type": "integer", "minimum": 1 } } }, "headers": { "RateLimit-Policy": { "description": "IETF RateLimit-Policy structured field, for example \"shared\";q=300;w=60.", "schema": { "type": "string" } }, "RateLimit": { "description": "IETF RateLimit structured field with the remaining quota and seconds to reset, for example \"shared\";r=299;t=42.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Requests allowed in the current window (compatibility header).", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window (compatibility header).", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window resets (compatibility header).", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "API-Version": { "description": "Version of the API that served the response.", "schema": { "type": "string" } }, "Link": { "description": "RFC 8288 links, including next and prev for pagination.", "schema": { "type": "string" } }, "Deprecation": { "description": "RFC 9745 Deprecation header. Sent only after this API version has been deprecated; v1 is not deprecated, so it is not sent today.", "schema": { "type": "string" } }, "Sunset": { "description": "RFC 8594 Sunset header: the HTTP date after which a deprecated version stops answering. Sent only together with Deprecation; not sent today.", "schema": { "type": "string" } } }, "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details.", "required": [ "type", "title", "status", "detail", "code", "resolution" ], "properties": { "type": { "type": "string", "format": "uri", "description": "Documentation of the problem type." }, "title": { "type": "string", "description": "Short summary of the problem." }, "status": { "type": "integer", "description": "HTTP status code." }, "detail": { "type": "string", "description": "What went wrong in this request." }, "instance": { "type": "string", "description": "Path of the request." }, "code": { "type": "string", "description": "Stable machine-readable error code.", "enum": [ "invalid_parameter", "not_found", "api_route_not_found", "method_not_allowed", "rate_limit_exceeded", "internal_error" ] }, "resolution": { "type": "string", "description": "How to fix the request." }, "documentation_url": { "type": "string", "format": "uri" } } }, "Endpoint": { "type": "object", "required": [ "method", "path", "operation_id", "description" ], "properties": { "method": { "type": "string" }, "path": { "type": "string" }, "operation_id": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string", "format": "uri" } } }, "ApiIndex": { "type": "object", "required": [ "name", "version", "read_only", "endpoints" ], "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "description": { "type": "string" }, "read_only": { "type": "boolean" }, "authentication": { "type": "string" }, "documentation": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } }, "languages": { "type": "array", "items": { "type": "string" } }, "default_language": { "type": "string" }, "pagination": { "type": "object" }, "rate_limit": { "type": "object" }, "errors": { "type": "object" }, "versioning": { "type": "string" }, "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/Endpoint" } } } }, "Product": { "type": "object", "required": [ "id", "name", "url", "description" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string" } } }, "ProductList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } } }, "Solution": { "type": "object", "required": [ "id", "name", "url", "description" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string" } } }, "SolutionList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Solution" } } } }, "Address": { "type": "object", "properties": { "street_address": { "type": "string" }, "postal_code": { "type": "string" }, "locality": { "type": "string" }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2" } } }, "Contact": { "type": "object", "required": [ "company", "sales", "support", "contact_page" ], "properties": { "company": { "type": "string" }, "parent_organisation": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" } } }, "sales": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "demo_url": { "type": "string", "format": "uri" } } }, "support": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "phone": { "type": "string" } } }, "contact_page": { "type": "string", "format": "uri" }, "pricing_page": { "type": "string", "format": "uri" }, "pricing_summary": { "type": "string" }, "headquarters": { "$ref": "#/components/schemas/Address" }, "note": { "type": "string" } } }, "ContentSummary": { "type": "object", "required": [ "id", "type", "title", "url", "language" ], "properties": { "id": { "type": "integer" }, "type": { "type": "string", "enum": [ "page", "case_study", "article" ] }, "title": { "type": "string" }, "url": { "type": "string", "format": "uri", "description": "Canonical page address." }, "markdown_url": { "type": [ "string", "null" ], "format": "uri", "description": "Markdown version of the page." }, "api_url": { "type": "string", "format": "uri" }, "language": { "type": "string" }, "description": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "published": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } }, "ContentItem": { "allOf": [ { "$ref": "#/components/schemas/ContentSummary" }, { "type": "object", "required": [ "content_markdown" ], "properties": { "content_markdown": { "type": "string", "description": "Page content converted to Markdown." } } } ] }, "Pagination": { "type": "object", "required": [ "page", "per_page", "total", "total_pages" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" }, "next": { "type": [ "string", "null" ], "format": "uri" }, "prev": { "type": [ "string", "null" ], "format": "uri" } } }, "ContentList": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContentSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "HelpCentreError": { "type": "object", "description": "Error body returned by the Zendesk-hosted help centre MCP server.", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "title": { "type": "string" } } } }, "txn": { "type": "string", "description": "Zendesk transaction ID." } } }, "JsonRpcRequest": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "id": { "type": [ "string", "integer" ] }, "method": { "type": "string", "description": "For example initialize, tools/list or tools/call." }, "params": { "type": "object" } } }, "JsonRpcResponse": { "type": "object", "required": [ "jsonrpc" ], "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "id": { "type": [ "string", "integer", "null" ] }, "result": { "type": "object" }, "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "data": [] } } } } } } }