Home

Management API

Manage your Supabase organizations and projects programmatically.

Status#

The Management API is in beta. It is usable in it's current state, but it's likely that there will be breaking changes.

Authentication#

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.

1  curl https://api.supabase.com/v1/projects \
2  -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
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    },
38    "required": [
39      "id",
40      "slug",
41      "name",
42      "status",
43      "version",
44      "created_at",
45      "updated_at"
46    ]
47  }
48}

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      },
40      "required": [
41        "id",
42        "slug",
43        "name",
44        "status",
45        "version",
46        "created_at",
47        "updated_at"
48      ]
49    }
50  }
51}

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    },
38    "required": [
39      "id",
40      "slug",
41      "name",
42      "status",
43      "version",
44      "created_at",
45      "updated_at"
46    ]
47  }
48}

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
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    },
38    "required": [
39      "id",
40      "slug",
41      "name",
42      "status",
43      "version",
44      "created_at",
45      "updated_at"
46    ]
47  }
48}

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}
© Supabase Inc—ContributingAuthor StyleguideOpen SourceSupaSquad