CoreStory ciu API
The ciu API from CoreStory — 4 operation(s) for ciu.
OpenAPI Specification
openapi: 3.1.0
info:
title: Crowdbotics API Documentation admin ciu API
description: "# CoreStory API Overview\n\nThe CoreStory API provides programmatic access to structured insights derived from software source code. It is designed for engineering, architecture, and product teams who need to extract business logic, technical specifications, architectural relationships, and system-level context from complex or legacy codebases.\n\nBy interfacing directly with CoreStory API, users can:\n\n- Generate full Product Requirements Documents (PRDs) from a codebase\n- Extract detailed Technical Specifications for modernization or migration\n- Query a codebase using natural language to surface implementation details, logic paths, dependencies, and architectural insights\n- Construct and visualize knowledge graphs of systems, components, and relationships\n- Ingest, store, and retrieve content from a vector store for AI-powered retrieval-augmented generation (RAG) workflows\n\nCoreStory is especially valuable in contexts where:\n\n- Codebases are large, unstructured, or under-documented\n- Product and engineering teams are onboarding to unfamiliar systems\n- Technical stakeholders require visibility into system design or feature coverage\n- Modernization, replatforming, or M&A due diligence is underway\n\nThe API can be integrated into existing CI/CD pipelines, internal developer portals, architecture review boards, product planning processes, or documentation automation workflows.\n\nAll endpoints support secure authentication and are designed for high-availability, asynchronous workloads. Output formats include JSON, Markdown, and PDF, with flexible formatting options for downstream consumption.\n\nFor step-by-step usage instructions and workflows, refer to the [CoreStory API Quick Start Guide](#section/CoreStory-API-Quick-Start-Guide).\n\n## Features\n\n* **Document Generation**\n * Generate complete Product Requirements Documents (PRD)\n * Generate Technical Specifications\n * Generate individual document sections (executive overview, user personas, etc.)\n * Format documents in JSON or Markdown\n\n* **Vector Store Management**\n * Ingest and manage documents in vector store\n * Query and retrieve document content\n * Manage document embeddings\n\n* **Context Management**\n * Manage context for different document types\n * Set and retrieve PRD context\n * Support for future context types (technical specs, user stories, etc.)\n\n* **Knowledge Graph**\n * Generate knowledge graphs from codebase queries\n * Visualize relationships between code entities\n * Analyze code structure and dependencies\n\n* **API Endpoints**\n * `/api/documents/*` - Document generation and formatting\n * `/api/generate/*` - Document formatting utilities\n * `/api/vector-store/*` - Vector store management\n * `/api/agents/*` - AI agent operations\n * `/api/context/*` - Context management for documents\n * `/api/graph/*` - Knowledge graph generation and analysis\n\nNote: JWT authentication support coming soon. All endpoints currently provide detailed OpenAPI documentation.\n\n* **Observability**\n * OpenTelemetry instrumentation for distributed tracing\n * Prometheus metrics endpoint at `/metrics`\n * Comprehensive request/response tracking\n * Custom business metrics\n\n\n\n# CoreStory System Architecture\n\nThis document provides a high-level overview of how the CoreStory platform ingests, analyzes, and serves structured software intelligence through its API. The system is designed to process codebases and related technical artifacts in order to generate product specifications, technical documents, and knowledge graph representations.\n\n---\n\n## Core Components\n\n### 1. **Ingestion Layer**\n\n- Accepts Git URLs, file uploads, or local archives\n- Extracts source files, documentation, and metadata\n- Initiates chunking and embedding via the vector store pipeline\n\n### 2. **Vector Store and Context Engine**\n\n- Stores chunked and embedded documents\n- Supports semantic search and document retrieval\n- Feeds LLMs with scoped context for generation and reasoning\n\n### 3. **LLM Orchestration Layer**\n\n- Fan-out to multiple large language models\n- Handles prompt templating, context injection, and result normalization\n- Evaluates and scores generated outputs\n\n### 4. **Document Generation Engine**\n\n- Produces:\n - PRDs\n - Technical Specs\n - Individual document sections\n - Markdown and PDF exports\n- Format-flexible output for portals, APIs, and documentation pipelines\n\n### 5. **Graph Construction Module**\n\n- Extracts static and dynamic code relationships\n- Builds DAGs and call graphs of components, services, and files\n- Allows natural-language queries that return graph subviews and LLM explanations\n\n### 6. **Query Engine**\n\n- Accepts free-form questions about codebases\n- Routes queries to code graph, document store, or LLMs\n- Returns structured JSON answers and explanatory text\n\n### 7. **API Gateway**\n\n- Authenticates and rate-limits clients\n- Routes requests to internal services\n- Serves all external-facing endpoints in REST format\n\n---\n\n## Security and Privacy\n\n- All data transfer is encrypted via HTTPS\n- API access is secured using provided auth credentials (JWT tokens coming soon)\n- Uploaded code is only used to generate customer-requested outputs and is not retained indefinitely\n\n---\n\n## Extensibility\n\nThe platform is modular. It can be extended to:\n\n- Add new LLMs for ensemble generation\n- Integrate alternative vector databases\n- Connect to internal developer portals or product management tools via webhook or export endpoints\n\nFor more information, see the Quick Start or contact the CoreStory team.\n\n\n# CoreStory API Quick Start Guide\n\nThe CoreStory API provides programmatic access to structured code intelligence, enabling your team to extract business and technical specifications directly from source code. You can use the API to integrate CoreStory-generated documents into existing workflows, support software modernization and maintenance efforts, or enrich internal platforms with architectural and feature-level metadata.\n\n---\n\n## Overview\n\nThe CoreStory API enables:\n\n- Ingestion of content into a **vector store** for LLM-driven analysis\n- Generation of **Product Requirements Documents (PRDs)** and **Technical Specifications** from code\n- Interrogation of your codebase via a natural language **query engine**\n- Construction of **knowledge graphs** describing code relationships and system architecture\n- Management of **custom document context** and **custom prompts** for improved output relevance and quality\n\nThese capabilities support SDLC workflows such as:\n\n- Application modernization, migration, and maintenance\n- Documentation and auditability of legacy systems\n- Alignment of product, engineering, and architecture teams and systems\n- Developer onboarding and code comprehension\n\n---\n\n**Note for POV customers:** If your codebase has already been ingested as part of a proof-of-value (POV) engagement, you can use your existing authentication credentials and skip step 2 (”Ingest a Codebase or Document Source) of this guide.\n\n## 1. Authentication\n\n```\nPOST /api/auth/login\n```\n\nObtain a JWT for future API calls.\n\n**Request:**\n\n```\n{\n \"email\": \"you@example.com\",\n \"password\": \"your-password\"\n}\n```\n\n**Response:**\n\n```\n{\n \"access_token\": \"...\",\n \"token_type\": \"bearer\"\n}\n```\n\nInclude this token in all subsequent requests:\n\n```\nAuthorization: Bearer <access_token>\n```\n\n---\n\n## 2. Ingest a Codebase or Document Source\n\n```\nPOST /api/vector-store/ingest\n```\n\nTrigger ingestion of code from a Git repo, ZIP file, or local document directory.\n\n**Example Payload (GitHub):**\n\n```\n{\n \"source_type\": \"url\",\n \"source\": \"https://github.com/example/repo.git\",\n \"force\": true\n}\n```\n\nIngestion automatically chunks, embeds, and summarizes source files for downstream analysis.\n\n<details>\n<summary>Supported File Extensions</summary>\n\n### Programming Languages\n- Python: `.py`, `.pyw`, `.pyx`, `.pyi`\n- JavaScript/TypeScript: `.js`, `.mjs`, `.cjs`, `.ts`, `.jsx`, `.tsx`\n- Java: `.java`, `.class`, `.jar`\n- C/C++: `.c`, `.cpp`, `.cc`, `.cxx`, `.c++`, `.h`, `.hpp`, `.hh`, `.hxx`, `.h++`\n- .NET: `.cs`, `.csx`, `.vb`, `.fs`, `.fsx`, `.fsi`\n- PHP: `.php`, `.php3`, `.php4`, `.php5`, `.phtml`\n- Ruby: `.rb`, `.rbw`, `.rake`, `.gemspec`\n- Go: `.go`, `.mod`, `.sum`\n- Rust: `.rs`, `.rlib`\n- Swift: `.swift`\n- Kotlin: `.kt`, `.kts`, `.ktm`\n- Scala: `.scala`, `.sc`\n- Clojure: `.clj`, `.cljs`, `.cljc`, `.edn`\n- Haskell: `.hs`, `.lhs`\n- OCaml: `.ml`, `.mli`, `.mll`, `.mly`\n- R: `.r`, `.R`, `.rmd`, `.rnw`\n- Objective-C: `.m`, `.mm`\n- Perl: `.pl`, `.pm`, `.t`, `.pod`\n- Shell scripts: `.sh`, `.bash`, `.zsh`, `.fish`, `.ksh`, `.csh`, `.tcsh`\n- PowerShell: `.ps1`, `.psm1`, `.psd1`\n- Windows batch: `.bat`, `.cmd`\n- Lua: `.lua`\n- Dart: `.dart`\n- Elm: `.elm`\n- Elixir: `.ex`, `.exs`\n- Erlang: `.erl`, `.hrl`\n- Julia: `.jl`\n- Nim: `.nim`, `.nims`\n- Crystal: `.cr`\n- D: `.d`\n- Pascal: `.pas`, `.pp`, `.inc`\n- Fortran: `.f`, `.f90`, `.f95`, `.f03`, `.f08`, `.for`, `.ftn`, `.fpp`\n- COBOL: `.cob`, `.cbl`, `.cpy`, `.cobol`, `.bms`, `.ctl`, `.jcl`, `.proc`\n- IBM i (AS/400) RPG ILE: `.rpgle`, `.rpgleinc`\n- IBM i (AS/400) CLLE: `.clle`\n- IBM i (AS/400) DDS: `.pf`, `.lf`, `.dspf`\n- PowerBuilder: `.pbt`, `.pbs`, `.pbr`, `.srw`, `.srd`, `.sru`, `.sra`, `.srp`, `.srf`, `.srq`, `.srs`, `.srm`, `.srj`\n- Ada: `.ada`, `.adb`, `.ads`\n- Assembly: `.asm`, `.s`, `.S`\n- Verilog/SystemVerilog: `.v`, `.vh`, `.sv`, `.svh`\n- VHDL: `.vhd`, `.vhdl`\n- Tcl/Tk: `.tcl`, `.tk`\n- Groovy: `.groovy`, `.gvy`, `.gy`, `.gsh`\n- CoffeeScript: `.coffee`, `.litcoffee`\n- PureScript: `.purs`\n- ReasonML: `.reason`, `.re`, `.rei`\n- Racket/Scheme: `.rkt`, `.scm`, `.ss`\n- Lisp: `.lisp`, `.lsp`, `.l`, `.cl`, `.fasl`\n- Prolog: `.prolog`, `.pro`, `.P`\n- MATLAB: `.matlab`, `.fig`\n- Mathematica: `.mathematica`, `.nb`, `.wl`, `.wls`\n- SageMath: `.sage`, `.spyx`\n- Zig: `.zig`\n- Odin: `.odin`\n- V: `.v3`, `.v2`, `.v1`\n- Pony: `.pony`\n- Red: `.red`, `.reds`\n- Io: `.io`\n- Factor: `.factor`\n- Forth: `.forth`, `.fth`, `.4th`\n- J/K/Q/APL: `.j`, `.k`, `.q`, `.apl`\n- Chapel: `.chapel`, `.chpl`\n- X10: `.x10`\n- Arduino/Processing: `.pde`, `.ino`\n\n### Web Technologies\n- HTML: `.html`, `.htm`, `.xhtml`, `.shtml`\n- CSS/Preprocessors: `.css`, `.scss`, `.sass`, `.less`, `.styl`, `.stylus`\n- Frontend frameworks: `.vue`, `.svelte`\n- JSP: `.jsp`, `.jspx`, `.tag`, `.tagx`\n- ASP.NET: `.asp`, `.aspx`, `.ascx`, `.asax`, `.ashx`, `.asmx`\n- Ruby templates: `.erb`, `.haml`, `.slim`\n- PHP templates: `.twig`, `.blade`\n- Template engines: `.mustache`, `.hbs`, `.handlebars`, `.ejs`, `.pug`, `.jade`, `.liquid`, `.ftl`, `.ftlh`, `.vm`, `.vtl`, `.thymeleaf`\n\n### Configuration/Data\n- JSON: `.json`, `.json5`, `.jsonc`, `.jsonl`, `.ndjson`\n- XML: `.xml`, `.xsd`, `.xsl`, `.xslt`, `.dtd`, `.rng`, `.rnc`\n- YAML/TOML: `.yaml`, `.yml`, `.toml`\n- INI/Cfg/Conf: `.ini`, `.cfg`, `.conf`, `.config`, `.properties`\n- Environment: `.env`, `.envrc`, `.env.local`, `.env.development`, `.env.production`\n- Property lists: `.plist`\n- HOCON: `.hocon`\n- RON/HJSON/CSON: `.ron`, `.hjson`, `.cson`\n\n### Documentation/Text\n- Markdown: `.md`, `.markdown`, `.mdown`, `.mkd`, `.mkdn`\n- Plain text: `.txt`, `.text`\n- reStructuredText: `.rst`, `.rest`\n- AsciiDoc: `.asciidoc`, `.adoc`, `.asc`\n- LaTeX: `.tex`, `.latex`, `.ltx`, `.sty`, `.cls`, `.bib`\n- Org mode: `.org`\n- Wiki markup: `.wiki`, `.mediawiki`\n- Textile/Creole/RDoc: `.textile`, `.creole`, `.rdoc`\n\n### Data Formats\n- Delimited: `.csv`, `.tsv`, `.psv`\n- SQL: `.sql`, `.ddl`, `.dml`, `.plsql`, `.psql`, `.mysql`\n- GraphQL: `.graphql`, `.gql`\n- Protocols: `.proto`, `.protobuf`, `.avro`, `.avsc`, `.avdl`, `.thrift`, `.capnp`, `.fbs`\n- Columnar: `.parquet`, `.orc`, `.arrow`\n\n### Build/Dependency\n- Gradle: `.gradle`, `.gradle.kts`\n- Maven: `.maven`, `.mvn`\n- SBT: `.sbt`\n- CMake: `.cmake`, `.cmake.in`\n- Make: `.make`, `.mk`, `.mak`\n- Docker: `.dockerfile`, `.containerfile`, `.dockerignore`\n- Git: `.gitignore`, `.gitattributes`, `.gitmodules`, `.gitkeep`\n- Mercurial/Subversion/Bazaar: `.hgignore`, `.hgrc`, `.svnignore`, `.bzrignore`\n- EditorConfig: `.editorconfig`\n- Linters/Formatters: `.eslintrc`, `.eslintignore`, `.prettierrc`, `.prettierignore`, `.babelrc`, `.babelignore`\n- Node.js: `.npmrc`, `.npmignore`, `.yarnrc`, `.yarnignore`\n- Python: `.pipfile`, `.pipfile.lock`, `.requirements`, `.requirements.txt`, `.poetry.lock`, `.pyproject.toml`, `.setup.py`, `.setup.cfg`, `.manifest.in`, `.tox.ini`, `.noxfile.py`, `.pre-commit-config.yaml`\n- CI/CD: `.github`, `.gitlab-ci.yml`, `.travis.yml`, `.appveyor.yml`, `.circleci`, `.jenkins`, `.jenkinsfile`, `.azure-pipelines.yml`, `.buildkite.yml`\n- Package Managers: `package.json`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `composer.json`, `composer.lock`, `gemfile`, `gemfile.lock`, `cargo.toml`, `cargo.lock`, `go.mod`, `go.sum`, `requirements.txt`, `pipfile`, `pipfile.lock`, `poetry.lock`, `pyproject.toml`, `build.gradle`, `build.gradle.kts`, `settings.gradle`, `gradle.properties`, `pom.xml`, `settings.xml`, `build.sbt`, `plugins.sbt`, `makefile`, `gnumakefile`, `makefile.am`, `makefile.in`, `dockerfile`, `containerfile`, `vagrantfile`, `rakefile`, `guardfile`, `capfile`, `gulpfile.js`, `gruntfile.js`, `webpack.config.js`, `rollup.config.js`, `tsconfig.json`, `jsconfig.json`, `deno.json`, `deno.jsonc`, `mix.exs`, `mix.lock`, `rebar.config`, `rebar.lock`, `project.clj`, `deps.edn`, `stack.yaml`, `cabal.config`, `setup.hs`, `dub.json`, `dub.sdl`, `nimble`, `config.nims`, `shard.yml`, `shard.lock`, `pubspec.yaml`, `pubspec.lock`, `elm.json`, `elm-package.json`, `project.json`, `global.json`, `nuget.config`, `packages.config`, `paket.dependencies`, `paket.lock`, `.log`, `.lock`, `.pid`, `.tmp`, `.temp`, `.patch`, `.diff`, `.spec`, `.rpm`, `.deb`, `.control`, `.pkgbuild`, `.ebuild`, `.formula`, `.port`, `.portfile`, `.nix`, `.bzl`, `.bazel`, `.workspace`, `.buck`, `.buckconfig`, `.pants`, `.pants.ini`, `.please`, `.plzconfig`, `.gn`, `.gni`, `.ninja`, `.waf`, `.wscript`, `.scons`, `.sconstruct`, `.sconscript`\n\n</details>\n\n<details>\n<summary>Configuration Files</summary>\n\n- `requirements.txt`\n- `.gitignore`\n- `.dockerignore`\n- `.editorconfig`\n- `.eslintrc.js`\n- `.eslintrc.json`\n- `.prettierrc.js`\n- `.prettierrc.json`\n- `.babelrc.js`\n- `.babelrc.json`\n\n</details>\n\n---\n\n## 3. Generate a Product Requirements Document (PRD)\n\n**Note**: Generating a PRD or technical specification will replace the existing PRD or technical specification. The new outputs will document your codebase as it was when it was most recently ingested.\n\n```\nPOST /api/documents/prd?format=json\n```\n\nGenerates a structured PRD with:\n\n- Executive Overview\n- User Personas\n- High-Level Requirements\n- User Stories\n- Business Value\n\n**Example Response (truncated):**\n\n```\n{\n \"content\": {\n \"executive_overview\": \"Modernize internal authentication platform\",\n \"user_personas\": [...],\n \"user_stories\": [...]\n }\n}\n```\n\n**Tip:** For PRDs or technical specs, use `format=markdown` to return a Markdown-formatted document instead.\n\n---\n\n## 4. Generate a Technical Specification\n\n```\nPOST /api/documents/technical-spec?format=json\n```\n\nReturns system-level implementation details including:\n\n- Architecture and Components\n- Data Models and Relationships\n- User Interface Screens and Components\n- APIs and Integration Points\n- System Interfaces and Specifications\n- Security Considerations\n- Implementation and Deployment Strategy\n\n---\n\n## 5. Query Your Code\n\n```\nPOST /api/graph/query-engine\n```\n\nAsk natural language questions about your codebase to return a structured graph of relationships.\n\n**Example Query:**\n\n```\n{\n \"query\": \"How does the system determine whether a user has admin privileges when accessing the audit log?\"\n}\n```\n\n**Response (truncated):**\n\n```\n{\n \"summary\": \"When a user requests access to the audit log, the system checks their assigned roles in `AuthService.getUserRoles`. If 'admin' is present, access is granted. This check occurs in `AuditLogController` before querying the log database. The middleware `CheckPermissions` is also invoked on this route.\"\n}\n```\n\n---\n\n## 6. Format and Retrieve Document Sections\n\nUse these endpoints to extract or reformat specific document sections:\n\n- `/api/documents/sections/{doc_type}` → generate a specific section\n- `/api/documents/format/markdown-output/{doc_type}` → format JSON as Markdown\n- `/api/documents/format/pdf-output/{doc_type}` → export PDF\n\nExample section names:\n\n- `executive-overview`\n- `data-models`\n- `system-architecture`\n- `integration-points`\n\n---\n\n## Questions?\n\nAfter reviewing this guide and the API docs, we recommend scheduling a short Q&A call if you have integration-specific needs or want assistance mapping this to your environment.\n"
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:
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.
ErrorSchema:
properties:
error:
$ref: '#/components/schemas/ErrorBody'
type: object
required:
- error
title: ErrorSchema
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.
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
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.
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.
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.
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.
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.
RenewalPeriod:
type: string
enum:
- monthly
- yearly
title: RenewalPeriod
description: Renewal period options for CIU plans and balances.
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
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/corestory/refs/heads/main/openapi/corestory-ciu-api-openapi.yml