Projects - API Docs - Terraform Enterprise | Terraform

Create a Project

POST /organizations/:organization_name/projects

Parameter	Description
`:organization_name`	The 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 the organization 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 path	Type	Default	Description
`data.type`	string		Must be `"projects"`.
`data.attributes.name`	string		The name of 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.description`	string	(nothing)	Optional. The description of the project. It must be no more than 256 characters long.

Sample Payload

{
  "data": {
    "attributes": {
      "name": "Test Project"
      "description": "An example project for documentation."
    },
    "type": "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

PATCH /projects/:project_id

Parameter	Description
`:project_id`	The 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 path	Type	Default	Description
`data.type`	string		Must be `"projects"`.
`data.attributes.name`	string	(previous value)	A 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.description`	string	(previous value)	The new description for the project. It must be no more than 256 characters long.

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

Parameter	Description
`:organization_name`	The name of the organization to list the projects of.

Query Parameters

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

Parameter	Description
`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.
`q`	Optional. A search query string. This query searches projects by name. This search is case-insensitive. If both `q` and `filter[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.
`sort`	Optional. 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

Parameter	Description
`:project_id`	The 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
      }
    },
    "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

Parameter	Description
`:project_id`	The ID of the project to delete

Status	Response	Reason(s)
204	No Content	Successfully deleted the project
403	JSON API error object	Not authorized to perform a force delete on the project
404	JSON API error object	Project 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 on the destination project as well as any source project(s). If you are not authorized to move any of the workspaces in the request, or if any workspaces in the request are not found, then no workspaces will be moved.

POST /projects/:project_id/relationships/workspaces

Parameter	Description
`:project_id`	The ID of the destination project

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

Key path	Type	Default	Description
`data[].type`	string		Must be `"workspaces"`
`data[].id`	string		The ids of workspaces to move into the destination project

Status	Response	Reason(s)
204	No Content	Successfully moved workspace(s)
403	JSON API error object	Workspace(s) not found, or user is not authorized to move all workspaces out of their current project(s)
404	JSON API error object	Project 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"
    }
  ]
}

Projects API

Create a Project

Request Body

Sample Payload

Sample Response

Update a Project

Request Body

Sample Payload

Sample Request

Sample Response

List projects

Query Parameters

Sample Request

Sample Response

Show project

Sample Request

Sample Response

Delete a project

Sample Request

Move workspaces into a project

Sample Payload

Sample Request

Sample Error Response