upriver-ai Account API

openapi: 3.2.0
info:
  title: Upriver Account API
  description: A social insights API for ad generation platforms. It provides structured signals, like psychographics, behavioral insights, trends, and audience language, to help AI models generate relevant, higher-converting ads.
  version: 1.0.0
servers:
- url: https://api.upriver.ai
  description: Production API server
tags:
- name: Account
paths:
  /v1/usage:
    get:
      tags:
      - Account
      summary: Get Usage
      description: Get usage for the provided API key
      operationId: get_usage_v1_usage_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: start_date
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          description: Start of custom date range (YYYY-MM-DD, UTC inclusive)
          title: Start Date
        description: Start of custom date range (YYYY-MM-DD, UTC inclusive)
      - name: end_date
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          description: End of custom date range (YYYY-MM-DD, UTC inclusive)
          title: End Date
        description: End of custom date range (YYYY-MM-DD, UTC inclusive)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    UsageResponse:
      properties:
        created_at:
          type: integer
          title: Created At
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        email:
          anyOf:
          - type: string
          - type: 'null'
          title: Email
        usage_by_range:
          additionalProperties:
            $ref: '#/components/schemas/UsageByRange'
          type: object
          title: Usage By Range
        usage_period:
          $ref: '#/components/schemas/UsagePeriod'
        pricing:
          anyOf:
          - additionalProperties:
              $ref: '#/components/schemas/PricingInfo'
            type: object
          - type: 'null'
          title: Pricing
      type: object
      required:
      - created_at
      - name
      - email
      - usage_by_range
      - usage_period
      title: UsageResponse
    UsageByRange:
      properties:
        features:
          additionalProperties:
            anyOf:
            - $ref: '#/components/schemas/SimpleFeatureData'
            - $ref: '#/components/schemas/CreditFeatureData'
          type: object
          title: Features
        time_series:
          items:
            $ref: '#/components/schemas/PeriodUsage'
          type: array
          title: Time Series
          default: []
      type: object
      required:
      - features
      title: UsageByRange
    PricingInfo:
      properties:
        amount:
          type: number
          title: Amount
        unit:
          type: string
          title: Unit
        interval:
          type: string
          title: Interval
        included_usage:
          type: integer
          title: Included Usage
      type: object
      required:
      - amount
      - unit
      - interval
      - included_usage
      title: PricingInfo
    FeatureBreakdown:
      properties:
        interval:
          anyOf:
          - type: string
          - type: 'null'
          title: Interval
          description: Reset cadence, or lifetime for no scheduled reset.
        interval_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Interval Count
          description: Number of cadence units between resets, when known.
        balance:
          anyOf:
          - type: number
          - type: 'null'
          title: Balance
          description: Current remaining allowance for this credit schedule.
        usage:
          anyOf:
          - type: number
          - type: 'null'
          title: Usage
          description: Current usage charged to this credit schedule.
        included_usage:
          anyOf:
          - type: number
          - type: 'null'
          title: Included Usage
          description: Total allowance for this credit schedule.
        next_reset_at:
          anyOf:
          - type: integer
          - type: 'null'
          title: Next Reset At
          description: Next reset in UTC milliseconds, or null when none is supplied.
        unlimited:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Unlimited
          description: Whether this credit schedule has unlimited usage.
      type: object
      title: FeatureBreakdown
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    PeriodUsage:
      properties:
        period:
          anyOf:
          - type: integer
          - type: string
          title: Period
        features:
          additionalProperties:
            type: integer
          type: object
          title: Features
      type: object
      required:
      - period
      - features
      title: PeriodUsage
    UsageByFeature:
      properties:
        credit_rate:
          type: number
          title: Credit Rate
        quantity:
          type: integer
          title: Quantity
        credits_used:
          type: number
          title: Credits Used
      type: object
      required:
      - credit_rate
      - quantity
      - credits_used
      title: UsageByFeature
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SimpleFeatureData:
      properties:
        name:
          type: string
          title: Name
        balance:
          type: number
          title: Balance
        usage:
          type: number
          title: Usage
        included_usage:
          type: number
          title: Included Usage
        next_reset_at:
          anyOf:
          - type: integer
          - type: 'null'
          title: Next Reset At
          description: Aggregate reset in UTC milliseconds. May be null for mixed schedules; inspect breakdown for individual resets.
        interval:
          anyOf:
          - type: string
          - type: 'null'
          title: Interval
          description: Reset cadence; multiple indicates combined credit schedules.
        interval_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Interval Count
          description: Number of cadence units between resets, when known.
        breakdown:
          items:
            $ref: '#/components/schemas/FeatureBreakdown'
          type: array
          title: Breakdown
          description: Current allowances grouped by credit schedule. These balances do not change with the requested history range. No main schedule is implied.
      type: object
      required:
      - name
      - balance
      - usage
      - included_usage
      title: SimpleFeatureData
    UsagePeriod:
      properties:
        start:
          anyOf:
          - type: integer
          - type: 'null'
          title: Start
          description: Shared current usage period start in UTC milliseconds, or null if no unambiguous shared period is available.
        end:
          anyOf:
          - type: integer
          - type: 'null'
          title: End
          description: Shared current usage period end in UTC milliseconds, or null if no unambiguous shared period is available.
      type: object
      required:
      - start
      - end
      title: UsagePeriod
    CreditFeatureData:
      properties:
        name:
          type: string
          title: Name
        balance:
          type: number
          title: Balance
        usage:
          type: number
          title: Usage
        included_usage:
          type: number
          title: Included Usage
        next_reset_at:
          anyOf:
          - type: integer
          - type: 'null'
          title: Next Reset At
          description: Aggregate reset in UTC milliseconds. May be null for mixed schedules; inspect breakdown for individual resets.
        interval:
          anyOf:
          - type: string
          - type: 'null'
          title: Interval
          description: Reset cadence; multiple indicates combined credit schedules.
        interval_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Interval Count
          description: Number of cadence units between resets, when known.
        breakdown:
          items:
            $ref: '#/components/schemas/FeatureBreakdown'
          type: array
          title: Breakdown
          description: Current allowances grouped by credit schedule. These balances do not change with the requested history range. No main schedule is implied.
        usage_by_feature:
          additionalProperties:
            $ref: '#/components/schemas/UsageByFeature'
          type: object
          title: Usage By Feature
      type: object
      required:
      - name
      - balance
      - usage
      - included_usage
      - usage_by_feature
      title: CreditFeatureData
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key