Cayra

Cayra Billing API

The billing API from Cayra — 3 operation(s) for billing.

GitHub OpenAPI

Operations 6

POST /api/v1/admin/billings Create Billing #
GET /api/v1/admin/billings List Billings #
GET /api/v1/admin/billings/{billing_id} Get Billing #
PATCH /api/v1/admin/billings/{billing_id} Update Billing #
POST /api/v1/admin/credit-events Create Credit Event #
GET /api/v1/admin/credit-events List Credit Events #

Specifications

⚙
OpenAPI
https://artifacts.apis.io/cayra-io/openapi/cayra-io-billing-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://artifacts.apis.io/cayra-io/json-schema/cayra-io-deployment-details-schema.json
📊
JSONSchema
https://artifacts.apis.io/cayra-io/json-schema/cayra-io-license-details-schema.json
📊
JSONSchema
https://artifacts.apis.io/cayra-io/json-schema/cayra-io-license-create-request-schema.json
📊
JSONSchema
https://artifacts.apis.io/cayra-io/json-schema/cayra-io-billing-response-schema.json
📊
JSONSchema
https://artifacts.apis.io/cayra-io/json-schema/cayra-io-company-create-request-schema.json
📊
JSONSchema
https://artifacts.apis.io/cayra-io/json-schema/cayra-io-plaud-webhook-payload-schema.json

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/cayra-io:cayra-io-billing-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

cayra-io-billing-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Cayra License Server Billing API
  description: '# Cayra Chat Agent - License Management Server


    Centralized license management for on-premise deployments.


    ## Features


    - 🔑 License key generation (installation, update, trial)

    - ⏰ Dynamic expiry management (extend/shorten licenses)

    - 🔄 Activation tracking and monitoring

    - 💓 Heartbeat mechanism (1-hour intervals)

    - 📊 Audit logging for compliance

    - 🔐 JWT tokens with RSA-4096 encryption


    ## API Categories


    ### Admin Endpoints (Requires API Key)

    Manage licenses, view activations, update expiry dates.


    ### Client Endpoints (Public)

    Activate licenses, send heartbeats, check status.


    ## Authentication


    Admin endpoints require API key in header:

    ```

    X-Admin-API-Key: your-admin-key-here

    ```


    ## Security


    - 🔒 RSA-4096 asymmetric encryption

    - 🔐 JWT tokens for offline validation

    - 📝 Complete audit trail

    - 🛡️ Rate limiting (Phase 6)'
  contact:
    name: Cayra AI Team
    email: support@cayra.ai
  license:
    name: Proprietary
  version: 1.0.0
tags:
- name: Billing
paths:
  /api/v1/admin/billings:
    post:
      tags:
      - Billing
      summary: Create Billing
      operationId: create_billing_api_v1_admin_billings_post
      parameters:
      - name: x-admin-api-key
        in: header
        required: false
        schema:
          type: string
          title: X-Admin-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillingCreateRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Billing
      summary: List Billings
      operationId: list_billings_api_v1_admin_billings_get
      parameters:
      - name: company_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Company Id
      - name: license_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: License Id
      - name: status_filter
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Status Filter
      - name: billing_type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Billing Type
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Offset
      - name: x-admin-api-key
        in: header
        required: false
        schema:
          type: string
          title: X-Admin-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/admin/billings/{billing_id}:
    get:
      tags:
      - Billing
      summary: Get Billing
      operationId: get_billing_api_v1_admin_billings__billing_id__get
      parameters:
      - name: billing_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Billing Id
      - name: x-admin-api-key
        in: header
        required: false
        schema:
          type: string
          title: X-Admin-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Billing
      summary: Update Billing
      operationId: update_billing_api_v1_admin_billings__billing_id__patch
      parameters:
      - name: billing_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Billing Id
      - name: x-admin-api-key
        in: header
        required: false
        schema:
          type: string
          title: X-Admin-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillingUpdateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/admin/credit-events:
    post:
      tags:
      - Billing
      summary: Create Credit Event
      operationId: create_credit_event_api_v1_admin_credit_events_post
      parameters:
      - name: x-admin-api-key
        in: header
        required: false
        schema:
          type: string
          title: X-Admin-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreditEventCreateRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditEventResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Billing
      summary: List Credit Events
      operationId: list_credit_events_api_v1_admin_credit_events_get
      parameters:
      - name: license_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: License Id
      - name: billing_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Billing Id
      - name: event_type
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/CreditEventTypeEnum'
          - type: 'null'
          title: Event Type
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Offset
      - name: x-admin-api-key
        in: header
        required: false
        schema:
          type: string
          title: X-Admin-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditEventListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    BillingListResponse:
      properties:
        billings:
          items:
            $ref: '#/components/schemas/BillingResponse'
          type: array
          title: Billings
        total:
          type: integer
          title: Total
        limit:
          type: integer
          title: Limit
        offset:
          type: integer
          title: Offset
      type: object
      required:
      - billings
      - total
      - limit
      - offset
      title: BillingListResponse
      description: Paginated billing list
    CreditEventCreateRequest:
      properties:
        license_id:
          type: string
          format: uuid
          title: License Id
        billing_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Billing Id
        event_type:
          allOf:
          - $ref: '#/components/schemas/CreditEventTypeEnum'
          description: Ledger event type
        credit_delta:
          type: number
          title: Credit Delta
          description: Positive or negative amount
        currency:
          type: string
          maxLength: 16
          title: Currency
          default: USD
        payment_channel:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Payment Channel
        reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason
        metadata:
          type: object
          title: Metadata
        occurred_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Occurred At
      type: object
      required:
      - license_id
      - event_type
      - credit_delta
      title: CreditEventCreateRequest
      description: Create license credit event
    BillingStatusEnum:
      type: string
      enum:
      - draft
      - pending
      - paid
      - failed
      - cancelled
      - refunded
      title: BillingStatusEnum
    BillingUpdateRequest:
      properties:
        status:
          anyOf:
          - $ref: '#/components/schemas/BillingStatusEnum'
          - type: 'null'
        amount:
          anyOf:
          - type: number
            minimum: 0.0
          - type: 'null'
          title: Amount
        currency:
          anyOf:
          - type: string
            maxLength: 16
          - type: 'null'
          title: Currency
        tax_amount:
          anyOf:
          - type: number
            minimum: 0.0
          - type: 'null'
          title: Tax Amount
        payment_provider:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Payment Provider
        provider_reference:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: Provider Reference
        metadata:
          anyOf:
          - type: object
          - type: 'null'
          title: Metadata
        notes:
          anyOf:
          - type: string
          - type: 'null'
          title: Notes
        due_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Due At
        paid_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Paid At
        canceled_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Canceled At
      type: object
      title: BillingUpdateRequest
      description: Update billing status/metadata
    BillingResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        company_id:
          type: string
          format: uuid
          title: Company Id
        license_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: License Id
        billing_code:
          type: string
          title: Billing Code
        billing_type:
          $ref: '#/components/schemas/BillingTypeEnum'
        status:
          $ref: '#/components/schemas/BillingStatusEnum'
        amount:
          type: number
          title: Amount
        currency:
          type: string
          title: Currency
        tax_amount:
          type: number
          title: Tax Amount
        total_amount:
          type: number
          title: Total Amount
        payment_provider:
          anyOf:
          - type: string
          - type: 'null'
          title: Payment Provider
        provider_reference:
          anyOf:
          - type: string
          - type: 'null'
          title: Provider Reference
        metadata:
          type: object
          title: Metadata
        notes:
          anyOf:
          - type: string
          - type: 'null'
          title: Notes
        issued_at:
          type: string
          format: date-time
          title: Issued At
        due_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Due At
        paid_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Paid At
        canceled_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Canceled At
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - id
      - company_id
      - license_id
      - billing_code
      - billing_type
      - status
      - amount
      - currency
      - tax_amount
      - total_amount
      - payment_provider
      - provider_reference
      - metadata
      - notes
      - issued_at
      - due_at
      - paid_at
      - canceled_at
      - created_at
      - updated_at
      title: BillingResponse
      description: Billing representation
    CreditEventResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        license_id:
          type: string
          format: uuid
          title: License Id
        billing_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Billing Id
        event_type:
          $ref: '#/components/schemas/CreditEventTypeEnum'
        credit_delta:
          type: number
          title: Credit Delta
        currency:
          type: string
          title: Currency
        balance_before:
          anyOf:
          - type: number
          - type: 'null'
          title: Balance Before
        balance_after:
          anyOf:
          - type: number
          - type: 'null'
          title: Balance After
        payment_channel:
          anyOf:
          - type: string
          - type: 'null'
          title: Payment Channel
        reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason
        metadata:
          type: object
          title: Metadata
        occurred_at:
          type: string
          format: date-time
          title: Occurred At
        created_by:
          anyOf:
          - type: string
          - type: 'null'
          title: Created By
      type: object
      required:
      - id
      - license_id
      - billing_id
      - event_type
      - credit_delta
      - currency
      - balance_before
      - balance_after
      - payment_channel
      - reason
      - metadata
      - occurred_at
      - created_by
      title: CreditEventResponse
      description: Credit ledger entry
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CreditEventListResponse:
      properties:
        events:
          items:
            $ref: '#/components/schemas/CreditEventResponse'
          type: array
          title: Events
        total:
          type: integer
          title: Total
        limit:
          type: integer
          title: Limit
        offset:
          type: integer
          title: Offset
      type: object
      required:
      - events
      - total
      - limit
      - offset
      title: CreditEventListResponse
      description: Paginated credit ledger
    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
    BillingCreateRequest:
      properties:
        company_id:
          type: string
          format: uuid
          title: Company Id
          description: Company the billing belongs to
        license_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: License Id
          description: Related license ID
        billing_code:
          anyOf:
          - type: string
            maxLength: 100
          - type: 'null'
          title: Billing Code
          description: Optional custom billing code
        billing_type:
          allOf:
          - $ref: '#/components/schemas/BillingTypeEnum'
          description: Billing type
        status:
          allOf:
          - $ref: '#/components/schemas/BillingStatusEnum'
          default: draft
        amount:
          type: number
          minimum: 0.0
          title: Amount
        currency:
          type: string
          maxLength: 16
          title: Currency
          default: USD
        tax_amount:
          type: number
          minimum: 0.0
          title: Tax Amount
          default: 0
        payment_provider:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Payment Provider
        provider_reference:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: Provider Reference
        metadata:
          type: object
          title: Metadata
        notes:
          anyOf:
          - type: string
          - type: 'null'
          title: Notes
        issued_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Issued At
        due_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Due At
      type: object
      required:
      - company_id
      - billing_type
      - amount
      title: BillingCreateRequest
      description: Create billing/invoice entry
    CreditEventTypeEnum:
      type: string
      enum:
      - topup
      - adjustment
      - refund
      title: CreditEventTypeEnum
    BillingTypeEnum:
      type: string
      enum:
      - prepaid_tokens
      - onprem_license
      title: BillingTypeEnum