Create tag

Creates a tag. Tags are cross-cutting labels applied to prompts and to competitors from one brand-level pool, and their ids are the values for the tag_id filter on the reads.

The slug is derived from the name and must be unique within the brand. You cannot set it directly: a tag created here and a tag created in the app must be indistinguishable afterwards.

Requires the write:tags scope, and the workspace must be enabled for API writes.


POST /v1/brands/{brand_id}/tags

Authorization

Header	Type	Required
`Authorization`	`Bearer asky_sk_…`	required
`Idempotency-Key`	`string`	required

Path parameters

Parameter	Type	Required	Description
`brand_id`	`uuid`	required	From List brands

Query parameters

None.

Any parameter you pass returns 400 invalid_request naming the offending key.

Body

application/json

Field	Type	Required	Description
`name`	`string`, 1–64 chars	required	Must contain at least one letter or number. Its derived slug must be unique in the brand
`color`	`string \| null`	optional	Hex value like `#4F46E5`. Rendered as the tag chip
`description`	`string \| null`, up to 200 chars	optional

Request

cURL


curl --request POST \
  --url 'https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/tags' \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Idempotency-Key: <unique-per-attempt>' \
  --header 'Content-Type: application/json' \
  --data '{"name":"Bottom funnel","color":"#4F46E5"}'

Python


import requests
 
url = "https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/tags"
headers = {"Authorization": "Bearer <api-key>", "Idempotency-Key": "<unique-per-attempt>"}
payload = {"name": "Bottom funnel", "color": "#4F46E5"}
 
response = requests.post(url, json=payload, headers=headers)
print(response.text)

JavaScript


const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <api-key>', 'Idempotency-Key': '<unique-per-attempt>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: 'Bottom funnel', color: '#4F46E5'})
};
 
fetch('https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/tags', options)
  .then(res => res.json()).then(res => console.log(res)).catch(err => console.error(err));

Response

200


{
  "data": {
    "tag": {
      "id": "9f2c1d84-6b31-4a2e-9c77-1e5b0a3f8d42",
      "name": "Bottom funnel",
      "slug": "bottom-funnel",
      "color": "#4F46E5",
      "description": null
    }
  },
  "request_id": "req_7d21b0af59c34e18b6ac"
}

409


{
  "error": {
    "code": "conflict",
    "message": "A tag with the slug \"bottom-funnel\" already exists for this brand.",
    "request_id": "req_4c81a0be29d34f1a6b72"
  }
}

403


{
  "error": {
    "code": "insufficient_scope",
    "message": "This action requires the \"write:tags\" scope, which your token does not have.",
    "request_id": "req_2a71d0ce38f14b9c7d05"
  }
}

404


{
  "error": {
    "code": "not_found",
    "message": "Not found.",
    "request_id": "req_5b0e77d213a94f6a8ce1"
  }
}

Response fields

Field	Type	Description
`data.tag.id`	`uuid`	required. Use it as a `tag_id` filter value, or to assign the tag
`data.tag.name`	`string`	required
`data.tag.slug`	`string`	required. Derived from the name, unique per brand
`data.tag.color`	`string \| null`	required
`data.tag.description`	`string \| null`	required
`request_id`	`string`	required. Also returned as the `x-request-id` header

Errors

Status	Code	When
400	`invalid_request`	Unknown field, empty name, a name with no letters or numbers, or a colour that is not hex
401	`invalid_token`	The key is missing, malformed, or does not exist
403	`insufficient_scope`	The key does not carry `write:tags`
403	`plan_required`	This workspace is not enabled for API writes
404	`not_found`	The brand does not exist, or this key is not allowed to reach it
409	`conflict`	Another tag in this brand already has that slug
429	`rate_limited`	Over 60 requests per minute

Notes

One pool, two kinds of thing. The same tag can label prompts and competitors. Apply it with Set prompt tags or Set competitor tags.

Slugs are derived, not supplied. "Bottom funnel" and "bottom-funnel" collide, and the second returns 409.

Idempotency-Key is required. Reuse it when retrying an attempt and the original response is replayed rather than a second tag being created. See Idempotency.