Tags API

Manage tags and the tags attached to products. Tags are shared across a store,
so you create them once and then attach them to products.

Endpoints

Tags:

• List Tags - GET /api/v1/tags/
• Create Tag - POST /api/v1/tags/
• Get Tag - GET /api/v1/tags/{tag_id}/
• Update Tag - PUT /api/v1/tags/{tag_id}/
• Delete Tag - DELETE /api/v1/tags/{tag_id}/

Product tags:

• List Product Tags - GET /api/v1/products/{product_id}/tags/
• Add Product Tag - PUT /api/v1/products/{product_id}/tags/{tag_id}/
• Remove Product Tag - DELETE /api/v1/products/{product_id}/tags/{tag_id}/

List Tags

Retrieve all tags in the store. This endpoint is not paginated.

Endpoint: GET /api/v1/tags/

Permission Required: Read

Request

curl -X GET "https://studio.easel.engineering/api/v1/tags/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 200 OK

{
  "data": [
    {
      "id": "tag_d0b6fmv28q6vn14peun0",
      "name": "Summer"
    }
  ]
}

Create Tag

Create a tag in the store.

Endpoint: POST /api/v1/tags/

Permission Required: Write

Request Body

{
  "name": "Summer"
}

Request

curl -X POST "https://studio.easel.engineering/api/v1/tags/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-12345" \
  -d '{"name": "Summer"}'

Response

Status: 201 Created

{
  "id": "tag_d0b6fmv28q6vn14peun0",
  "name": "Summer"
}

Error Responses

Missing required field

Status: 400 Bad Request

{
  "error": "Name is required",
  "code": "MISSING_FIELD"
}

Tag already exists

Status: 409 Conflict

{
  "error": "Resource already exists",
  "code": "DUPLICATE"
}

Get Tag

Retrieve a single tag by its public ID.

Endpoint: GET /api/v1/tags/{tag_id}/

Permission Required: Read

Request

curl -X GET "https://studio.easel.engineering/api/v1/tags/tag_d0b6fmv28q6vn14peun0/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 200 OK

{
  "id": "tag_d0b6fmv28q6vn14peun0",
  "name": "Summer"
}

Error Responses

Tag not found

Status: 404 Not Found

{
  "error": "Resource not found",
  "code": "NOT_FOUND"
}

Update Tag

Rename a tag.

Endpoint: PUT /api/v1/tags/{tag_id}/

Permission Required: Write

Request Body

{
  "name": "Summer Sale"
}

Request

curl -X PUT "https://studio.easel.engineering/api/v1/tags/tag_d0b6fmv28q6vn14peun0/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-67890" \
  -d '{"name": "Summer Sale"}'

Response

Status: 200 OK

{
  "id": "tag_d0b6fmv28q6vn14peun0",
  "name": "Summer Sale"
}

Delete Tag

Delete a tag. The tag is removed from any products and collections that
reference it.

Endpoint: DELETE /api/v1/tags/{tag_id}/

Permission Required: Write

Request

curl -X DELETE "https://studio.easel.engineering/api/v1/tags/tag_d0b6fmv28q6vn14peun0/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 204 No Content

List Product Tags

Retrieve the tags attached to a product.

Endpoint: GET /api/v1/products/{product_id}/tags/

Permission Required: Read

Request

curl -X GET "https://studio.easel.engineering/api/v1/products/pro_d0b6fmv28q6vn14peun0/tags/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 200 OK

{
  "data": [
    {
      "id": "tag_d0b6fmv28q6vn14peun0",
      "name": "Summer"
    }
  ]
}

Add Product Tag

Attach an existing tag to a product.

Endpoint: PUT /api/v1/products/{product_id}/tags/{tag_id}/

Permission Required: Write

Request

curl -X PUT "https://studio.easel.engineering/api/v1/products/pro_d0b6fmv28q6vn14peun0/tags/tag_d0b6fmv28q6vn14peun0/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Idempotency-Key: unique-request-id-24680"

Response

Status: 204 No Content

Remove Product Tag

Detach a tag from a product.

Endpoint: DELETE /api/v1/products/{product_id}/tags/{tag_id}/

Permission Required: Write

Request

curl -X DELETE "https://studio.easel.engineering/api/v1/products/pro_d0b6fmv28q6vn14peun0/tags/tag_d0b6fmv28q6vn14peun0/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 204 No Content

Tag Object

Fields