openapi: 3.1.0
info:
  title: AFM Access Profiles Usage API
  version: 0.1.0
tags:
- name: Usage
paths:
  /api/v1/usage/stats:
    get:
      tags:
      - Usage
      summary: Get Usage Stats
      description: 'Get daily usage statistics for the API key''s organization.


        Returns paginated daily usage statistics with optional filtering by date range,

        model, provider, and source. Each record represents aggregated usage for a specific

        user/model/provider/source combination on a given date.'
      operationId: get_usage_stats_api_v1_usage_stats_get
      parameters:
      - name: start_date
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Start date for filtering (ISO format)
          title: Start Date
        description: Start date for filtering (ISO format)
      - name: end_date
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: End date for filtering (ISO format)
          title: End Date
        description: End date for filtering (ISO format)
      - name: model
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by specific model
          title: Model
        description: Filter by specific model
      - name: model_provider
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by model provider
          title: Model Provider
        description: Filter by model provider
      - name: source
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by source (api or app)
          title: Source
        description: Filter by source (api or app)
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          description: Number of records to return
          default: 100
          title: Limit
        description: Number of records to return
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Number of records to skip
          default: 0
          title: Offset
        description: Number of records to skip
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UsageStatsResponse'
                title: Response Get Usage Stats Api V1 Usage Stats Get
        '401':
          description: Authentication Fails
          content:
            application/json:
              example:
                detail: Authentication failed due to invalid or missing API key
        '422':
          description: Invalid Parameters
          content:
            application/json:
              example:
                detail: One or more request parameters are invalid or out of range
        '500':
          description: Server Error
          content:
            application/json:
              example:
                detail: An internal server error occurred while processing the request
  /api/v1/usage/summary:
    get:
      tags:
      - Usage
      summary: Get Usage Summary
      description: 'Get aggregated usage summary statistics for the API key''s organization.


        Returns high-level metrics including total tokens, requests, unique users,

        models, providers, and breakdown by API vs app usage.'
      operationId: get_usage_summary_api_v1_usage_summary_get
      parameters:
      - name: start_date
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Start date for summary (ISO format)
          title: Start Date
        description: Start date for summary (ISO format)
      - name: end_date
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: End date for summary (ISO format)
          title: End Date
        description: End date for summary (ISO format)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_external__usage__models__UsageSummaryResponse'
        '401':
          description: Authentication Fails
          content:
            application/json:
              example:
                detail: Authentication failed due to invalid or missing API key
        '422':
          description: Invalid Parameters
          content:
            application/json:
              example:
                detail: One or more request parameters are invalid or out of range
        '500':
          description: Server Error
          content:
            application/json:
              example:
                detail: An internal server error occurred while processing the request
  /api/v1/usage/credits:
    get:
      tags:
      - Usage
      summary: Get User Credits
      description: Endpoint for users to get their credit balance.
      operationId: get_user_credits_api_v1_usage_credits_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditsResponse'
        '401':
          description: Authentication Fails
          content:
            application/json:
              example:
                detail: Authentication failed due to invalid or missing API key
        '422':
          description: Invalid Parameters
          content:
            application/json:
              example:
                detail: One or more request parameters are invalid or out of range
        '500':
          description: Server Error
          content:
            application/json:
              example:
                detail: An internal server error occurred while processing the request
  /v1/usage/stats:
    get:
      tags:
      - Usage
      summary: Get Usage Stats
      description: 'Get daily usage statistics for the API key''s organization.


        Returns paginated daily usage statistics with optional filtering by date range,

        model, provider, and source. Each record represents aggregated usage for a specific

        user/model/provider/source combination on a given date.'
      operationId: get_usage_stats_v1_usage_stats_get
      parameters:
      - name: start_date
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Start date for filtering (ISO format)
          title: Start Date
        description: Start date for filtering (ISO format)
      - name: end_date
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: End date for filtering (ISO format)
          title: End Date
        description: End date for filtering (ISO format)
      - name: model
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by specific model
          title: Model
        description: Filter by specific model
      - name: model_provider
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by model provider
          title: Model Provider
        description: Filter by model provider
      - name: source
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by source (api or app)
          title: Source
        description: Filter by source (api or app)
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          description: Number of records to return
          default: 100
          title: Limit
        description: Number of records to return
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Number of records to skip
          default: 0
          title: Offset
        description: Number of records to skip
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UsageStatsResponse'
                title: Response Get Usage Stats V1 Usage Stats Get
        '401':
          description: Authentication Fails
          content:
            application/json:
              example:
                detail: Authentication failed due to invalid or missing API key
        '422':
          description: Invalid Parameters
          content:
            application/json:
              example:
                detail: One or more request parameters are invalid or out of range
        '500':
          description: Server Error
          content:
            application/json:
              example:
                detail: An internal server error occurred while processing the request
  /v1/usage/summary:
    get:
      tags:
      - Usage
      summary: Get Usage Summary
      description: 'Get aggregated usage summary statistics for the API key''s organization.


        Returns high-level metrics including total tokens, requests, unique users,

        models, providers, and breakdown by API vs app usage.'
      operationId: get_usage_summary_v1_usage_summary_get
      parameters:
      - name: start_date
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Start date for summary (ISO format)
          title: Start Date
        description: Start date for summary (ISO format)
      - name: end_date
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: End date for summary (ISO format)
          title: End Date
        description: End date for summary (ISO format)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_external__usage__models__UsageSummaryResponse'
        '401':
          description: Authentication Fails
          content:
            application/json:
              example:
                detail: Authentication failed due to invalid or missing API key
        '422':
          description: Invalid Parameters
          content:
            application/json:
              example:
                detail: One or more request parameters are invalid or out of range
        '500':
          description: Server Error
          content:
            application/json:
              example:
                detail: An internal server error occurred while processing the request
  /v1/usage/credits:
    get:
      tags:
      - Usage
      summary: Get User Credits
      description: Endpoint for users to get their credit balance.
      operationId: get_user_credits_v1_usage_credits_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditsResponse'
        '401':
          description: Authentication Fails
          content:
            application/json:
              example:
                detail: Authentication failed due to invalid or missing API key
        '422':
          description: Invalid Parameters
          content:
            application/json:
              example:
                detail: One or more request parameters are invalid or out of range
        '500':
          description: Server Error
          content:
            application/json:
              example:
                detail: An internal server error occurred while processing the request
components:
  schemas:
    UsageStatsResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        user_id:
          type: string
          format: uuid
          title: User Id
        org_id:
          type: string
          format: uuid
          title: Org Id
        email:
          anyOf:
          - type: string
          - type: 'null'
          title: Email
        model:
          type: string
          title: Model
        source:
          type: string
          title: Source
        input_tokens:
          type: integer
          title: Input Tokens
        output_tokens:
          type: integer
          title: Output Tokens
        total_tokens:
          type: integer
          title: Total Tokens
        total_requests:
          type: integer
          title: Total Requests
        date:
          type: string
          format: date-time
          title: Date
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - user_id
      - org_id
      - email
      - model
      - source
      - input_tokens
      - output_tokens
      - total_tokens
      - total_requests
      - date
      - created_at
      title: UsageStatsResponse
      description: API response model for daily usage statistics.
    api_external__usage__models__UsageSummaryResponse:
      properties:
        total_input_tokens:
          type: integer
          title: Total Input Tokens
        total_output_tokens:
          type: integer
          title: Total Output Tokens
        total_tokens:
          type: integer
          title: Total Tokens
        total_requests:
          type: integer
          title: Total Requests
        unique_users:
          type: integer
          title: Unique Users
        unique_models:
          type: integer
          title: Unique Models
        unique_providers:
          type: integer
          title: Unique Providers
        api_usage:
          type: integer
          title: Api Usage
        app_usage:
          type: integer
          title: App Usage
        date_range_days:
          type: integer
          title: Date Range Days
      type: object
      required:
      - total_input_tokens
      - total_output_tokens
      - total_tokens
      - total_requests
      - unique_users
      - unique_models
      - unique_providers
      - api_usage
      - app_usage
      - date_range_days
      title: UsageSummaryResponse
      description: API response model for aggregated usage summary.
    CreditsResponse:
      properties:
        credit_balance:
          type: number
          title: Credit Balance
      type: object
      required:
      - credit_balance
      title: CreditsResponse
      description: API response model for credit balance.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer