Scheduling API reference

Reference documentation for the Scheduling HTTP endpoints.

The Scheduling API lets you 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

Rate limits

The Scheduling API has the following limits:

  • 100 requests per minute per project.
  • 1,000 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.
  • Document IDs must be published (non-draft) IDs. Draft IDs, which start with drafts., are rejected.
  • If you set ifRevisionId, it must match the _rev of the published document.

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 or unpublish documents in that dataset.
  • Schedules can be filtered by dataset.
  • Schedules can be canceled 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 documents

post/publish/{projectId}/{dataset}

Publish one or more documents in a single transaction. Each document must have a published or draft version, 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

Request body application/json

    items
    • documentIdstringrequired

      The ID of the document to be published or unpublished. Must be a published (non-draft) document ID. Draft IDs, which start with drafts., are rejected.

      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

Examplesapplication/json
[
  {
    "documentId": "01208c30-0872-465a-9e4d-9b02d8b9cf7d"
  },
  {
    "documentId": "9f515369-87f4-4c70-9009-1c9d7a14aec8"
  }
]

Responses

200

Successful response

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

Unpublish documents

post/unpublish/{projectId}/{dataset}

Unpublish one or more documents in a single transaction. Each document must have a published or draft version, 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

Request body application/json

    items
    • documentIdstringrequired

      The ID of the document to be published or unpublished. Must be a published (non-draft) document ID. Draft IDs, which start with drafts., are rejected.

      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

Examplesapplication/json
[
  {
    "documentId": "01208c30-0872-465a-9e4d-9b02d8b9cf7d"
  },
  {
    "documentId": "9f515369-87f4-4c70-9009-1c9d7a14aec8"
  }
]

Responses

200

Successful response

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

List schedules

get/schedules/{projectId}/{dataset}

Path parameters

Query parameters

  • documentIdsarray

    List of document IDs to filter returned schedules by

    items
    • itemsstring
  • statestring

    Schedule state to filter by

  • actionstring

    Schedule action 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
    • actionstring

      The action the schedule performs when it executes

      Example:publish
    • 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",
      "action": "publish",
      "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

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 published (non-draft) document ID. Draft IDs, which start with drafts., are rejected.

      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 2077 release
  • descriptionstring

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

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

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

    Example:2077-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 2077 release",
  "description": "Documents to publish at the end of 2077",
  "executeAt": "2077-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
  • actionstring

    The action the schedule performs when it executes

    Example:publish
  • 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 2077 release",
  "description": "Documents to publish at the end of 2077",
  "projectId": "hb6nr9ev",
  "dataset": "production",
  "author": "p-EiESybeCRamQ",
  "action": "publish",
  "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": "2077-12-25T19:45:00Z"
}

Get schedule by ID

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

Path parameters

  • projectIdstringrequired

    Project ID

  • datasetstringrequired

    Dataset name

  • scheduleIdstringrequired

    Schedule ID. To get several schedules in one request, separate the IDs with commas.

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

  • 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
    • actionstring

      The action the schedule performs when it executes

      Example:publish
    • 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",
      "action": "publish",
      "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

  • scheduleIdstringrequired

    Schedule ID. To get several schedules in one request, separate the IDs with commas.

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 published (non-draft) document ID. Draft IDs, which start with drafts., are rejected.

      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 the future. 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. The response body is empty.

Run schedule

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

Immediately run one or more schedules that are in the scheduled state and have the publish action. To run several schedules, separate the schedule IDs with commas. If any schedule ID doesn't match a scheduled schedule with the publish action, the request fails with a 404 status code.

Path parameters

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
    • actionstring

      The action the schedule performs when it executes

      Example:publish
    • 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",
      "action": "publish",
      "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"
    }
  ]
}
sanity.ioAll Systems Operational© Sanity 2026
Change site theme