Managing pipeline definitions¶

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

To build one step by step, see Building a custom pipeline. Object field tables live in the object reference.

List all pipeline definitions¶

Endpoint

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

Query parameters

Parameter	Type	Description
`tag`	string	Optional. Filter to definitions that include this tag. Repeat the parameter for multiple tags; matching uses AND (the definition must include all given tags). Example: `?tag=funnel:<funnel_id>&tag=support`.

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.
`slug`	string	Optional. Machine-readable identifier. Lowercase alphanumeric, hyphens, and underscores only. Unique per organization. Cannot collide with a predefined pipeline slug (`impressions`, `shopping-cart`). Empty string is stored as `null`.
`description`	string	Optional description.
`tags`	array	Optional list of free-form string labels. Blank tags are rejected; duplicates are de-duplicated (order preserved).
`pageview_source_field`	string	Field used for the pageview 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`, or `dim1`–`dim5`. Default `visitor_id`. Used by `/counts` only; ignored by last-state.
`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. Optional identity_field for last-state occupancy. 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.
`slug`	string	Optional machine-readable identifier. May be null.
`description`	string	Optional description. May be null.
`tags`	array	Free-form labels. Empty list if none.
`pageview_source_field`	string	Field used for the pageview source breakdown. May be null (defaults to `referrer_medium` at query time).
`steps`	array	List of step objects (name, count_field, events including optional `identity_field`, metrics).
`dimensions`	array	List of dimension objects. Empty list if none defined.
`is_predefined`	bool	Always `false` for user-created definitions.
`supports_last_state`	bool	`true` only when every step has events and every event has `identity_field`.
`created_at`	string	Creation time (ISO-8601).
`modified_at`	string	Last modification time (ISO-8601).

Retrieve a pipeline definition by slug¶

Look up a pipeline by its slug. Resolves predefined pipelines first, then organization-owned definitions.

Endpoint

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

Response

Same structure as Retrieve a pipeline definition, for both predefined and org-owned pipelines.

Predefined match: is_predefined: true. organization_id is the requesting org. created_at / modified_at are null, tags is [].
Org definition match: is_predefined: false.
No match: 404 with {"error": "Pipeline definition not found"}.

Example:

GET /api/objectives/v1/orgs/<organization_id>/pipeline/definitions/by-slug/impressions/

GET /api/objectives/v1/orgs/<organization_id>/pipeline/definitions/by-slug/my-custom-funnel/

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, slug, description, tags, 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. Setting slug to null clears it. Omitting tags leaves existing tags unchanged.

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.

Sync from a case funnel¶

Creates or updates five pipeline definitions from a giosg case funnel (one per variant). Existing pipelines are matched by funnel:<funnel_id> and pipeline-variant:<variant>; if several share the same tags, the newest by modified_at wins for that variant.

When to use each variant: Choosing a funnel variant.

Endpoint

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

Payload

Attribute	Type	Description
`mode`	string	Optional. `update` (default) or `create`. `update` refreshes each variant or creates missing ones. `create` always creates five new definitions.

POST /api/objectives/v1/orgs/<organization_id>/pipeline/funnels/<funnel_id>/sync
Content-Type: application/json

{
  "mode": "update"
}

An empty body {} uses mode: "update".

Response: JSON array of five definitions (same shape as retrieve), newest created_at first.

Status	Meaning
201	At least one variant was newly created.
200	All five existing variants were updated.
404	Case funnel not found.
502 / 503	Upstream funnel service error / unavailable.

What sync writes¶

Variant tag	Name	`count_field`	`identity_field`	Event action	Metrics
`pipeline-variant:enter`	Case step entered	`event_id`	—	`step_started` every step	none
`pipeline-variant:movements`	Case step exited	`event_id`	—	`step_ended` (open stages) / `step_started` (closed)	Duration by case + Duration total; closed: Count by case
`pipeline-variant:enter-unique`	Case step entered (1×)	`dim3`	—	`step_started` every step	none
`pipeline-variant:enter-last-state`	Case status snapshot	`dim3`	`dim3`	same as enter-unique	none
`pipeline-variant:unique`	Case step exited (1×)	`dim3`	—	same as movements	like movements, duration metrics use `sum` only

Shared for all variants:

Tags: funnel:<funnel_id> and the variant tag above
One step per funnel stage (stage order); filter category=case_management, label=<stage id>
Dimensions: case (dim3 = case number, not the case UUID) and chat (dim4 = chat session id) on every step
Only Case status snapshot has supports_last_state: true

By-case duration metrics use group_by: ["dim3"], single_period: true, and display metadata (units, display_names, group_by_display_names).

Note

After mode: "create", later mode: "update" syncs target the newest definition per variant tag pair.

Predefined pipeline definitions¶

Predefined pipelines are global and read-only. At query time they behave like custom definitions; 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.
`slug`	string	Stable machine-readable identifier (e.g. `impressions`).
`name`	string	Human-readable pipeline name.
`description`	string	Optional description.
`pageview_source_field`	string	Field used for the pageview source breakdown.
`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`.
`supports_last_state`	bool	`true` only when every step has events and every event has `identity_field`. Predefined pipelines currently have none, so this is `false`.

Predefined pipelines can also be looked up by slug via Retrieve a pipeline definition by slug.

Impression Pipeline¶

Pipeline ID and slug

00000000-0000-0000-0000-000000000001 · slug impressions

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). All use count_distinct(visitor_id):

Step	Metric	`group_by`	Mapping
0	Impressions by interaction	`label`	`f$interactions`
1	Engaged with giosg by interaction	`label`	`f$interactions`
2	Positive outcome by interaction	`label`	`f$interactions`
2	Users by action	`action`	—
3	Users by goal	`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 and slug

00000000-0000-0000-0000-000000000002 · slug shopping-cart

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), with display_names: ["Total", "Average"].