Projects
Create, find, change and delete projects.
A project groups the apps of one product. See How Teral is organized.
Create a project
POST /v1/projects.createProject
Creates an empty project. Add apps to it with apps.createApp.
Permissions: the key needs project.*.create_project.
Request
| Field | Type | Description |
|---|---|---|
name | string, required | The project's name, shown in the dashboard. 1 to 256 characters. |
slug | string, required | The project's slug: lowercase letters, digits and hyphens. It appears in every generated URL of the project's apps and must be unique in the workspace. 3 to 255 characters. |
curl -X POST https://api.teral.dev/v1/projects.createProject \
-H "Authorization: Bearer $TERAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Shop",
"slug": "shop"
}'Response
On success the status is 200 OK. The fields in data:
| Field | Type | Description |
|---|---|---|
id | string | The new project's ID. 8 to 255 characters. |
Error statuses: 400, 401, 403, 409, 429, 500. See Errors for the codes behind them.
List projects
POST /v1/projects.listProjects
Returns the workspace's projects, a page at a time.
Permissions: the key needs project.*.read_project.
Request
| Field | Type | Description |
|---|---|---|
limit | integer | How many results to return in one page. Default 100. 1 to 100. |
cursor | string | The pagination.cursor of the previous response, to get the next page. |
search | string | Only return projects whose ID, name or slug contains this text. Not case sensitive. At most 256 characters. |
curl -X POST https://api.teral.dev/v1/projects.listProjects \
-H "Authorization: Bearer $TERAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"limit": 20
}'Response
On success the status is 200 OK. The fields in data:
| Field | Type | Description |
|---|---|---|
id | string | The project's ID. |
name | string | The project's name. |
slug | string | The project's slug. |
createdAt | integer | When it was created, in Unix milliseconds. 0 to 9223372036854776000. |
updatedAt | integer | When it last changed, in Unix milliseconds. Missing if it never changed. 0 to 9223372036854776000. |
deleteProtection | boolean | Whether delete protection is on. A protected project can't be deleted. |
When pagination.hasMore is true, pass pagination.cursor as cursor to get the next page.
Error statuses: 400, 401, 403, 429, 500. See Errors for the codes behind them.
Get a project
POST /v1/projects.getProject
Returns one project.
Permissions: the key needs one of project.*.read_project, project.<project_id>.read_project.
Request
| Field | Type | Description |
|---|---|---|
project | string, required | The project, by ID (proj_…) or slug. 3 to 255 characters. |
curl -X POST https://api.teral.dev/v1/projects.getProject \
-H "Authorization: Bearer $TERAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"project": "shop"
}'Response
On success the status is 200 OK. The fields in data:
| Field | Type | Description |
|---|---|---|
id | string | The project's ID. |
name | string | The project's name. |
slug | string | The project's slug. |
createdAt | integer | When it was created, in Unix milliseconds. 0 to 9223372036854776000. |
updatedAt | integer | When it last changed, in Unix milliseconds. Missing if it never changed. 0 to 9223372036854776000. |
deleteProtection | boolean | Whether delete protection is on. A protected project can't be deleted. |
Error statuses: 400, 401, 403, 404, 429, 500. See Errors for the codes behind them.
Update a project
POST /v1/projects.updateProject
Changes a project's name, slug or delete protection. Fields you leave out stay as they are. A new slug changes the generated URLs of the project's apps from their next deployment.
Permissions: the key needs one of project.*.update_project, project.<project_id>.update_project.
Request
| Field | Type | Description |
|---|---|---|
project | string, required | The project, by ID or slug. 3 to 255 characters. |
slug | string | A new slug. 3 to 255 characters. |
name | string | A new name. 1 to 256 characters. |
deleteProtection | boolean | Turns delete protection on or off. |
curl -X POST https://api.teral.dev/v1/projects.updateProject \
-H "Authorization: Bearer $TERAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"project": "shop",
"deleteProtection": true
}'Response
On success the status is 200 OK. The fields in data:
| Field | Type | Description |
|---|---|---|
id | string | The project's ID. |
name | string | The project's name. |
slug | string | The project's slug. |
createdAt | integer | When it was created, in Unix milliseconds. 0 to 9223372036854776000. |
updatedAt | integer | When it last changed, in Unix milliseconds. Missing if it never changed. 0 to 9223372036854776000. |
deleteProtection | boolean | Whether delete protection is on. A protected project can't be deleted. |
Error statuses: 400, 401, 403, 404, 409, 429, 500. See Errors for the codes behind them.
Delete a project
POST /v1/projects.deleteProject
Deletes a project with all its apps, deployments, domains and variables. The response comes right away and the cleanup runs in the background. Fails with 412 while delete protection is on.
Permissions: the key needs one of project.*.delete_project, project.<project_id>.delete_project.
Request
| Field | Type | Description |
|---|---|---|
project | string, required | The project, by ID or slug. 3 to 255 characters. |
curl -X POST https://api.teral.dev/v1/projects.deleteProject \
-H "Authorization: Bearer $TERAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"project": "shop"
}'Response
On success the status is 202 Accepted.
Error statuses: 400, 401, 403, 404, 412, 429, 500. See Errors for the codes behind them.