kokofinance-net Developers API

openapi: 3.2.0
info:
  title: Koko Finance Developers API
  description: Credit card portfolio intelligence — analyze portfolios, compare cards, get recommendations, and check renewal value.
  version: 1.0.0
tags:
- name: Developers
  description: Developer account management — dashboard, API keys, organization settings.
paths:
  /api/v1/platform/developers/dashboard:
    get:
      tags:
      - Developers
      summary: Get developer dashboard data
      description: Return user profile, org info, per-key usage stats, key list, and key type catalog.
      operationId: get_dashboard_api_v1_platform_developers_dashboard_get
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/platform/developers/setup:
    post:
      tags:
      - Developers
      summary: Initial developer setup (org + tier selection)
      description: 'First-time developer setup. Creates organization and handles tier selection.


        Free tier: Creates org + generates API key immediately.

        Paid tier: Creates org + Stripe customer + checkout session → redirect to Stripe → webhook generates key after payment.'
      operationId: developer_setup_api_v1_platform_developers_setup_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetupRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/platform/developers/keys:
    post:
      tags:
      - Developers
      summary: Generate a new API key
      description: 'Create a new API key with specified tier (free or paid).


        Free keys: Created immediately, 250 calls lifetime.

        Paid keys: If no active Stripe subscription, redirects to Checkout.

        If subscription exists, key is created immediately (billing

        is org-scoped, not per-key -- no subscription quantity to update).'
      operationId: create_key_api_v1_platform_developers_keys_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateKeyRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/platform/developers/keys/{key_prefix}/rotate:
    post:
      tags:
      - Developers
      summary: Rotate an existing API key
      description: Rotate a key. Invalidates the old key and returns a new one ONCE.
      operationId: rotate_key_api_v1_platform_developers_keys__key_prefix__rotate_post
      parameters:
      - name: key_prefix
        in: path
        required: true
        schema:
          type: string
          title: Key Prefix
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/platform/developers/keys/{key_prefix}/deactivate:
    post:
      tags:
      - Developers
      summary: Deactivate an API key
      description: 'Deactivate an API key. The key will immediately stop working.

        If it''s the last active paid key on the org, the Stripe subscription

        is canceled (paid-tier billing is org-scoped, not per-key).'
      operationId: deactivate_key_api_v1_platform_developers_keys__key_prefix__deactivate_post
      parameters:
      - name: key_prefix
        in: path
        required: true
        schema:
          type: string
          title: Key Prefix
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/platform/developers/organization:
    put:
      tags:
      - Developers
      summary: Update organization name
      description: Update the organization name for this user's org.
      operationId: update_organization_api_v1_platform_developers_organization_put
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOrgRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/platform/developers/billing/setup-intent:
    post:
      tags:
      - Developers
      summary: Create a SetupIntent to save a card without charging it
      description: 'Create a Stripe SetupIntent so the frontend can collect and verify a card

        via Stripe Elements, without charging anything. Used identically whether

        someone is proactively adding a card ahead of time (still under 250 free

        calls) or reactively adding one after being blocked at the wall -- in

        either case, this just saves a payment method; the actual conversion to

        the paid tier happens transparently on the next API/MCP call via

        auth._check_monthly_limit -> usage_tracking.auto_convert_free_org_or_block,

        once org.default_payment_method_id is set below (via the

        setup_intent.succeeded webhook, not trusted directly from the client).


        Returns: {"client_secret": str, "publishable_key": str} for Stripe.js/Elements

        on the frontend.'
      operationId: developer_setup_intent_api_v1_platform_developers_billing_setup_intent_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/platform/developers/billing/portal:
    post:
      tags:
      - Developers
      summary: Open billing management portal
      description: Create Stripe Customer Portal session for managing subscription and payment methods.
      operationId: developer_portal_api_v1_platform_developers_billing_portal_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/platform/developers/usage-history:
    get:
      tags:
      - Developers
      summary: Get monthly usage history from snapshots
      description: 'Return monthly usage history for all keys in the user''s organization.


        Reads from the monthly_usage_snapshots table, which is populated by

        the proactive monthly reset job or lazily on dashboard load.


        Query parameter:

        months: Number of months of history to return (default 6, max 24)'
      operationId: get_usage_history_api_v1_platform_developers_usage_history_get
      parameters:
      - name: months
        in: query
        required: false
        schema:
          type: integer
          default: 6
          title: Months
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    SetupRequest:
      properties:
        org_name:
          type: string
          maxLength: 200
          minLength: 1
          title: Org Name
        key_name:
          type: string
          maxLength: 100
          minLength: 1
          title: Key Name
        tier:
          type: string
          pattern: ^(free|paid)$
          title: Tier
      type: object
      required:
      - org_name
      - key_name
      - tier
      title: SetupRequest
      description: Request model for initial developer setup.
    CreateKeyRequest:
      properties:
        name:
          type: string
          maxLength: 100
          minLength: 1
          title: Name
        tier:
          type: string
          pattern: ^(free|paid)$
          title: Tier
          default: free
      type: object
      required:
      - name
      title: CreateKeyRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    UpdateOrgRequest:
      properties:
        name:
          type: string
          maxLength: 200
          minLength: 1
          title: Name
      type: object
      required:
      - name
      title: UpdateOrgRequest
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      description: 'Your Koko API key (format: koko_xxxxx)'
      in: header
      name: X-API-Key