Sequenzy Account API

openapi: 3.2.0
info:
  title: Sequenzy Account 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
paths:
  /account:
    get:
      operationId: getAccount
      summary: Get account
      description: Returns the companies available to the authenticated API key, the currently selected company, and a read-only summary of the key's own permissions.
      tags:
      - Account
      responses:
        '200':
          description: Account context returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  user:
                    type: object
                    properties:
                      id:
                        type: string
                        example: user_abc123
                  companies:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        role:
                          type: string
                          description: Account-key access role. Viewer access remains read-only regardless of key scopes; marketer access is limited to marketing scopes (no transactional, settings, integration, webhook, team, or API-key scopes).
                          enum:
                          - owner
                          - admin
                          - marketer
                          - viewer
                  currentCompanyId:
                    type:
                    - string
                    - 'null'
                  apiKeyPermissions:
                    type: object
                    description: Read-only identity and permission metadata for the authenticated key, including a recovery URL. This does not bypass resource scopes.
                    properties:
                      activeKey:
                        type: object
                        description: Non-secret identity of the bearer key that authenticated this request. Use it to verify that a restarted client loaded the intended replacement key.
                        properties:
                          id:
                            type: string
                          name:
                            type:
                            - string
                            - 'null'
                          prefix:
                            type:
                            - string
                            - 'null'
                            description: Stored non-secret key prefix, such as seq_live_A or seq_user_B. Pair it with the key name and ID when verifying a replacement credential.
                          type:
                            type:
                            - string
                            - 'null'
                            enum:
                            - company
                            - personal
                            - null
                      preset:
                        type: string
                        enum:
                        - full_access
                        - read_only
                        - agent_safe
                        - ai_drafting
                        - data_ingest_safe
                        - data_ingest_automations
                        - transactional_sender
                        - marketing_sender
                        - custom
                      fullAccess:
                        type: boolean
                      selectedScopeCount:
                        type: integer
                        description: Number of currently defined scopes enabled for the key. For full-access keys this equals currentScopeCount, while fullAccess still indicates future-scope access.
                      currentScopeCount:
                        type: integer
                        description: Total number of permission scopes defined when the response was generated.
                      description:
                        type: string
                        description: Human-readable explanation of the effective permission selection.
                      scopes:
                        type:
                        - array
                        - 'null'
                        items:
                          type: string
                      canDiscoverMarketingWork:
                        type: boolean
                        description: Whether the key can read campaigns, sequences, and landing pages.
                      missingMarketingReadScopes:
                        type: array
                        items:
                          type: string
                      canSendLive:
                        type: boolean
                        description: Whether the key holds any scope that delivers to a real person. False for drafting-only keys, which can create and update content but cannot send it.
                      missingLiveDeliveryScopes:
                        type: array
                        description: Live-delivery scopes the key does not hold, such as transactional:send for one-to-one sends or campaigns:send for campaigns. Drafting permission such as transactional:write does not imply delivery.
                        items:
                          type: string
                      liveDeliveryBlockedByRole:
                        type: boolean
                        description: Whether the authenticated user's role in the selected workspace blocks every kind of sending regardless of key scopes. Personal keys held by a viewer are read-only, so widening the key's permissions does not enable delivery; the role has to change. A marketer is not blocked here because they can still send campaigns; their transactional restriction is listed in roleRestrictedScopes.
                      roleRestrictedScopes:
                        type: array
                        description: Scopes the authenticated user's workspace role cannot use through a personal key, such as transactional:send or team:manage for a marketer. Empty for owners, admins, and company keys.
                        items:
                          type: string
                      manageUrl:
                        type:
                        - string
                        - 'null'
                        format: uri
                        description: Direct management URL for the authenticated key. Personal keys open Account API Keys; company keys open the selected workspace's API Keys settings.
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/TransientDatabaseUnavailable'
  /api-keys:
    get:
      operationId: listApiKeys
      summary: List API keys
      description: Lists company-scoped API keys as non-secret metadata. The caller must have the `api_keys:manage` permission. Account-scoped keys select the company with the x-company-id header. Plain key values and stored hashes are never returned.
      tags:
      - Account
      responses:
        '200':
          description: API key metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  apiKeys:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiKeyMetadata'
                required:
                - success
                - apiKeys
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Missing required API key management permission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/TransientDatabaseUnavailable'
    post:
      operationId: createApiKey
      summary: Create API key
      description: Creates a company-scoped API key. The caller must have the `api_keys:manage` permission. Account-scoped keys select the target company with the x-company-id header; companyId in the JSON body is not a supported selector. The plain key is returned only once.
      tags:
      - Account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                name:
                  type: string
                  description: Human-readable key name.
                preset:
                  type: string
                  description: Permission preset to apply when scopes is omitted. Defaults to full_access. Full-access keys are stored with scopes set to null, meaning all current and future permissions.
                  enum:
                  - full_access
                  - read_only
                  - agent_safe
                  - ai_drafting
                  - data_ingest_safe
                  - data_ingest_automations
                  - transactional_sender
                  - marketing_sender
                scopes:
                  type: array
                  description: Explicit permission scopes for the new key. Overrides preset when provided.
                  minItems: 1
                  items:
                    type: string
      responses:
        '200':
          description: API key created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  apiKey:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      key:
                        type: string
                        description: Plain API key. This is shown only on creation.
                      prefix:
                        type: string
                      scopes:
                        type:
                        - array
                        - 'null'
                        description: Explicit permission scopes, or null for full access.
                        items:
                          type: string
                      permissions:
                        type: object
                        description: Effective permission receipt for the newly created key. Only scopes set to null grant current and future full access.
                        properties:
                          preset:
                            type: string
                            description: Effective preset derived from the stored scopes. An explicit all-current-scopes array is custom, not full_access.
                          fullAccess:
                            type: boolean
                          selectedScopeCount:
                            type: integer
                          currentScopeCount:
                            type: integer
                          description:
                            type: string
                      createdAt:
                        type: string
                        format: date-time
                  message:
                    type: string
                  instructions:
                    type: object
                    additionalProperties: true
        '400':
          description: Invalid permission preset or scope list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Missing required API key management permission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: API key could not be created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api-key-handoff:
    post:
      operationId: requestApiKeyHandoff
      summary: Request API key handoff
      description: Builds a dashboard link that opens the create-key form prefilled with a suggested name and permissions. Requires only `account:read`, because it creates nothing, changes nothing, and returns no secret - the new key is issued in the owner's authenticated browser session. Use it when key management is blocked because the calling key lacks `api_keys:manage`, which cannot be granted through the API by the key that is missing it. Pass replaceApiKeyId to rotate; the dashboard then offers to revoke the predecessor once the replacement exists.
      tags:
      - Account
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                name:
                  type: string
                  description: Suggested name for the new key. Trimmed to 80 characters in the link.
                preset:
                  type: string
                  description: Suggested permission preset.
                  enum:
                  - full_access
                  - read_only
                  - agent_safe
                  - ai_drafting
                  - data_ingest_safe
                  - data_ingest_automations
                  - transactional_sender
                  - marketing_sender
                scopes:
                  type: array
                  description: Suggested explicit permission scopes. Overrides preset when provided.
                  minItems: 1
                  items:
                    type: string
                replaceApiKeyId:
                  type: string
                  description: ID of the key the new one replaces. Pass the literal string "current" for the key making the request.
      responses:
        '200':
          description: Handoff link prepared
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  handoff:
                    type: object
                    properties:
                      url:
                        type: string
                        description: Dashboard URL that opens the create-key form prefilled with the request.
                      manageUrl:
                        type: string
                        description: The plain API Keys settings URL, without the prefill.
                      keyType:
                        type: string
                        description: Whether the link targets workspace or account API key settings.
                        enum:
                        - company
                        - personal
                      name:
                        type:
                        - string
                        - 'null'
                      preset:
                        type:
                        - string
                        - 'null'
                      scopes:
                        type:
                        - array
                        - 'null'
                        items:
                          type: string
                      permissions:
                        type:
                        - object
                        - 'null'
                        description: Permission receipt for the suggested selection. Null when the request suggested no preset and no scopes, because the form then opens on the dashboard default.
                        additionalProperties: true
                      replaces:
                        type:
                        - object
                        - 'null'
                        description: The key being replaced. name and prefix are populated only when it is the key making the request.
                        properties:
                          id:
                            type: string
                          name:
                            type:
                            - string
                            - 'null'
                          prefix:
                            type:
                            - string
                            - 'null'
                          isCurrentKey:
                            type: boolean
                      canSelfServe:
                        type: boolean
                        description: True when the calling key already holds api_keys:manage and could create the replacement directly.
                      deliversKeyToCaller:
                        type: boolean
                        description: Always false. The new key is shown in the browser and never returned through this endpoint.
                  message:
                    type: string
                  nextSteps:
                    type: array
                    items:
                      type: string
                required:
                - success
                - handoff
        '400':
          description: Invalid permission preset, scope list, or replaceApiKeyId
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Missing required account read permission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api-keys/{apiKeyId}:
    patch:
      operationId: updateApiKey
      summary: Update API key
      description: Renames a company-scoped API key and/or replaces its permissions in place. The caller must have the `api_keys:manage` permission. The key value is unchanged. Added permissions apply on the next retry; removed permissions may remain usable for up to five minutes while API caches expire. `preset` and `scopes` replace the whole selection rather than merging into it. The response contains non-secret metadata only.
      tags:
      - Account
      parameters:
      - name: apiKeyId
        in: path
        required: true
        description: Exact API key ID returned by the list API keys endpoint.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              description: Provide at least one of name, preset, or scopes.
              properties:
                name:
                  type: string
                  description: New human-readable key name.
                preset:
                  type: string
                  description: Replacement permission preset. Full-access keys are stored with scopes set to null, meaning all current and future permissions.
                  enum:
                  - full_access
                  - read_only
                  - agent_safe
                  - ai_drafting
                  - data_ingest_safe
                  - data_ingest_automations
                  - transactional_sender
                  - marketing_sender
                scopes:
                  type: array
                  description: Replacement explicit permission scopes. Overrides preset when provided.
                  minItems: 1
                  items:
                    type: string
      responses:
        '200':
          description: API key updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  apiKey:
                    $ref: '#/components/schemas/ApiKeyMetadata'
                  message:
                    type: string
                    example: API key permissions updated. Added permissions apply on the next retry; removed permissions may take up to five minutes to expire across API instances.
                required:
                - success
                - apiKey
                - message
        '400':
          description: Nothing to update, or an invalid permission preset or scope list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Missing required API key management permission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: API key not found for the selected company
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: revokeApiKey
      summary: Revoke API key
      description: Permanently revokes a company-scoped API key. The caller must have the `api_keys:manage` permission. The response contains non-secret metadata only.
      tags:
      - Account
      parameters:
      - name: apiKeyId
        in: path
        required: true
        description: Exact API key ID returned by the list API keys endpoint.
        schema:
          type: string
      responses:
        '200':
          description: API key revoked
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  apiKey:
                    $ref: '#/components/schemas/ApiKeyMetadata'
                  message:
                    type: string
                    example: API key revoked successfully.
                required:
                - success
                - apiKey
                - message
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Missing required API key management permission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: API key not found for the selected company
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/TransientDatabaseUnavailable'
  /integration-guide:
    post:
      operationId: getIntegrationGuide
      summary: Get integration guide
      description: Returns a framework-specific code example and implementation tip for common integration use cases.
      tags:
      - Account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                framework:
                  type: string
                  example: nextjs
                use_case:
                  type: string
                  example: transactional
      responses:
        '200':
          description: Integration guide returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  framework:
                    type: string
                  use_case:
                    type: string
                  code:
                    type: string
                  tip:
                    type: string
        '401':
          description: Unauthorized
          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:
    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
    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
    ApiKeyMetadata:
      type: object
      description: Non-secret metadata for a company-scoped API key. Plain key values and stored hashes are never returned.
      additionalProperties: false
      properties:
        id:
          type: string
        name:
          type: string
        prefix:
          type: string
          description: Non-secret key prefix for identifying the credential.
        type:
          type: string
          enum:
          - company
        scopes:
          type:
          - array
          - 'null'
          description: Explicit permission scopes, or null for full access.
          items:
            type: string
        permissions:
          type: object
          description: Effective permission receipt for the key.
          additionalProperties: true
        deviceName:
          type:
          - string
          - 'null'
        lastUsedAt:
          type:
          - string
          - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        isCurrent:
          type: boolean
          description: Whether this is the credential authenticating the request.
      required:
      - id
      - name
      - prefix
      - type
      - scopes
      - permissions
      - deviceName
      - lastUsedAt
      - createdAt
      - updatedAt
      - isCurrent
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key passed as Bearer token