CoreStory Sync Status API

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


    The 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. By interfacing directly with CoreStory API, users can:


    - Generate full Product Requirements Documents (PRDs) from a codebase

    - Extract detailed Technical Specifications for modernization or migration

    - Query a codebase using natural language to surface implementation details, logic paths, dependencies, and architectural insights

    - Construct and visualize knowledge graphs of systems, components, and relationships

    - Ingest, store, and retrieve content from a vector store for AI-powered retrieval-augmented generation (RAG) workflows


    CoreStory is especially valuable in contexts where:


    - Codebases are large, unstructured, or under-documented

    - Product and engineering teams are onboarding to unfamiliar systems

    - Technical stakeholders require visibility into system design or feature coverage

    - Modernization, replatforming, or M&A due diligence is underway


    The API can be integrated into existing CI/CD pipelines, internal developer portals, architecture review boards, product planning processes, or documentation automation workflows. All 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. For step-by-step usage instructions and workflows, refer to the CoreStory API Quick Start Guide. ## Features


    * **Document Generation**

    * Generate complete Product Requirements Documents (PRD)

    * Generate Technical Specifications

    * Generate individual document sections (executive overview, user personas, etc.)

    * Format documents in JSON or Markdown


    * **Vector Store Management**

    * Ingest and manage documents in vector store

    * Query and retrieve document content

    * Manage document embeddings


    * **Context Management**

    * Manage context for different document types

    * Set and retrieve PRD context

    * Support for future context types (technical specs, user stories, etc.)


    * **Knowledge Graph**

    * Generate knowledge graphs from codebase queries

    * Visualize relationships between code entities

    * Analyze code structure and dependencies


    * **API Endpoints**

    * `/api/documents/*` - Document generation and formatting

    * `/api/generate/*` - Document formatting utilities

    * `/api/vector-store/*` - Vector store management

    * `/api/agents/*` - AI agent operations

    * `/api/context/*` - Context management for documents

    * `/api/graph/*` - Knowledge graph generation and analysis


    Note: JWT authentication support coming soon. All endpoints currently provide detailed OpenAPI documentation. * **Observability**

    * OpenTelemetry instrumentation for distributed tracing

    * Prometheus metrics endpoint at `/metrics`

    * Comprehensive request/response tracking

    * Custom business metrics


    # CoreStory System Architecture


    This 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. ---


    ## Core Components


    ### 1. **Ingestion Layer**


    - Accepts Git URLs, file uploads, or local archives

    - Extracts source files, documentation, and metadata

    - Initiates chunking and embedding via the vector store pipeline


    ### 2. **Vector Store and Context Engine**


    - Stores chunked and embedded documents

    - Supports semantic search and document retrieval

    - Feeds LLMs with scoped context for generation and reasoning


    ### 3.'
  version: 1.33.0
servers:
- url: /
  description: Current server
security:
- BearerAuth: []
tags:
- name: Sync Status
paths:
  /api/organizations/projects/sync-status:
    get:
      tags:
      - Sync Status
      summary: List org projects with sync status
      description: Return a paginated list of projects in the org with their sync mode and status.
      operationId: list_project_sync_status
      parameters:
      - name: sync_mode
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/SyncMode'
          - type: 'null'
          description: Filter by sync mode
          title: Sync Mode
        description: Filter by sync mode
      - name: sort_by
        in: query
        required: false
        schema:
          enum:
          - name
          - last_ingested_at
          type: string
          description: Sort field
          default: name
          title: Sort By
        description: Sort field
      - name: sort_order
        in: query
        required: false
        schema:
          enum:
          - asc
          - desc
          type: string
          description: Sort direction
          default: asc
          title: Sort Order
        description: Sort direction
      - 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
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncStatusResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '404':
          description: Not found
components:
  schemas:
    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.
        code:
          anyOf:
          - type: string
          - type: 'null'
          title: Code
          description: Stable machine-readable code for clients that branch on the specific failure.
        required_organization:
          anyOf:
          - $ref: '#/components/schemas/RequiredOrganization'
          - type: 'null'
          description: Set when the caller can retry after switching organization context.
      type: object
      required:
      - message
      - type
      title: ErrorBody
    SyncStatusSummary:
      properties:
        total_count:
          type: integer
          title: Total Count
          description: Total projects across the organization ignoring filter
        auto_count:
          type: integer
          title: Auto Count
          description: Projects with sync_mode=auto across the org
        blocked_count:
          type: integer
          title: Blocked Count
          description: Projects with status=couldnt_process across the org
        is_ciu_exhausted:
          type: boolean
          title: Is Ciu Exhausted
          description: Whether the org has run out of CIUs
      type: object
      required:
      - total_count
      - auto_count
      - blocked_count
      - is_ciu_exhausted
      title: SyncStatusSummary
      description: Org-wide aggregates rendered as page-level chrome. Not affected by filters.
    SyncMode:
      type: string
      enum:
      - manual
      - auto
      title: SyncMode
      description: Whether a project syncs manually or automatically with its repo.
    PaginationMeta:
      properties:
        total:
          type: integer
          title: Total
        page:
          type: integer
          title: Page
        size:
          type: integer
          title: Size
        pages:
          type: integer
          title: Pages
      type: object
      required:
      - total
      - page
      - size
      - pages
      title: PaginationMeta
    RequiredOrganization:
      properties:
        id:
          type: string
          title: Id
          description: Clerk organization id the client should switch to.
        name:
          type: string
          title: Name
          description: Display name of that organization.
      type: object
      required:
      - id
      - name
      title: RequiredOrganization
      description: The organization a caller must be acting under before a denied request can succeed.
    SyncStatusItem:
      properties:
        project_id:
          type: integer
          title: Project Id
          description: Project ID
        name:
          type: string
          title: Name
          description: Project name
        sync_mode:
          $ref: '#/components/schemas/SyncMode'
          description: Manual or Auto
        status:
          $ref: '#/components/schemas/ProjectSyncStatus'
          description: Current sync/processing status
        last_ingested_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Ingested At
          description: Last successful ingestion timestamp
      type: object
      required:
      - project_id
      - name
      - sync_mode
      - status
      title: SyncStatusItem
      description: A single project row in the org project sync-status list.
    ProjectSyncStatus:
      type: string
      enum:
      - up_to_date
      - updating
      - stale
      - failed
      - couldnt_process
      title: ProjectSyncStatus
      description: 'Derived sync/processing status for a project, shared across the org roster,

        pinned-workspaces, and project detail/list surfaces.'
    ErrorSchema:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      type: object
      required:
      - error
      title: ErrorSchema
    SyncStatusResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/SyncStatusItem'
          type: array
          title: Items
          description: List of items
        pagination:
          $ref: '#/components/schemas/PaginationMeta'
          description: Pagination metadata
        summary:
          $ref: '#/components/schemas/SyncStatusSummary'
          description: Org-wide aggregates (unaffected by filters)
      type: object
      required:
      - items
      - pagination
      - summary
      title: SyncStatusResponse
      description: Paginated project sync-status list with org-wide summary aggregates.
  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
  - git_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
x-provenance:
  method: harvested
  publisher: CoreStory
  source: https://c2s.corestory.ai/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)