Resource groups
Named boxes drawn around resources on the project overview's resource graph. Groups nest, a resource sits in at most one, and they change only how the project is drawn — nothing a group holds behaves any differently for being in it.
Every group in the project, ordered by name. Groups are named boxes drawn around resources
on the project overview; a group with a parentId is nested inside that group.
Auth: a project API key carrying projects:read.
Authorization
apiKey A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.
In: header
Path Parameters
1 <= lengthResponse Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/projects/string/resource-groups"{ "success": true, "data": [ { "id": "string", "name": "string", "parentId": "string" } ]}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}Creates a group at the top level, or inside parentId. Groups nest up to five levels deep,
and a project can hold up to 100 of them.
Members with the viewer role cannot change groups.
Auth: a project API key carrying all of projects:read and projects:write.
Authorization
apiKey A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.
In: header
Path Parameters
1 <= lengthRequest Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/projects/string/resource-groups" \ -H "Content-Type: application/json" \ -d '{ "name": "string" }'{ "success": true, "data": { "id": "string", "name": "string", "parentId": "string" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}Renames the group, moves it, or both. Send parentId: null to move it to the top level;
leave parentId out to keep it where it is. Its subgroups and resources move with it.
Members with the viewer role cannot change groups.
Auth: a project API key carrying all of projects:read and projects:write.
Authorization
apiKey A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.
In: header
Path Parameters
1 <= length1 <= lengthRequest Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PATCH "https://example.com/v1/projects/string/resource-groups/string" \ -H "Content-Type: application/json" \ -d '{}'{ "success": true, "data": { "id": "string", "name": "string", "parentId": "string" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}Removes the group. Its resources and subgroups move up into its parent — or to the top level for a top-level group. No resource is changed or deleted.
Members with the viewer role cannot change groups.
Auth: a project API key carrying all of projects:read and projects:write.
Authorization
apiKey A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.
In: header
Path Parameters
1 <= length1 <= lengthResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X DELETE "https://example.com/v1/projects/string/resource-groups/string"{ "success": true, "data": null}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}Puts a resource in a group, or takes it out of its group with groupId: null. A resource
sits in at most one group, so placing it moves it out of any group it was in.
Container repositories and git repositories cannot be placed directly: a repository is shown in its registry's group, and a git repository with the apps that deploy from it.
Members with the viewer role cannot change groups.
Auth: a project API key carrying all of projects:read and projects:write.
Authorization
apiKey A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.
In: header
Path Parameters
1 <= lengthRequest Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PUT "https://example.com/v1/projects/string/resource-groups/assignment" \ -H "Content-Type: application/json" \ -d '{ "kind": "app", "resourceId": "string", "groupId": "string" }'{ "success": true, "data": { "groupId": "string" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}Projects
A project is the unit of ownership and billing: every resource belongs to exactly one, and an API key reaches exactly one. Address a project by its `id` or its `slug` — both are accepted wherever `{projectId}` appears.
Members
The people in a project, each holding one role: `viewer`, `developer`, `admin` or `owner`. Viewers are read-only across the API. Developers create, change, deploy and delete the project's resources, billable ones included, but cannot change its members, plans, API keys, secrets, variables or settings. Admins can do everything except delete the project, which is the owner's alone. The payment method, refunds and service agreements are the biller's, whatever their role. Only an owner can grant the owner role, change an owner's role or remove an owner. [Team roles](/docs/guides/team-roles) lists exactly what each role may do; a request the caller's role does not allow is refused with `403 INSUFFICIENT_ROLE`. Exactly one member is the **biller**, responsible for paying for the project. The biller cannot be removed, or leave, while they hold that responsibility — the attempt is refused with `409 BILLER_CANNOT_LEAVE` — so transfer it to another member first. Inviting, removing and changing the role of a member are done from the control panel by a signed-in owner or admin, never with an API key: a key is refused with `401 API_KEY_NOT_ALLOWED`. A pending invitation can be cancelled through the API.