Tags

Create a tag

Create a new tag for organizing your audience.

Endpoint: POST /v3/tags

Request body:

Field	Type	Required	Description
name	string	Yes	Tag name (must be unique per clone)
color	string	No	Tag color (defaults to "default")

Example request:

curl -X POST https://api.delphi.ai/v3/tags \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"name": "VIP", "color": "blue"}'

Example response:

{
  "id": "tag-001",
  "name": "VIP",
  "color": "blue",
  "created_at": "2025-06-15T10:00:00.000Z",
  "updated_at": "2025-06-15T10:00:00.000Z"
}

Returns 409 if a tag with the same name already exists.

List all tags

Retrieve all tags for your clone.

Endpoint: GET /v3/tags

Example request:

curl "https://api.delphi.ai/v3/tags" \
  -H "x-api-key: YOUR_API_KEY"

Example response:

{
  "tags": [
    {
      "id": "tag-001",
      "name": "VIP",
      "color": "blue",
      "created_at": "2025-06-15T10:00:00.000Z",
      "updated_at": "2025-06-15T10:00:00.000Z"
    },
    {
      "id": "tag-002",
      "name": "Free Trial",
      "color": "default",
      "created_at": "2025-06-14T08:00:00.000Z",
      "updated_at": "2025-06-14T08:00:00.000Z"
    }
  ],
  "total_count": 2
}

Tags are sorted by newest first.

Tag a user

Apply a tag to a user in your audience.

Endpoint: POST /v3/users/{user_id}/tags/{tag_name}

Path parameters:

Parameter	Type	Description
user_id	string	UUID of the user
tag_name	string	Exact tag name

Example request:

curl -X POST "https://api.delphi.ai/v3/users/u-123/tags/VIP" \
  -H "x-api-key: YOUR_API_KEY"

Example response:

{
  "success": true,
  "tag_id": "tag-001",
  "tag_name": "VIP",
  "user_id": "u-123",
  "message": "Tag applied successfully"
}

This operation is idempotent — tagging a user who already has the tag will succeed without error.

Untag a user

Remove a tag from a user.

Endpoint: DELETE /v3/users/{user_id}/tags/{tag_name}

Path parameters:

Parameter	Type	Description
user_id	string	UUID of the user
tag_name	string	Exact tag name

Example request:

curl -X DELETE "https://api.delphi.ai/v3/users/u-123/tags/VIP" \
  -H "x-api-key: YOUR_API_KEY"

Example response:

{
  "success": true,
  "tag_id": "tag-001",
  "tag_name": "VIP",
  "user_id": "u-123",
  "message": "Tag removed successfully"
}

This operation is idempotent — untagging a user who doesn't have the tag will succeed without error.