CoreStory Ciu API

openapi: 3.2.0
info:
  title: Crowdbotics API Documentation Ciu API
  description: '# CoreStory API Overview


    The CoreStory API provides programmatic access to structured insights derived from software source code.'
  version: 1.26.2
servers:
- url: /
  description: Current server
security:
- BearerAuth: []
tags:
- name: ciu
paths:
  /api/ciu/plans:
    get:
      tags:
      - ciu
      summary: List active CIU plans
      description: Return all active CIU plan tiers.
      operationId: list_ciu_plans
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/CIUPlanResponse'
                type: array
                title: Response List Ciu Plans
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/ciu/balance:
    get:
      tags:
      - ciu
      summary: Get current organization's CIU balance
      description: Return the CIU balance for the authenticated user's organization.
      operationId: get_ciu_balance
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationCIUBalanceResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
    patch:
      tags:
      - ciu
      summary: Update current organization's CIU balance
      description: Update the CIU balance for the given organization. This is typically used for manual adjustments or testing purposes and allowed to admins.
      operationId: update_ciu_balance
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationCIUBalanceUpdate'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationCIUBalanceResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/ciu/action-costs:
    get:
      tags:
      - ciu
      summary: List CIU costs per metered action
      description: Return the CIU cost for every metered action.
      operationId: list_action_costs
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionCostsResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/ciu/ledger:
    get:
      tags:
      - ciu
      summary: Get the CIU ledger history for the current organization
      description: Return the CIU ledger history for the authenticated user's organization.
      operationId: get_ciu_ledger
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Page number (1-based)
          default: 1
          title: Page
        description: Page number (1-based)
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          description: Items per page
          default: 50
          title: Size
        description: Items per page
      - name: start_date
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Filter entries from this date (inclusive)
          title: Start Date
        description: Filter entries from this date (inclusive)
      - name: end_date
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Filter entries up to this date (inclusive)
          title: End Date
        description: Filter entries up to this date (inclusive)
      - name: action_type
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              $ref: '#/components/schemas/ActionType'
          - type: 'null'
          description: Filter entries by action type. Repeat the parameter to filter by multiple types (e.g. ?action_type=chat&action_type=workflow).
          title: Action Type
        description: Filter entries by action type. Repeat the parameter to filter by multiple types (e.g. ?action_type=chat&action_type=workflow).
      - name: sort_order
        in: query
        required: false
        schema:
          type: string
          pattern: ^(asc|desc)$
          description: Sort order for entries by created_at
          default: desc
          title: Sort Order
        description: Sort order for entries by created_at
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LedgerHistoryResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
components:
  schemas:
    ActionCostsResponse:
      properties:
        actions:
          items:
            $ref: '#/components/schemas/ActionCostResponse'
          type: array
          title: Actions
          description: List of action costs
      type: object
      required:
      - actions
      title: ActionCostsResponse
      description: Response schema listing all metered action costs.
    ErrorSchema:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      type: object
      required:
      - error
      title: ErrorSchema
    ActionType:
      type: string
      enum:
      - chat
      - mcp_query
      - workflow
      - doc_generation
      - ingestion
      - plan_assignment
      - monthly_renewal
      - manual_adjustment
      title: ActionType
      description: Types of actions that can affect CIU balances.
    RenewalPeriod:
      type: string
      enum:
      - monthly
      - yearly
      title: RenewalPeriod
      description: Renewal period options for CIU plans and balances.
    OrganizationCIUBalanceResponse:
      properties:
        id:
          type: string
          title: Id
          description: Balance record ID
        organization_id:
          type: string
          title: Organization Id
          description: Organization ID
        plan_id:
          type: string
          title: Plan Id
          description: Associated CIU plan ID
        total_cius:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Total Cius
          description: Total CIUs allocated for current cycle
        consumed_cius:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Consumed Cius
          description: CIUs consumed in current cycle
        available_cius:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Available Cius
          description: Remaining available CIUs
        renewal_date:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Renewal Date
          description: Next renewal date
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the balance was created
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: When the balance was last updated
        plan:
          $ref: '#/components/schemas/CIUPlanResponse'
          description: Associated CIU plan details
      type: object
      required:
      - id
      - organization_id
      - plan_id
      - total_cius
      - consumed_cius
      - available_cius
      - created_at
      - updated_at
      - plan
      title: OrganizationCIUBalanceResponse
      description: Response schema for an organization's CIU balance.
    ActionCostResponse:
      properties:
        action:
          type: string
          title: Action
          description: Action identifier
        cost:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Cost
          description: CIU cost for this action
      type: object
      required:
      - action
      - cost
      title: ActionCostResponse
      description: Cost of a single metered action.
    LedgerEntryResponse:
      properties:
        id:
          type: string
          title: Id
          description: Ledger entry ID
        action_type:
          type: string
          title: Action Type
          description: Metered action that incurred CIU cost
        entry_type:
          type: string
          title: Entry Type
          description: Whether this entry is a credit or debit
        ciu_change:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Ciu Change
          description: CIU change on this action
        status:
          type: string
          title: Status
          description: Status of the ledger entry (e.g., 'pending', 'completed', 'failed')
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the ledger entry was created
        balance_snapshot:
          anyOf:
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          - type: 'null'
          title: Balance Snapshot
          description: Organization's CIU balance after this entry was applied
      type: object
      required:
      - id
      - action_type
      - entry_type
      - ciu_change
      - status
      - created_at
      - balance_snapshot
      title: LedgerEntryResponse
      description: Response schema for a single CIU ledger entry.
    CIUPlanResponse:
      properties:
        id:
          type: string
          title: Id
          description: Plan ID
        slug:
          type: string
          title: Slug
          description: Stable plan identifier (e.g. 'free', 'enterprise_10m')
        family:
          type: string
          title: Family
          description: 'Customer-facing tier: free / pro / business / enterprise'
        display_name:
          type: string
          title: Display Name
          description: Human-readable plan name
        loc_cap:
          type: integer
          title: Loc Cap
          description: Lines-of-code allowance for this plan
        default_ciu_allowance:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Default Ciu Allowance
          description: Default CIU allowance for this plan
        project_limit:
          type: integer
          title: Project Limit
          description: Max projects; 0 = unlimited
        mcp_token_limit:
          type: integer
          title: Mcp Token Limit
          description: Max MCP tokens; 0 = unlimited
        features:
          items:
            type: string
          type: array
          title: Features
          description: Entitlements included in this plan
        renewal_period:
          anyOf:
          - $ref: '#/components/schemas/RenewalPeriod'
          - type: 'null'
          description: Renewal period for this plan (null for one-time/free plans)
        is_active:
          type: boolean
          title: Is Active
          description: Whether this plan is currently active
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the plan was created
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: When the plan was last updated
      type: object
      required:
      - id
      - slug
      - family
      - display_name
      - loc_cap
      - default_ciu_allowance
      - project_limit
      - mcp_token_limit
      - features
      - is_active
      - created_at
      - updated_at
      title: CIUPlanResponse
      description: Response schema for a CIU plan.
    OrganizationCIUBalanceUpdate:
      properties:
        organization_id:
          type: string
          minLength: 1
          title: Organization Id
          description: Clerk organization ID
        total_cius:
          anyOf:
          - type: number
            minimum: 0.0
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          - type: 'null'
          title: Total Cius
          description: Total CIUs allocated
        consumed_cius:
          anyOf:
          - type: number
            minimum: 0.0
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          - type: 'null'
          title: Consumed Cius
          description: CIUs consumed
      type: object
      required:
      - organization_id
      title: OrganizationCIUBalanceUpdate
      description: Request schema for updating an organization CIU balance.
    ErrorBody:
      properties:
        message:
          type: string
          title: Message
        type:
          type: string
          title: Type
        details:
          additionalProperties: true
          type: object
          title: Details
          description: Optional extra context for the error.
      type: object
      required:
      - message
      - type
      title: ErrorBody
    LedgerHistoryResponse:
      properties:
        entries:
          items:
            $ref: '#/components/schemas/LedgerEntryResponse'
          type: array
          title: Entries
          description: List of ledger entries for the organization
        pagination:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Pagination
          description: Pagination details, if applicable
      type: object
      required:
      - entries
      - pagination
      title: LedgerHistoryResponse
      description: Response schema for an organization's CIU ledger history.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Enter the Bearer token from Clerk authentication
x-tagGroups:
- name: Ingest Your Codebase
  tags:
  - vector_store
  - projects
  - pre_ingestion
  - reingestion
- name: Generate Code Intelligence
  tags:
  - documents
  - document_generation
  - document_formatters
  - prd
  - prd_version
  - tech_spec
  - quality_metrics
  - sample_projects
- name: Query Your Codebase
  tags:
  - conversations
  - workflows
  - discovery
  - context
  - artifacts
- name: Manage and Inspect Intelligence
  tags:
  - api_debugging
  - events
  - version
  - files
  - cache
  - token_tracking
- name: Authenticate and Manage Access
  tags:
  - clerk_authentication
  - github_webhooks
  - github_integration
  - organizations
  - api_key_management
  - mcp_token_management
  - user
- name: (Advanced) Prompt Tuning
  tags:
  - prompts
- name: MCP Protocol
  tags:
  - mcp_protocol
- name: Administration
  tags:
  - admin