HTTP API ReferenceLast updated January 9, 2026

Scheduling API reference

Reference documentation for the Scheduling HTTP endpoints.

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

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

Endpoints

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"
    }
  ]
}

This API is deprecated

Authentication

Rate / API limits

Status and error codes

Publishing rules

Specifying dates

Schedules and your dataset

Other caveats

Base API server URL

Variables

Endpoints

Publish documents

Path parameters

Query parameters

items

Responses

Unpublish documents

Path parameters

Query parameters

items

Responses

List schedules

Path parameters

Query parameters

items

Responses

items

items

Create schedule

Path parameters

Query parameters

Request body application/json

items

Responses

items

Get schedule by ID

Path parameters

Query parameters

items

Responses

items

Update schedule

Path parameters

Query parameters

items

Request body application/json

items

Responses

Run schedule

Path parameters

Responses

items

items

Request body `application/json`

Request body `application/json`