_template
Follow this template to format each API method. There are usually multiple sections like this on a given API endpoint page.
Create a Something
POST /organizations/:organization_name/somethings
Parameter | Description |
---|---|
:organization_name | The name of the organization to create the something in. The organization must already exist in the system, and the user must have permissions to create new somethings. |
Note: This endpoint cannot be accessed with organization tokens. You must access it with a user token or team token.
Status | Response | Reason |
---|---|---|
200 | JSON API document (type: "somethings" ) | Successfully created a team |
400 | JSON API error object | Invalid include parameter |
404 | JSON API error object | Organization not found, or user unauthorized to perform action |
422 | JSON API error object | Malformed request body (missing attributes, wrong types, etc.) |
500 | JSON API error object | Failure during team creation |
Query Parameters
These are standard URL query parameters; remember to percent-encode [
as %5B
and ]
as %5D
if your tooling doesn't automatically encode URLs.
Parameter | Description |
---|---|
filter[workspace][id] | Required. The workspace ID where this action will happen. |
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 "somethings" . | |
data[].type | string | ... | |
data.attributes.category | string | Whether this is a blue or red something. Valid values are "blue" or "red" . | |
data.attributes.sensitive | bool | false | Whether the value is sensitive. If true then the something is written once and not visible thereafter. |
filter.workspace.name | string | The name of the workspace that owns the something. | |
filter.organization.name | string | The name of the organization that owns the workspace. |
Available Related Resources
This GET endpoint can optionally return related resources, if requested with the include
query parameter. The following resource types are available:
Resource Name | Description |
---|---|
organization | The full organization record. |
current_run | Additional information about the current run. |
current_run.plan | The plan used in the current run. |
Sample Payload
{ "data": { "type":"somethings", "attributes": { "category":"red", "sensitive":true } }, "filter": { "organization": { "name":"my-organization" }, "workspace": { "name":"my-workspace" } }}
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/somethings
Sample Response
{ "data": { "id":"som-EavQ1LztoRTQHSNT", "type":"somethings", "attributes": { "sensitive":true, "category":"red", }, "relationships": { "configurable": { "data": { "id":"ws-4j8p6jX1w33MiDC7", "type":"workspaces" }, "links": { "related":"/api/v2/organizations/my-organization/workspaces/my-workspace" } } }, "links": { "self":"/api/v2/somethings/som-EavQ1LztoRTQHSNT" } }}