Sanity

Content reads: GET to /v{version}/data/query/{dataset}?query={GROQ} — the entire read API is one endpoint with GROQ queries. GROQ enables filtering (*[_type == 'post' && published]), projections ({title, slug, author->name}), ordering, slicing, and graph traversal. Content writes: POST to /v{version}/data/mutate/{dataset} with transaction array of create/createOrReplace/createIfNotExists/patch/delete operations. Mutations are transactional — all operations in a request succeed or fail together. Asset management: upload images and files via /assets/images/ or /assets/files/. Real-time listener: GET /v{version}/data/listen/{dataset}?query={GROQ} returns SSE stream of matching document changes. The GROQ-based read API is more flexible than REST resource endpoints but requires learning the query syntax. Mutations provide atomic multi-document operations.

API errors return JSON with error, message, and statusCode. GROQ syntax errors return descriptive parse error messages. Mutation errors include per-operation error details within the transaction response. Rate limits: generous for reads (CDN handles caching), stricter for writes (varies by plan — free tier: 25 req/s writes). Real-time listener connections have per-project limits. The transactional mutation model means partial failures don't occur — the entire transaction succeeds or fails. Content history tracks document revisions. The CDN caches read responses with configurable TTL. The main consideration for agents: GROQ query performance depends on query complexity and dataset size. Unoptimized queries on large datasets can be slow. The GROQ specification provides optimization guidance.

Sanity treats content as structured data in a 'Content Lake' — a real-time, collaborative content database. For agents, the key differentiator is GROQ (Graph-Relational Object Queries), a query language purpose-built for content that enables complex filtering, projections, and joins across content types. The HTTP API provides content reads (GROQ queries), writes (mutations), and asset management. Real-time listeners enable agents to subscribe to content changes via Server-Sent Events. The content model uses schemas defined in JavaScript/TypeScript — agents can query any schema structure. Sanity Studio (the editing UI) is fully customizable in React, enabling custom editorial workflows. For agents managing complex content structures — multi-reference documents, deeply nested content, conditional fields — Sanity's flexibility is stronger than Contentful's. The trade-off: GROQ has a learning curve.

API tokens are created per-project with configurable permissions: read (viewer), read + write (editor), and deploy studio. Tokens are passed via Authorization: Bearer header. No fine-grained field-level or document-level permissions on tokens. The CDN API endpoint (apicdn.sanity.io) allows unauthenticated reads for published content with a project-specific hostname. For agents, creating a write token for content management and using the CDN endpoint for public reads provides clean separation. OAuth is not available for third-party integrations. Tokens don't expire. The auth model is simple — appropriate for a content API. For agents needing granular access control, document-level permissions require the enterprise plan.

Documentation at sanity.io/docs is well-organized with API reference, GROQ documentation, Studio customization guides, and tutorials. The GROQ documentation includes a comprehensive language reference, cheat sheet, and interactive playground (GROQ Arcade). The HTTP API documentation covers queries, mutations, listeners, and assets with examples. SDK documentation for JavaScript (@sanity/client) covers all API operations with TypeScript types. The Studio customization documentation enables building custom editorial workflows. Community is active on Slack and GitHub. The documentation's challenge: learning GROQ is a prerequisite to effective Sanity use — the GROQ documentation is good but represents a learning investment. For agents, the GROQ cheat sheet and @sanity/client quick start are the essential starting points.