Dev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunityDoc feedbackLog In
GitHubNuGetDev CommunityDoc feedback

API Usage

Learn how to use the Optimizely Data Platform (ODP) Real-Time Segment API.

The following two APIs let you work with segments in different ways:

The Real-Time Segments API expands on what the GraphQL API lets you do. This section focuses on the Real-Time Segments API. You can use the Real-Time Segments API to create new segments, delete existing segments, list all segments, and view segment definitions.

The hostname for the API is region-specific. See the API reference to find your region's hostname.

πŸ“˜

Note

This documentation uses the US region hostname (https://api.zaius.com).

These requests require authentication with private API token. See Authentication for more information.

The data type for segment-id is string, but they must always conform to case insensitive regexp pattern [a-z][a-z0-9_]*.

Operations

The possible operations are:

  • List segments (GET)
  • Get segment (GET)
  • Delete segment (DELETE)
  • Create segment (POST)
  • Update segment (PUT)

List segments

GET https://{hostname}/v3/segments

Responses

StatusContent-TypeBody
200application/json{
segment_ids: "h-0"
}

Example request

$ curl -H'x-api-key: your-private-key' \
https://api.zaius.com/v3/segments
{segment_ids: ["is_active"]}

Get segment

Gets a previously defined segment.

GET https://{hostname}/v3/segments/{segment-id}

Responses

StatusContent-TypeBody
200application/json{
revision: int,
description: string,
definition: segment_definition
}
400application/json{
status: 404,
request_id: null,
message: "Segment not found."
}

Delete segment

Deletes a previously defined segment. Returns all segmentIds that exist after the delete.

DELETE https://{hostname}/v3/segments/{segment-id}

Responses

StatusContent-TypeBody
200application/json{
segment_ids: "h-0"
}
400application/json{
status: 404,
request_id: null,
message: "Segment not found."
}

Example request

Assuming there are three installed segments with segmentIds "example_one", "example_two" and "example_three":

$ curl -H'x-api-key: your-private-key' \
https://api.zaius.com/v3/segments/example_two
{segment_ids: ["example_one", "example_three"]}

$ curl -H'x-api-key: your-private-key' \
https://api.zaius.com/v3/segments/example_two
{"status": 404,"request_id":null,"message"Segment not found."}

Create segment

PUT https://{hostname}/v3/segments/{segment-id}

{
    "description": "total revenue less than 25",
    "definition": {
        "root_condition": {
          "customer_condition": {
            "customer_filter": {
              "comparison": {
                  "lhs": {
                      "path_reference": {
                          "value": "customer.observations.total_revenue_percentile"
                      }
                  },
                  "comparator": "LESS_THAN",
                  "rhs": {
                      "number_literal": {
                          "value": "25"
                      }
                  }
              }
            }
          }
        }
    }
}
ParameterTypeExample
segment-idstringtotal_revenue_lt_25
descriptionstringTotal revenue percentile less than 25
definitionsegment_definition{
"root_condition": {
"customer_condition": {
"customer_filter": {
"comparison": {
"lhs": {
"path_reference": {
"value": "customer.observations.total_revenue_percentile"
}
},
"comparator": "LESS_THAN",
"rhs": {
"number_literal": {
"value": "25"
}
}
}
}
}
}
}

Responses

StatusContent-TypeBodyComment
200application/json{
"revision": int
}
{
"revision": Starts at 0 when
segment is created,
incremented on update
}
400application/json{
"code": int,
"message": "string"
}
{
"code": Same as HTTP
status code.,
"message": "Provides
reason why segment
definition is invalid"
}

Example request

curl -XPUT -H 'x-api-key: your-private-key' \
-H 'Content-Type': 'application/json' \
https://api.zaius.com/v3/segments/is_active \
-d '{
  "description": "Users who were active in the last 7 days",
  "definition": {
    "root_condition": {
      "sequence_condition": {
        "sequence": {
          "entry_event_filter": {
            "path_reference": {
              "value": "event.active_event"
            }
          },
          "max_age_seconds": 604800
        },
        "min_count": 1
      }
    }
  }
}'

Update segment

Updating a segment is similar to creating a segment. If you issue a PUT with a segment-id that already exists and a new segment definition, then that segment-id is updated with the new segment definition and the revision number is incremented.

Example request

Assume you have two variables with segment definitions. The first one is ${ACTIVE_7_DAYS} and matches the Create segment example body. The second one is ${ACTIVE_1_DAY}, which looks the same, except it has "max_age_seconds": 86400. This requires the user to have an active event within the last 86400 seconds (1 day).

The following requests would then:

  1. Create the segment is_active, including users that were active in the last 7 days. This returns {"revision":0}.
  2. Update the description for segment is_active. This returns {"revision":1}.
  3. Update the definition for segment is_active. This returns {"revision":2}.
$ curl -XPUT -H'x-api-key: your-private-key' \
    https://api.zaius.com/v3/segments/is_active \
    -d @- << EOF
    {
      "description": "User was active in the last week.",
      "definition": ${ACTIVE_7_DAYS}
    }
    EOF
    {"revision":0}
    
    $ curl -XPUT -H'x-api-key: your-private-key' \
    https://api.zaius.com/v3/segments/is_active \
    -d @- << EOF
    {
      "description": "User was recently active",
      "definition": ${ACTIVE_7_DAYS}
    }
    EOF
    {"revision":1}

    $ curl -XPUT -H'x-api-key: your-private-key' \
    https://api.zaius.com/v3/segments/is_active \
    -d @- << EOF
    {
      "description": "User was recently active",
      "definition": ${ACTIVE_1_DAY}
    }
    EOF
    {"revision":2}