---
title: "A product's step-by-step connect walkthrough."
method: GET
path: "/integrations/providers/{slug}/walkthrough"
tags: ["Integrations"]
---

# A product's step-by-step connect walkthrough.

`GET /integrations/providers/{slug}/walkthrough`

## Request

- Base URL: `https://docs.sleeperhit.studio/api/v1`
- URL: `https://docs.sleeperhit.studio/api/v1/integrations/providers/{slug}/walkthrough`
- Auth: HTTP bearer

Who can connect, what is read, what is never done or included, what the product's own screen shows and how to answer it, how to choose what to bring in, the honest first-check estimate, and — when an admin must approve first — a prefilled message and the approval link. With the organization's live state. The same data the app's Connect drawer renders. Scope: `story:read`. Free.

## Response `200`

The walkthrough and the live state.

- IntegrationWalkthrough
  - `slug` string, required
  - `label` string, required
  - `logoPath` string, nullable, required
  - `state` 'READY' | 'COMING_SOON' | 'PENDING' | 'CONNECTED' | 'NEEDS_ATTENTION' | 'RATE_LIMITED', required
  - `connect` IntegrationConnectGuide, required
    - `whoCanConnect` string, required
    - `reads` string[], required: One plain line per permission.
    - `neverDoes` string[], required
    - `excluded` string[], required
    - `vendorScreen` object, required
      - `title` string, required
      - `whatYouSee` string, required
      - `tip` string
      - `unreviewedNote` string
    - `choose` object, required
      - `title` string, required
      - `body` string, required: One short line: how to add more later.
      - `mode` 'in-vendor' | 'origins-picker' | 'install-then-pick', required
      - `noun` object, required: What one chosen place is called in this product ("page", "channel").
        - `one` string, required
        - `many` string, required
      - `emptyHint` string
    - `firstSync` string, required: An honest first-check estimate in one short line.
    - `firstItemHint` string
    - `adminBranch` object
      - `when` string, required
      - `alwaysRequired` boolean
      - `messageTemplate` string, required: `{vendor}`, `{approvalUrl}` and `{organization}` are filled in.
      - `adminUrl` string
      - `adminUrlLabel` string
    - `revoke` object, required
      - `inVendor` string, required
      - `url` string
  - `adminApprovalUrl` string, nullable, required: The approval link an admin opens, when the product has one (Microsoft).
  - `connection` IntegrationConnection, nullable, required
    - `id` string, required
    - `providerSlug` string, required
    - `status` 'PENDING' | 'CONNECTED' | 'NEEDS_RECONNECT' | 'DISABLED', required
    - `healthCode` 'revoked' | 'admin_policy' | 'rate_limited' | 'missing_scopes' | 'wrong_account' | 'vendor_error' | 'null', nullable, required: Why a connection that still exists is not reading. `rate_limited` and `vendor_error` clear by themselves.
    - `healthLine` string, nullable, required: One plain line from `healthCode`, or null when healthy.
    - `accountLabel` string, required
    - `origins` string[], required: The places chosen to bring in.
    - `lastSyncedAt` string, nullable, required
    - `lastSyncStartedAt` string, nullable, required
    - `nextSyncAt` string, nullable, required
    - `lastRunItemsSeen` integer, nullable, required
    - `lastRunItemsNew` integer, nullable, required
    - `connectedAt` string, required
    - `statusLine` string, required: The card's one status line, e.g. "Acme · 5 pages · feeds Demo · checked 3m ago" or "… · no project reads it yet".
    - `projectsFeeding` object[], required: The projects that read from this product: fed as a project (PUT /story-projects/{projectId}/integration-feed) or through a live season's own rule. Empty means no check runs yet.
      - `projectId` string, required
      - `projectName` string, required
    - `itemsWaiting` integer, required: Items found and waiting for someone to keep or turn down, across every season.
    - `reviewHref` string, nullable, required: The app review queue holding the most waiting items, or null when nothing waits.
    - `itemsHeld` integer, required: Items found for a fed project that has no season yet; its next season's review queue takes them.
    - `heldHref` string, nullable, required: The app Seasons tab of the project holding the most of them, or null.
  - `readOnly` string, required
  - `keepGate` string, required
  - `feedTargets` IntegrationFeedTarget[], required: Your projects, product projects first, then most recently edited (up to 100); each can feed from this product in one step.
    - `projectId` string, required: Feed it with PUT /story-projects/{projectId}/integration-feed; no live season is needed.
    - `projectName` string, required
    - `projectKind` 'story' | 'product', required
    - `feeding` boolean, required: The project already feeds from this product.

## Other responses

- `401`: Missing, malformed, revoked, or expired API key.
- `403`: API key is valid but lacks the scope, is blocked by IP allowlist, or the account is disabled.
- `404`: `integration_not_found`: not a catalogued product.
- `429`: Rate limit for this API key + IP + route family was exceeded.
- `500`: The API failed unexpectedly. Safe to retry with the same Idempotency-Key.

---

[API](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api.md) · [All operations](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api/revisions/4534f5d25540?raw)