Sequenzy Account Health API

openapi: 3.2.0
info:
  title: Sequenzy Account Health API
  description: Sequenzy API for managing subscribers, tags, events, sequences, and transactional emails
  version: 1.0.0
servers:
- url: https://api.sequenzy.com/api/v1
  description: Production server
- url: https://api.sequenzy.com/v1
  description: Legacy production server alias
security:
- bearerAuth: []
tags:
- name: Account Health
paths:
  /account-health:
    get:
      operationId: getAccountHealth
      summary: Get account health
      description: Returns the account health report for the active company - the schedule, AI budget and spend, the latest check with its AI summary and stats, and open and snoozed insights, most severe first. Checks run for companies with more than 1,000 active subscribers that sent email in the last 14 days. Requires the analytics:read scope.
      tags:
      - Account Health
      responses:
        '200':
          description: Account health report returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  accountHealth:
                    $ref: '#/components/schemas/AccountHealthOverview'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: API key is missing the analytics:read scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/TransientDatabaseUnavailable'
  /account-health/settings:
    patch:
      operationId: updateAccountHealthSettings
      summary: Update account health settings
      description: Turns the weekly account health check (Mondays, 05:00 UTC) on or off and chooses whether it drafts fixes. Pass only the fields to change; unknown fields are rejected. Who gets the findings is each person's account_health notification preference. Requires the companies:manage scope plus owner or admin access.
      tags:
      - Account Health
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountHealthSettings'
      responses:
        '200':
          description: Settings saved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  settings:
                    $ref: '#/components/schemas/AccountHealthSettings'
                  nextRunAt:
                    type:
                    - string
                    - 'null'
                    format: date-time
        '400':
          description: A field is unknown or has the wrong type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: API key is missing the companies:manage scope, or the user is not an owner or admin
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Company not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /account-health/runs:
    post:
      operationId: runAccountHealthCheck
      summary: Run account health check
      description: Queues an account health check now. A check that is already queued or running is returned instead, with alreadyInProgress true. Manual checks never send the report email, are limited to one every 10 minutes, and wait a day after a check that left findings open. Poll Get account health until runInProgress is false. Requires the sequences:write scope.
      tags:
      - Account Health
      responses:
        '202':
          description: Check queued, or the in-flight check returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  run:
                    $ref: '#/components/schemas/AccountHealthRun'
                  alreadyInProgress:
                    type: boolean
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: API key is missing the sequences:write scope, or the user has view-only access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: NOT_ELIGIBLE - the company has 1,000 or fewer active subscribers, or sent no email in the last 14 days
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: RATE_LIMITED - a manual check ran in the last 10 minutes, or the latest check (under a day old) left findings open. retryAfterSeconds says when to try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /account-health/insights/{insightId}:
    patch:
      operationId: updateAccountHealthInsight
      summary: Update account health insight
      description: Dismisses, snoozes, resolves or reopens one insight. A resolved insight reopens if the next check still finds it; a dismissed one stays hidden. Requires the sequences:write scope.
      tags:
      - Account Health
      parameters:
      - name: insightId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - action
              properties:
                action:
                  type: string
                  enum:
                  - dismiss
                  - snooze
                  - resolve
                  - reopen
                snoozeDays:
                  type: integer
                  minimum: 1
                  maximum: 90
                  description: Days to snooze, only with action snooze. Defaults to 7.
      responses:
        '200':
          description: Insight updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  insight:
                    $ref: '#/components/schemas/AccountHealthInsight'
        '400':
          description: action is missing or unknown, or snoozeDays is out of range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: API key is missing the sequences:write scope, or the user has view-only access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Insight not found in this company
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /account-health/insights/{insightId}/feedback:
    post:
      operationId: submitAccountHealthFeedback
      summary: Send account health feedback
      description: Records whether a finding was useful to the API key owner, with an optional comment, and passes it to the Sequenzy team to improve the suggestions. It changes nothing in the workspace. Each person has one answer per finding, for findings of any status; sending again replaces the rating and keeps the earlier comment unless comment is given (null or an empty string clears it). Requires the analytics:read scope, so viewers can answer too.
      tags:
      - Account Health
      parameters:
      - name: insightId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - rating
              properties:
                rating:
                  type: string
                  enum:
                  - useful
                  - not_useful
                comment:
                  type:
                  - string
                  - 'null'
                  maxLength: 2000
                  description: What made it useful or not. Leading and trailing spaces are trimmed. Omit to keep an earlier comment; null or an empty string clears it.
      responses:
        '200':
          description: Feedback saved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  insightId:
                    type: string
                  feedback:
                    $ref: '#/components/schemas/AccountHealthInsightFeedback'
        '400':
          description: rating is missing or unknown, comment is not a string or null or is longer than 2,000 characters, or the body has an unknown field
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: API key is missing the analytics:read scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Insight not found in this company
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /account-health/insights/{insightId}/fix:
    post:
      operationId: createAccountHealthFix
      summary: Build account health fix
      description: Builds the draft sequence an "event without a sequence" (unhandled_event) or "missing sequence" (missing_sequence) finding asks for, with its trigger, timing and titled email steps, then writes the emails with AI like a sequence from a template. An unhandled_event draft is triggered by its event; a missing_sequence draft uses the trigger and steps in the finding's evidence (new contacts, an event, or manual enrollment). It stays inactive until you enable it. Calling it again returns the existing draft with created false; email steps that still have no email (for example a draft the weekly check laid out that nobody opened yet) are written then, and existing emails are never rewritten. Requires the sequences:write scope.
      tags:
      - Account Health
      parameters:
      - name: insightId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A draft already existed and is returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountHealthFixResult'
        '201':
          description: Draft sequence built
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountHealthFixResult'
        '400':
          description: The insight is neither an event without a sequence nor a missing sequence
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: API key is missing the sequences:write scope, or the user has view-only access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Insight not found in this company
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: IN_PROGRESS - another request is building this fix right now
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  headers:
    RetryAfter:
      description: Number of seconds to wait before retrying the request.
      schema:
        type: integer
        minimum: 1
        example: 1
  responses:
    TransientDatabaseUnavailable:
      description: The database was temporarily unavailable. The request may be retried after the delay in Retry-After.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error: The service could not reach its database for a moment. Retry the request.
            code: SERVICE_UNAVAILABLE
  schemas:
    AccountHealthPeriodStats:
      type: object
      description: Email stats for one period. Rates are percentages (0-100).
      properties:
        sends:
          type: integer
        deliveries:
          type: integer
        opens:
          type: integer
        clicks:
          type: integer
        bounces:
          type: integer
        complaints:
          type: integer
        unsubscribes:
          type: integer
        openRate:
          type: number
        clickRate:
          type: number
        bounceRate:
          type: number
        complaintRate:
          type: number
        campaignsSent:
          type: integer
    AccountHealthFixResult:
      type: object
      properties:
        success:
          type: boolean
        sequenceId:
          type: string
        created:
          type: boolean
          description: False when an existing draft was returned.
        enrichmentStatus:
          type: string
          enum:
          - processing
          - not_queued
          description: 'When created is true, or when an existing draft still had email steps without an email (absent once every email exists). `processing` while AI writes the emails; poll Get Sequence for progress. `not_queued` means the draft exists but writing could not start: open it in the dashboard to write the emails, and do not build it again.'
    AccountHealthRun:
      type: object
      description: One account health check.
      properties:
        id:
          type: string
        trigger:
          type: string
          enum:
          - scheduled
          - manual
        status:
          type: string
          enum:
          - queued
          - running
          - completed
          - failed
          - skipped
        scheduledFor:
          type: string
          format: date-time
        startedAt:
          type:
          - string
          - 'null'
          format: date-time
        completedAt:
          type:
          - string
          - 'null'
          format: date-time
        skippedReason:
          type:
          - string
          - 'null'
          enum:
          - below_subscriber_minimum
          - no_recent_sends
          - disabled
          - null
        error:
          type:
          - string
          - 'null'
        summary:
          type:
          - string
          - 'null'
          description: Short AI-written summary. Null when the AI step did not run (budget exhausted or the call failed).
        stats:
          description: This period against the one before (7 days for weekly checks, 30 for monthly).
          oneOf:
          - type: object
            properties:
              periodDays:
                type: integer
              periodStart:
                type: string
                format: date-time
              periodEnd:
                type: string
                format: date-time
              current:
                $ref: '#/components/schemas/AccountHealthPeriodStats'
              previous:
                $ref: '#/components/schemas/AccountHealthPeriodStats'
          - type: 'null'
        insightCount:
          type: integer
          description: Open insights after this check.
        newInsightCount:
          type: integer
          description: Insights that were not open before this check.
        draftsCreated:
          type: integer
          description: Inactive draft sequences this check created.
        emailedAt:
          type:
          - string
          - 'null'
          format: date-time
          description: When the report email send was claimed for this run. Set once, before the first recipient, so a retry never sends it twice.
        createdAt:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          example: Error message
        code:
          type: string
          description: Optional stable machine-readable error discriminator when available.
          example: COMPANY_CREATE_REQUIRES_PERSONAL_KEY
        retryable:
          type: boolean
          description: Whether retrying the request can recover from the error.
        issues:
          type: array
          description: Field-level problems with the request, when the endpoint reports them. Up to ten entries; `error` summarizes the first three.
          items:
            $ref: '#/components/schemas/InputIssue'
      required:
      - error
    AccountHealthInsightFeedback:
      type: object
      description: One person's answer to "was this useful?" for one finding.
      properties:
        rating:
          type: string
          enum:
          - useful
          - not_useful
        comment:
          type:
          - string
          - 'null'
          description: What made it useful or not, or null.
        updatedAt:
          type: string
          format: date-time
    AccountHealthInsight:
      type: object
      description: One finding of the account health check. The same problem keeps one insight across checks.
      properties:
        id:
          type: string
        detector:
          type: string
          enum:
          - unhandled_event
          - stalled_sequence
          - campaign_gap
          - stale_campaign_drafts
          - underperforming_sequence_email
          - deliverability_spike
          - sending_domain_failing
          - missing_sequence
          - over_emailing
          - neglected_subscribers
          - unengaged_signups
        severity:
          type: string
          enum:
          - high
          - medium
          - low
        status:
          type: string
          enum:
          - open
          - snoozed
          - dismissed
          - resolved
        title:
          type: string
          example: Nothing happens after "trial_ended"
        detail:
          type: string
        recommendation:
          type: string
        evidence:
          type: object
          additionalProperties: true
          description: Detector-specific numbers behind the finding. Event findings carry `monthlyRevenue` (USD a month the people behind the event pay) when a payment integration syncs revenue to contacts. A missing_sequence finding carries the suggested `playbook`, `name`, `goal`, `trigger` and `steps`. An over_emailing finding carries `overloadedSubscribers`, `recipients`, `peakPerDay`, `dailyThreshold`, `windowDays`, `frequencyCap` (null when off) and `sources` (type campaign, sequence or api, id, name, sends, and respectsFrequencyCap for sequences, plus enrollsEveryTime when the sequence uses unlimited re-entry and peakEnrollmentsPerPerson, the most times one person entered it in the window; the api source has an empty id and stands for marketing Send API email, which the frequency cap does not limit). A neglected_subscribers finding carries `neglectedSubscribers`, `eligibleSubscribers`, `days`, `estimated` and `sampled`. An unengaged_signups finding carries `provider` and `providerLabel` (a consumer mailbox provider such as gmail or yahoo; business domains are never reported), `listId` and `listName` (the list these contacts joined first, null for none), `subscribers`, `emailed` (how many got at least two emails), `sends`, `engaged` (how many of them opened or clicked), `baselineEmailed` and `baselineEngaged` (the same for the other new signups), `windowDays`, `sampled` and `capped` (`true` when more people joined than were checked).
        subjectType:
          type: string
          enum:
          - event
          - automation
          - campaign
          - sending_domain
          - company
        subjectId:
          type:
          - string
          - 'null'
        subjectName:
          type:
          - string
          - 'null'
        fixAutomationId:
          type:
          - string
          - 'null'
          description: Inactive draft sequence the agent created to fix this, if any.
        actions:
          type: array
          description: What to do about the finding, primary first. Actions with a path open that dashboard screen; the others are performed by the api call listed, after the confirm prompt when one is given.
          items:
            $ref: '#/components/schemas/AccountHealthAction'
        feedback:
          description: Included in Get Account Health only. Your own answer to "was this useful?" for this finding (the API key owner's), or null when you have not answered. Other responses that return an insight leave it out.
          oneOf:
          - $ref: '#/components/schemas/AccountHealthInsightFeedback'
          - type: 'null'
        snoozedUntil:
          type:
          - string
          - 'null'
          format: date-time
        firstSeenAt:
          type: string
          format: date-time
        lastSeenAt:
          type: string
          format: date-time
        resolvedAt:
          type:
          - string
          - 'null'
          format: date-time
    AccountHealthAction:
      type: object
      properties:
        kind:
          type: string
          enum:
          - create_sequence
          - open_sequence
          - activate_sequence
          - pause_sequence
          - create_campaign
          - review_campaign_drafts
          - open_campaign
          - verify_sending_domain
          - open_domain_settings
          - review_deliverability
          - open_frequency_cap_settings
          - apply_frequency_cap
          - review_subscribers
        label:
          type: string
          example: Build this sequence
        primary:
          type: boolean
          description: The main fix. At most one action per insight is primary.
        path:
          type:
          - string
          - 'null'
          description: Dashboard path under /dashboard/company/{companyId}, for actions that open a screen.
          example: /campaign?action=new
        targetId:
          type:
          - string
          - 'null'
          description: The sequence, campaign or sending domain the action works on.
        confirm:
          description: Prompt to show before performing the action because it changes live sending.
          oneOf:
          - type: object
            properties:
              title:
                type: string
              description:
                type: string
              confirmLabel:
                type: string
              destructive:
                type: boolean
          - type: 'null'
        api:
          description: Public API call that performs the action, relative to /api/v1.
          oneOf:
          - type: object
            properties:
              method:
                type: string
                enum:
                - POST
              path:
                type: string
                example: /sequences/seq_123/disable
          - type: 'null'
        workspaceOnly:
          type: boolean
          description: Only owners and admins can perform it.
    AccountHealthOverview:
      type: object
      properties:
        eligibility:
          type: object
          properties:
            eligible:
              type: boolean
              description: True when hasMinimumSubscribers and sentRecently are both true.
            hasMinimumSubscribers:
              type: boolean
              description: Whether the workspace has more than minimumActiveSubscribers active subscribers.
            sentRecently:
              type: boolean
              description: Whether the workspace sent at least one non-test email in the last activityDays days.
            minimumActiveSubscribers:
              type: integer
              example: 1000
            activityDays:
              type: integer
              example: 14
        settings:
          $ref: '#/components/schemas/AccountHealthSettings'
        nextRunAt:
          type:
          - string
          - 'null'
          format: date-time
          description: Next scheduled check. Null when checks are off, the workspace is not eligible, or the scheduled slot has passed and the check has not started yet.
        latestRun:
          oneOf:
          - $ref: '#/components/schemas/AccountHealthRun'
          - type: 'null'
        runInProgress:
          type: boolean
          description: True while a check is queued or running. Poll until false.
        insights:
          type: array
          description: Open and snoozed insights, most severe first.
          items:
            $ref: '#/components/schemas/AccountHealthInsight'
    InputIssue:
      type: object
      properties:
        path:
          type: string
          description: Dotted field path, such as `audience.subscriberIds[0]`. Empty when the problem is with the request body itself.
          example: kind
        message:
          type: string
          description: What is wrong with the field.
          example: must be "add_tags"
        allowedValues:
          type: array
          description: Accepted values when the field only takes a fixed set of values.
          items: {}
          example:
          - add_tags
      required:
      - path
      - message
    AccountHealthSettings:
      type: object
      description: Whether the weekly account health check runs and whether it drafts fixes. Checks run every Monday at 05:00 UTC; the schedule and AI budget are fixed. Checks never send email to subscribers or activate anything.
      properties:
        enabled:
          type: boolean
          description: Whether weekly checks run. Manual checks work either way.
          example: true
        autonomy:
          type: string
          enum:
          - draft_fixes
          - report_only
          description: draft_fixes lets the agent lay out up to 2 inactive draft sequences per check (named for the business, with trigger, timing and titled email steps; the check writes no email, they are written when the draft is opened in the dashboard or its fix is requested); report_only only reports.
          example: draft_fixes
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key passed as Bearer token