RetroSearch Browse

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Showing content from https://developer.hashicorp.com/terraform/cloud-docs/api-docs/projects below:

/projects API reference for HCP Terraform | Terraform

This topic provides reference information about the projects API.

The scope of the API includes the following endpoints:

You must be on a team with one of the Owners or Manage projects permissions settings enabled to create and manage projects. Refer to Permissions for additional information.

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

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. 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 none 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 three characters long and no more than 40 characters long. data.attributes.description string none Optional. The description of the project. It must be no more than 256 characters long. data.attributes.auto-destroy-activity-duration string none Specifies 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 than 0 followed by either a d for days or h hours. For example, to queue destroy runs after fourteen days of inactivity set auto-destroy-activity-duration: "14d". All future workspaces in this project inherit this default value. Refer to Automatically destroy inactive workspaces for additional information. data.relationships.tag-bindings.data list of objects none Specifies a list of tags to bind to the project. Workspaces inherit the tags bound to their project. data.relationships.tag-bindings.data.type string none Must be tag-bindings for each object in the list. data.relationships.tag-bindings.data.attributes.key string none Specifies the tag key for each object in the list. data.relationships.tag-bindings.data.attributes.value string none Specifies the tag value for each object in the list. data.attributes.default-execution-mode boolean remote Specifies which execution mode to use by default. Valid values are remote, local, and agent. data.attributes.default-agent-pool string (previous value) Required when default-execution-mode is set to agent. The ID of the agent pool belonging to the project. Do not specify this value if you set execution-mode to remote or local. data.attributes.setting-overwrites object The keys in this object are attributes that have project-level defaults. Each attribute key stores a boolean value which is false by default. To overwrite the default inherited value, set an attribute's value to true. For example, to unset execution-mode as the project-level default, you set setting-overwrites.execution-mode = true. Sample Payload

{
  "data": {
    "attributes": {
      "name": "Test Project",
      "description": "An example project for documentation.",
      "default-execution-mode": "remote",
      "setting-overwrites": {
       "execution-mode": false
      }
    },
    "type": "projects",
    "relationships": {
     "default-agent-pool": {
        "data": null
     },
      "tag-bindings": {
        "data": [
          {
            "type": "tag-bindings",
            "attributes": {
              "key": "environment",
              "value": "development"
            }
          },
        ]
      }
    }
  }
}

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.",
      "default-execution-mode": "remote",
      "permissions": {
        "can-update": true
      },
      "setting-overwrites": {
        "execution-mode": false
      }
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "my-organization",
          "type": "organizations"
        },
        "links": {
          "related": "/api/v2/organizations/my-organization"
        }
      },
       "default-agent-pool": {
         "data": null
       },
      "tag-bindings": {
        "links": {
          "related": "/api/v2/projects/prj-WsVcWRr7SfxRci1v/tag-bindings"
        }
      },
      "effective-tag-bindings": {
        "links": {
          "related": "/api/v2/projects/prj-WsVcWRr7SfxRci1v/effective-tag-bindings"
        }
      }
    },
    "links": {
      "self": "/api/v2/projects/prj-WsVcWRr7SfxRci1v"
    }
  }
}

Call the following endpoint to 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 none Must be "projects". data.attributes.name string existing 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 existing value The new description for the project. It must be no more than 256 characters long. data.attributes.auto-destroy-activity-duration string none Specifies 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 than 0 followed by either a d for days or h hours. For example, to queue destroy runs after fourteen days of inactivity set auto-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 to Automatically destroy inactive workspaces for additional information. data.relationships.tag-bindings.data list of objects none Specifies a list of tags to bind to the project. Workspaces inherit the tags bound to their project. data.relationships.tag-bindings.data.type string none Must be tag-bindings for each object in the list. data.relationships.tag-bindings.data.attributes.key string none Specifies the tag key for each object in the list. data.relationships.tag-bindings.data.attributes.value string none Specifies the tag value for each object in the list. data.attributes.default-execution-mode boolean remote Specifies which execution mode to use by default. Valid values are remote, local, and agent. data.attributes.default-agent-pool string (previous value) Required when default-execution-mode is set to agent. The ID of the agent pool belonging to the project. Do not specify this value if you set execution-mode to remote or local. data.attributes.setting-overwrites object The keys in this object are attributes that have project-level defaults. Each attribute key stores a boolean value which is false by default. To overwrite the default inherited value, set an attribute's value to true. For example, to unset execution-mode as the project-level default, you set setting-overwrites.execution-mode = true. Sample Payload

{
  "data": {
    "attributes": {
      "name": "Infrastructure Project",
      "default-execution-mode": "remote",
      "setting-overwrites": {
        "execution-mode": false
      }
    },
    "type": "projects",
    "relationships": {
      "default-agent-pool": {
        "data": null
      },
      "tag-bindings": {
        "data": [
          {
            "type": "tag-bindings",
            "attributes": {
              "key": "environment",
              "value": "staging"
            }
          }
        ]
      }
    }
  }
}

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,
      "default-execution-mode": "remote",
      "permissions": {
        "can-update": true,
        "can-destroy": true,
        "can-create-workspace": true
      },
      "setting-overwrites": {
        "execution-mode": false
      }
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "my-organization",
          "type": "organizations"
        },
        "links": {
          "related": "/api/v2/organizations/my-organization"
        }
      },
      "default-agent-pool": {
         "data": null
      },
      "tag-bindings": {
        "links": {
          "related": "/api/v2/projects/prj-WsVcWRr7SfxRci1v/tag-bindings"
        }
      },
      "effective-tag-bindings": {
        "links": {
          "related": "/api/v2/projects/prj-WsVcWRr7SfxRci1v/effective-tag-bindings"
        }
      }
    },
    "links": {
      "self": "/api/v2/projects/prj-WsVcWRr7SfxRci1v"
    }
  }
}

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,
        "default-execution-mode": "remote",
        "setting-overwrites": {
          "execution-mode": false
        },
        "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"
          }
        },
        "default-agent-pool": {
          "data": null
        },
        "tag-bindings": {
          "links": {
            "related": "/api/v2/projects/prj-W6k9K23oSXRHGpj3/tag-bindings"
          }
        },
        "effective-tag-bindings": {
          "links": {
            "related": "/api/v2/projects/prj-W6k9K23oSXRHGpj3/effective-tag-bindings"
          }
        }
      },
      "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"
          }
        },
        "tag-bindings": {
          "links": {
            "related": "/api/v2/projects/prj-YoriCxAawTMDLswn/tag-bindings"
          }
        },
        "effective-tag-bindings": {
          "links": {
            "related": "/api/v2/projects/prj-YoriCxAawTMDLswn/effective-tag-bindings"
          }
        }
      },
      "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
    }
  }
}

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,
      "default-execution-mode": "remote",
      "setting-overwrites": {
        "execution-mode": false
      },
      "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"
        }
      },
      "default-agent-pool": {
        "data": null
      },
      "tag-bindings": {
        "links": {
          "related": "/api/v2/projects/prj-WsVcWRr7SfxRci1v/tag-bindings"
        }
      },
      "effective-tag-bindings": {
        "links": {
          "related": "/api/v2/projects/prj-WsVcWRr7SfxRci1v/effective-tag-bindings"
        }
      }
    },
    "links": {
      "self": "/api/v2/projects/prj-WsVcWRr7SfxRci1v"
    }
  }
}

A project cannot be deleted if it contains stacks or workspaces.

DELETE /projects/:project_id

Parameter Description :project_id The ID of the project to 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

Call the following endpoints to list the tags bound to a project.

GET /projects/:project_id/tag-bindings: Lists the set of tags associated with the project. Tags set on the project are inherited by its workspaces.

Parameter Description :project_id The ID of the project. Sample request

The following request returns all tags bound to a project with the ID prj-WsVcWRr7SfxRci1v.

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

Sample response

{
    "data": [
        {
            "type": "tag-bindings",
            "attributes": {
                "key": "added",
                "value": "new",
                "created-at": "2024-11-20T00:04:47.948Z"
            }
        },
        {
            "type": "tag-bindings",
            "attributes": {
                "key": "aww",
                "value": "aww",
                "created-at": "2024-11-20T00:04:47.948Z"
            }
        }
    ]
}

Use this endpoint to add key-value tag bindings to an existing resource or to update existing tag binding values on the resource. You cannot use this endpoint to remove tag bindings from the resource. This endpoint is useful for ensuring that a modification is additive.

Tag bindings have the following constraints and behaviors:

A project can have up to 10 tags.
All workspaces within the project inherit its tag bindings.
Keys can have up to 128 characters.
Keys support all alphanumeric characters and the symbols _, ., =, +, -, @, :.
Values can have up to 256 characters.
Values support all alphanumeric characters and the symbols _, ., =, +, -, @, :.
You cannot use hc: and hcp: as key prefixes.

PATCH /projects/:project_id/tag-bindings

Parameter Description :project_id The ID of the project to update Request Body

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

It is important to note that for each data item, type, as well as attributes.key is required.

Key path Type Default Description data[].type string Must be "tag-bindings". data[].attributes.key string The key of the tag to add or update. data[].attributes.value string The name of the tag to add or update. Sample Payload

{
  "data": [
    {
      "type": "tag-bindings",
      "attributes": {
        "key": "costcenter",
        "value": "123"
      }
    },
    {
      "type": "tag-bindings",
      "attributes": {
        "key": "bar",
        "value": "baz"
      }
    }
  ]
}

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-82d2281aa259ba09/tag-bindings

Sample Response

Example status code 200 response after updating tag bindings:

{
  "data": [
    {
      "id": "tb-e4a5847b2cf06559",
      "type": "tag-bindings",
      "attributes": {
        "key": "costcenter",
        "value": "123"
      }
    },
    {
      "id": "tb-97ce954636f93a6c",
      "type": "tag-bindings",
      "attributes": {
        "key": "bar",
        "value": "baz"
      }
    }
  ]
}

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"
    }
  ]
}

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4