CoreStory Subscriptions API

openapi: 3.2.0
info:
  title: Crowdbotics API Documentation Subscriptions 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: Subscriptions
paths:
  /api/subscription/status:
    get:
      tags:
      - Subscriptions
      summary: Get Subscription Status
      description: Retrieve the current subscription status for the authenticated organization.
      operationId: get_subscription_status
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionStatusResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/subscriptions/usage:
    get:
      tags:
      - Subscriptions
      summary: Get Usage Data
      description: 'Retrieve usage data for the current organization.


        Returns token consumption metrics, project count, and user count

        for the specified period (defaults to current month).


        Authenticated via API key.'
      operationId: get_usage_data
      parameters:
      - name: period_start
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Period Start
      - name: period_end
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Period End
      - name: X-API-Key
        in: header
        required: true
        schema:
          type: string
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageDataResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
components:
  schemas:
    ErrorSchema:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      type: object
      required:
      - error
      title: ErrorSchema
    UsageDataResponse:
      properties:
        period_start:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Period Start
          description: Start of the usage period. Null when no date filter was applied.
        period_end:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Period End
          description: End of the usage period. Null when no date filter was applied.
        token_usage:
          type: integer
          title: Token Usage
          description: Total tokens consumed (input + output)
        input_tokens:
          type: integer
          title: Input Tokens
          description: Total input/prompt tokens consumed. Sentinel value -1 when the usage provider does not expose a prompt/completion split.
        output_tokens:
          type: integer
          title: Output Tokens
          description: Total output/completion tokens consumed. Sentinel value -1 when the usage provider does not expose a prompt/completion split.
        total_projects:
          type: integer
          title: Total Projects
          description: Number of projects in the organization
        total_users:
          type: integer
          title: Total Users
          description: Number of active users in the organization
        token_cost:
          anyOf:
          - type: number
          - type: 'null'
          title: Token Cost
          description: Token cost in USD (if available)
      type: object
      required:
      - token_usage
      - input_tokens
      - output_tokens
      - total_projects
      - total_users
      title: UsageDataResponse
      description: Response model for organization usage data.
    SubscriptionStatusResponse:
      properties:
        status:
          type: string
          title: Status
          description: 'Subscription status: ''active'', ''suspended'', ''canceled'', or ''none'''
          examples:
          - active
          - suspended
          - canceled
          - none
        plan_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Plan Id
          description: Plan identifier (e.g., 'enterprise-monthly')
        provider:
          anyOf:
          - $ref: '#/components/schemas/SubscriptionProvider'
          - type: 'null'
          description: Subscription provider
        created_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Created At
          description: Timestamp when subscription was created
        updated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updated At
          description: Timestamp when subscription was last updated
        current_period_start:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Current Period Start
          description: Start of the current billing period
        current_period_end:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Current Period End
          description: End of the current billing period (renewal date)
        price_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Price Id
          description: Stripe Price ID for the active plan
        unit_amount:
          anyOf:
          - type: integer
          - type: 'null'
          title: Unit Amount
          description: Price per unit in the smallest currency unit (e.g. cents for USD)
        quantity:
          anyOf:
          - type: integer
          - type: 'null'
          title: Quantity
          description: Number of units subscribed
        currency:
          anyOf:
          - type: string
          - type: 'null'
          title: Currency
          description: Three-letter ISO currency code (e.g. 'usd')
        interval:
          anyOf:
          - type: string
          - type: 'null'
          title: Interval
          description: Billing interval from the price (e.g. 'month', 'year')
        cancel_at_period_end:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Cancel At Period End
          description: Stripe's cancel_at_period_end flag for the subscription
        cancel_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Cancel At
          description: Timestamp when the subscription is scheduled to cancel, if any
        canceled_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Canceled At
          description: Timestamp when the cancellation was requested, if any
      type: object
      required:
      - status
      title: SubscriptionStatusResponse
      description: Response model for organization subscription status.
    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
    SubscriptionProvider:
      type: string
      enum:
      - ms_marketplace
      - stripe
      title: SubscriptionProvider
      description: Subscription provider enum.
  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