Managing pipeline definitions¶

Pipeline definitions are stored objects that describe steps and event filters. Endpoints support an optional trailing slash.

List all pipeline definitions¶

Endpoint

GET	`https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/pipeline/definitions/`

Returns a paginated list. Each item has the structure described in Retrieve a pipeline definition.

Create a pipeline definition¶

Endpoint

POST	`https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/pipeline/definitions/`

Payload

Attribute	Type	Description
`name`	string	Pipeline name. Required.
`description`	string	Optional description.
`pageview_source_field`	string	Pageview column for the source breakdown when `include_pageview_counts: true`. One of `referrer_medium` (default) or `referrer_source`.
`steps`	array	List of step objects. Required; at least one step.
`dimensions`	array	Optional list of dimension objects. See Object reference — Dimensions.

Each step object:

Attribute	Type	Description
`name`	string	Step name. Required.
`count_field`	string	One of `event_id`, `session_id`, `visitor_id`. Default `visitor_id`.
`events`	array	List of event filter objects. Required; at least one event per step.
`metrics`	array	Optional list of metric objects. See Object reference — Metrics.

Each event filter object: at least one of vendor, category, action, label, room_ids, properties must be present. See Object reference — Event filters.

Example:

{
  "name": "Impressions to goals",
  "description": "Widget impressions, engagement, and goal triggers",
  "pageview_source_field": "referrer_medium",
  "steps": [
    {
      "name": "Impressions",
      "count_field": "visitor_id",
      "events": [
        { "category": "widget", "action": "start", "label": "$interaction-ids" }
      ]
    },
    {
      "name": "Goals",
      "count_field": "visitor_id",
      "events": [
        { "category": "goal", "action": "trigger", "label": "$goal-ids" }
      ],
      "metrics": [
        {
          "name": "Users by goal",
          "measure": { "field": "visitor_id", "aggregations": ["count_distinct"] },
          "group_by": ["label"]
        }
      ]
    }
  ]
}

Response: same structure as Retrieve a pipeline definition.

Retrieve a pipeline definition¶

Endpoint

GET	`https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/pipeline/definitions/<definition_id>/`

Response

Attribute	Type	Description
`id`	uuid	Unique identifier.
`organization_id`	uuid	Organization that owns the definition.
`name`	string	Pipeline name.
`description`	string	Optional description. May be null.
`pageview_source_field`	string	Pageview source dimension field. May be null (defaults to `referrer_medium` at query time).
`steps`	array	List of step objects (name, count_field, events, metrics).
`dimensions`	array	List of dimension objects. Empty list if none defined.
`is_predefined`	bool	Always `false` for user-created definitions.
`created_at`	string	Creation time (ISO-8601).
`modified_at`	string	Last modification time (ISO-8601).

Update a pipeline definition¶

Endpoint

PATCH / PUT	`https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/pipeline/definitions/<definition_id>/`

Same fields as create (name, description, pageview_source_field, steps, dimensions). For PATCH, include only the fields to change. If steps is provided, the step list is replaced entirely; the new list must contain at least one step.

Remove a pipeline definition¶

Endpoint

DELETE	`https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/pipeline/definitions/<definition_id>/`

No response body. Returns 204 on success.

Predefined pipeline definitions¶

Predefined pipelines are global, read-only and available to all organizations. They behave exactly like custom definitions at query time — the only difference is that they cannot be modified or deleted.

Endpoint

GET	`https://api.giosg.com/api/objectives/v1/orgs/<organization_id>/pipeline/predefined-definitions`

Returns a non-paginated list. Each item has:

Attribute	Type	Description
`id`	uuid	Stable ID of the predefined pipeline.
`name`	string	Human-readable pipeline name.
`description`	string	Optional description.
`pageview_source_field`	string	Pageview column used as source dimension.
`steps`	array	List of step objects (same shape as custom definitions, including metrics).
`dimensions`	array	List of dimension objects. Empty list if none.
`is_predefined`	bool	Always `true`.

Impression Pipeline¶

Pipeline ID

00000000-0000-0000-0000-000000000001

Tracks the funnel from widget impressions through engagement to outcomes and goal triggers.

Steps:

Index	Name	Events
0	Impressions	`category=widget, action=start, label=$interaction-ids`
1	Engaged with giosg	`category=widget, action=click, label=$interaction-ids`
2	Positive outcome	`category=widget, action=<outcome actions>, label=$interaction-ids`
3	Goals reached	`category=goal, action=trigger, label=$goal-ids`

Metrics (returned by step-detail):

Step 0: Impressions by interaction — count_distinct(visitor_id) grouped by label, with mapping_functions: { "label": "f$interactions" }.
Step 2: Users by action — count_distinct(visitor_id) grouped by action.
Step 3: Users by goal — count_distinct(visitor_id) grouped by label, with mapping_functions: { "label": "f$goals" }.

Dimensions:

Name	partial	Covers	Mapping
`interaction`	false	All 4 steps	Steps 0–2: `field=label`; step 3: `cohort_from_step=2`. `pageview_cohort_from_step: 0`.
`goal`	false	All 4 steps	Steps 0–2: `cohort_from_step=3`; step 3: `field=label`. `pageview_cohort_from_step: 3`.
`interactions_only`	true	Steps 0–2	Steps 0–2: `field=label`.
`goals_only`	true	Step 3	Step 3: `field=label`.

Value sets supported: create interaction-ids and goal-ids for your organization if you want to limit the pipeline to specific interactions or goals. (e.g. to exclude non-relevant goals or interactions) See Managing value sets.

Shopping Cart Pipeline¶

Pipeline ID

00000000-0000-0000-0000-000000000002

Tracks the cart creation-to-purchase funnel, including whether a purchase was accompanied by a real conversation.

Steps:

Index	Name	Events
0	Cart Created	`vendor=com.giosg.chat, category=shopping-cart, action=created`
1	Cart Purchased	`vendor=com.giosg.chat, category=shopping-cart, action=purchased`
2	Cart Purchased with Real Chat	`vendor=com.giosg.chat, category=shopping-cart, action=purchased, properties=["with_real_conversation=true"]`

Metrics (returned by step-detail for steps 1 and 2): Cart value — sum(value) and avg(value).