Projects API

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, which can only include letters, numbers, spaces, `-`, and `_`. It must be at least 3 characters long and no more than 36 characters long.

Sample Payload

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

Sample Response

{
  "data": {
    "id": "prj-WsVcWRr7SfxRci1v",
    "type": "projects",
    "attributes": {
      "name": "Test Project",
      "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, which can only include letters, numbers, spaces, `-`, and `_`. It must be at least 3 characters long and no more than 36 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",
      "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.

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",
        "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",
        "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",
      "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	Nothing	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