Ellipse Gradient for Header

Sanity Integration Guide

Integrate Sanity content with enterprise applications through HTTP APIs, GROQ queries, mutations, assets, webhooks, and selected GraphQL APIs.

Sanity integration options at a glance

Sanity provides HTTP APIs for GROQ queries, document mutations, transactions, and project or dataset operations. Its asset APIs support image and file upload and retrieval, while webhooks provide selected document-change notifications with filters and projections. Sanity also offers a schema-generated GraphQL API whose availability depends on the project schema and API version. Martini can consume these endpoints, receive Sanity webhook requests through an exposed API, map JSON documents, orchestrate downstream workflows, and securely manage project-specific tokens. For larger synchronizations, Martini can combine paginated queries, checkpoint-based scheduling, deterministic mutations, and reconciliation workflows.

Integration pointSupported by Sanity?Common use casesHow Martini supports it
HTTP APIs and GROQYesQuery documents and related content, retrieve selected fields, and send document operations against a project and dataset.Martini can consume Sanity HTTP endpoints, submit GROQ queries, map JSON responses, and expose the result through a Martini API or workflow.
Document mutations and transactionsYesCreate, replace, patch, or delete documents and apply multiple mutation operations in one transaction.Martini can construct mutation payloads, apply validation and idempotency rules, and handle response errors and retries.
Webhooks / outbound callbacksYesNotify external endpoints about configured document and content changes using filters and projections.Martini can expose an API or workflow endpoint, validate the request, retrieve authoritative content, and route the event downstream.
GraphQL APIsLimitedQuery published content through a schema-generated API when the project schema and API version support the required operation.Martini can consume the GraphQL endpoint, but the workflow should verify project-specific schema, version, authentication, and operation behavior.
Listen and change notificationsLimitedMaintain a subscription-style feed for real-time document changes where a long-lived stream is operationally appropriate.Martini can support an HTTP-based implementation where the runtime and workflow design suit a long-lived stream; webhooks are often simpler for enterprise delivery.
Image and file asset APIsYesUpload, retrieve, or download image and file assets referenced by Sanity documents.Martini can retrieve asset references, copy or transform files, and preserve document-to-asset relationships in downstream systems.
Bulk and transactional operationsLimitedGroup multiple document mutations in transactions; this is not a general-purpose bulk export or asynchronous job API.Martini can batch carefully scoped mutation requests and apply deterministic identifiers, partial-failure handling, and reconciliation logic.
AuthenticationYesAuthenticate server-to-server API requests with project- and dataset-scoped API tokens and permissions.Martini stores tokens in protected secrets or environment configuration and applies them to API requests without embedding credentials in mappings.

How Sanity exposes data and business events

Sanity HTTP APIs and GROQ

Sanity's HTTP APIs provide GROQ queries, document mutations, transactions, and asset operations scoped to a project and dataset. GROQ projections can limit responses to fields required by an integration.

Martini implementation pattern

Martini implementation pattern: a workflow calls the appropriate Sanity endpoint with environment-specific project, dataset, API version, and token settings. It parses the JSON response, applies mappings and business rules, and writes to or exposes the target system.

Implementation sequence

Build a scoped GROQ query or mutation request
Call the Sanity HTTP API with a protected bearer token
Validate and transform the JSON response
Apply document-state and idempotency rules
Write the result to the target system
Store checkpoints and handle failures

Sanity Webhooks

Sanity webhooks notify configured external endpoints about selected document and content changes. Filters and projections can restrict the notification, but coverage depends on configuration and supported events.

Martini implementation pattern

Martini implementation pattern: an exposed Martini API receives and validates the webhook, then retrieves the authoritative document when the notification is incomplete. The workflow applies publication rules, enriches related content, and routes the result to one or more downstream systems.

Implementation sequence

Receive the Sanity webhook notification
Validate the request and configured security controls
Check dataset, document type, and document state
Retrieve the current document with GROQ
Map and route the content
Record the event key and outcome

Sanity GraphQL API

Sanity provides a schema-generated GraphQL API for projects where the required schema and API version support the operation. Availability and behavior are project-specific, so GROQ remains the usual primary mechanism.

Martini implementation pattern

Martini implementation pattern: Martini consumes the configured GraphQL endpoint when a consuming application requires GraphQL-shaped queries. The workflow validates the schema assumptions, transforms the response, and applies the same checkpoint, retry, and monitoring controls used for HTTP API integrations.

Implementation sequence

Confirm the project GraphQL schema and API version
Configure the endpoint and protected authentication
Execute the required GraphQL query
Validate the response and map fields
Apply business rules and write the target result
Log errors and retry safe operations

Sanity Asset APIs

Sanity provides image and file asset upload and retrieval APIs. Documents typically contain references to asset documents rather than embedded binary content.

Martini implementation pattern

Martini implementation pattern: a workflow retrieves the source document, resolves referenced assets, and either preserves URLs or downloads, transforms, and uploads physical files to the destination. The workflow maintains the relationship between document fields and transferred assets.

Implementation sequence

Retrieve the source document and asset references
Determine destination asset ownership and format
Download or upload the required asset
Map asset metadata and destination references
Update the related document or target record
Handle access, size, and transfer failures

Common Sanity integration patterns

Pattern 1: Publish Sanity content to a website

When to use this pattern

Use this pattern when published articles, pages, or products must trigger a website rebuild, revalidation, or content-delivery operation. It avoids trusting a minimal notification payload as the complete source document.

Integration direction
Sanity
Martini
Next.js
Example Mapping
Sanity FieldCanonical FieldTarget Field
_idsourceDocumentIdcontentId
titletitlepageTitle
bodycontentBodyrenderedContent
mainImage.assetheroAssetReferenceheroImage
Martini implementation pattern

A Martini API receives the selected webhook, verifies the request, checks whether the document is published, and retrieves the current document with a scoped GROQ projection. It resolves assets, maps the content model, calls the website or deployment API, and uses the document ID plus revision as an idempotency key. Failures are retried only when safe and sent for operator review when retries are exhausted.

Martini capabilities used
  • workflows
  • API consumption
  • API exposure
  • data mapping
  • business rules
  • error handling

Pattern 2: Sync Sanity products to Shopify

When to use this pattern

Use this pattern when Sanity owns enriched product descriptions, merchandising content, or media while Shopify owns commerce catalog operations. Webhooks provide near-real-time updates, with scheduled reconciliation for missed events.

Integration direction
Sanity
Martini
Shopify
Example Mapping
Sanity FieldCanonical FieldTarget Field
_idsourceProductIdexternalId
titleproductTitletitle
descriptionproductDescriptionbodyHtml
image.assetproductImageimages
Martini implementation pattern

Martini receives or schedules product synchronization, queries the required document fields, resolves image and file assets, and maps Sanity values into Shopify's product model. Validation rejects incomplete products, while deterministic external IDs make updates idempotent. A checkpoint and periodic reconciliation workflow detect missed changes and retry transient Shopify or Sanity failures.

Martini capabilities used
  • scheduled workflows
  • webhook triggers
  • API consumption
  • asset handling
  • data mapping
  • reconciliation
  • error handling

Pattern 3: Index Sanity changes in Algolia

When to use this pattern

Use this pattern when selected Sanity document types must become searchable records after publication or content changes. It is useful for routing one content source to a dedicated search index with normalized fields.

Integration direction
Sanity
Martini
Algolia
Example Mapping
Sanity FieldCanonical FieldTarget Field
_idsearchObjectIdobjectID
titlesearchTitletitle
descriptionsearchDescriptiondescription
_typecontentTypecontentType
Martini implementation pattern

A webhook-triggered Martini workflow filters eligible document types and states, retrieves a projected document, normalizes text and asset URLs, and upserts the result to Algolia. Delete or unpublish events are mapped to removals where applicable. The workflow records source IDs and revisions, retries safe indexing operations, and sends malformed documents to an operator queue or review path.

Martini capabilities used
  • webhook triggers
  • GROQ API consumption
  • data mapping
  • conditional routing
  • business rules
  • monitoring

Pattern 4: Load approved business data into Sanity

When to use this pattern

Use this pattern when an ERP, CRM, or product information system is the authoritative source for selected profiles, products, locations, or reference content that must be published in Sanity.

Integration direction
Salesforce
Martini
Sanity
Example Mapping
Sanity FieldCanonical FieldTarget Field
IdsourceSystemIdsourceSystemId
NamedisplayNametitle
DescriptioncontentDescriptiondescription
StatuspublicationStatusworkflowStatus
Martini implementation pattern

Martini retrieves approved source data, validates required fields, maps the source model to a Sanity document type, and sends deterministic create or patch mutations. Rules prevent unapproved or incomplete data from being published, while stable document IDs avoid duplicates. Transaction responses, mutation failures, and reconciliation results are logged with the source identifier and dataset.

Martini capabilities used
  • API consumption
  • document mutations
  • data mapping
  • validation
  • business rules
  • idempotent upserts
  • error handling

Applications commonly integrated with Sanity

Sanity is commonly used as a content source or editorial system alongside web delivery, commerce, search, business, and workflow applications. Martini can mediate these integrations when content requires validation, enrichment, transformation, routing, or reliable synchronization.

Application Scenario Direction Martini Pattern
Next.js Next.js applications consume Sanity content for server-rendered pages, previews, and websites. Martini can enrich or route content before delivery when enterprise rules are required. Sanity → Martini → Next.js Receive a selected Sanity webhook, retrieve the authoritative document with GROQ, resolve relevant assets, map the content model, and call the application or deployment API with controlled retries.
Vercel Sanity content changes can initiate revalidation, rebuild, or deployment-related actions for applications hosted on Vercel. Sanity → Martini → Vercel Expose a Martini API for Sanity notifications, validate the document state, apply publication rules, and invoke the appropriate Vercel API operation while recording the document ID and revision.
Netlify Published Sanity content can trigger a build hook or deployment action for a Netlify-hosted site. Sanity → Martini → Netlify Use a webhook-driven workflow to distinguish publication from draft changes, optionally query related documents, and call the Netlify build or deployment endpoint with idempotent event handling.
Shopify Sanity can manage enriched product content and media while Shopify manages commerce catalog and transaction operations. Sanity → Martini → Shopify Run a webhook or scheduled workflow that queries product documents, resolves image and file assets, maps fields to Shopify, and updates products using stable external identifiers and retry-safe rules.
Algolia Sanity document changes can be transformed into search records and sent to Algolia for indexing. Sanity → Martini → Algolia Filter relevant document changes, retrieve projected content, normalize searchable fields and asset URLs, then upsert or remove Algolia records while preserving the Sanity document ID.
Jira Editorial or content changes may require review, localization, remediation, or follow-up work managed in Jira. Sanity → Martini → Jira Route qualifying Sanity document events to Jira after applying workflow-field rules, create or update issues using a deterministic key, and optionally synchronize status information back to Sanity.

How to build a Sanity integration in Martini

Objective

Configure the Sanity project, dataset, API version, endpoint paths, and authentication details for each environment.

Instructions in Martini

  • Identify the required Sanity project and dataset
  • Store the API token in protected Martini secrets or environment configuration
  • Configure the HTTP or GraphQL endpoint appropriate to the workflow
  • Confirm the minimum project and dataset permissions

Objective

Select a webhook, scheduled workflow, API invocation, or other supported trigger based on latency and recovery requirements.

Instructions in Martini

  • Use a Sanity webhook for selected near-real-time content changes
  • Use a scheduler for reconciliation or checkpoint-based synchronization
  • Use an exposed Martini API when another application initiates the process
  • Define how drafts, published documents, unpublishing, and deletes are handled

Objective

Retrieve the authoritative Sanity documents, references, and assets required by the integration rather than relying on an incomplete notification.

Instructions in Martini

  • Create a narrow GROQ projection for required fields
  • Use stable ordering and boundaries for large result sets
  • Resolve related documents and asset references deliberately
  • Capture project, dataset, document ID, and revision context

Objective

Implement the Martini workflow that validates input, coordinates Sanity calls, applies routing, and invokes downstream APIs.

Instructions in Martini

  • Validate webhook structure and request security
  • Branch by document type, state, or business status
  • Enrich events by querying related documents when necessary
  • Call downstream systems in a controlled sequence

Objective

Transform Sanity JSON-like documents and assets into the target application's model while accommodating schema variation.

Instructions in Martini

  • Map document fields to a canonical or target model
  • Handle optional fields, references, arrays, and changing schemas
  • Choose whether to preserve, transform, or copy asset URLs
  • Apply format, naming, and content validation rules

Objective

Create, update, remove, or publish data in the target system or Sanity using safe and deterministic operations.

Instructions in Martini

  • Use stable source identifiers for target updates
  • Use deterministic Sanity document IDs for inbound mutations
  • Batch related mutations only when transaction behavior is understood
  • Avoid retrying non-idempotent operations without an idempotency strategy

Common Sanity data objects used in integrations

ObjectTypical UseCommon target systemsMartini handling
DocumentsJSON-like content objects representing articles, products, pages, settings, or other editorial data.Next.js, Shopify, Algolia, Netlify, Vercel, and business applicationsMartini queries projected documents with GROQ, validates and transforms fields, tracks document IDs and revisions, and routes the result to target APIs.
Document typesSchema-defined types such as articles, products, authors, pages, and settings.Websites, commerce platforms, search indexes, and downstream content systemsMartini uses the type and schema fields to select mappings, apply type-specific business rules, and tolerate optional or evolving fields.
DatasetsNamed content environments for production, staging, or development.Deployment platforms, test environments, and reconciliation storesMartini keeps project, dataset, API version, and credentials environment-specific and includes dataset context in checkpoints and idempotency keys.
ProjectsContainers for datasets, schemas, API configuration, members, and project settings.Configuration management and operational monitoring systemsMartini treats project identifiers and permissions as protected configuration and records project context in workflow logs.
Image assetsImages referenced by document image fields and asset documents.Next.js, Shopify, Netlify, Vercel, and search servicesMartini can retrieve, copy, transform, or preserve asset URLs according to the destination's ownership and access requirements.
File assetsNon-image files referenced by document file fields and asset documents.Websites, document repositories, commerce platforms, and business applicationsMartini downloads or uploads files through Sanity asset APIs, maps metadata, and maintains the relationship between the destination object and source document.

Authentication and security considerations

Token and project security

Sanity normally uses project- and dataset-scoped API tokens for server-to-server queries and mutations. Martini should store tokens, project identifiers, datasets, API versions, and any webhook verification configuration in protected secrets or environment-specific configuration.

Least privilege and request validation

  • Grant only the permissions required by each workflow.
  • Restrict datasets and document operations by integration purpose.
  • Validate webhook methods, payload structure, dataset, and document state before processing.
  • Do not assume OAuth is the normal authentication method for Sanity content APIs.

Browser and delivery considerations

Public-read datasets and CORS settings may be appropriate for selected delivery scenarios, but server-side Martini workflows should use authenticated access where content is private or mutations are required.

Operational considerations for Sanity integrations

Pagination and checkpoints

Paginate or partition large GROQ result sets with stable ordering. Store a checkpoint based on document IDs, update metadata, revisions, or another source marker, and run scheduled reconciliation to recover missed webhook deliveries.

Idempotency and retries

Use dataset, document ID, document state, and revision or update markers to construct idempotency keys. Apply controlled backoff for transient HTTP failures and avoid retrying non-idempotent mutations without deterministic IDs or conditional logic.

Schema and state changes

Sanity schemas can evolve from scalar values to references, arrays, or optional fields. Validate required values and define handling for drafts, publication, unpublishing, deletes, and archived content. Pin the API version and test changes before deployment.

Assets and monitoring

Decide whether downstream systems retain Sanity asset URLs or require copied files. Log the project, dataset, document ID, operation, revision, asset, and destination identifier so failed records can be replayed without duplicating successful updates.

Why use Martini instead of scripts or point-to-point integrations?

Centralized orchestration

Martini coordinates Sanity queries, webhooks, mutations, asset operations, and downstream APIs in an explicit workflow rather than scattering logic across scripts or point-to-point calls.

Reusable transformation and rules

Mappings, validation, document-state rules, enrichment, routing, and idempotency behavior can be reused across publishing, commerce, search, and business-system integrations.

Operational control

  • Use protected environment configuration for project, dataset, API version, and tokens.
  • Support event-driven processing together with scheduled reconciliation.
  • Apply controlled retries and error handling around API and mutation operations.
  • Expose governed APIs when consumers should not access Sanity directly.

Maintainable integration assets

Martini provides a developer-oriented low-code environment for mapping, workflow orchestration, API consumption, API exposure, monitoring, and custom logic when a Sanity integration requires behavior beyond standard HTTP requests.

Frequently asked questions

How can Sanity be integrated with enterprise systems?

Sanity can integrate through its HTTP APIs, GROQ query and mutation endpoints, transactions, image and file asset APIs, configured webhooks, and selected schema-generated GraphQL APIs. Enterprise workflows commonly use webhooks for selected content changes, scheduled queries for reconciliation, and API mutations for controlled updates.

Can Martini integrate with Sanity?

Yes. Martini can consume Sanity HTTP and supported GraphQL APIs, send GROQ queries and mutations, receive Sanity webhook requests through an exposed API or workflow endpoint, and orchestrate document and asset synchronization with downstream systems.

Do I need a connector to integrate Sanity with Martini?

No. A dedicated Sanity connector is not required. Martini can use Sanity's native HTTP APIs, GROQ, mutation endpoints, asset APIs, supported GraphQL endpoints, webhooks, and API-token authentication.

Is there any extra Lonti cost to integrate Sanity with Martini?

Lonti does not charge an additional per-connector or per-vendor fee to integrate Sanity. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Sanity, cloud infrastructure, or other third-party systems based on subscription, usage, and deployment model.

Which Sanity integration method should an enterprise use?

Sanity's HTTP APIs and GROQ are generally the primary choice for document queries, mutations, transactions, and assets. Webhooks are useful for selected content changes, while GraphQL is appropriate when the project exposes the required schema and the consuming design benefits from GraphQL. The listen mechanism should be selected only when a long-lived change stream is operationally suitable.

Can Martini receive Sanity webhook events?

Yes. Martini can expose an API or workflow endpoint for Sanity webhook requests. Because webhook coverage depends on configuration, dataset, filters, projections, and supported events, the workflow should validate the notification and usually retrieve the authoritative document before processing it.

How does synchronization handle drafts, revisions, and duplicate events?

The integration should explicitly define whether it processes drafts, published documents, or both. Sanity document IDs, dataset context, revision or update markers, and Martini-managed checkpoints can identify processed changes. Deterministic identifiers and idempotent target updates help prevent duplicate results during webhook delivery or retries.

Can Martini expose an API façade for Sanity?

Yes. Martini can expose a controlled REST API that applies authentication, validation, business rules, and response shaping before calling Sanity. This can provide downstream applications with a stable enterprise-facing contract while keeping Sanity project, dataset, query, and token details behind the workflow.

Related Martini documentation

APIs

Workflows

Security

Data

Operations

Integrate Sanity with Martini

Connect Sanity content, assets, and change notifications to enterprise systems through governed APIs and reliable Martini workflows.

EXPLORE MARTINI
BOOK A DEMO