lytics-integrations

Lytics Integrations

Everything between "I want to connect X" and a running job: picking the provider and workflow, field mapping, auth credentials, connections to external data sources, webhook templates for custom destinations, the job lifecycle (create, update, pause, resume, bounce, kill, logs), and debugging why one user did or didn't reach a destination. Integrations are layered: Provider (what platform) -> Auth (how to authenticate) -> Connection (optional, for data-source integrations) -> Job (runs one workflow).

Before you start

• Credentials: references/auth.md.
• Request conventions, URL-encoding and the /v2 error shape (.errors[0].message): references/api.md.
• Every create, update, delete and lifecycle command goes through references/confirmation-gate.md (pause/resume may use a brief confirmation; kill needs explicit confirmation).
• Never log or display full credential values. OAuth cannot be completed from the CLI: send the user to the Lytics UI, then pick up the new auth_id via GET /v2/auth.

Gotchas

• Create starts the job. POST /v2/job and POST /v2/job/{workflow} default run_job to true, so an export begins sending data the moment it is created. Say so in the gate; pass ?run_job=false to create it without running.
• Job update is a full replace, not a merge. Omitted description, quiet-window fields, expires_at, meta, hidden, verbose_logging are reset, and a sent config replaces the stored one wholesale. GET the job, edit only what was asked, PUT the whole object back.
• Kill is a delete. POST /v2/job/{id}/kill soft-deletes the job; it drops out of the job list and there is no API to undelete it. Offer pause as the reversible alternative.
• Status values are running, sleeping, paused, pausing, initializing, failed, completed, deleted, deleting, unknown, fault-N. Match faults by the fault prefix; the API never returns runnable, fault or killed.
• Killed jobs are hidden by default. List them with show_all=true (or show_deleted=true&show_completed=true); show_deleted alone does not show them. /v2/job/logs (account-wide) also excludes killed jobs.
• sleep_until is only on the list. GET /v2/job/{id} omits it; use GET /v2/job?show_state=true. With drop_events_during_quiet_window: true, quiet-time events are dropped, not queued.
• Webhook templates: update is PUT /v2/template/{id} (POST is 405); desired_format must be set or /test returns an empty 500; a template that threw still returns HTTP 200 with the error in data; the source is never readable back. js1 entry point is function template(data).
• Webhook job config has no headers field -- headers live on a header_param_auth auth provider referenced by auth_ids[]. Live names are segment_ids, audience_events (""/enters_only/exits_only), do_not_retry (array of ints), withbackfill.

Modes

Read the mode file before acting in that mode.

Mode	When	File
advise	Choosing a provider/workflow, weighing tradeoffs, planning field mappings, checking a segment for an export	advise.md
setup	End-to-end creation: auth -> connection -> job, in dependency order, behind one gate	setup.md
connections	List/get/create/update/delete connections and auth providers, list providers, scan a connection or read its schema	connections.md
jobs	List/get/create/update jobs, pause/resume/bounce/kill/release, job logs	jobs.md
webhook-templates	Send triggers/enrichment to a custom webhook; list/get/create/update/delete/test templates; build one from the destination's docs	webhook-templates.md (+ webhook-templates-reference.md)
export-debug	Why one user was or wasn't exported: segment -> job status -> quiet window -> flow step -> logs (read-only)	export-debug.md

A specific, well-defined request ("create a job with workflow X and auth Y") goes straight to jobs or setup. A request that involves choosing a workflow, mapping fields, or a new integration from scratch starts in advise, then continues in setup. An existing export that is failing or sending fewer users than expected goes to export-debug; a custom webhook destination goes to webhook-templates, which hands off to connections and jobs.

Related skills

• lytics-audiences -- the export needs a segment that does not exist yet, or the user wants help choosing the audience.
• lytics-schema -- look up or add the Lytics fields an import maps into or an export maps from.
• lytics-profiles -- explain why a user is not in an export's segment, or pull a real profile to test a webhook template.
• lytics-flows -- an export driven by a flow step, when the user's flow position is the question.
• lytics-account -- copy jobs, connections or auth from one account to another.