openapi: 3.1.0
info:
  title: Triton One Customers Accounts Subscriptions API
  description: 'Account management REST API for Triton One. Use this API to manage accounts, subscriptions, endpoints, tokens, address watch lists, and rate tiers for your Triton RPC services. Token-based authentication via the Authorization header. Distinct from RPC consumption tokens — Customers API tokens are only used against customers.triton.one.

    '
  version: v1
  contact:
    name: Triton One Support
    url: https://triton.one
    email: support@triton.one
  license:
    name: Triton One Terms of Service
    url: https://triton.one/terms
servers:
- url: https://customers.triton.one
  description: Production Customers API
security:
- BearerAuth: []
tags:
- name: Subscriptions
  description: Manage subscriptions (Developer, Mainnet-Shared, Mainnet-Dedicated).
paths:
  /api/v1/subscriptions:
    get:
      summary: List Subscriptions
      description: List subscriptions visible to the authenticated token.
      operationId: listSubscriptions
      tags:
      - Subscriptions
      parameters:
      - name: subscription_type
        in: query
        schema:
          type: string
          enum:
          - developer
          - mainnet-shared
          - mainnet-dedicated
      - name: account_uuid
        in: query
        schema:
          type: string
          format: uuid
      - name: user_uuid
        in: query
        schema:
          type: string
          format: uuid
      - name: per
        in: query
        schema:
          type: integer
          default: 50
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      responses:
        '200':
          description: List of subscriptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionList'
    post:
      summary: Create Subscription
      description: Create a new subscription. Reseller role only.
      operationId: createSubscription
      tags:
      - Subscriptions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionCreate'
      responses:
        '201':
          description: Created subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionEnvelope'
  /api/v1/subscriptions/{subscriptionUuid}:
    get:
      summary: Get Subscription
      operationId: getSubscription
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/SubscriptionUuid'
      responses:
        '200':
          description: Subscription detail.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionEnvelope'
    put:
      summary: Update Subscription
      operationId: updateSubscription
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/SubscriptionUuid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
      responses:
        '200':
          description: Updated subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionEnvelope'
  /api/v1/subscriptions/{subscriptionUuid}/activate:
    put:
      summary: Activate Subscription
      description: Activate a previously deactivated subscription. Reseller role only.
      operationId: activateSubscription
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/SubscriptionUuid'
      responses:
        '204':
          description: Activated.
  /api/v1/subscriptions/{subscriptionUuid}/deactivate:
    put:
      summary: Deactivate Subscription
      description: Deactivate an active subscription. Reseller role only.
      operationId: deactivateSubscription
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/SubscriptionUuid'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                deactivation_reason:
                  type: string
      responses:
        '204':
          description: Deactivated.
components:
  schemas:
    Subscription:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        name:
          type: string
        subscription_type:
          type: string
          enum:
          - developer
          - mainnet-shared
          - mainnet-dedicated
        is_active:
          type: boolean
        starts_at:
          type: string
          format: date-time
        ends_at:
          type: string
          format: date-time
        endpoints:
          type: array
          items:
            $ref: '#/components/schemas/Endpoint'
        tokens:
          type: array
          items:
            $ref: '#/components/schemas/Token'
        supported_rate_tiers:
          type: array
          items:
            type: string
        account:
          $ref: '#/components/schemas/Account'
        deactivation_reasons:
          type: array
          items:
            type: string
    SubscriptionCreate:
      type: object
      required:
      - account_uuid
      - subscription_type
      - name
      properties:
        account_uuid:
          type: string
          format: uuid
        subscription_type:
          type: string
          enum:
          - developer
          - mainnet-shared
          - mainnet-dedicated
        name:
          type: string
        starts_at:
          type: string
          format: date-time
        ends_at:
          type: string
          format: date-time
    Token:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        value:
          type: string
          description: The opaque token string to use for RPC auth.
        auth_username:
          type: string
        name:
          type: string
        rate_tier:
          type: string
          enum:
          - free
          - tier1
          - tier2
          - tier3
          - dedi
        is_active:
          type: boolean
        deactivation_reasons:
          type: array
          items:
            type: string
    SubscriptionList:
      type: object
      properties:
        subscriptions:
          type: array
          items:
            $ref: '#/components/schemas/Subscription'
        meta:
          $ref: '#/components/schemas/Meta'
    Endpoint:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        name:
          type: string
        slug:
          type: string
        rate_tier:
          type: string
          enum:
          - free
          - tier1
          - tier2
          - tier3
          - dedi
        is_active:
          type: boolean
        values:
          type: array
          items:
            type: string
        allowed_origins:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
              is_active:
                type: boolean
    Meta:
      type: object
      properties:
        current_page:
          type: integer
        next_page:
          type:
          - integer
          - 'null'
        per_page:
          type: integer
        prev_page:
          type:
          - integer
          - 'null'
        total_pages:
          type: integer
        total_count:
          type: integer
    SubscriptionEnvelope:
      type: object
      properties:
        subscription:
          $ref: '#/components/schemas/Subscription'
    Account:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        name:
          type: string
        billing_address1:
          type: string
        billing_address2:
          type: string
        billing_address3:
          type: string
        billing_city:
          type: string
        billing_state_or_province:
          type: string
        billing_postal_code:
          type: string
        billing_country_code:
          type: string
        telephone_country_code:
          type: string
        telephone:
          type: string
        is_active:
          type: boolean
        subscriptions:
          type: array
          items:
            $ref: '#/components/schemas/Subscription'
        deactivation_reasons:
          type: array
          items:
            type: string
  parameters:
    SubscriptionUuid:
      name: subscriptionUuid
      in: path
      required: true
      schema:
        type: string
        format: uuid
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Customers API token passed in Authorization header.