Skip to content
threada Docs

Zapier Public Integration

This guide defines the next public integration-store path after Slack Marketplace. It is a design and launch-control document, not evidence that a Zapier public integration has been built or approved.

Current Status

Zapier is planned as the next public integration after Slack. Threada already has a public API for tenant-scoped WorkItem intake and follow-up, and the private Zapier Platform app scaffold now lives in packages/zapier-platform-app. The scaffold exports the v1 action-only surface: Create WorkItem, Append WorkItem Message, and Update WorkItem. Studio also exposes https://studio.threada.ai/integrations/zapier/install to preload the Zapier runtime integration kind and connector preset for a pack. Do not submit a public Zapier listing until the private integration passes authenticated Zapier validation, Zap Editor testing, reviewer credential handoff, and the remaining review gates below.

The public setup and support guide for reviewer testing and future public users is Zapier setup and support. Use https://docs.threada.ai/integrations/zapier-setup/ as the support/setup URL unless the launch owner replaces it with a stronger public help-center URL.

The existing custom Zapier path remains Custom HTTP or webhook-style use by individual customers. It should not be described as the public Zapier app.

Positioning

Threada for Zapier should let teams move requests between Zapier workflows and Threada WorkItems without bypassing Threada governance.

The v1 public app should stay narrow:

  • Create a governed WorkItem from a Zap.
  • Append a human-readable update to an existing WorkItem.
  • Update WorkItem routing or lifecycle fields that the public API already accepts.
  • Trigger downstream Zaps only from WorkItem records that the API can expose with stable polling or webhook semantics.

The v1 app must not claim that Zapier can execute third-party actions through Threada. Direct external execution remains inside Threada’s policy, approval, idempotency, and audit controls.

Source Of Truth

Do not duplicate request or response schemas in this document. The public API source of truth is Threada Public API and its generated OpenAPI artifact at /openapi/public-api.openapi.yaml. The committed source copy is docs/developers/public-api.openapi.yaml.

Build the Zapier package from the WorkItems and WorkItem message operations in the generated contract. If an operation ID, field, enum, error code, or auth behavior changes, update the OpenAPI contract and generated docs first, then adjust this design.

Authentication

The enterprise-safe first path is API-key authentication only if a reviewer and customer admin can create, copy, rotate, and revoke a tenant-scoped key without human support. Zapier’s authentication docs say apps with private data need authentication, and that OAuth v2 is preferred where possible while API keys are the next-best option when users can obtain keys self-serve.

Public submission is blocked if the reviewer cannot obtain a credential through a self-service path or approved secure reviewer notes. Do not ask Zapier reviewers to email Threada for an API key.

Required auth behavior:

  • Store the tenant-scoped API key in Zapier’s credential store. The private scaffold also accepts an optional non-sensitive workspace label so admins can distinguish Zapier connections; do not place secrets or customer data in that label.
  • Test authentication with a read-only public API call.
  • Show a connection label that identifies the Threada tenant or workspace without exposing the key.
  • Document how a tenant admin rotates or revokes the key.
  • Keep keys, cookies, raw payloads, customer data, and reviewer credentials out of repo evidence and public screenshots.

V1 Actions

Create WorkItem

Call the generated OpenAPI operation for creating a WorkItem.

Inputs should map to the public API fields for subject, channel, channel ID, optional thread/source metadata, contact details, tags, and the initial message. For app-to-app Zapier-created records, use the existing custom channel unless the source cleanly maps to another accepted WorkItemChannel enum value. Preserve Zapier provenance in channel_id, tags, or message metadata instead of inventing a new channel enum value.

Outputs must expose the created WorkItem ID, status, subject, channel, queue, assignee, timestamps, and a Work shell URL if the public API or Zapier app can derive one safely. Zapier actions should return structured fields, not just a success message.

Append WorkItem Message

Call the generated OpenAPI operation for appending a WorkItem message.

Inputs should include the WorkItem ID and message content. Keep the initial v1 surface to user-readable notes; do not use this action to post raw event dumps from third-party apps.

Outputs should include the message ID, WorkItem ID, role, channel, and created timestamp.

Update WorkItem

Call the generated OpenAPI operation for updating a WorkItem.

The v1 Zapier action should expose only mutable fields accepted by the live public API handler: status, queue, and assignee. Do not expose priority, tags, subject, or action execution fields unless the public API contract and live handler accept them end to end.

V1 Triggers

New WorkItem

Use the public WorkItems list operation only after the API can give Zapier a stable recency window or cursor suitable for polling without missing or replaying large sets of work. If that guarantee is not present, keep this trigger private or blocked and prefer a future webhook trigger.

Minimum trigger output should include the WorkItem ID, subject, status, channel, queue, assignee, created timestamp, updated timestamp, and a Work shell URL if safe.

Updated WorkItem

Use the public WorkItems list operation only after the API exposes stable updated-order polling or changed-since semantics. Without that API behavior, this trigger is not review-ready because Zapier polling could miss updates or produce noisy duplicates.

Explicit Non-Goals

  • No direct side-effecting external action execution from Zapier.
  • No delete, bulk destructive, or irreversible Zapier actions.
  • No crawling, scraping, or named third-party data extraction positioned as a Threada feature.
  • No customer-data screenshots, raw third-party payloads, or workspace exports in Zapier screenshots or review evidence.
  • No broad “AI agent executes any app action” listing copy. Public copy must stay anchored to WorkItem intake, updates, and governed review.

Review Gates

Implemented:

  • Public API exists for WorkItem creation, listing, retrieval, updates, and message append.
  • Public API uses tenant-scoped API keys and documented scopes.
  • Public API docs and OpenAPI are published.
  • Public Zapier setup/support documentation is published from docs/integrations/zapier-setup.md.
  • Studio exposes the public setup handoff at https://studio.threada.ai/integrations/zapier/install, which preloads the Zapier runtime integration kind and connector preset before the reviewer or customer completes Zapier connected-account setup.
  • Private Zapier Platform app scaffold exists at packages/zapier-platform-app.
  • Zapier custom authentication test calls the read-only WorkItems list endpoint.
  • Zapier v1 actions define input fields, output fields, help text, and sample data for Create WorkItem, Append WorkItem Message, and Update WorkItem.
  • Package tests cover auth middleware, action payload mapping, mutable-field allowlisting, and API error surfacing.

Missing:

  • Authenticated zapier validate result from a Zapier developer account.
  • Private version push and Zap Editor smoke test with a reviewer-safe Threada tenant API key.
  • Trigger-safe public API recency/cursor behavior or a Zapier-compatible webhook trigger for New WorkItem and Updated WorkItem.
  • Private integration validation and Zapier review evidence.
  • Reviewer test account or secure reviewer credential handoff.
  • Zap templates for the first customer workflows.

Blocked:

  • Public Zapier submission is blocked until auth is self-service or securely reviewer-provisioned, trigger semantics are safe or omitted from public v1, Zapier validation passes, Zap Editor smoke evidence exists, and reviewer credential handoff is ready.

Initial Zap Templates

Create templates only after the Zapier app is public. Zapier’s template docs say templates are for public integrations and help users discover preconfigured workflows.

Recommended first templates:

  • Create a Threada WorkItem from a new Typeform response.
  • Create a Threada WorkItem from a new Gmail message matching a label.
  • Append a Threada WorkItem message when a Jira issue changes status.
  • Create a Slack notification when a Threada WorkItem is completed.

Each template must use sanitized sample data and avoid implying that Threada executes downstream system actions without governance.

Launch Checklist

  1. Confirm whether v1 auth is API key with self-service key management or OAuth v2.
  2. Keep the private Zapier app package action-only until trigger semantics are safe.
  3. Add trigger support only after the public WorkItems list operation has stable recency semantics or a webhook trigger exists.
  4. Run package tests, authenticated zapier validate, and a private Zap Editor smoke test.
  5. Review the published public setup/support documentation for the exact private or public Zapier version being submitted.
  6. Prepare reviewer credential handoff through Zapier-approved secure notes or another approved secure channel.
  7. Run Zapier validation and fix all warnings before public submission.
  8. Create Zap templates only after the integration is public.

References