_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.

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