> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperline.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an agent billing plan

> Assemble a new offer. `mode` is fixed at creation. A `windows` plan requires at least one window definition; `rate_card_id` must name a card whose denomination matches the mode. Asking for `overage_mode: metered` also mints the plan's hidden invoice container — the pass-through catalog product that carries metered overage onto ordinary invoices — so overage is billable the moment a customer joins.



## OpenAPI

````yaml post /v1/agents/plans
openapi: 3.1.0
info:
  title: Hyperline API
  version: 0.0.0
servers:
  - url: https://api.hyperline.co
  - url: https://sandbox.api.hyperline.co
security: []
paths:
  /v1/agents/plans:
    post:
      tags:
        - Agents
      summary: Create an agent billing plan
      description: >-
        Assemble a new offer. `mode` is fixed at creation. A `windows` plan
        requires at least one window definition; `rate_card_id` must name a card
        whose denomination matches the mode. Asking for `overage_mode: metered`
        also mints the plan's hidden invoice container — the pass-through
        catalog product that carries metered overage onto ordinary invoices — so
        overage is billable the moment a customer joins.
      operationId: createAgentPlan
      requestBody:
        description: Create plan payload
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 120
                rate_card_id:
                  type:
                    - string
                    - 'null'
                  minLength: 1
                overage_mode:
                  type:
                    - string
                    - 'null'
                  enum:
                    - refuse
                    - metered
                markup_percent:
                  type:
                    - string
                    - 'null'
                  pattern: ^\d+(\.\d+)?$
                overage_markup_percent:
                  type:
                    - string
                    - 'null'
                  pattern: ^\d+(\.\d+)?$
                overage_rate_card_id:
                  type:
                    - string
                    - 'null'
                  minLength: 1
                windows:
                  type: array
                  items:
                    type: object
                    properties:
                      key:
                        type: string
                        minLength: 1
                        maxLength: 32
                        pattern: ^[a-z0-9][a-z0-9_-]*$
                      duration_minutes:
                        type: integer
                        minimum: 1
                        maximum: 527040
                      included_units:
                        type: string
                        maxLength: 40
                        pattern: ^\d+(\.\d+)?$
                    required:
                      - key
                      - duration_minutes
                      - included_units
                  minItems: 1
                  maxItems: 8
                per_seat_credits:
                  type:
                    - string
                    - 'null'
                  pattern: ^\d+(\.\d+)?$
                grant_rollover_enabled:
                  type: boolean
                settlement_interval_minutes:
                  type:
                    - integer
                    - 'null'
                  minimum: 60
                  maximum: 44640
                settlement_schedule:
                  type:
                    - string
                    - 'null'
                  enum:
                    - calendar_month
                mode:
                  type: string
                  enum:
                    - wallet
                    - credits
                    - windows
              required:
                - name
                - mode
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  mode:
                    type: string
                    enum:
                      - wallet
                      - credits
                      - windows
                  rate_card:
                    type:
                      - object
                      - 'null'
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      denomination:
                        type: string
                        enum:
                          - credits
                          - units
                          - currency
                      currency:
                        type:
                          - string
                          - 'null'
                      description:
                        type:
                          - string
                          - 'null'
                      fallback_per_usd:
                        type:
                          - string
                          - 'null'
                      rows:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            kind:
                              type: string
                              enum:
                                - llm
                                - item
                            provider:
                              type:
                                - string
                                - 'null'
                            model:
                              type:
                                - string
                                - 'null'
                            rate_per_m_input:
                              type:
                                - string
                                - 'null'
                            rate_per_m_output:
                              type:
                                - string
                                - 'null'
                            rate_unit:
                              type:
                                - string
                                - 'null'
                            rate_per_m_cached_input:
                              type:
                                - string
                                - 'null'
                            rate_per_m_cache_write:
                              type:
                                - string
                                - 'null'
                            dimensions:
                              type: array
                              items:
                                type: object
                                properties:
                                  key:
                                    type: string
                                    pattern: ^[a-z0-9_.]{1,64}$
                                  rate:
                                    type: string
                                    maxLength: 40
                                    pattern: ^\d+(\.\d+)?$
                                  per:
                                    type: string
                                    enum:
                                      - 1m
                                      - 1k
                                      - unit
                                required:
                                  - key
                                  - rate
                                  - per
                          required:
                            - id
                            - kind
                            - provider
                            - model
                            - rate_per_m_input
                            - rate_per_m_output
                            - rate_unit
                            - rate_per_m_cached_input
                            - rate_per_m_cache_write
                            - dimensions
                      attached_product_id:
                        type:
                          - string
                          - 'null'
                      using_policy_count:
                        type: number
                      using_policies:
                        type: array
                        items:
                          type: object
                          properties:
                            customer_id:
                              type: string
                            customer_name:
                              type: string
                            agent_slug:
                              type: string
                          required:
                            - customer_id
                            - customer_name
                            - agent_slug
                      using_plan_count:
                        type: number
                    required:
                      - id
                      - name
                      - denomination
                      - currency
                      - description
                      - fallback_per_usd
                      - rows
                      - attached_product_id
                      - using_policy_count
                      - using_policies
                      - using_plan_count
                  windows:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                          minLength: 1
                          maxLength: 32
                          pattern: ^[a-z0-9][a-z0-9_-]*$
                        duration_minutes:
                          type: integer
                          minimum: 1
                          maximum: 527040
                        included_units:
                          type: string
                          maxLength: 40
                          pattern: ^\d+(\.\d+)?$
                      required:
                        - key
                        - duration_minutes
                        - included_units
                  markup_percent:
                    type:
                      - string
                      - 'null'
                  overage_mode:
                    type: string
                    enum:
                      - refuse
                      - metered
                  overage_markup_percent:
                    type:
                      - string
                      - 'null'
                  overage_rate_card_id:
                    type:
                      - string
                      - 'null'
                  settlement_interval_minutes:
                    type:
                      - number
                      - 'null'
                  settlement_schedule:
                    type:
                      - string
                      - 'null'
                    enum:
                      - calendar_month
                  per_seat_credits:
                    type:
                      - string
                      - 'null'
                  grant_rollover_enabled:
                    type: boolean
                  billing_item_ids:
                    type: array
                    items:
                      type: string
                  price_configuration_ids:
                    type: array
                    items:
                      type: string
                  using_policy_count:
                    type: number
                  is_default:
                    type: boolean
                required:
                  - id
                  - name
                  - mode
                  - rate_card
                  - windows
                  - markup_percent
                  - overage_mode
                  - overage_markup_percent
                  - overage_rate_card_id
                  - settlement_interval_minutes
                  - settlement_schedule
                  - per_seat_credits
                  - grant_rollover_enabled
                  - billing_item_ids
                  - price_configuration_ids
                  - using_policy_count
                  - is_default
      security:
        - bearer: []
components:
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT

````