Projects API

Manage your Sanity projects using the HTTP API.

The Projects API lets you manage all your Sanity projects, including their CORS origins, datasets and roles. All requests have to be authenticated.

List all projects

GET /v1/projects

Returns a list of all projects you are a member of. The projects are ordered by creation date, with the oldest projects appearing first.

Example

Request

curl GET 'https://api.sanity.io/v1/projects' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json'

Response

[
 {
    "id": "54n1ty10",
    "displayName": "My Sanity Project",
    "studioHost": null,
    "organizationId": null,
    "metadata": {
      "color": "#c7494b"
    },
    "isBlocked": false,
    "isDisabled": false,
    "isDisabledByUser": false,
    "createdAt": "2020-05-08T12:09:53.563Z",
    "members": [
      {
        "id": "p-rbzaPneUhfNp",
        "role": "read",
        "isRobot": true,
        "isCurrentUser": false
      },
      {
        "id": "p6yJeps3h",
        "role": "administrator",
        "isRobot": false,
        "isCurrentUser": true
      }
    ]
  }
]

Create a project

POST /v1/projects

Creates a new Sanity project.

Parameters

  • REQUIREDdisplayNamestring

    The display name of your project.

Example

Request

curl POST 'https://api.sanity.io/v1/projects' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-d '{
    "displayName": "My Sanity Project"
}'

Response

{
  "isBlocked": false,
  "isDisabled": false,
  "isDisabledByUser": false,
  "metadata": {},
  "maxRetentionDays": null,
  "dataClass": null,
  "id": "54n1ty10",
  "displayName": "My Sanity Project",
  "organizationId": null,
  "updatedAt": "2020-05-08T11:22:17.999Z",
  "createdAt": "2020-05-08T11:22:17.999Z",
  "studioHost": null,
  "deletedAt": null,
  "members": [
    {
      "id": "pModkh5Yq7",
      "role": "administrator"
    }
  ]
}

Retrieve a project

GET /v1/projects/:id

Returns the details of an existing project. Provide the unique project ID and the endpoint will retrieve the corresponding project information.

Example

Request

curl GET 'https://api.sanity.io/v1/projects/54n1ty10' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json'

Response

{
  "id": "54n1ty10",
  "displayName": "My Sanity Project",
  "studioHost": null,
  "isBlocked": false,
  "isDisabled": false,
  "isDisabledByUser": false,
  "metadata": {
    "color": "#c7494b"
  },
  "maxRetentionDays": 3,
  "createdAt": "2020-05-08T12:09:53.563Z",
  "updatedAt": "2020-05-08T12:13:49.191Z",
  "deletedAt": null,
  "organizationId": null,
  "members": [
    {
      "id": "p-pbkazNehPGlp",
      "role": "read",
      "isRobot": true
    },
    {
      "id": "p1iJcZsn3",
      "role": "administrator",
      "isRobot": false
    }
  ],
  "pendingInvites": 0
}

Update a project

PATCH /v1/projects/:id

Updates a specific project with the values of the parameters passed. Any parameters not provided will be left unchanged.

Parameters

  • displayNamestring

    The display name of your project.

  • studioHoststring

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

  • metadataobject

    A set of additional configuration options, including:

    • color - a hex value to distinguish your project on https://manage.sanity.io/.
    • externalStudioHost - set this to a URL if you host your Studio outside of Sanity.
  • isDisabledByUserboolean

    Disables your project when set to true.

Example

Request

curl PATCH 'https://api.sanity.io/v1/projects/54n1ty10' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-d '{
	"metadata": {
	  "color": "#c7494b"
	}
}'

Response

{
    "id": "54n1ty10",
    "displayName": "My Sanity Project",
    "studioHost": null,
    "isBlocked": false,
    "isDisabled": false,
    "isDisabledByUser": false,
    "metadata": {
        "color": "#c7494b"
    },
    "maxRetentionDays": 3,
    "dataClass": "normal",
    "createdAt": "2020-05-08T12:09:53.563Z",
    "updatedAt": "2020-05-08T12:13:49.191Z",
    "deletedAt": null,
    "organizationId": null,
    "createdByUserId": "grfwFqjIy"
}

Delete a project

DELETE /v1/projects/:id

Deletes a specific project.

Gotcha

Use this endpoint with caution. Deleting your project is an irreversible action. You may want to export all your data beforehand.

Example

Request

curl DELETE 'https://api.sanity.io/v1/projects/54n1ty10' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json'

Response

{
  "deleted": true
}

List all CORS entries

GET /v1/projects/:id/cors

Returns a list of all CORS origins allowed to access the API for this project.

Example

Request

curl GET 'https://api.sanity.io/v1/projects/54n1ty10/cors' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json'

Response

[
  {
    "id": 110863,
    "origin": "http://localhost:3333",
    "allowCredentials": true,
    "createdAt": "2020-05-08T12:09:53.576Z",
    "updatedAt": "2020-05-08T12:09:53.576Z",
    "projectId": "54n1ty10"
  }
]

Create a CORS entry

POST /v1/projects/:id/cors

Allows a new origin to use your project API through CORS. Read about browser security and CORS.

Parameters

  • REQUIREDoriginurl

    The origin you want to allow traffic from, stating explicitly the protocol, host name and port. Wildcards (*) are allowed. Use the following format: protocol://host:port.

  • allowCredentialsboolean

    Let the origin send credentials (e.g. a session cookie or an authorization token). Defaults to true.

Example

Request

curl POST 'https://api.sanity.io/v1/projects' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-d '{
	"origin": "https://localhost:3333",
	"allowCredentials": false
}'

Response

{
  "id": 112762,
  "projectId": "54n1ty10",
  "origin": "https://localhost:3333",
  "allowCredentials": false,
  "updatedAt": "2020-05-12T18:19:50.102Z",
  "createdAt": "2020-05-12T18:19:50.102Z"
}

Delete a CORS entry

DELETE /v1/projects/:id/cors/:id

Deletes an existing CORS origin from your project.

Example

Request

curl DELETE 'https://api.sanity.io/v1/projects/54n1ty10/cors/110882' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json'

Response

{
  "id": 110882,
  "deleted": true
}

List all datasets

GET /v1/projects/:id/datasets

Returns a list of all datasets available to a project.

Example

Request

curl GET 'https://api.sanity.io/v1/projects/54n1ty10/datasets' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json'

Response

[
  {
    "name": "production",
    "aclMode": "public"
  }
]

Create a dataset

PUT /v1/projects/:id/datasets/:name

Creates a new dataset for your project.

Parameters

  • aclModestring

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

Example

Request

curl PUT 'https://api.sanity.io/v1/projects/54n1ty10/datasets/staging' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-d '{
	"aclMode": "private"
}'

Response

{
  "datasetName": "staging",
  "aclMode": "private"
}

Delete a dataset

DELETE /v1/projects/:id/datasets/:id

Deletes an existing dataset within your project.

Gotcha

Tread carefully when using this endpoint. Deleting your dataset is an irreversible action. You may want to export your dataset beforehand.

Example

Request

curl DELETE 'https://api.sanity.io/v1/projects/54n1ty10/datasets/staging' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json'

Response

{
  "deleted": true
}

List active features

GET /v1/projects/:id/features

Returns a list of all active features on your project.

Example

Request

curl GET 'https://api.sanity.io/v1/projects/54n1ty10/features' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json'

Response

[
  "privateDataset"
]

Check if a feature is active

GET /v1/projects/:id/features/:name

Shows whether a specific feature is enabled on your project. Current features you can check for are privateDataset and thirdPartyLogin.

Example

Request

curl GET 'https://api.sanity.io/v1/projects/54n1ty10/features/thirdPartyLogin' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json'

Response

false

List project permissions

GET /v1/projects/:id/permissions

Returns a list of permissions you have as a member of a project.

Example

Request

curl GET 'https://api.sanity.io/v1/projects/54n1ty10/permissions' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json'

Response

[
  "manageProject",
  "manageUsers",
  "manageCors",
  "manageWebhooks",
  "manageTokens",
  "deployStudio",
  "manageDatasets",
  "readAll",
  "writeAll"
]

Retrieve a user

GET /v1/projects/:id/users/:id

Fetches the details of a user on a project.

Example

Request

curl GET 'https://api.sanity.io/v1/projects/54n1ty10/users/<id>' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json'

Response

{
  "id": "h87f1dh9",
  "sanityUserId": "9Ha09aoi",
  "projectId": "54n1ty10",
  "displayName": "Arthur Dent",
  "familyName": "Dent",
  "givenName": "Arthur",
  "middleName": null,
  "imageUrl": null,
  "createdAt": "2020-04-01T11:31:31.767Z",
  "updatedAt": "2020-04-01T11:31:31.767Z"
}

List project roles

GET /v1/projects/:id/roles

Returns a list of existing roles on a project.

Example

Request

curl GET 'https://api.sanity.io/v1/projects/54n1ty10/roles' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json'

Response

[
  {
    "id": "administrator",
    "name": "Administrator",
    "description": "Manage all aspects of the project",
    "isRootRole": true,
    "readOnly": true,
    "isListed": true,
    "permissions": [
      "manageProject",
      "manageUsers",
      "manageCors",
      "manageWebhooks",
      "manageTokens",
      "deployStudio",
      "manageDatasets",
      "readAll",
      "writeAll"
    ]
  },
  {
    "id": "write",
    "name": "Read+Write",
    "description": "Read and write from/to all datasets within the project",
    "isRootRole": true,
    "readOnly": true,
    "isListed": true,
    "permissions": [
      "writeAll",
      "readAll"
    ]
  },
  {
    "id": "read",
    "name": "Read",
    "description": "Read data from all datasets within the project",
    "isRootRole": true,
    "readOnly": true,
    "isListed": true,
    "permissions": [
      "readAll"
    ]
  }
]

List project tokens

GET /v1/projects/:id/tokens

Returns a list of existing tokens on a specific project.

Gotcha

The endpoint does not expose the actual tokens, only information about the tokens.

Example

Request

curl GET 'https://api.sanity.io/v1/projects/54n1ty10/tokens' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json'

Response

[
  {
    "id": "si3TnJKagwzJUq",
    "label": "Website preview",
    "projectUserId": "p-rbzaWnePhknL",
    "createdAt": "2020-05-08T16:16:03.775Z"
  }
]

Was this article helpful?