HTTP API Reference

Projects API reference

Reference documentation for the projects HTTP endpoint.

The project API allows you to 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.
  • Managing projects requires the Administrator or Developer role, or equivalent.

Base API server URL

Sanity API base URL

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

Variables

  • apiVersionstringdefault: "v2021-06-07"

    API version

Endpoints

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, the project is assigned to your personal account.

    Example:org_123
  • isBlockedboolean
    Example:false
  • isDisabledboolean
    Example:false
  • isDisabledByUserboolean
    Example:false
  • maxRetentionDaysinteger
  • activityFeedEnabledboolean
    Example:true
  • idstring
    Example:wefsadfj
  • updatedAtstring (date-time)
    Example:2021-01-01T00:00:00Z
  • createdAtstring (date-time)
    Example:2021-01-01T00:00:00Z
  • 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
  • membersarray
    Show child attributes
    items

Responses

201

Project created successfully.

Retrieve a project

get/projects/{projectId}

Returns the details of a specific project by ID.

Path parameters

  • projectIdstringrequired

    The unique ID of the project.

Responses

200

Project details.

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

Responses

200

Project updated successfully.

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.

Delete a CORS entry

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

Deletes a specific CORS origin for a project.

Path parameters

Responses

200

OK

Retrieve a dataset

post/projects/{projectId}/datasets/{name}

Returns the details of a specific dataset by name.

Path parameters

Request body application/json

  • aclModestring

    Set the visibility of the dataset to either public or private. Defaults to public. default: public

Responses

200

OK

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.

    Example:public
  • embeddingsobject

    The settings for the embeddings index for the dataset.

    Show child attributes
    • enabledbooleandefault: false

      Whether the embeddings index is enabled 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}

Responses

200

OK

Update a dataset

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

Updates a specific dataset in the project.

Path parameters

Request body application/json

  • aclModestringdefault: "public"

    The ACL mode to set for the dataset.

    Example:public

Responses

200

OK

Copy a dataset

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

Copies a dataset to a new dataset. This is a feature available to Business and Enterprise customers.

Path parameters

  • projectIdstringrequired

    The unique ID of the project.

  • namestringrequired

    The name of the dataset to copy.

Request body application/json

  • targetDatasetstring

    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.

  • aclModestringdefault: "public"

    The ACL mode to set for the new dataset.

Responses

200

OK

List copy jobs history

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

List copy jobs history for a dataset. This is a feature available to Business and Enterprise customers.

Path parameters

  • projectIdstringrequired

    The unique ID of the project.

  • namestringrequired

    The name of the dataset.

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
    • 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 permissions for the project

get/projects/{projectId}/permissions

Returns a list of permissions for the project.

Path parameters

  • projectIdstringrequired

    The unique ID of the project.

Responses

200

OK

    items
    • string

Create a new token for the project

post/projects/{projectId}/tokens

Creates a new token for the project.

Path parameters

  • projectIdstringrequired

    The unique ID of the project.

Request body application/json

  • labelstringrequired

    A descriptive label for your token. This can help you identify it later so you know where it's being used.

  • roleNamestringrequired

    The permissions to assign your token. These will vary by plan. On a Free plan, roleName must be viewer, editor, or deploy-studio.

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. Use the PUT endpoint to assign datasets to the tag.

Path parameters

  • projectIdstringrequired

    The unique ID of the project.

Request body application/json

  • titlestring

    The title of the tag.

  • namestring

    The name of the tag.

  • descriptionstring

    The description of the tag.

  • metadataobject

    A set of additional configuration options

    Show child attributes
    • tonestringdefault: "default"

      The color of your tag.

Responses

200

OK

Update a tag by identifier

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

Updates a tag by identifier.

Path parameters

Request body application/json

  • titlestring

    The title of the tag.

  • namestring

    The name of the tag.

  • descriptionstring

    The description of the tag.

  • metadataobject

    A set of additional configuration options

    Show child attributes
    • tonestringdefault: "default"

      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.

Path parameters

Responses

200

OK

Assign a tag to a dataset

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

Assigns a tag to a dataset.

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. (ready, updating, 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.

example

Enables the embeddings index for a dataset. 

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

Request body application/json

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

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. (ready, updating, error)

    Example:updating