Projects API reference

Reference documentation for the projects HTTP endpoint.

The Projects API lets you create and manage projects and datasets.

For role and permission management, we suggest using the newer Access API instead.

Authentication

  • All requests must be authenticated.
  • Updating or deleting a project requires the Administrator role. Managing datasets, tags, tokens, and CORS origins requires the Administrator or Developer role, or equivalent permissions.

Base API server URL

Sanity API base URL

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

Variables

  • apiVersionstringdefault: "v2021-06-07"

    API version

Endpoints

List all projects

get/projects

Returns a list of all projects you are a member of.

Query parameters

  • includeMembersbooleandefault: true

    Whether to include project members in the response.

  • includeFeaturesbooleandefault: true

    Whether to include project features in the response.

  • organizationIdstring

    Only return projects that belong to this organization.

  • onlyExplicitMembershipbooleandefault: false

    Only return projects where you have explicit project membership.

  • includeOrganizationProjectsbooleandefault: false

    Also return projects you can read through your organization membership. Ignored when onlyExplicitMembership is true.

  • includeOnlyCreatedProjectsbooleandefault: false

    Only return projects you created.

Responses

200

A list of projects.

    items
    • idstring
    • displayNamestring
    • studioHoststring|nulldeprecated

      This field is deprecated. Use the /user-applications API instead.

    • organizationIdstring|null
    • metadataobject
      Show child attributes
    • isBlockedboolean
    • isDisabledboolean
    • isDisabledByUserboolean
    • activityFeedEnabledboolean
    • createdAtstring (date-time)
    • updatedAtstring (date-time)
    • membersarray

      Only included when includeMembers is true.

      Show child attributes
      items
      • idstring
      • rolestringdeprecated

        The member's legacy role. Only returned in the create project response and on API versions before v2021-06-07. Use roles instead.

        Example:administrator
      • rolesarray
        Show child attributes
        items
      • isCurrentUserboolean

        Whether this member is you. Not included in the create project response.

      • isRobotboolean

        Whether this member is a token rather than a person. Not included in the create project response.

      • createdAtstring (date-time)
      • updatedAtstring (date-time)
    • featuresarray

      Only included when includeFeatures is true.

      Show child attributes
      items
      • string
    • organizationobject

      The project's organization. Only included when retrieving a single project with includeOrganization set to true.

Create a project

post/projects

Creates a new Sanity project.

Request body application/json

  • displayNamestringrequired

    The display name of the project.

    Example:My Project
  • organizationIdstring

    Assign the created project to the specified organization. The organization to which organizationId belongs must already exist and you must have sufficient permissions to assign a project to the organization. If omitted, a new organization is created for you and the project is assigned to it.

    Example:oAbC123xyz
  • idstring

    A preferred ID for the project, 5 to 16 characters. It is converted to lowercase.

    Example:wefsadfj
  • metadataobject
    Show child attributes
    • colorstring
      Example:#000000
    • externalStudioHoststringdeprecated

      This field is deprecated. Use the /user-applications API instead.

      Example:https://my-project.my-domain.com
  • studioHoststringdeprecated

    This field is deprecated. Use the /user-applications API instead.

  • createDefaultCorsOriginbooleandefault: true

    Whether to create a default localhost CORS origin for the project.

Responses

201

Project created successfully.

  • idstring
  • displayNamestring
  • studioHoststring|nulldeprecated

    This field is deprecated. Use the /user-applications API instead.

  • organizationIdstring|null
  • metadataobject
    Show child attributes
  • isBlockedboolean
  • isDisabledboolean
  • isDisabledByUserboolean
  • activityFeedEnabledboolean
  • createdAtstring (date-time)
  • updatedAtstring (date-time)
  • membersarray

    Only included when includeMembers is true.

    Show child attributes
    items
    • idstring
    • rolestringdeprecated

      The member's legacy role. Only returned in the create project response and on API versions before v2021-06-07. Use roles instead.

      Example:administrator
    • rolesarray
      Show child attributes
      items
    • isCurrentUserboolean

      Whether this member is you. Not included in the create project response.

    • isRobotboolean

      Whether this member is a token rather than a person. Not included in the create project response.

    • createdAtstring (date-time)
    • updatedAtstring (date-time)
  • featuresarray

    Only included when includeFeatures is true.

    Show child attributes
    items
    • string
  • organizationobject

    The project's organization. Only included when retrieving a single project with includeOrganization set to true.

Retrieve a project

get/projects/{projectId}

Returns the details of a specific project by ID.

Path parameters

  • projectIdstringrequired

    The unique ID of the project.

Query parameters

  • includeMembersbooleandefault: true

    Whether to include project members in the response.

  • includeFeaturesbooleandefault: true

    Whether to include project features in the response.

  • includeOrganizationbooleandefault: false

    Whether to include the project's organization in the response.

Responses

200

Project details.

  • idstring
  • displayNamestring
  • studioHoststring|nulldeprecated

    This field is deprecated. Use the /user-applications API instead.

  • organizationIdstring|null
  • metadataobject
    Show child attributes
  • isBlockedboolean
  • isDisabledboolean
  • isDisabledByUserboolean
  • activityFeedEnabledboolean
  • createdAtstring (date-time)
  • updatedAtstring (date-time)
  • membersarray

    Only included when includeMembers is true.

    Show child attributes
    items
    • idstring
    • rolestringdeprecated

      The member's legacy role. Only returned in the create project response and on API versions before v2021-06-07. Use roles instead.

      Example:administrator
    • rolesarray
      Show child attributes
      items
    • isCurrentUserboolean

      Whether this member is you. Not included in the create project response.

    • isRobotboolean

      Whether this member is a token rather than a person. Not included in the create project response.

    • createdAtstring (date-time)
    • updatedAtstring (date-time)
  • featuresarray

    Only included when includeFeatures is true.

    Show child attributes
    items
    • string
  • organizationobject

    The project's organization. Only included when retrieving a single project with includeOrganization set to true.

Update a project

patch/projects/{projectId}

Updates a specific project by ID.

Path parameters

  • projectIdstringrequired

    The unique ID of the project.

Request body application/json

  • displayNamestring
  • studioHoststringdeprecated

    Your studio hostname for deployment on Sanity's hosted service: https://.sanity.studio/. This field is deprecated. Use the /user-applications API instead.

    Example:my-project
  • metadataobject
    Show child attributes
    • colorstring

      The color of the project.

      Example:#000000
    • externalStudioHoststringdeprecated

      The external studio hostname for deployment on a custom domain. This field is deprecated. Use the /user-applications API instead.

      Example:https://my-project.my-domain.com
  • isDisabledByUserboolean
  • activityFeedEnabledboolean

Responses

200

Project updated successfully. Returns the updated project.

  • idstring
  • displayNamestring
  • studioHoststring|nulldeprecated

    This field is deprecated. Use the /user-applications API instead.

  • organizationIdstring|null
  • metadataobject
    Show child attributes
  • isBlockedboolean
  • isDisabledboolean
  • isDisabledByUserboolean
  • activityFeedEnabledboolean
  • createdAtstring (date-time)
  • updatedAtstring (date-time)
  • membersarray

    Only included when includeMembers is true.

    Show child attributes
    items
    • idstring
    • rolestringdeprecated

      The member's legacy role. Only returned in the create project response and on API versions before v2021-06-07. Use roles instead.

      Example:administrator
    • rolesarray
      Show child attributes
      items
    • isCurrentUserboolean

      Whether this member is you. Not included in the create project response.

    • isRobotboolean

      Whether this member is a token rather than a person. Not included in the create project response.

    • createdAtstring (date-time)
    • updatedAtstring (date-time)
  • featuresarray

    Only included when includeFeatures is true.

    Show child attributes
    items
    • string
  • organizationobject

    The project's organization. Only included when retrieving a single project with includeOrganization set to true.

Delete a project

delete/projects/{projectId}

Deletes a specific project by ID.

Path parameters

  • projectIdstringrequired

    The unique ID of the project.

Responses

200

Project deleted successfully.

Create a CORS entry

post/projects/{projectId}/cors

Adds a new CORS origin for a project.

Path parameters

Request body application/json

  • originstringrequired

    The origin to allow, including the protocol. It can't include a path. Use * to allow all origins.

    Example:https://www.example.com
  • allowCredentialsbooleandefault: false

    Whether to allow authenticated requests from this origin. Can't be true when origin is *.

Responses

201

CORS entry created.

Delete a CORS entry

delete/projects/{projectId}/cors/{id}

Deletes a specific CORS origin for a project.

Path parameters

Responses

200

OK

List all datasets available to the project

get/projects/{projectId}/datasets

Returns a list of all datasets for the project.

Path parameters

Query parameters

  • includeStatsstring

    Include statistics for each dataset in a stats field. Any value turns this on, including false, so omit the parameter to leave statistics out.

  • datasetProfilestring

    Only return datasets with this dataset profile.

  • addonForstring

    Only return add-on datasets for the dataset with this name. If no dataset has this name, the request fails with Dataset "<name>" not found.

Responses

200

OK

    items
    • namestring
    • aclModestring
    • descriptionstring

      Only included when the dataset has a description.

    • createdAtstring (date-time)
    • createdByUserIdstring
    • addonForstring|null

      Only returned on API version v2023-11-13 or later.

    • datasetProfilestring

      Only returned on API version v2023-11-13 or later.

    • featuresarray

      Only returned on API version v2023-11-13 or later.

      Show child attributes
      items
      • string
    • statsobject

      Dataset statistics. Only included when you set includeStats.

    • tagsarray
      Show child attributes
      items
    • embeddingsobject

      Only included when embeddings are configured.

      Show child attributes

Create a dataset

put/projects/{projectId}/datasets/{name}

Creates a new dataset in the project.

Path parameters

Request body application/json

  • aclModestringdefault: "public"

    The ACL mode to set for the new dataset. Defaults to public. Setting private requires the private datasets feature, and custom requires the third-party login feature. Otherwise, the request fails with ACL mode "<mode>" not allowed for this project.

    Example:public
  • descriptionstring|null

    A description of the dataset.

  • embeddingsobject

    The settings for the embeddings index for the dataset.

    Show child attributes
    • enabledbooleanrequired

      Whether the embeddings index is enabled for the dataset. Required when you include embeddings.

    • projectionstring

      The GROQ projection that defines which fields to include in the embeddings index. If you don't include a projection, we process the entire document JSON into a less verbose format and embed all of it. Example: "{title, author}" or "{...}" for all fields

      Example:{title, author}

Responses

201

OK

Update a dataset

patch/projects/{projectId}/datasets/{name}

Updates a specific dataset in the project.

Path parameters

Request body application/json

  • aclModestring

    The ACL mode to set for the dataset. Omit to keep the current mode. Setting private requires the private datasets feature, and custom requires the third-party login feature. Otherwise, the request fails with ACL mode "<mode>" not allowed for this project.

    Example:public
  • descriptionstring|null

    A description of the dataset. Set to null to clear it.

Responses

200

OK

Copy a dataset

put/projects/{projectId}/datasets/{name}/copy

Copies a dataset to a new dataset. This feature is part of Advanced Dataset Management, available on the Enterprise plan. Without it, the request fails with Your current plan does not include the advanced dataset management feature.

Path parameters

  • projectIdstringrequired

    The unique ID of the project.

  • namestringrequired

    The name of the dataset to copy.

Request body application/json

  • targetDatasetstringrequired

    The name of the new dataset to create.

  • skipHistorybooleandefault: false

    If true, revision history is not copied, which will usually result in a much faster copy. If false or omitted, revision history is copied to targetDataset.

  • skipContentReleasesbooleandefault: false

    If true, content release documents are not copied to targetDataset.

  • aclModestringdeprecated

    Deprecated. The API accepts this field for backward compatibility but ignores it.

Responses

201

OK

  • datasetNamestring

    The name of the source dataset.

    Example:production
  • messagestring
    Example:Starting copying dataset production to production-copy...
  • aclModestring

    The ACL mode of the source dataset.

    Example:public
  • jobIdstring

    The ID of the copy job. Use it with the Jobs API to check the status of the copy.

List copy jobs history

get/projects/{projectId}/datasets/copy

Lists the dataset copy jobs for the project.

Path parameters

  • projectIdstringrequired

    The unique ID of the project.

Query parameters

  • offsetintegerdefault: 0

    Start position in list.

  • limitintegerdefault: 10

    Number of items to return.

  • statearraydefault: []

    Comma separated list of job states.

    items
    • itemsstring

Responses

200

OK

    items
    • idstring
      Example:123456
    • statestring
      Example:pending
    • createdAtstring (date-time)
      Example:2021-01-01T00:00:00Z
    • updatedAtstring (date-time)
      Example:2021-01-01T00:00:00Z
    • sourceDatasetstring
      Example:my-dataset
    • targetDatasetstring
      Example:my-dataset-copy
    • withHistoryboolean

      Whether the copy included document history.

    • authorsarray
      Show child attributes
      items
      • string
        Example:user_123

List active features for the project

get/projects/{projectId}/features

Returns a list of active features for the project.

Path parameters

  • projectIdstringrequired

    The unique ID of the project.

Responses

200

OK

    items
    • string
      Example:privateDataset

List your permissions for the project

get/projects/{projectId}/permissions

Returns the legacy permissions for your project role, such as manageProject or readAll. The list is based on the original fixed project roles (Administrator, Write, and Read), not on the current roles system, so it doesn't reflect everything your role allows. Members with other roles, such as Developer, Contributor, or custom roles, and organization members without project membership, get an empty array.

Path parameters

  • projectIdstringrequired

    The unique ID of the project.

Responses

200

OK

    items
    • string

Retrieve a user

get/projects/{projectId}/users/{userId}

Returns a list of details for the user.

Path parameters

  • projectIdstringrequired

    The unique ID of the project.

  • userIdstringrequired

    The project user ID, which starts with p. Global user IDs, which start with g, are rejected. To fetch several users, pass a comma-separated list of IDs. The response is then an array.

Responses

200

OK

Create a new token for the project

post/projects/{projectId}/tokens

Creates a new token for the project. To manage tokens with the newer Access API, see the Access API reference.

Path parameters

  • projectIdstringrequired

    The unique ID of the project.

Query parameters

  • sendNotificationbooleandefault: true

    Whether to email the project's administrators about the new token. You can only set it to false within five minutes of creating the project. Otherwise, the request fails with Cannot skip token notification.

Request body application/json

Responses

201

OK

List tags for a dataset

get/projects/{projectId}/datasets/{name}/tags

Returns a list of tags for the dataset.

Path parameters

  • projectIdstringrequired

    The unique ID of the project.

  • namestringrequired

    The name of the dataset.

Responses

200

OK

Create a new tag for the project

post/projects/{projectId}/tags

Creates a new tag for the project. Datasets cannot be assigned at tag creation. To assign a tag to a dataset, use PUT /projects/{projectId}/datasets/{datasetName}/tags/{tagIdentifier}. Requires a project plan that includes advanced roles management.

Path parameters

  • projectIdstringrequired

    The unique ID of the project.

Request body application/json

  • titlestringrequired

    The title of the tag.

  • namestringrequired

    The name of the tag. It starts with a lowercase letter or digit, followed by 1 to 20 letters, digits, hyphens, or underscores. You can't rename a tag after you create it.

  • descriptionstring

    The description of the tag.

  • metadataobject

    A set of additional configuration options

    Show child attributes
    • tonestring

      The color of your tag.

Responses

201

OK

Retrieve a tag

get/projects/{projectId}/tags/{tagIdentifier}

Returns a tag by name. The datasets list is empty unless you have read access to the project's datasets.

Path parameters

Responses

200

OK

Update a tag by identifier

put/projects/{projectId}/tags/{tagIdentifier}

Updates a tag by identifier. You can update the title, description, and metadata. A tag can't be renamed: sending a different name fails with a 400 error. Requires a project plan that includes advanced roles management.

Path parameters

Request body application/json

  • titlestring

    The title of the tag.

  • descriptionstring

    The description of the tag.

  • metadataobject

    A set of additional configuration options

    Show child attributes
    • tonestring

      The color of your tag.

Responses

200

OK

Delete a tag by identifier

delete/projects/{projectId}/tags/{tagIdentifier}

Deletes a tag by identifier. The tag must not be assigned to any datasets. Otherwise, the request fails with a 422 error: Tag is applied to a dataset. Requires a project plan that includes advanced roles management.

Path parameters

Responses

200

OK

Assign a tag to a dataset

put/projects/{projectId}/datasets/{datasetName}/tags/{tagIdentifier}

Assigns a tag to a dataset. Requires a project plan that includes advanced roles management.

Path parameters

Responses

201

OK

Remove a tag from a dataset

delete/projects/{projectId}/datasets/{datasetName}/tags/{tagIdentifier}

Removes a tag from a dataset. Requires a project plan that includes advanced roles management.

Path parameters

Responses

200

OK

Get embeddings index settings for a dataset

get/projects/{projectId}/datasets/{name}/settings/embeddings

Returns the settings for the embeddings index for a dataset.

Path parameters

  • projectIdstringrequired

    The unique ID of the project.

  • namestringrequired

    The name of the dataset.

Responses

200

OK

  • enabledboolean
  • projectionstring

    The GROQ projection that defines which fields to include in the embeddings index. If you don't include a projection, we process the entire document JSON into a less verbose format and embed all of it. Example: "{title, author}" or "{...}" for all fields

    Example:{title, author}
  • statusstring

    The status of the embeddings index. disabled when embeddings are off, unknown when the status couldn't be fetched, and otherwise ready, updating, or error.

    Example:updating

Update embeddings index settings for a dataset

put/projects/{projectId}/datasets/{name}/settings/embeddings

Updates the settings for the embeddings index for a dataset.

Path parameters

  • projectIdstringrequired

    The unique ID of the project.

  • namestringrequired

    The name of the dataset.

Request body application/json

  • enabledbooleanrequired

    Whether to enable the embeddings index for the dataset.

  • projectionstring

    The GROQ projection that defines which fields to include in the embeddings index. If you don't include a projection, we process the entire document JSON into a less verbose format and embed all of it. Example: "{title, author}" or "{...}" for all fields

    Example:{title, author}
Examplesapplication/json
Enable embeddings index for a dataset

Enables the embeddings index for a dataset. 

{
  "enabled": true,
  "projection": "{title, author}"
}

Responses

200

The change was applied synchronously, for example when disabling embeddings. Returns an empty object.

  • object
sanity.ioAll Systems Operational© Sanity 2026
Change site theme