Create tag

POST /api/v3/tags

Request

Response

URL

POST https://example.aha.io/api/v3/tags

JSON body

{
  "record": {
    "name": "Example record"
  }
}

cURL command

curl --request POST 'https://example.aha.io/api/v3/tags' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "record": {
    "name": "Example record"
  }
}'

Request conventions

API key or OAuth2 access token. See Authentication.

Use your account domain and token in copied requests. Request values and conditional fields must satisfy your account’s validation rules.

URL settings

Account subdomain

The part before .aha.io. Leave blank to use the example domain.

Request fields

Send fields for the new record inside a JSON record object.

Only writable fields for this endpoint are listed. Required flags reflect the endpoint schema; record and workspace validation also applies.

Search request fields

Field	Type	Response field
Name of the record.	string	`name`
Include name in request Value for name Accepted value shape and constraints Type: `string`
Type of the tag. research requires Aha! Discovery.	string	`type`
Include type in request Accepted value shape and constraints Type: `string` Allowed values: "general", "research" Allowed values: `generalresearch`
Color assigned to the record as a hex value.	string	`color`
Include color in request Accepted value shape and constraints Type: `string`

Response fields

Choose which fields to include in the response. Expand a field for examples and associated fields. Collections can only be returned on the top-level resource, not inside an associated resource.

Default response fields are returned until you select specific fields.

Search fields

Field	Type	Returned by default
Unique record ID.	integer	Yes
Include id in response
Name of the record.	string	Yes
Include name in response
Type of the tag. research requires Aha! Discovery.	string	No
Include type in response Allowed values: `generalresearch`
Color assigned to the record as a hex value.	string	No
Include color in response

Search matches the start of a field path and includes matching associations’ subfields. Use a dotted path to search within a specific association.

Response field selection

Create and update responses also include fields submitted in the record body. Submitted association IDs return their associated response fields.

Return selected fields with a comma-separated fields parameter, or add a field to the defaults with fields=default,{field}. Expand an association above for its supported subfields and selection examples.

See field selection for details.

Response statuses

Error shape for 400, 401, 403, 404, 409

Type: object

error

Type: object

Required properties: status, code, message, request_id.

status

Type: integer

code

Type: string

message

Type: string

request_id

Type: string

Error shape for 422

Type: object

error

Type: object

Required properties: status, code, message, details, request_id.

status

Type: integer

Allowed values: 422

code

Type: string

Allowed values: "record.validation_failed", "record.cannot_delete"

message

Type: string

details

Type: array

Array item shape

Type: object

field

Type: string

message

Type: string

code

Type: string

request_id

Type: string

Response envelope and pagination

record: a single record. Fields are documented above.

Download the complete OpenAPI specification