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

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	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.
`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	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).

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¶

Create or update a pipeline definition from a giosg case funnel. The endpoint fetches the funnel and its stages from the upstream service API, maps each stage to a pipeline step, and persists the definition.

Existing pipelines for a funnel are found via the reserved tag funnel:<funnel_id>. When multiple pipelines share that tag, the newest by modified_at is used for updates.

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` updates the newest matching pipeline, or creates one if none exists. `create` always creates a new pipeline definition.

Example:

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

{
  "mode": "update"
}

An empty body {} is valid and uses mode: "update".

Response: same structure as Retrieve a pipeline definition.

Status	Meaning
201	A new pipeline definition was created.
200	An existing pipeline was updated (`mode: "update"`).
404	Case funnel not found upstream.
502 / 503	Upstream funnel service error / unavailable.

Mapping rules¶

Name: funnel name.
Description: built from optional case_number_prefix and divisions (e.g. Case funnel SUP - divisions: Loyalty).
Tags: always includes funnel:<funnel_id>.
Steps: one per stage, ordered by stage order.
count_field: event_id.
Event filter: category=case_management, label=<stage id>, action=step_ended for non-terminal stages, or action=step_started when case_status is closed.
Metrics: duration and/or count-by-case aggregations (terminal/closed stages get count-by-case only).
Dimensions: case (dim3) and chat (dim4), each mapped on every step.

Note

If you update an earlier version of a funnel-linked pipeline (for example after mode: "create" produced a newer copy), that older pipeline becomes the "current" one for subsequent mode: "update" syncs if it is the newest by modified_at.

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.
`slug`	string	Stable machine-readable identifier (e.g. `impressions`).
`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`.

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):

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 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).