HomeGuidesAPI ReferenceGraphQL
Submit Documentation FeedbackJoin Developer CommunityOptimizely GitHubOptimizely NuGetLog In

API Usage

This topic describes how to work with real-time segments via Optimizely Data Platform's (ODP's) APIs.

Overview

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

  • RealtimeSegments API - Allows you to create, delete, list and get segments.
  • GraphQL API - Allows you to view the results of existing segments. For more information, refer to the Querying Real-Time Segments section.

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

The hostname for the API is region-specific. Refer to the list below to find your region's hostname:

📘

Note

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

These requests require your account id as well as your private API token. The account id goes in the first path segment, and the private API token goes in the header.

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

  • Create Segment
  • Update Segment
  • List Segments
  • Delete Segment
  • Get Segment

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"
                      }
                  }
              }
            }
          }
        }
    }
}

Parameter

Type

Example

segment-id

string

total_revenue_lt_25

description

string

Total revenue percentile less than 25

definition

segment_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

Status

Content-Type

Body

Comment

200

application/json

{
"revision": int
}

{
"revision": Starts at 0 when
segment is created,
incremented on update
}

400

application/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 we 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 that 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}

List Segments

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

Responses

Status

Content-Type

Body

200

application/json

{
segment_ids: [string]
}

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

Status

Content-Type

Body

200

application/json

{
revision: int,
description: string,
definition: segment_definition
}

400

application/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

Status

Content-Type

Body

200

application/json

{
segment_ids: [string]
}

400

application/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."}

Did this page help you?