Paid costs API

openapi: 3.1.0
info:
  title: API Reference agents costs API
  version: 1.0.0
servers:
- url: https://api.agentpaid.io/api/v1
  description: Production
tags:
- name: costs
paths:
  /costs/bulk:
    post:
      operationId: create-costs
      summary: Submit cost and/or usage data
      description: 'Ingests a batch of cost records. Each record is either a pre-computed `cost` (caller supplies amount + currency) or a `usage` record (caller supplies vendor/model/token counts and Paid prices it server-side). The batch is all-or-nothing: if any record fails validation, the entire request is rejected with a 400 and nothing is persisted.'
      tags:
      - costs
      parameters:
      - name: Authorization
        in: header
        description: API Key authentication using Bearer token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/costIngestResponse'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: '403'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        description: Body
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/costIngestRequest'
components:
  schemas:
    costOverride:
      type: object
      properties:
        amount:
          type: number
          format: double
        currency:
          type: string
          description: ISO 4217 currency code, e.g. "USD".
      required:
      - amount
      - currency
      description: If supplied, overrides server-side pricing. The usage breakdown is still recorded for analytics.
      title: costOverride
    CustomerById:
      type: object
      properties:
        customerId:
          type: string
          description: The Paid customer ID
      required:
      - customerId
      title: CustomerById
    tokenUsage:
      type: object
      properties:
        inputTokens:
          type: integer
          description: Non-cached input tokens. Matches Anthropic's `input_tokens` semantic (does not include cached or cache-creation tokens).
        outputTokens:
          type: integer
          description: Output tokens generated by the model.
        cacheReadInputTokens:
          type: integer
          description: Input tokens served from cache (cache hit).
        cacheCreationInputTokens:
          type: integer
          description: Input tokens written to cache on this request (Anthropic prompt caching).
        reasoningOutputTokens:
          type: integer
          description: Reasoning tokens emitted by reasoning models (o1/o3, Claude extended thinking).
      title: tokenUsage
    ProductAttribution:
      oneOf:
      - $ref: '#/components/schemas/ProductById'
      - $ref: '#/components/schemas/ProductByExternalId'
      title: ProductAttribution
    ProductById:
      type: object
      properties:
        productId:
          type: string
          description: The Paid product ID
      required:
      - productId
      title: ProductById
    ProductByExternalId:
      type: object
      properties:
        externalProductId:
          type: string
          description: Your external product ID
      required:
      - externalProductId
      title: ProductByExternalId
    cost:
      oneOf:
      - type: object
        properties:
          type:
            type: string
            enum:
            - cost
            description: 'Discriminator value: cost'
          timestamp:
            type: string
            format: date-time
            description: Record time in RFC3339 format with timezone. Defaults to server receive time.
          customer:
            $ref: '#/components/schemas/CustomerAttribution'
          product:
            $ref: '#/components/schemas/ProductAttribution'
          metadata:
            type: object
            additionalProperties:
              description: Any type
            description: Free-form metadata for filtering and analytics.
          amount:
            type: number
            format: double
            description: Cost amount in major units of `currency` (e.g. dollars).
          currency:
            type: string
            description: ISO 4217 currency code, e.g. "USD".
          vendor:
            type: string
            description: Optional vendor tag for analytics (e.g. "openai", "anthropic"). Not used for pricing in this mode.
          model:
            type: string
            description: Optional model tag for analytics (e.g. "gpt-4o-2024-08-06").
        required:
        - type
        - customer
        - amount
        - currency
        description: cost variant
      - type: object
        properties:
          type:
            type: string
            enum:
            - usage
            description: 'Discriminator value: usage'
          timestamp:
            type: string
            format: date-time
            description: Record time in RFC3339 format with timezone. Defaults to server receive time.
          customer:
            $ref: '#/components/schemas/CustomerAttribution'
          product:
            $ref: '#/components/schemas/ProductAttribution'
          metadata:
            type: object
            additionalProperties:
              description: Any type
            description: Free-form metadata for filtering and analytics.
          vendor:
            type: string
            description: Provider name, used together with `model` to look up pricing (e.g. "openai", "anthropic").
          model:
            type: string
            description: Exact provider model ID (e.g. "gpt-4o-2024-08-06").
          usage:
            $ref: '#/components/schemas/tokenUsage'
          costOverride:
            $ref: '#/components/schemas/costOverride'
        required:
        - type
        - customer
        - vendor
        - model
        - usage
        description: usage variant
      discriminator:
        propertyName: type
      title: cost
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
        details:
          type: string
      required:
      - error
      title: ErrorResponse
    costIngestRequest:
      type: object
      properties:
        costs:
          type: array
          items:
            $ref: '#/components/schemas/cost'
      required:
      - costs
      title: costIngestRequest
    CustomerByExternalId:
      type: object
      properties:
        externalCustomerId:
          type: string
          description: Your external customer ID
      required:
      - externalCustomerId
      title: CustomerByExternalId
    costIngestResponse:
      type: object
      properties:
        ingested:
          type: integer
          description: Number of records persisted.
        duplicates:
          type: integer
          description: Number of records skipped because their `idempotencyKey` matched a previously ingested record.
      required:
      - ingested
      - duplicates
      title: costIngestResponse
    CustomerAttribution:
      oneOf:
      - $ref: '#/components/schemas/CustomerById'
      - $ref: '#/components/schemas/CustomerByExternalId'
      title: CustomerAttribution
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer