openapi: 3.0.3
info:
  title: Quiltt Admin & Auth REST API
  description: >-
    Quiltt is a hybrid API platform. This REST specification covers the
    administrative and authentication surfaces used to manage Profiles,
    Connections, Session Tokens, and Webhooks. End-user financial data
    (accounts, balances, transactions, holdings, statements) is read through
    the separate GraphQL Data API at https://api.quiltt.io/v1/graphql.
    Admin endpoints are authenticated with your Quiltt API Secret Key
    (Bearer). Session Token endpoints live on the auth host.
  termsOfService: https://www.quiltt.io/legal/terms
  contact:
    name: Quiltt Support
    url: https://www.quiltt.dev
    email: support@quiltt.io
  version: '1.0'
servers:
  - url: https://api.quiltt.io/v1
    description: Admin API (Profiles, Connections, Webhooks)
  - url: https://auth.quiltt.io/v1
    description: Auth API (Session Tokens)
security:
  - apiSecretKey: []
tags:
  - name: Profiles
    description: Manage end-user Profiles.
  - name: Connections
    description: Manage a Profile's aggregator Connections.
  - name: Session Tokens
    description: Issue, verify, and revoke Profile-scoped session tokens.
  - name: Webhooks
    description: Manage webhook subscriptions for real-time events.
paths:
  /profiles:
    get:
      operationId: listProfiles
      tags:
        - Profiles
      summary: List Profiles
      description: Retrieve a paginated list of Profiles in the environment.
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
        - name: per_page
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: A list of Profiles.
          content:
            application/json:
              schema:
                type: object
                properties:
                  profiles:
                    type: array
                    items:
                      $ref: '#/components/schemas/Profile'
    post:
      operationId: createProfile
      tags:
        - Profiles
      summary: Create Profile
      description: Create a new Profile.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProfileInput'
      responses:
        '201':
          description: The created Profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Profile'
  /profiles/{profileId}:
    parameters:
      - name: profileId
        in: path
        required: true
        description: The Profile ID (e.g. p_17KTMuJseY4Cx2LcbgKA7wU) or your UUID.
        schema:
          type: string
    get:
      operationId: getProfile
      tags:
        - Profiles
      summary: Get Profile
      responses:
        '200':
          description: The requested Profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Profile'
        '404':
          description: Profile not found.
    patch:
      operationId: updateProfile
      tags:
        - Profiles
      summary: Update Profile
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProfileInput'
      responses:
        '200':
          description: The updated Profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Profile'
    delete:
      operationId: deleteProfile
      tags:
        - Profiles
      summary: Delete Profile
      description: Permanently delete a Profile and its associated data.
      responses:
        '204':
          description: Profile deleted.
  /profiles/{profileId}/connections:
    parameters:
      - name: profileId
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: listConnections
      tags:
        - Connections
      summary: List Connections
      description: List the Connections belonging to a Profile.
      responses:
        '200':
          description: A list of Connections.
          content:
            application/json:
              schema:
                type: object
                properties:
                  connections:
                    type: array
                    items:
                      $ref: '#/components/schemas/Connection'
  /profiles/{profileId}/connections/{connectionId}:
    parameters:
      - name: profileId
        in: path
        required: true
        schema:
          type: string
      - name: connectionId
        in: path
        required: true
        description: The Connection ID.
        schema:
          type: string
    get:
      operationId: getConnection
      tags:
        - Connections
      summary: Get Connection
      responses:
        '200':
          description: The requested Connection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connection'
        '404':
          description: Connection not found.
    delete:
      operationId: deleteConnection
      tags:
        - Connections
      summary: Delete Connection
      description: >-
        Disconnect and remove a Connection, stopping Quiltt from syncing data
        from the underlying aggregator source.
      responses:
        '204':
          description: Connection deleted.
  /webhooks:
    get:
      operationId: listWebhooks
      tags:
        - Webhooks
      summary: List Webhook Subscriptions
      responses:
        '200':
          description: A list of webhook subscriptions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhooks:
                    type: array
                    items:
                      $ref: '#/components/schemas/Webhook'
    post:
      operationId: createWebhook
      tags:
        - Webhooks
      summary: Create Webhook Subscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookInput'
      responses:
        '201':
          description: The created webhook subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
  /webhooks/{webhookId}:
    parameters:
      - name: webhookId
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getWebhook
      tags:
        - Webhooks
      summary: Get Webhook Subscription
      responses:
        '200':
          description: The requested webhook subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
    delete:
      operationId: deleteWebhook
      tags:
        - Webhooks
      summary: Delete Webhook Subscription
      responses:
        '204':
          description: Webhook subscription deleted.
  /users/sessions:
    post:
      operationId: issueSessionToken
      tags:
        - Session Tokens
      summary: Issue Session Token
      description: >-
        Issue a Profile-scoped JWT session token. Authenticated with your API
        Secret Key. Served from https://auth.quiltt.io/v1. Rate limited to
        10 per hour and 20 per day per Profile.
      servers:
        - url: https://auth.quiltt.io/v1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionTokenInput'
      responses:
        '201':
          description: The issued session token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionToken'
        '429':
          description: Session token rate limit exceeded for this Profile.
  /users/session:
    get:
      operationId: verifySessionToken
      tags:
        - Session Tokens
      summary: Verify Session Token
      description: >-
        Verify a session token. Pass the session token itself as the Bearer
        credential. Served from https://auth.quiltt.io/v1.
      servers:
        - url: https://auth.quiltt.io/v1
      security:
        - sessionToken: []
      responses:
        '200':
          description: The token is valid; returns its claims.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionToken'
        '401':
          description: The token is invalid, revoked, or expired.
  /users/sessions/revoke:
    post:
      operationId: revokeSessionToken
      tags:
        - Session Tokens
      summary: Revoke Session Token
      description: >-
        Revoke a session token. Pass the token to revoke as the Bearer
        credential. Served from https://auth.quiltt.io/v1.
      servers:
        - url: https://auth.quiltt.io/v1
      security:
        - sessionToken: []
      responses:
        '200':
          description: The token was revoked.
components:
  securitySchemes:
    apiSecretKey:
      type: http
      scheme: bearer
      description: Your Quiltt API Secret Key used for Admin and token-issuance calls.
    sessionToken:
      type: http
      scheme: bearer
      description: A Profile-scoped JWT session token.
  schemas:
    Profile:
      type: object
      properties:
        id:
          type: string
          example: p_17KTMuJseY4Cx2LcbgKA7wU
        uuid:
          type: string
          description: Your own external identifier for the Profile.
        name:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
        birthday:
          type: string
          format: date
        address:
          type: object
          additionalProperties: true
        metadata:
          type: object
          additionalProperties: true
          description: Arbitrary key-value data you store on the Profile.
        connectionIds:
          type: array
          items:
            type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ProfileInput:
      type: object
      properties:
        uuid:
          type: string
        name:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
        birthday:
          type: string
          format: date
        address:
          type: object
          additionalProperties: true
        metadata:
          type: object
          additionalProperties: true
    Connection:
      type: object
      properties:
        id:
          type: string
        provider:
          type: string
          enum:
            - PLAID
            - MX
            - FINICITY
            - MASTERCARD
          description: The underlying aggregator source.
        status:
          type: string
          enum:
            - INITIALIZING
            - SYNCING
            - SYNCED
            - DISCONNECTED
            - ERROR_REPAIRABLE
            - ERROR_SERVICE
            - ERROR_INSTITUTION
          description: Sync status of the Connection.
        institution:
          type: object
          properties:
            name:
              type: string
            logo:
              type: string
        externallyManaged:
          type: boolean
        metadata:
          type: object
          additionalProperties: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    SessionTokenInput:
      type: object
      properties:
        userId:
          type: string
          description: An existing Profile ID to scope the token to.
        uuid:
          type: string
          description: Your external identifier; creates a Profile if none exists.
        email:
          type: string
          format: email
        metadata:
          type: object
          additionalProperties: true
    SessionToken:
      type: object
      properties:
        token:
          type: string
          description: The JWT session token.
        userId:
          type: string
        environmentId:
          type: string
        expiration:
          type: integer
          description: Unix timestamp when the token expires.
        expiresAt:
          type: string
          format: date-time
    Webhook:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            type: string
          example:
            - profile.created
            - connection.synced.successful
            - account.verified
        enabled:
          type: boolean
        createdAt:
          type: string
          format: date-time
    WebhookInput:
      type: object
      required:
        - url
        - events
      properties:
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            type: string
            enum:
              - profile.created
              - connection.synced.successful
              - connection.synced.successful.initial
              - connection.synced.successful.historical
              - connection.synced.errored.repairable
              - account.verified