Movatterモバイル変換

[0]ホーム
URL:

HashiConf 2025Don't miss the live stream of HashiConf Day 2 happening now View live stream

You are viewing documentation for version v202410-1.View latest version.

This topic provides reference information about the projects API.

The scope of the API includes the following endpoints:

MethodPathAction
POST/organizations/:organization_name/projectsCall this endpoint tocreate a project.
PATCH/projects/:project_idCall this endpoint toupdate an existing project.
GET/organizations/:organization_name/projectsCall this endpoint tolist existing projects.
GET/projects/:project_idCall this endpoint toshow project details.
DELETE/projects/:project_idCall this endpoint todelete a project.

Requirements

You must be on a team with one of theOwners orManage projects permissions settings enabled to create and manage projects. Refer toPermissions for additional information.

You can also provide an organization API token to call project API endpoints. Refer toOrganization API Tokens for additional information.

Create a Project

POST /organizations/:organization_name/projects

ParameterDescription
:organization_nameThe name of the organization to create the project in. The organization must already exist in the system, and the user must have permissions to create new projects.

Note: Project creation is restricted to the owners team, teams with the "Manage Projects" permission, and theorganization API token.

Request Body

This POST endpoint requires a JSON object with the following properties as a request payload.

Properties without a default value are required.

Key pathTypeDefaultDescription
data.typestringnoneMust be"projects".
data.attributes.namestringThe name of the project. The name can contain letters, numbers, spaces,-, and_, but cannot start or end with spaces. It must be at least three characters long and no more than 40 characters long.
data.attributes.descriptionstringnoneOptional. The description of the project. It must be no more than 256 characters long.
data.attributes.auto-destroy-activity-durationstringnoneSpecifies the default for how long each workspace in the project should wait before automatically destroying its infrastructure. You can specify a duration up to four digits that is greater than0 followed by either ad for days orh hours. For example, to queue destroy runs after fourteen days of inactivity setauto-destroy-activity-duration: "14d". All future workspaces in this project inherit this default value. Refer toAutomatically destroy inactive workspaces for additional information.

Sample Payload

{  "data": {     "attributes": {       "name": "Test Project",       "description": "An example project for documentation."     },     "type": "projects"    }}

Sample Request

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  --request POST \  --data @payload.json \  https://app.terraform.io/api/v2/organizations/my-organization/projects

Sample Response

{  "data": {    "id": "prj-WsVcWRr7SfxRci1v",    "type": "projects",    "attributes": {      "name": "Test Project",      "description": "An example project for documentation.",      "permissions": {        "can-update": true      }    },    "relationships": {      "organization": {        "data": {          "id": "my-organization",          "type": "organizations"        },        "links": {          "related": "/api/v2/organizations/my-organization"        }    },    "links": {      "self": "/api/v2/projects/prj-WsVcWRr7SfxRci1v"    }  }}

Update a Project

Call the following endpoint to update a project:

PATCH /projects/:project_id

ParameterDescription
:project_idThe ID of the project to update

Request Body

These PATCH endpoints require a JSON object with the following properties as a request payload.

Properties without a default value are required.

Key pathTypeDefaultDescription
data.typestringnoneMust be"projects".
data.attributes.namestringexisting valueA new name for the project. The name can contain letters, numbers, spaces,-, and_, but cannot start or end with spaces. It must be at least 3 characters long and no more than 40 characters long.
data.attributes.descriptionstringexisting valueThe new description for the project. It must be no more than 256 characters long.
data.attributes.auto-destroy-activity-durationstringnoneSpecifies how long each workspace in the project should wait before automatically destroying its infrastructure by default. You can specify a duration up to four digits that is greater than0 followed by either ad for days orh hours. For example, to queue destroy runs after fourteen days of inactivity setauto-destroy-activity-duration: "14d". When you update this value, all workspaces in the project receive the new value unless you previously configured an override. Refer toAutomatically destroy inactive workspaces for additional information.

Sample Payload

{  "data": {    "attributes": {      "name": "Infrastructure Project"    },    "type": "projects"  }}

Sample Request

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  --request PATCH \  --data @payload.json \  https://app.terraform.io/api/v2/projects/prj-WsVcWRr7SfxRci1v

Sample Response

{  "data": {    "id": "prj-WsVcWRr7SfxRci1v",    "type": "projects",    "attributes": {      "name": "Infrastructure Project",      "description": null,      "workspace-count": 4,      "team-count": 2,      "permissions": {        "can-update": true,        "can-destroy": true,        "can-create-workspace": true      }    },    "relationships": {      "organization": {        "data": {          "id": "my-organization",          "type": "organizations"        },        "links": {          "related": "/api/v2/organizations/my-organization"        }       }    },    "links": {      "self": "/api/v2/projects/prj-WsVcWRr7SfxRci1v"    }  }}

List projects

This endpoint lists projects in the organization.

GET /organizations/:organization_name/projects

ParameterDescription
:organization_nameThe name of the organization to list the projects of.

Query Parameters

This endpoint supports paginationwith standard URL query parameters. Remember to percent-encode[ as%5B and] as%5D if your tooling doesn't automatically encode URLs.

ParameterDescription
page[number]Optional. If omitted, the endpoint will return the first page.
page[size]Optional. If omitted, the endpoint will return 20 projects per page.
qOptional. A search query string. This query searches projects by name. This search is case-insensitive. If bothq andfilter[names] are specified,filter[names] will be used.
filter[names]Optional. If specified, returns the project with the matching name. This filter is case-insensitive. If multiple comma separated values are specified, projects matching any of the names are returned.
filter[permissions][create-workspace]Optional. If present, returns a list of projects that the authenticated user can create workspaces in.
filter[permissions][update]Optional. If present, returns a list of projects that the authenticated user can update.
sortOptional. Allows sorting the organization's projects by"name". Prepending a hyphen to the sort parameter reverses the order. For example,"-name" sorts by name in reverse alphabetical order. If omitted, the default sort order is arbitrary but stable.

Sample Request

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  https://app.terraform.io/api/v2/organizations/my-organization/projects

Sample Response

{  "data": [    {      "id": "prj-W6k9K23oSXRHGpj3",      "type": "projects",      "attributes": {        "name": "Default Project",        "description": null,        "workspace-count": 2,        "team-count": 1,        "permissions": {          "can-update": true,          "can-destroy": true,          "can-create-workspace": true        }      },      "relationships": {        "organization": {          "data": {            "id": "my-organization",            "type": "organizations"          },          "links": {            "related": "/api/v2/organizations/my-organization"          }        }      },      "links": {        "self": "/api/v2/projects/prj-W6k9K23oSXRHGpj3"      }    },    {      "id": "prj-YoriCxAawTMDLswn",      "type": "projects",      "attributes": {        "name": "Infrastructure Project",        "description": null,        "workspace-count": 4,        "team-count": 2,        "permissions": {          "can-update": true,          "can-destroy": true,          "can-create-workspace": true        }      },      "relationships": {        "organization": {          "data": {            "id": "my-organization",            "type": "organizations"          },          "links": {            "related": "/api/v2/organizations/my-organization"          }        }      },      "links": {        "self": "/api/v2/projects/prj-YoriCxAawTMDLswn"      }    }  ],  "links": {    "self": "https://app.terraform.io/api/v2/organizations/my-organization/projects?page%5Bnumber%5D=1&page%5Bsize%5D=20",    "first": "https://app.terraform.io/api/v2/organizations/my-organization/projects?page%5Bnumber%5D=1&page%5Bsize%5D=20",    "prev": null,    "next": null,    "last": "https://app.terraform.io/api/v2/organizations/my-organization/projects?page%5Bnumber%5D=1&page%5Bsize%5D=20"  },  "meta": {    "status-counts": {      "total": 2,      "matching": 2    },    "pagination": {      "current-page": 1,      "page-size": 20,      "prev-page": null,      "next-page": null,      "total-pages": 1,      "total-count": 2    }  }}

Show project

GET /projects/:project_id

ParameterDescription
:project_idThe project ID

Sample Request

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  https://app.terraform.io/api/v2/projects/prj-WsVcWRr7SfxRci1v

Sample Response

{  "data": {    "id": "prj-WsVcWRr7SfxRci1v",    "type": "projects",    "attributes": {      "name": "Infrastructure Project",      "description": null,      "workspace-count": 4,      "team-count": 2,      "permissions": {        "can-update": true,        "can-destroy": true,        "can-create-workspace": true      },      "auto-destroy-activity-duration": "2d"    },    "relationships": {      "organization": {        "data": {          "id": "my-organization",          "type": "organizations"        },        "links": {          "related": "/api/v2/organizations/my-organization"        }      }    },    "links": {      "self": "/api/v2/projects/prj-WsVcWRr7SfxRci1v"    }  }}

Delete a project

A project cannot be deleted if it contains workspaces.

DELETE /projects/:project_id

ParameterDescription
:project_idThe ID of the project to delete
StatusResponseReason(s)
204No ContentSuccessfully deleted the project
403JSON API error objectNot authorized to perform a force delete on the project
404JSON API error objectProject not found, or user unauthorized to perform project delete

Sample Request

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  --request DELETE \  https://app.terraform.io/api/v2/projects/prj-WsVcWRr7SfxRci1v

Move workspaces into a project

This endpoint allows you to move one or more workspaces into a project. You must have permission to move workspaces onthe destination project as well as any source project(s). If you are not authorized to move any of the workspaces in therequest, or if any workspaces in the request are not found, then no workspaces will be moved.

POST /projects/:project_id/relationships/workspaces

ParameterDescription
:project_idThe ID of the destination project

This POST endpoint requires a JSON object with the following properties as a request payload.

Key pathTypeDefaultDescription
data[].typestringMust be"workspaces"
data[].idstringThe ids of workspaces to move into the destination project
StatusResponseReason(s)
204No ContentSuccessfully moved workspace(s)
403JSON API error objectWorkspace(s) not found, or user is not authorized to move all workspaces out of their current project(s)
404JSON API error objectProject not found, or user unauthorized to move workspaces into project

Sample Payload

{  "data": [    {      "type": "workspaces",      "id": "ws-AQEct2XFuH4HBsmS"    }  ]}

Sample Request

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  --request POST \  --data @payload.json \  https://app.terraform.io/api/v2/projects/prj-zXm4y2BjeGPgHtkp/relationships/workspaces

Sample Error Response

{  "errors": [    {      "status": "403",      "title": "forbidden",      "detail": "Workspace(s) not found, or you are not authorized to move them: ws-AQEct2XFuH4HBmS"    }  ]}
Edit this page on GitHub
[8]ページ先頭
©2009-2025 Movatter.jp