Sanity logosanity.ioAll Systems Operational© Sanity 2026
Change Site Theme
Sanity logo

Documentation

    • Overview
    • Platform introduction
    • Next.js quickstart
    • Nuxt.js quickstart
    • Astro quickstart
    • React Router quickstart
    • Studio quickstart
    • Build with AI
    • Content Lake
    • Functions
    • APIs and SDKs
    • Visual Editing
    • Blueprints
    • Platform management
    • Dashboard
    • Studio
    • Canvas
    • Media Library
    • App SDK
    • Content Agent
    • HTTP API
    • CLI
    • Libraries
    • Specifications
    • Changelog
    • User guides
    • Developer guides
    • Courses and certifications
    • Join the community
    • Templates

On this page

HTTP API Reference
Overview

  • Content Lake API

    Actions
    Assets
    Copy
    Backups
    Doc
    Export
    History
    Jobs
    Listen
    Live
    Mutation
    Query
    Scheduling
    Webhooks

  • Compute and AI

    Agent Actions
    Embeddings Index

  • Apps

    Media Library

  • Management API

    Access
    Projects
    Roles

On this page

  • Authentication
  • Rate / API limits
  • Status and error codes
  • Publishing rules
  • Specifying dates
  • Schedules and your dataset
  • Other caveats
Endpoints
  • Publish documents
  • Unpublish documents
  • List schedules
  • Create schedule
  • Get schedule by ID
  • Update schedule
  • Run schedule
HTTP API ReferenceLast updated January 9, 2026

Scheduling API reference

  • Article
  • Changelog

Reference documentation for the Scheduling HTTP endpoints.

The Scheduling API allows you to schedule documents using the legacy scheduling feature.

This API is deprecated

The Scheduling API was officially deprecated with the release of Scheduled Drafts. We suggest using Scheduled Drafts alongside the Actions API, or moving to Content Releases.

Authentication

  • All requests must be authenticated.

Rate / API limits

  • The Scheduling API has the following limits:
  • 100 requests per minute per project.
  • 1000 requests per hour per project.

Status and error codes

The API uses standard HTTP status codes:

  • 200: Success
  • 400: Bad Request
  • 401: Unauthorized
  • 403: Forbidden
  • 404: Not Found
  • 429: Too Many Requests

Publishing rules

  • Documents must exist in the dataset
  • Documents must be valid according to their schema
  • Documents must not be locked by another user

Specifying dates

All dates must be in UTC format with a Z suffix, corresponding to the UTC+00:00 time zone.

Format: `YYYY-MM-DDTHH:mm:ss.sssZ`

Example: `2077-12-25T07:45:00.000Z`

Schedules and your dataset

  • Schedules are created in a specific dataset.
  • Schedules can only publish/unpublish documents in that dataset.
  • Schedules can be filtered by dataset.
  • Schedules can be cancelled before they execute.

Other caveats

  • Only schedules with a `scheduled` state can be marked as cancelled.
  • It's not possible to cancel already completed schedules.
  • A schedule cannot have its state changed once in a cancelled state.
  • Multiple schedule IDs can be specified as a comma-separated list when running schedules.

Note: While you can use the HTTP API endpoint directly, we recommend using a client library if you can.

Base API server URL

Sanity API base URL

https://{projectId}.api.sanity.io/{apiVersion}

Variables

  • projectIdstringdefault: "projectId"

    Project ID

  • apiVersionstringdefault: "v2022-04-01"

    API version

Previous

Query

Next

Webhooks

Endpoints

Publish documents

post/publish/{projectId}/{dataset}

Publish one or more documents in a single transaction. Each document must be valid and you must have permission to publish it. The transaction ID is returned in the response. You can use this ID to track the status of the transaction.

Path parameters

  • projectIdstringrequired

    Project ID

  • datasetstringrequired

    Dataset name

Query parameters

  • documentIdsarrayrequired

    List of comma-separated document IDs to publish

    Example
    01208c30-0872-465a-9e4d-9b02d8b9cf7d,9f515369-87f4-4c70-9009-1c9d7a14aec8
    items
    • itemsstring

Responses

200

Successful response

  • transactionIdstring
Examplesapplication/json
{
  "transactionId": "AXfzpiiJdFhpbwBLvIYojP"
}

Unpublish documents

post/unpublish/{projectId}/{dataset}

Unpublish one or more documents in a single transaction. Each document must be valid and you must have permission to unpublish it. The transaction ID is returned in the response. You can use this ID to track the status of the transaction.

Path parameters

  • projectIdstringrequired

    Project ID

  • datasetstringrequired

    Dataset name

Query parameters

  • documentIdsarrayrequired

    List of comma-separated document IDs to unpublish

    Example
    01208c30-0872-465a-9e4d-9b02d8b9cf7d,9f515369-87f4-4c70-9009-1c9d7a14aec8
    items
    • itemsstring

Responses

200

Successful response

  • transactionIdstring
Examplesapplication/json
{
  "transactionId": "AXfzpiiJdFhpbwBLvIYojP"
}

List schedules

get/schedules/{projectId}/{dataset}

Path parameters

  • projectIdstringrequired

    Project ID

  • datasetstringrequired

    Dataset name

Query parameters

  • documentIdsarray

    List of document IDs to filter returned schedules by

    items
    • itemsstring
  • statestring

    Schedule state to filter by

  • offsetinteger

    Offset to start the list from

  • limitinteger

    Limit the number of schedules returned

  • authorstring

    A single user ID to filter returned schedules by.

Responses

200

Successful response

  • schedulesarray

    Array of schedule objects

    Show child attributes
    items
    • idstring

      Unique identifier for the schedule

      Example:sch-28MRSuc1Ij4xtNa1rNbhTlMAszj
    • namestring

      A custom name for the schedule. Make it human-readable and understandable

      Example:March update
    • descriptionstring

      A custom description for the schedule. It helps understand the purpose of the schedule

    • projectIdstring

      The ID of the project this schedule belongs to

      Example:hb6nr9ev
    • datasetstring

      The dataset this schedule operates on

      Example:production
    • authorstring

      The ID of the user who created the schedule

      Example:poLhU1V3X
    • statestring

      The current state of the schedule

    • stateReasonstring

      Explanation of the current state

      Example:execution completed
    • documentsarray

      List of documents to be published or unpublished

      Show child attributes
      items
      • documentIdstring

        The ID of the document

        Example:f28fe6ce-0454-42c2-8a9a-c469fbf79281
      • documentTypestring

        The type of the document

        Example:article
      • ifRevisionIdstring

        The revision ID of the document

    • createdAtstring (date-time)

      When the schedule was created

      Example:2022-04-27T01:54:31.536236Z
    • executeAtstring (date-time)

      When the schedule is planned to execute

      Example:2022-04-27T01:55:00Z
    • executedAtstring (date-time)

      When the schedule was actually executed (if applicable)

      Example:2022-04-27T06:19:53.267576Z
    • transactionIdstring

      ID of the transaction that executed the schedule (if applicable)

      Example:AXfzpiiJdFhpbwBLvIYojP
Examplesapplication/json
{
  "schedules": [
    {
      "id": "sch-28MRSuc1Ij4xtNa1rNbhTlMAszj",
      "name": "March update",
      "description": "",
      "projectId": "hb6nr9ev",
      "dataset": "production",
      "author": "poLhU1V3X",
      "state": "succeeded",
      "stateReason": "execution completed",
      "documents": [
        {
          "documentId": "f28fe6ce-0454-42c2-8a9a-c469fbf79281",
          "documentType": "article"
        }
      ],
      "createdAt": "2022-04-27T01:54:31.536236Z",
      "executeAt": "2022-04-27T01:55:00Z"
    }
  ]
}

Create schedule

post/schedules/{projectId}/{dataset}

Path parameters

  • projectIdstringrequired

    Project ID

  • datasetstringrequired

    Dataset name

Query parameters

  • namestringrequired

    Name of the schedule

  • descriptionstring

    Description of the schedule

  • executeAtstringrequired

    When the schedule should execute

  • actionstringrequired

    The action to perform. Defaults to 'publish' if not specified

  • ifRevisionIdstring

    Run the schedule only if the document _rev value matches ifRevisionId.

Request body application/json

  • documentsarrayrequired

    Array of documents to be published or unpublished

    Show child attributes
    items
    • documentIdstringrequired

      The ID of the document to be published or unpublished. Must be a valid UUID.

      Example:f28fe6ce-0454-42c2-8a9a-c469fbf79281
    • ifRevisionIdstring

      Optional revision ID that must match the document's _rev value in order to proceed with the publish or unpublish action

  • namestringrequired

    A custom name for the schedule. Make it human-readable and understandable

    Example:December 2025 release
  • descriptionstring

    A custom description for the schedule. It helps understand the purpose of the schedule

    Example:Documents to publish at the end of 2025
  • executeAtstring (date-time)required

    When the schedule should execute. Must be in UTC format with Z suffix (YYYY-MM-DDTHH:mm:ss.sssZ)

    Example:2025-12-25T19:45:00.000Z
  • actionstringdefault: "publish"

    The action to perform. Defaults to 'publish' if not specified

Examplesapplication/json
{
  "documents": [
    {
      "documentId": "01208c30-0872-465a-9e4d-9b02d8b9cf7d"
    },
    {
      "documentId": "9f515369-87f4-4c70-9009-1c9d7a14aec8"
    }
  ],
  "name": "December 2025 release",
  "description": "Documents to publish at the end of 2025",
  "executeAt": "2025-12-25T19:45:00.000Z"
}

Responses

200

Successful response

  • idstring

    Unique identifier for the schedule

    Example:sch-28MRSuc1Ij4xtNa1rNbhTlMAszj
  • namestring

    A custom name for the schedule. Make it human-readable and understandable

    Example:March update
  • descriptionstring

    A custom description for the schedule. It helps understand the purpose of the schedule

  • projectIdstring

    The ID of the project this schedule belongs to

    Example:hb6nr9ev
  • datasetstring

    The dataset this schedule operates on

    Example:production
  • authorstring

    The ID of the user who created the schedule

    Example:poLhU1V3X
  • statestring

    The current state of the schedule

  • stateReasonstring

    Explanation of the current state

    Example:execution completed
  • documentsarray

    List of documents to be published or unpublished

    Show child attributes
    items
    • documentIdstring

      The ID of the document

      Example:f28fe6ce-0454-42c2-8a9a-c469fbf79281
    • documentTypestring

      The type of the document

      Example:article
    • ifRevisionIdstring

      The revision ID of the document

  • createdAtstring (date-time)

    When the schedule was created

    Example:2022-04-27T01:54:31.536236Z
  • executeAtstring (date-time)

    When the schedule is planned to execute

    Example:2022-04-27T01:55:00Z
  • executedAtstring (date-time)

    When the schedule was actually executed (if applicable)

    Example:2022-04-27T06:19:53.267576Z
  • transactionIdstring

    ID of the transaction that executed the schedule (if applicable)

    Example:AXfzpiiJdFhpbwBLvIYojP
Examplesapplication/json
{
  "id": "sch-28MkGjFSYRBSlcKExN2WBnBxtdQ",
  "name": "December 2025 release",
  "description": "Documents to publish at the end of 2025",
  "projectId": "hb6nr9ev",
  "dataset": "production",
  "author": "p-EiESybeCRamQ",
  "state": "scheduled",
  "stateReason": "created by user",
  "documents": [
    {
      "documentId": "01208c30-0872-465a-9e4d-9b02d8b9cf7d",
      "ifRevisionId": ""
    },
    {
      "documentId": "9f515369-87f4-4c70-9009-1c9d7a14aec8",
      "ifRevisionId": ""
    }
  ],
  "createdAt": "2022-04-27T04:29:08.668197Z",
  "executeAt": "2025-12-25T19:45:00Z"
}

Get schedule by ID

get/schedules/{projectId}/{dataset}/{scheduleId}

Path parameters

  • scheduleIdstringrequired

    Schedule ID

  • projectIdstringrequired

    Project ID

  • datasetstringrequired

    Dataset name

Query parameters

  • documentIdsarray

    List of document IDs to filter returned schedules by

    items
    • itemsstring
  • statestring

    Schedule state to filter by

  • authorstring

    A single user ID to filter returned schedules by.

Responses

200

Successful response

  • idstring

    Unique identifier for the schedule

    Example:sch-28MRSuc1Ij4xtNa1rNbhTlMAszj
  • namestring

    A custom name for the schedule. Make it human-readable and understandable

    Example:March update
  • descriptionstring

    A custom description for the schedule. It helps understand the purpose of the schedule

  • projectIdstring

    The ID of the project this schedule belongs to

    Example:hb6nr9ev
  • datasetstring

    The dataset this schedule operates on

    Example:production
  • authorstring

    The ID of the user who created the schedule

    Example:poLhU1V3X
  • statestring

    The current state of the schedule

  • stateReasonstring

    Explanation of the current state

    Example:execution completed
  • documentsarray

    List of documents to be published or unpublished

    Show child attributes
    items
    • documentIdstring

      The ID of the document

      Example:f28fe6ce-0454-42c2-8a9a-c469fbf79281
    • documentTypestring

      The type of the document

      Example:article
    • ifRevisionIdstring

      The revision ID of the document

  • createdAtstring (date-time)

    When the schedule was created

    Example:2022-04-27T01:54:31.536236Z
  • executeAtstring (date-time)

    When the schedule is planned to execute

    Example:2022-04-27T01:55:00Z
  • executedAtstring (date-time)

    When the schedule was actually executed (if applicable)

    Example:2022-04-27T06:19:53.267576Z
  • transactionIdstring

    ID of the transaction that executed the schedule (if applicable)

    Example:AXfzpiiJdFhpbwBLvIYojP
Examplesapplication/json
{
  "id": "sch-28MRSuc1Ij4xtNa1rNbhTlMAszj",
  "name": "March update",
  "description": "",
  "projectId": "hb6nr9ev",
  "dataset": "production",
  "author": "poLhU1V3X",
  "state": "succeeded",
  "stateReason": "execution completed",
  "documents": [
    {
      "documentId": "f28fe6ce-0454-42c2-8a9a-c469fbf79281",
      "documentType": "article"
    }
  ],
  "createdAt": "2022-04-27T01:54:31.536236Z",
  "executeAt": "2022-04-27T01:55:00Z"
}

Update schedule

patch/schedules/{projectId}/{dataset}/{scheduleId}

Path parameters

  • projectIdstringrequired

    Project ID

  • datasetstringrequired

    Dataset name

Query parameters

  • descriptionstring

    Description of the schedule

  • documentsarray

    An array of objects containing a key documentId that references a non-draft document ID.

    items
    • itemsstring
  • executeAtstring

    When the schedule should execute

  • statestring

    The target state of the schedule. Can only be set to 'cancelled'

Request body application/json

  • descriptionstring

    A custom description for the schedule. It helps understand the purpose of the schedule

  • documentsarray

    Array of documents to be published or unpublished

    Show child attributes
    items
    • documentIdstringrequired

      The ID of the document to be published or unpublished. Must be a valid UUID.

      Example:f28fe6ce-0454-42c2-8a9a-c469fbf79281
    • ifRevisionIdstring

      Optional revision ID that must match the document's _rev value in order to proceed with the publish or unpublish action

  • executeAtstring (date-time)

    When the schedule should execute. Must be in UTC format with Z suffix

    Example:2077-01-01T12:00:00.000Z
  • namestring

    A custom name for the schedule. Make it human-readable and understandable

  • statestring

    The target state of the schedule. Can only be set to 'cancelled'

Examplesapplication/json
{
  "executeAt": "2077-01-01T12:00:00.000Z",
  "documents": [
    {
      "documentId": "27aef7e9-7c9f-4b67-9c46-d786b54d0624"
    }
  ]
}

Responses

200

Schedule updated successfully

  • object

Run schedule

post/schedules/{projectId}/{dataset}/{scheduleId}/publish

Path parameters

  • projectIdstringrequired

    Project ID

  • datasetstringrequired

    Dataset name

  • scheduleIdstringrequired

    Schedule ID

Responses

200

Successful response

  • schedulesarray

    Array of schedule objects

    Show child attributes
    items
    • idstring

      Unique identifier for the schedule

      Example:sch-28MRSuc1Ij4xtNa1rNbhTlMAszj
    • namestring

      A custom name for the schedule. Make it human-readable and understandable

      Example:March update
    • descriptionstring

      A custom description for the schedule. It helps understand the purpose of the schedule

    • projectIdstring

      The ID of the project this schedule belongs to

      Example:hb6nr9ev
    • datasetstring

      The dataset this schedule operates on

      Example:production
    • authorstring

      The ID of the user who created the schedule

      Example:poLhU1V3X
    • statestring

      The current state of the schedule

    • stateReasonstring

      Explanation of the current state

      Example:execution completed
    • documentsarray

      List of documents to be published or unpublished

      Show child attributes
      items
      • documentIdstring

        The ID of the document

        Example:f28fe6ce-0454-42c2-8a9a-c469fbf79281
      • documentTypestring

        The type of the document

        Example:article
      • ifRevisionIdstring

        The revision ID of the document

    • createdAtstring (date-time)

      When the schedule was created

      Example:2022-04-27T01:54:31.536236Z
    • executeAtstring (date-time)

      When the schedule is planned to execute

      Example:2022-04-27T01:55:00Z
    • executedAtstring (date-time)

      When the schedule was actually executed (if applicable)

      Example:2022-04-27T06:19:53.267576Z
    • transactionIdstring

      ID of the transaction that executed the schedule (if applicable)

      Example:AXfzpiiJdFhpbwBLvIYojP
Examplesapplication/json
{
  "schedules": [
    {
      "id": "sch-26jr9toRuHMfFqdCtHONjHB2nl7",
      "name": "May release",
      "description": "",
      "projectId": "hb6nr9ev",
      "dataset": "production",
      "author": "poLhU1V3X",
      "state": "succeeded",
      "stateReason": "execution completed",
      "documents": [
        {
          "documentId": "b80b96b7-24dc-4c49-a5c3-340ef1750b8f",
          "documentType": "article"
        }
      ],
      "createdAt": "2022-03-22T11:14:47.281244Z",
      "executeAt": "2022-05-20T11:30:00Z",
      "executedAt": "2022-04-27T06:19:53.267576Z",
      "transactionId": "AXfzpiiJdFhpbwBLvIYojP"
    }
  ]
}