Coordinate Segments - Confidence Documentation

Use coordination to make segments mutually exclusive, ensuring users can only be in one experiment at a time.

See Coordination in the reference for details on how coordination works, common patterns, and best practices.

Set Up Basic Coordination

Create segments that exclude each other using matching tags:

curl -X POST "https://flags.confidence.dev/v1/segments?segmentId=ranking-exp-1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Ranking Experiment 1",
    "targeting": {},
    "allocation": {
      "proportion": {"value": "0.1"},
      "exclusivityTags": ["ranking"],
      "exclusiveTo": ["ranking"]
    }
  }'

Create a second segment with the same coordination:

curl -X POST "https://flags.confidence.dev/v1/segments?segmentId=ranking-exp-2" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Ranking Experiment 2",
    "targeting": {},
    "allocation": {
      "proportion": {"value": "0.1"},
      "exclusivityTags": ["ranking"],
      "exclusiveTo": ["ranking"]
    }
  }'

These segments are now mutually exclusive—no user can be in both.

Coordinate Across Multiple Groups

Exclude a segment from multiple coordination groups:

curl -X POST "https://flags.confidence.dev/v1/segments?segmentId=mixed-experiment" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Mixed Experiment",
    "targeting": {},
    "allocation": {
      "proportion": {"value": "0.05"},
      "exclusivityTags": ["search"],
      "exclusiveTo": ["search", "ranking", "mixer"]
    }
  }'

This segment doesn’t overlap with any segment that has search, ranking, or mixer as exclusivity tags.

Update Coordination Tags

Change coordination tags on an existing segment:

curl -X PATCH "https://flags.confidence.dev/v1/segments/ranking-exp-1?updateMask=allocation.exclusivityTags,allocation.exclusiveTo" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "allocation": {
      "exclusivityTags": ["ranking", "search"],
      "exclusiveTo": ["ranking", "search", "mixer"]
    }
  }'

Changing coordination tags on an allocated segment may require re-allocating it, which can affect which users are in the segment.

Allocate with Coordination

Allocate a segment with coordination tags:

curl -X POST "https://flags.confidence.dev/v1/segments/ranking-exp-1:allocate" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

If successful, the segment is allocated and guaranteed to be mutually exclusive with coordinating segments. If allocation fails due to insufficient space:

Reduce the allocation proportion
Archive some existing segments
Change coordination tags

Check Available Space

List all segments to check available space in a coordination group:

curl -X GET "https://flags.confidence.dev/v1/segments" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Filter the results for segments with overlapping coordination tags and sum their allocation proportions to see how much space the segments use.

Next Steps

After setting up coordination:

Create flag rules to use your coordinated segments
Allocate segments to activate them
Resolve flags to test your coordination logic

​Set Up Basic Coordination

​Coordinate Across Multiple Groups

​Update Coordination Tags

​Allocate with Coordination

​Check Available Space

​Next Steps

Set Up Basic Coordination

Coordinate Across Multiple Groups

Update Coordination Tags

Allocate with Coordination

Check Available Space

Next Steps