Example name API reference

Follow this template to format each API method. An API endpoint page usually contains multiple sections that follow this format.

Describe what this resource is in HCP Terraform in one sentence.

Create a something

Add at least one sentence of description about what this endpoint does.

POST /organizations/:organization_name/somethings

Parameter	Description
`:organization_name`	The name of the organization to create the something in. The organization must already exist, and you must have permission to create somethings.

Provide a user token or team token to access this endpoint. It does not accept organization tokens.

Status	Response	Reason
200	JSON API document with `type: "somethings"`	Created the something
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, such as missing attributes or wrong types
500	JSON API error object	Failure during something creation

Query parameters

Use the standard query parameters to modify the request. Percent-encode [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs.

Parameter	Required	Description
`filter[workspace][id]`	Yes	The ID of the workspace to perform the action in.

Request body

Send a JSON object with the following properties in the request payload. Properties without a default value are required.

Key path	Type	Default	Description
`data.type`	string		Must be `"somethings"`.
`data[].type`	string		Must be `"somethings"`. Use this key path when `data` is an array of objects.
`data.attributes.category`	string		Whether this is a blue or red something. Valid values are `"blue"` or `"red"`.
`data.attributes.sensitive`	boolean	`false`	Whether the value is sensitive. If `true`, you can write the something once, and it is not visible afterward.
`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.

Call the GET endpoint with the include query parameter to retrieve related resources. 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"
    }
  }
}