Developers

Ocho developer resources

Everything a developer — or an AI agent — needs to work with Ocho programmatically: the MCP server for the product itself, the public content API for this site, and the machine-readable surfaces we publish for crawlers and agents.

Ocho MCP server

The Ocho platform speaks Model Context Protocol natively, so agents like Claude and ChatGPT can operate Ocho directly — search your datasets, ask cited questions, and drive workflows — as the signed-in user.

  • Endpoint: https://mcp.ocho.bot (Streamable HTTP transport)
  • Auth: OAuth 2.1 — the server issues an OAuth challenge at initialize; sign in with your Ocho account and the tool list is returned after authorization. There is no anonymous tool access, because every tool operates on your organization’s private knowledge base.
  • Getting access: MCP access comes with every Ocho workspace. Request a demo if your team doesn’t have one yet.

Public content API

Everything published on this site — blog posts, documentation, categories, search — is readable through a REST API with no authentication. The full surface is described in the OpenAPI 3.1 spec at /openapi.json, with typed schemas, operation IDs, and descriptions on every operation, so it drops straight into LLM function-calling and codegen tooling.

# Latest blog posts
curl "https://ocho.bot/api/posts?sort=-publishedAt&limit=5"

# One post by slug
curl "https://ocho.bot/api/posts?where[slug][equals]=what-is-agentic-ingestion"

# All documentation pages
curl "https://ocho.bot/api/docs?limit=100"

GraphQL

The same content collections are queryable over GraphQL at POST /api/graphql. Introspection is enabled — type your queries against the live schema, or use the OpenAPI document for the REST shape. Conventions: errors return a typed errors array (message + locations); pagination is page-based (limit/page arguments, totalPages and hasNextPage on every result set); versioning policy: the schema evolves additively and fields are marked @deprecated for at least one release before removal (no URL versioning); all query operations are synchronous and read-only, safe to retry. Collections map to types named Posts, Docs, Pages, and Categories, each with docs-array pagination matching the REST shape. GraphQL requests are rate limited to 120 per IP per 60 seconds; every GraphQL response carries RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, and RateLimit-Policy: 120;w=60 headers, with Retry-After on a 429:

curl -X POST https://ocho.bot/api/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ Posts(limit: 5, sort: \"-publishedAt\") { docs { title slug } } }"}'

Rate limits

REST content reads have no hard per-client limit today — keep sustained traffic under 2 requests/second. POST /api/graphql is limited to 120 requests per IP per 60 seconds, and the one write endpoint, POST /api/contact, to 5 requests per IP per 60 seconds. Both advertise their state on every response with the standard rate-limit headers, so agents can self-throttle:

  • RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset — requests allowed, requests left, and seconds until the window resets
  • RateLimit-Policy: 5;w=60 — the quota policy itself
  • Retry-After — on a 429, seconds to wait before retrying

Machine-readable surfaces

Built for agents and crawlers, all public:

  • /llms.txt — product summary, when-to-use guidance for agents, and a curated link index
  • /llms-full.txt — the full documentation corpus as plain text
  • Markdown negotiation — every public page serves a Markdown variant (with YAML frontmatter) three ways: Accept: text/markdown (responses Vary: Accept), a .md URL suffix (https://ocho.bot/index.md — append .md to any page or blog-post URL), or automatically for known AI crawler User-Agents. HTML responses advertise the variant with a Link: rel="alternate" header.
  • MCP server card — /.well-known/mcp/server-card.json describes the Ocho MCP server for pre-connect discovery
  • /sitemap.xml and /blog/rss.xml — URL inventory and blog feed
  • /openapi.json — this site’s API, as OpenAPI 3.1

Questions, or building an integration? Email hello@ocho.bot — a founder reads it.

Developers | Ocho