All API requests require a Supabase Personal token to be included in the Authorization header: Authorization Bearer <supabase_personal_token. To generate or manage your API token, visit your account page. Your API tokens carry the same privileges as your user account, so be sure to keep it secret.


_10  curl https://api.supabase.com/v1/projects \
_10  -H "Authorization: Bearer sbp_bdd0••••••••••••••••••••••••••••••••4f23"

All API requests must be authenticated and made over HTTPS.

Rate limits#

The API is currently subject to our fair-use policy. In the future, are likely to introduce rate limits. All resources created via the API are subject to the pricing detailed on our Pricing pages.

Additional links

List all projects

get/v1/projects

Returns a list of all projects you've previously created.

Responses

1{
2  "schema": {
3    "type": "array",
4    "items": {
5      "type": "object",
6      "properties": {
7        "id": {
8          "type": "string",
9          "description": "Id of your project"
10        },
11        "organization_id": {
12          "type": "string",
13          "description": "Slug of your organization"
14        },
15        "name": {
16          "type": "string",
17          "description": "Name of your project"
18        },
19        "region": {
20          "type": "string",
21          "description": "Region of your project",
22          "example": "us-east-1"
23        },
24        "created_at": {
25          "type": "string",
26          "description": "Creation timestamp",
27          "example": "2023-03-29T16:32:59Z"
28        },
29        "database": {
30          "type": "object",
31          "properties": {
32            "host": {
33              "type": "string",
34              "description": "Database host"
35            },
36            "version": {
37              "type": "string",
38              "description": "Database version"
39            }
40          },
41          "required": [
42            "host",
43            "version"
44          ]
45        }
46      },
47      "required": [
48        "id",
49        "organization_id",
50        "name",
51        "region",
52        "created_at"
53      ]
54    }
55  }
56}

Create a project

post/v1/projects

Responses

1{
2  "schema": {
3    "type": "object",
4    "properties": {
5      "id": {
6        "type": "string",
7        "description": "Id of your project"
8      },
9      "organization_id": {
10        "type": "string",
11        "description": "Slug of your organization"
12      },
13      "name": {
14        "type": "string",
15        "description": "Name of your project"
16      },
17      "region": {
18        "type": "string",
19        "description": "Region of your project",
20        "example": "us-east-1"
21      },
22      "created_at": {
23        "type": "string",
24        "description": "Creation timestamp",
25        "example": "2023-03-29T16:32:59Z"
26      },
27      "database": {
28        "type": "object",
29        "properties": {
30          "host": {
31            "type": "string",
32            "description": "Database host"
33          },
34          "version": {
35            "type": "string",
36            "description": "Database version"
37          }
38        },
39        "required": [
40          "host",
41          "version"
42        ]
43      }
44    },
45    "required": [
46      "id",
47      "organization_id",
48      "name",
49      "region",
50      "created_at"
51    ]
52  }
53}

List all organizations

get/v1/organizations

Returns a list of organizations that you currently belong to.

Responses

1{
2  "schema": {
3    "type": "array",
4    "items": {
5      "type": "object",
6      "properties": {
7        "id": {
8          "type": "string"
9        },
10        "name": {
11          "type": "string"
12        }
13      },
14      "required": [
15        "id",
16        "name"
17      ]
18    }
19  }
20}

Create an organization

post/v1/organizations

Responses

1{
2  "schema": {
3    "type": "object",
4    "properties": {
5      "id": {
6        "type": "string"
7      },
8      "name": {
9        "type": "string"
10      }
11    },
12    "required": [
13      "id",
14      "name"
15    ]
16  }
17}

List all secrets

get/v1/projects/{ref}/secrets

Returns all secrets you've previously added to the specified project.

Path Parameters

ref

REQUIRED

no type

Project ref

Responses

1{
2  "schema": {
3    "type": "array",
4    "items": {
5      "type": "object",
6      "properties": {
7        "name": {
8          "type": "string"
9        },
10        "value": {
11          "type": "string"
12        }
13      },
14      "required": [
15        "name",
16        "value"
17      ]
18    }
19  }
20}

Bulk create secrets

post/v1/projects/{ref}/secrets

Creates multiple secrets and adds them to the specified project.

Path Parameters

ref

REQUIRED

no type

Project ref

Responses

Bulk delete secrets

delete/v1/projects/{ref}/secrets

Deletes all secrets with the given names from the specified project

Path Parameters

ref

REQUIRED

no type

Project ref

Responses

1{
2  "schema": {
3    "type": "object"
4  }
5}

Generate TypeScript types

get/v1/projects/{ref}/types/typescript

Returns the TypeScript types of your schema for use with supabase-js.

Path Parameters

ref

REQUIRED

no type

Project ref

Query Parameters

included_schemas

Optional

no type

Responses

1{
2  "schema": {
3    "type": "object",
4    "properties": {
5      "types": {
6        "type": "string"
7      }
8    },
9    "required": [
10      "types"
11    ]
12  }
13}

Create a function

post/v1/projects/{ref}/functions

Creates a function and adds it to the specified project.

Path Parameters

ref

REQUIRED

no type

Project ref

Query Parameters

slug

Optional

no type

name

Optional

no type

verify_jwt

Optional

no type

import_map

Optional

no type

entrypoint_path

Optional

no type

import_map_path

Optional

no type

Responses

1{
2  "schema": {
3    "type": "object",
4    "properties": {
5      "id": {
6        "type": "string"
7      },
8      "slug": {
9        "type": "string"
10      },
11      "name": {
12        "type": "string"
13      },
14      "status": {
15        "enum": [
16          "ACTIVE",
17          "REMOVED",
18          "THROTTLED"
19        ],
20        "type": "string"
21      },
22      "version": {
23        "type": "number"
24      },
25      "created_at": {
26        "type": "number"
27      },
28      "updated_at": {
29        "type": "number"
30      },
31      "verify_jwt": {
32        "type": "boolean"
33      },
34      "import_map": {
35        "type": "boolean"
36      },
37      "entrypoint_path": {
38        "type": "string"
39      },
40      "import_map_path": {
41        "type": "string"
42      }
43    },
44    "required": [
45      "id",
46      "slug",
47      "name",
48      "status",
49      "version",
50      "created_at",
51      "updated_at"
52    ]
53  }
54}

List all functions

get/v1/projects/{ref}/functions

Returns all functions you've previously added to the specified project.

Path Parameters

ref

REQUIRED

no type

Project ref

Responses

1{
2  "schema": {
3    "type": "array",
4    "items": {
5      "type": "object",
6      "properties": {
7        "id": {
8          "type": "string"
9        },
10        "slug": {
11          "type": "string"
12        },
13        "name": {
14          "type": "string"
15        },
16        "status": {
17          "enum": [
18            "ACTIVE",
19            "REMOVED",
20            "THROTTLED"
21          ],
22          "type": "string"
23        },
24        "version": {
25          "type": "number"
26        },
27        "created_at": {
28          "type": "number"
29        },
30        "updated_at": {
31          "type": "number"
32        },
33        "verify_jwt": {
34          "type": "boolean"
35        },
36        "import_map": {
37          "type": "boolean"
38        },
39        "entrypoint_path": {
40          "type": "string"
41        },
42        "import_map_path": {
43          "type": "string"
44        }
45      },
46      "required": [
47        "id",
48        "slug",
49        "name",
50        "status",
51        "version",
52        "created_at",
53        "updated_at"
54      ]
55    }
56  }
57}

Retrieve a function

get/v1/projects/{ref}/functions/{function_slug}

Retrieves a function with the specified slug and project.

Path Parameters

ref

REQUIRED

no type

Project ref

function_slug

REQUIRED

no type

Function slug

Responses

1{
2  "schema": {
3    "type": "object",
4    "properties": {
5      "id": {
6        "type": "string"
7      },
8      "slug": {
9        "type": "string"
10      },
11      "name": {
12        "type": "string"
13      },
14      "status": {
15        "enum": [
16          "ACTIVE",
17          "REMOVED",
18          "THROTTLED"
19        ],
20        "type": "string"
21      },
22      "version": {
23        "type": "number"
24      },
25      "created_at": {
26        "type": "number"
27      },
28      "updated_at": {
29        "type": "number"
30      },
31      "verify_jwt": {
32        "type": "boolean"
33      },
34      "import_map": {
35        "type": "boolean"
36      },
37      "entrypoint_path": {
38        "type": "string"
39      },
40      "import_map_path": {
41        "type": "string"
42      }
43    },
44    "required": [
45      "id",
46      "slug",
47      "name",
48      "status",
49      "version",
50      "created_at",
51      "updated_at"
52    ]
53  }
54}

Update a function

patch/v1/projects/{ref}/functions/{function_slug}

Updates a function with the specified slug and project.

Path Parameters

ref

REQUIRED

no type

Project ref

function_slug

REQUIRED

no type

Function slug

Query Parameters

slug

Optional

no type

name

Optional

no type

verify_jwt

Optional

no type

import_map

Optional

no type

entrypoint_path

Optional

no type

import_map_path

Optional

no type

Responses

1{
2  "schema": {
3    "type": "object",
4    "properties": {
5      "id": {
6        "type": "string"
7      },
8      "slug": {
9        "type": "string"
10      },
11      "name": {
12        "type": "string"
13      },
14      "status": {
15        "enum": [
16          "ACTIVE",
17          "REMOVED",
18          "THROTTLED"
19        ],
20        "type": "string"
21      },
22      "version": {
23        "type": "number"
24      },
25      "created_at": {
26        "type": "number"
27      },
28      "updated_at": {
29        "type": "number"
30      },
31      "verify_jwt": {
32        "type": "boolean"
33      },
34      "import_map": {
35        "type": "boolean"
36      },
37      "entrypoint_path": {
38        "type": "string"
39      },
40      "import_map_path": {
41        "type": "string"
42      }
43    },
44    "required": [
45      "id",
46      "slug",
47      "name",
48      "status",
49      "version",
50      "created_at",
51      "updated_at"
52    ]
53  }
54}

Delete a function

delete/v1/projects/{ref}/functions/{function_slug}

Deletes a function with the specified slug from the specified project.

Path Parameters

ref

REQUIRED

no type

Project ref

function_slug

REQUIRED

no type

Function slug

Responses

Retrieve a function body

get/v1/projects/{ref}/functions/{function_slug}/body

Retrieves a function body for the specified slug and project.

Path Parameters

ref

REQUIRED

no type

Project ref

function_slug

REQUIRED

no type

Function slug

Responses

Gets project's custom hostname config

get/v1/projects/{ref}/custom-hostname

Path Parameters

ref

REQUIRED

no type

Project ref

Responses

1{
2  "schema": {
3    "type": "object",
4    "properties": {
5      "status": {
6        "enum": [
7          "1_not_started",
8          "2_initiated",
9          "3_challenge_verified",
10          "4_origin_setup_completed",
11          "5_services_reconfigured"
12        ],
13        "type": "string"
14      },
15      "custom_hostname": {
16        "type": "string"
17      },
18      "data": {
19        "type": "object"
20      }
21    },
22    "required": [
23      "status",
24      "custom_hostname",
25      "data"
26    ]
27  }
28}

Deletes a project's custom hostname configuration

delete/v1/projects/{ref}/custom-hostname

Path Parameters

ref

REQUIRED

no type

Project ref

Responses

Updates project's custom hostname configuration

post/v1/projects/{ref}/custom-hostname/initialize

Path Parameters

ref

REQUIRED

no type

Project ref

Responses

1{
2  "schema": {
3    "type": "object",
4    "properties": {
5      "status": {
6        "enum": [
7          "1_not_started",
8          "2_initiated",
9          "3_challenge_verified",
10          "4_origin_setup_completed",
11          "5_services_reconfigured"
12        ],
13        "type": "string"
14      },
15      "custom_hostname": {
16        "type": "string"
17      },
18      "data": {
19        "type": "object"
20      }
21    },
22    "required": [
23      "status",
24      "custom_hostname",
25      "data"
26    ]
27  }
28}

Attempts to verify the DNS configuration for project's custom hostname configuration

post/v1/projects/{ref}/custom-hostname/reverify

Path Parameters

ref

REQUIRED

no type

Project ref

Responses

1{
2  "schema": {
3    "type": "object",
4    "properties": {
5      "status": {
6        "enum": [
7          "1_not_started",
8          "2_initiated",
9          "3_challenge_verified",
10          "4_origin_setup_completed",
11          "5_services_reconfigured"
12        ],
13        "type": "string"
14      },
15      "custom_hostname": {
16        "type": "string"
17      },
18      "data": {
19        "type": "object"
20      }
21    },
22    "required": [
23      "status",
24      "custom_hostname",
25      "data"
26    ]
27  }
28}

Activates a custom hostname for a project.

post/v1/projects/{ref}/custom-hostname/activate

Path Parameters

ref

REQUIRED

no type

Project ref

Responses

1{
2  "schema": {
3    "type": "object",
4    "properties": {
5      "status": {
6        "enum": [
7          "1_not_started",
8          "2_initiated",
9          "3_challenge_verified",
10          "4_origin_setup_completed",
11          "5_services_reconfigured"
12        ],
13        "type": "string"
14      },
15      "custom_hostname": {
16        "type": "string"
17      },
18      "data": {
19        "type": "object"
20      }
21    },
22    "required": [
23      "status",
24      "custom_hostname",
25      "data"
26    ]
27  }
28}

Gets project's pgsodium config

get/v1/projects/{ref}/pgsodium

Path Parameters

ref

REQUIRED

no type

Project ref

Responses

1{
2  "schema": {
3    "type": "object",
4    "properties": {
5      "root_key": {
6        "type": "string"
7      }
8    },
9    "required": [
10      "root_key"
11    ]
12  }
13}

Updates project's pgsodium config. Updating the root_key can cause all data encrypted with the older key to become inaccessible.

put/v1/projects/{ref}/pgsodium

Path Parameters

ref

REQUIRED

no type

Project ref

Responses

1{
2  "schema": {
3    "type": "object",
4    "properties": {
5      "root_key": {
6        "type": "string"
7      }
8    },
9    "required": [
10      "root_key"
11    ]
12  }
13}

Gets project's network bans

post/v1/projects/{ref}/network-bans/retrieve

Path Parameters

ref

REQUIRED

no type

Project ref

Responses

1{
2  "schema": {
3    "type": "object",
4    "properties": {
5      "banned_ipv4_addresses": {
6        "type": "array",
7        "items": {
8          "type": "string"
9        }
10      }
11    },
12    "required": [
13      "banned_ipv4_addresses"
14    ]
15  }
16}

Remove network bans.

delete/v1/projects/{ref}/network-bans

Path Parameters

ref

REQUIRED

no type

Project ref

Responses

Gets project's network restrictions

get/v1/projects/{ref}/network-restrictions

Path Parameters

ref

REQUIRED

no type

Project ref

Responses

1{
2  "schema": {
3    "type": "object",
4    "properties": {
5      "entitlement": {
6        "enum": [
7          "disallowed",
8          "allowed"
9        ],
10        "type": "string"
11      },
12      "config": {
13        "type": "object",
14        "properties": {
15          "dbAllowedCidrs": {
16            "type": "array",
17            "items": {
18              "type": "string"
19            }
20          }
21        },
22        "required": [
23          "dbAllowedCidrs"
24        ]
25      },
26      "old_config": {
27        "type": "object",
28        "properties": {
29          "dbAllowedCidrs": {
30            "type": "array",
31            "items": {
32              "type": "string"
33            }
34          }
35        },
36        "required": [
37          "dbAllowedCidrs"
38        ]
39      },
40      "status": {
41        "enum": [
42          "stored",
43          "applied"
44        ],
45        "type": "string"
46      }
47    },
48    "required": [
49      "entitlement",
50      "config",
51      "status"
52    ]
53  }
54}

Updates project's network restrictions

post/v1/projects/{ref}/network-restrictions/apply

Path Parameters

ref

REQUIRED

no type

Project ref

Responses

1{
2  "schema": {
3    "type": "object",
4    "properties": {
5      "entitlement": {
6        "enum": [
7          "disallowed",
8          "allowed"
9        ],
10        "type": "string"
11      },
12      "config": {
13        "type": "object",
14        "properties": {
15          "dbAllowedCidrs": {
16            "type": "array",
17            "items": {
18              "type": "string"
19            }
20          }
21        },
22        "required": [
23          "dbAllowedCidrs"
24        ]
25      },
26      "old_config": {
27        "type": "object",
28        "properties": {
29          "dbAllowedCidrs": {
30            "type": "array",
31            "items": {
32              "type": "string"
33            }
34          }
35        },
36        "required": [
37          "dbAllowedCidrs"
38        ]
39      },
40      "status": {
41        "enum": [
42          "stored",
43          "applied"
44        ],
45        "type": "string"
46      }
47    },
48    "required": [
49      "entitlement",
50      "config",
51      "status"
52    ]
53  }
54}

Need some help?
Contact support
Latest product updates?
See Changelog
Something's not right?
Check system status