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
    • Agent Actions
    • 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

HTTP API ReferenceLast updated January 9, 2026

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

Previous

Access

Next

Roles

On this page

  • Authentication
Endpoints
  • List all projects
  • Create a project
  • Retrieve a project
  • Update a project
  • Delete a project
  • List all CORS entries
  • Create a CORS entry
  • Delete a CORS entry
  • List all datasets available to the project
  • Retrieve a dataset
  • Delete a dataset
  • Create a dataset
  • Update a dataset
  • Copy a dataset
  • List copy jobs history
  • List active features for the project
  • List permissions for the project
  • Retrieve a user
  • List tokens for the project
  • Create a new token for the project
  • Delete a token for the project
  • List tags for a dataset
  • Create a new tag for the project
  • Update a tag by identifier
  • Delete a tag by identifier
  • Assign a tag to a dataset
  • Remove a tag from a dataset

Endpoints

List all projects

get/projects

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

Responses

200

A list of projects.

    items
    • idstring
    • displayNamestring
    • studioHoststring | null
    • organizationIdstring | null
    • metadataobject
      Show child attributes
      • colorstring
    • isBlockedboolean
    • isDisabledboolean
    • activityFeedEnabledboolean
    • createdAtstring (date-time)
    • membersarray
      Show child attributes
      items
      • idstring
      • rolestring
        Example:administrator
      • rolesarray
        Show child attributes
        items
        • namestring
        • titlestring
        • descriptionstring

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
    • idstring
    • rolestring
      Example:administrator
    • rolesarray
      Show child attributes
      items
      • namestring
      • titlestring
      • descriptionstring

Responses

201

Project created successfully.

  • idstring
  • displayNamestring
  • studioHoststring | null
  • organizationIdstring | null
  • metadataobject
    Show child attributes
    • colorstring
  • isBlockedboolean
  • isDisabledboolean
  • activityFeedEnabledboolean
  • createdAtstring (date-time)
  • membersarray
    Show child attributes
    items
    • idstring
    • rolestring
      Example:administrator
    • rolesarray
      Show child attributes
      items
      • namestring
      • titlestring
      • descriptionstring

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.

  • idstring
  • displayNamestring
  • studioHoststring | null
  • organizationIdstring | null
  • metadataobject
    Show child attributes
    • colorstring
  • isBlockedboolean
  • isDisabledboolean
  • activityFeedEnabledboolean
  • createdAtstring (date-time)
  • membersarray
    Show child attributes
    items
    • idstring
    • rolestring
      Example:administrator
    • rolesarray
      Show child attributes
      items
      • namestring
      • titlestring
      • descriptionstring

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

    Your studio hostname for deployment on Sanity's hosted service: https://.sanity.studio/.

    Example:https://my-project.sanity.studio
  • metadataobject
    Show child attributes
    • colorstring

      The color of the project.

      Example:#000000
    • externalStudioHoststring

      The external studio hostname for deployment on a custom domain.

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

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.

List all CORS entries

get/projects/{projectId}/cors

Returns a list of all CORS origins for a specific project.

Path parameters

  • projectIdstringrequired

Responses

200

A list of CORS entries.

    items
    • idinteger
    • originstring
    • allowCredentialsboolean
    • createdAtstring (date-time)

Create a CORS entry

post/projects/{projectId}/cors

Adds a new CORS origin for a project.

Path parameters

  • projectIdstringrequired

Request body application/json

  • originstringrequired
  • allowCredentialsboolean

Responses

201

CORS entry created.

Delete a CORS entry

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

Deletes a specific CORS origin for a project.

Path parameters

  • projectIdstringrequired
  • idintegerrequired

Responses

200

OK

  • idinteger
  • deletedboolean
    Example:true

List all datasets available to the project

get/projects/{projectId}/datasets

Returns a list of all datasets for the project.

Path parameters

  • projectIdstringrequired

Responses

200

OK

    items
    • namestring
    • aclModestring

Retrieve a dataset

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

Returns the details of a specific dataset by name.

Path parameters

  • projectIdstringrequired
  • namestringrequired

Request body application/json

  • aclModestring

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

Responses

200

OK

  • namestring
  • aclModestring

Delete a dataset

delete/projects/{projectId}/datasets/{name}

Deletes a specific dataset by name.

Path parameters

  • projectIdstringrequired
  • namestringrequired

Responses

200

OK

  • deletedboolean

Create a dataset

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

Creates a new dataset in the project.

Path parameters

  • projectIdstringrequired
  • namestringrequired

Request body application/json

  • aclModestringdefault: "public"

    The ACL mode to set for the new dataset. Defaults to public.

    Example:public

Responses

200

OK

Update a dataset

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

Updates a specific dataset in the project.

Path parameters

  • projectIdstringrequired
  • namestringrequired

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

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 unique ID of the user. If authenticated with a user token, you can substitute "me" for the user ID.

Responses

200

OK

  • idstring
  • sanityUserIdstring
  • projectIdstring
  • displayNamestring
  • familyNamestring
  • givenNamestring
  • imageUrlstring
  • createdAtstring (date-time)
  • updatedAtstring (date-time)

List tokens for the project

get/projects/{projectId}/tokens

Returns a list of tokens for the project.

This endpoint does not reveal the actual token, only details about the token.

Path parameters

  • projectIdstringrequired

    The unique ID of the project.

Responses

200

OK

    items
    • idstring
    • labelstring
    • projectUserIdstring
    • createdAtstring (date-time)
    • rolesarray
      Show child attributes
      items
      • namestring
      • titlestring

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

  • idstring
  • labelstring
  • keystring
  • projectUserIdstring
  • rolesarray
    Show child attributes
    items
    • namestring
    • titlestring

Delete a token for the project

delete/projects/{projectId}/tokens/{tokenId}

Deletes a token for the project.

Path parameters

  • projectIdstringrequired

    The unique ID of the project.

  • tokenIdstringrequired

    The unique ID of the token.

Responses

200

OK

  • deletedboolean
  • idstring

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

    items
    • namestring
    • titlestring
    • descriptionstring
    • metadataobject
      Show child attributes
      • tonestring
    • datasetsarray
      Show child attributes
      items
      • string
        Example:

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

  • namestring
  • titlestring
  • descriptionstring
  • metadataobject
    Show child attributes
    • tonestring
  • datasetsarray
    Show child attributes
    items
    • string
      Example:

Update a tag by identifier

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

Updates a tag by identifier.

Path parameters

  • projectIdstringrequired

    The unique ID of the project.

  • tagIdentifierstringrequired

    The unique ID of the tag.

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

  • namestring
  • titlestring
  • descriptionstring
  • metadataobject
    Show child attributes
    • tonestring
  • datasetsarray
    Show child attributes
    items
    • string
      Example:

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

  • projectIdstringrequired

    The unique ID of the project.

  • tagIdentifierstringrequired

    The unique ID of the tag.

Responses

200

OK

  • deletedboolean

Assign a tag to a dataset

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

Assigns a tag to a dataset.

Path parameters

  • projectIdstringrequired

    The unique ID of the project.

  • datasetNamestringrequired

    The name of the dataset.

  • tagIdentifierstringrequired

    The unique ID of the tag.

Responses

200

OK

Remove a tag from a dataset

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

Removes a tag from a dataset.

Path parameters

  • projectIdstringrequired

    The unique ID of the project.

  • datasetNamestringrequired

    The name of the dataset.

  • tagIdentifierstringrequired

    The unique ID of the tag.

Responses

200

OK

  • deletedboolean