openapi: 3.2.0
info:
  title: Hilt Memberships API
  description: Hilt Pay Workspace and Hilt Pay API routes for zero-custody Solana checkout, MPP metered payment channels, receipts, memberships, entitlements, native subscriptions, webhooks, and support context.
  version: 1.0.0
  contact:
    name: Hilt
    url: https://www.hilt.so
    email: hello@hilt.so
  x-guidance: Start with POST /v1/access/agent-bootstrap. An agent can purchase 30 days of Starter, Growth, or Scale through the matching x402 V2 activation endpoint paid in Solana USDC. For metered integrations, settle PAYMENT-SIGNATURE through POST /v1/access/x402/settle and atomically consume through POST /v1/access/entitlements/consume before serving. Never send private keys, seed phrases, or wallet secrets.
servers:
- url: https://api.hilt.so
tags:
- name: Memberships
paths:
  /v1/memberships:
    get:
      tags:
      - Memberships
      summary: List memberships
      operationId: api_list_memberships_v1_memberships_get
      parameters:
      - name: product_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Product Id
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
      - name: platform
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Platform
      - name: q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Q
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/memberships/lookup:
    get:
      tags:
      - Memberships
      summary: Lookup memberships by wallet, identity, or transaction
      operationId: api_lookup_memberships_v1_memberships_lookup_get
      parameters:
      - name: product_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Product Id
      - name: wallet
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Wallet
      - name: identity
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Identity
      - name: tx_signature
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Tx Signature
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/memberships/renewal-intelligence:
    get:
      tags:
      - Memberships
      summary: Renewal cohorts, reminders, and reporting
      operationId: api_membership_renewal_intelligence_v1_memberships_renewal_intelligence_get
      parameters:
      - name: window_days
        in: query
        required: false
        schema:
          type: integer
          maximum: 60
          minimum: 1
          default: 7
          title: Window Days
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 60
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipRenewalIntelligenceResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/memberships/{membership_id}:
    get:
      tags:
      - Memberships
      summary: Get membership by ID
      operationId: api_get_membership_v1_memberships__membership_id__get
      parameters:
      - name: membership_id
        in: path
        required: true
        schema:
          type: string
          title: Membership Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipDetailResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/memberships/{membership_id}/notes:
    patch:
      tags:
      - Memberships
      summary: Save merchant notes for a membership
      operationId: api_update_membership_notes_v1_memberships__membership_id__notes_patch
      parameters:
      - name: membership_id
        in: path
        required: true
        schema:
          type: string
          title: Membership Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MembershipNotesRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipDetailResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/memberships/{membership_id}/profile:
    patch:
      tags:
      - Memberships
      summary: Update member display details
      operationId: api_update_membership_profile_v1_memberships__membership_id__profile_patch
      parameters:
      - name: membership_id
        in: path
        required: true
        schema:
          type: string
          title: Membership Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MembershipProfileRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipDetailResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/memberships/{membership_id}/gift:
    post:
      tags:
      - Memberships
      summary: Gift extra access time to a member
      operationId: api_gift_membership_extension_v1_memberships__membership_id__gift_post
      parameters:
      - name: membership_id
        in: path
        required: true
        schema:
          type: string
          title: Membership Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MembershipGiftRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipDetailResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/memberships/{membership_id}/retry-delivery:
    post:
      tags:
      - Memberships
      summary: Retry membership access delivery
      operationId: api_retry_membership_delivery_v1_memberships__membership_id__retry_delivery_post
      parameters:
      - name: membership_id
        in: path
        required: true
        schema:
          type: string
          title: Membership Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipDeliveryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/memberships/{membership_id}/delivery-diagnostics:
    get:
      tags:
      - Memberships
      summary: Inspect Telegram or Discord automation for a membership
      operationId: api_membership_delivery_diagnostics_v1_memberships__membership_id__delivery_diagnostics_get
      parameters:
      - name: membership_id
        in: path
        required: true
        schema:
          type: string
          title: Membership Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipDeliveryDiagnosticsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/memberships/{membership_id}/delivery-support-ticket:
    post:
      tags:
      - Memberships
      summary: Open or reuse a support ticket for a delivery issue
      operationId: api_membership_delivery_support_ticket_v1_memberships__membership_id__delivery_support_ticket_post
      parameters:
      - name: membership_id
        in: path
        required: true
        schema:
          type: string
          title: Membership Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipSupportTicketResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/memberships/{membership_id}/reactivation:
    get:
      tags:
      - Memberships
      summary: Get renewal and reactivation links for a membership
      operationId: api_membership_reactivation_detail_v1_memberships__membership_id__reactivation_get
      parameters:
      - name: membership_id
        in: path
        required: true
        schema:
          type: string
          title: Membership Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipReactivationResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    MembershipProfileRequest:
      properties:
        platform_display:
          type: string
          title: Platform Display
          default: ''
      type: object
      title: MembershipProfileRequest
    MembershipDeliveryDiagnosticsResponse:
      properties:
        membership_id:
          type: string
          title: Membership Id
        owner_id:
          type: string
          title: Owner Id
        product_id:
          type: string
          title: Product Id
        product_title:
          anyOf:
          - type: string
          - type: 'null'
          title: Product Title
        product_slug:
          anyOf:
          - type: string
          - type: 'null'
          title: Product Slug
        platform:
          type: string
          title: Platform
        platform_user_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Platform User Id
        platform_display:
          anyOf:
          - type: string
          - type: 'null'
          title: Platform Display
        membership_status:
          anyOf:
          - type: string
          - type: 'null'
          title: Membership Status
        delivery_status:
          anyOf:
          - type: string
          - type: 'null'
          title: Delivery Status
        delivery_last_error:
          anyOf:
          - type: string
          - type: 'null'
          title: Delivery Last Error
        latest_payment_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Latest Payment Id
        latest_tx_signature:
          anyOf:
          - type: string
          - type: 'null'
          title: Latest Tx Signature
        automation_ready:
          type: boolean
          title: Automation Ready
        fallback_ready:
          type: boolean
          title: Fallback Ready
        fallback_value:
          anyOf:
          - type: string
          - type: 'null'
          title: Fallback Value
        overall_status:
          type: string
          title: Overall Status
        summary:
          type: string
          title: Summary
        provider_state:
          type: object
          title: Provider State
        checks:
          items:
            type: object
          type: array
          title: Checks
        actions:
          additionalProperties:
            type: boolean
          type: object
          title: Actions
        generated_at:
          type: string
          title: Generated At
      additionalProperties: true
      type: object
      required:
      - membership_id
      - owner_id
      - product_id
      - product_title
      - product_slug
      - platform
      - platform_user_id
      - platform_display
      - membership_status
      - delivery_status
      - delivery_last_error
      - latest_payment_id
      - latest_tx_signature
      - automation_ready
      - fallback_ready
      - fallback_value
      - overall_status
      - summary
      - provider_state
      - checks
      - actions
      - generated_at
      title: MembershipDeliveryDiagnosticsResponse
    MembershipEvent:
      properties:
        id:
          type: integer
          title: Id
        membership_id:
          type: string
          title: Membership Id
        payment_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Payment Id
        event_type:
          type: string
          title: Event Type
        actor_type:
          type: string
          title: Actor Type
        actor_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Actor Id
        payload_json:
          type: object
          title: Payload Json
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
      additionalProperties: true
      type: object
      required:
      - id
      - membership_id
      - payment_id
      - event_type
      - actor_type
      - actor_id
      - payload_json
      - created_at
      title: MembershipEvent
    MembershipDeliveryResponse:
      properties:
        membership:
          $ref: '#/components/schemas/Membership'
        delivery:
          type: object
          title: Delivery
      additionalProperties: true
      type: object
      required:
      - membership
      - delivery
      title: MembershipDeliveryResponse
    MembershipSupportTicketResponse:
      properties:
        ticket_id:
          type: string
          title: Ticket Id
        created:
          type: boolean
          title: Created
      additionalProperties: true
      type: object
      required:
      - ticket_id
      - created
      title: MembershipSupportTicketResponse
    MembershipDetailResponse:
      properties:
        membership:
          $ref: '#/components/schemas/Membership'
        periods:
          items:
            $ref: '#/components/schemas/MembershipPeriod'
          type: array
          title: Periods
        events:
          items:
            $ref: '#/components/schemas/MembershipEvent'
          type: array
          title: Events
        auto_renew:
          anyOf:
          - type: object
          - type: 'null'
          title: Auto Renew
      additionalProperties: true
      type: object
      required:
      - membership
      - periods
      - events
      - auto_renew
      title: MembershipDetailResponse
    MembershipGiftRequest:
      properties:
        days:
          type: integer
          title: Days
        note:
          type: string
          title: Note
          default: ''
      type: object
      required:
      - days
      title: MembershipGiftRequest
    MembershipNotesRequest:
      properties:
        notes:
          type: string
          title: Notes
          default: ''
      type: object
      title: MembershipNotesRequest
    MembershipReactivationResponse:
      properties:
        membership_id:
          type: string
          title: Membership Id
        product_title:
          type: string
          title: Product Title
        product_slug:
          type: string
          title: Product Slug
        amount_minor_units:
          type: integer
          title: Amount Minor Units
        amount_display:
          type: string
          title: Amount Display
        token_mint:
          type: string
          title: Token Mint
        billing_interval_days:
          type: integer
          title: Billing Interval Days
        access_period:
          type: string
          title: Access Period
        membership_started_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Membership Started At
        merchant_name:
          type: string
          title: Merchant Name
        merchant_wallet_preview:
          type: string
          title: Merchant Wallet Preview
        access_target_label:
          anyOf:
          - type: string
          - type: 'null'
          title: Access Target Label
        renewal_url:
          type: string
          title: Renewal Url
        reactivation_url:
          type: string
          title: Reactivation Url
        templates:
          type: object
          title: Templates
        generated_at:
          type: string
          title: Generated At
      additionalProperties: true
      type: object
      required:
      - membership_id
      - product_title
      - product_slug
      - amount_minor_units
      - amount_display
      - token_mint
      - billing_interval_days
      - access_period
      - membership_started_at
      - merchant_name
      - merchant_wallet_preview
      - access_target_label
      - renewal_url
      - reactivation_url
      - templates
      - generated_at
      title: MembershipReactivationResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    MembershipPeriod:
      properties:
        id:
          type: string
          title: Id
        membership_id:
          type: string
          title: Membership Id
        payment_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Payment Id
        tx_signature:
          anyOf:
          - type: string
          - type: 'null'
          title: Tx Signature
        amount_lamports:
          type: integer
          title: Amount Lamports
        token_mint:
          type: string
          title: Token Mint
        period_start_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Period Start At
        period_end_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Period End At
        status:
          type: string
          title: Status
        activated_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Activated At
        revoked_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Revoked At
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
      additionalProperties: true
      type: object
      required:
      - id
      - membership_id
      - payment_id
      - tx_signature
      - amount_lamports
      - token_mint
      - period_start_at
      - period_end_at
      - status
      - activated_at
      - revoked_at
      - created_at
      title: MembershipPeriod
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    MembershipRenewalIntelligenceResponse:
      properties:
        summary:
          type: object
          title: Summary
        expiring_memberships:
          items:
            type: object
          type: array
          title: Expiring Memberships
        product_reports:
          items:
            type: object
          type: array
          title: Product Reports
        recent_events:
          items:
            $ref: '#/components/schemas/MembershipEvent'
          type: array
          title: Recent Events
        generated_at:
          type: string
          title: Generated At
      additionalProperties: true
      type: object
      required:
      - summary
      - expiring_memberships
      - product_reports
      - recent_events
      - generated_at
      title: MembershipRenewalIntelligenceResponse
    MembershipListResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/Membership'
          type: array
          title: Items
        count:
          type: integer
          title: Count
      additionalProperties: true
      type: object
      required:
      - items
      - count
      title: MembershipListResponse
    Membership:
      properties:
        id:
          type: string
          title: Id
        product_id:
          type: string
          title: Product Id
        owner_id:
          type: string
          title: Owner Id
        platform:
          type: string
          title: Platform
        platform_user_id:
          type: string
          title: Platform User Id
        platform_display:
          anyOf:
          - type: string
          - type: 'null'
          title: Platform Display
        customer_identity_type:
          type: string
          title: Customer Identity Type
        customer_identity_value:
          type: string
          title: Customer Identity Value
        payer_wallet:
          anyOf:
          - type: string
          - type: 'null'
          title: Payer Wallet
        status:
          type: string
          title: Status
        current_period_start_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Current Period Start At
        current_period_end_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Current Period End At
        grace_ends_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Grace Ends At
        latest_payment_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Latest Payment Id
        latest_tx_signature:
          anyOf:
          - type: string
          - type: 'null'
          title: Latest Tx Signature
        delivery_status:
          type: string
          title: Delivery Status
        delivery_last_error:
          anyOf:
          - type: string
          - type: 'null'
          title: Delivery Last Error
        renewal_count:
          type: integer
          title: Renewal Count
        last_reminder_sent_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Reminder Sent At
        metadata_json:
          type: object
          title: Metadata Json
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
        updated_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Updated At
      additionalProperties: true
      type: object
      required:
      - id
      - product_id
      - owner_id
      - platform
      - platform_user_id
      - platform_display
      - customer_identity_type
      - customer_identity_value
      - payer_wallet
      - status
      - current_period_start_at
      - current_period_end_at
      - grace_ends_at
      - latest_payment_id
      - latest_tx_signature
      - delivery_status
      - delivery_last_error
      - renewal_count
      - last_reminder_sent_at
      - metadata_json
      - created_at
      - updated_at
      title: Membership
x-hilt-agent-commerce:
  offer: https://api.hilt.so/v1/agent-commerce/offer
  catalog: https://api.hilt.so/agent-catalog.json
  pricing: https://api.hilt.so/pricing
  x402: https://api.hilt.so/x402