CoreStory Sio Actions API

openapi: 3.2.0
info:
  title: Crowdbotics API Documentation Sio Actions 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: sio-actions
paths:
  /api/sio-actions/security/create-issue:
    post:
      tags:
      - sio-actions
      summary: Create a tracker issue from an AI-suggested security action
      operationId: dispatch_security_action_create_issue
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecurityActionDispatchRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionDispatchResult'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/sio-actions/executions:
    get:
      tags:
      - sio-actions
      summary: List dispatched SIO action executions for a project
      description: Returns the persisted executions for the project's SIO actions in the current organization, so the frontend can restore each action card's state on load.
      operationId: list_sio_action_executions
      parameters:
      - name: project_id
        in: query
        required: true
        schema:
          type: integer
          title: Project Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DispatchedActionRead'
                title: Response List Sio Action Executions
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/sio-actions/executions/{execution_id}/resolve:
    post:
      tags:
      - sio-actions
      summary: Resolve a parked (needs_reconciliation) SIO action execution
      description: 'Records the true outcome of a dispatch whose result couldn''t be confirmed: the tracker issue was created (marks it done with the supplied link) or was never created (marks it failed so the action can be dispatched again).'
      operationId: resolve_sio_action_execution
      parameters:
      - name: execution_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Execution Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecutionResolveRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DispatchedActionRead'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
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
    DispatchedActionRead:
      properties:
        id:
          type: string
          title: Id
          description: Execution id; the target for resolving a parked action.
        action_id:
          type: string
          title: Action Id
          description: The SIO action this execution came from.
        status:
          $ref: '#/components/schemas/ActionExecutionStatus'
          description: Execution status; drives which control the card shows.
        external_id:
          anyOf:
          - type: string
          - type: 'null'
          title: External Id
          description: Created issue's id in the tracker, when succeeded.
        external_url:
          anyOf:
          - type: string
          - type: 'null'
          title: External Url
          description: Link to the created issue, when succeeded.
      type: object
      required:
      - id
      - action_id
      - status
      title: DispatchedActionRead
      description: 'Persisted state of one dispatched SIO action, for restoring card state on load.


        Lets the FE re-render each action card after a refresh: a succeeded row shows the

        created issue (``external_id``/``external_url``), a failed row offers a retry, an

        unconfirmed (``needs_reconciliation``) row prompts the user to check the tracker.'
    ActionDispatchResult:
      properties:
        status:
          type: string
          title: Status
          description: '''succeeded'', ''failed'', or ''uncertain''.'
        external_id:
          anyOf:
          - type: string
          - type: 'null'
          title: External Id
          description: Created issue's id in the tool.
        external_url:
          anyOf:
          - type: string
          - type: 'null'
          title: External Url
          description: Link to the created issue.
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Failure/uncertainty reason when not 'succeeded'.
      type: object
      required:
      - status
      title: ActionDispatchResult
      description: "The outcome of a dispatched action.\n\n``status`` is one of:\n\n* ``'succeeded'`` — the issue was created (``external_id``/``external_url`` set).\n* ``'failed'`` — the tracker rejected the create (network, rate limit, tool\n  error); ``error`` explains it and the card may retry.\n* ``'uncertain'`` — the create couldn't be confirmed (lost response); the card\n  should prompt the user to check the tracker rather than blind-retry."
    SecurityActionDispatchRequest:
      properties:
        title:
          type: string
          minLength: 1
          title: Title
          description: Becomes the issue title verbatim.
        description:
          type: string
          title: Description
          description: The action's explanation; becomes the issue body.
        expected_impact:
          type: string
          title: Expected Impact
          description: Appended to the issue body under 'Expected impact'.
        severity:
          $ref: '#/components/schemas/ActionSeverity'
          description: Critical/Warning/Info; maps to issue priority.
        source_sio_url:
          type: string
          title: Source Sio Url
          description: Link back to the SIO the action came from.
        category:
          type: string
          title: Category
          description: Source signal category; 'security' in V1.
          default: security
        project_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Project Id
          description: SIO project id; feeds the idempotency key.
        action_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Action Id
          description: SIO action id; feeds the idempotency key.
      type: object
      required:
      - title
      - description
      - expected_impact
      - severity
      - source_sio_url
      title: SecurityActionDispatchRequest
      description: 'An AI-suggested security action the caller wants landed as a tracker issue.


        The action data is supplied by the caller (the SIO card holds it) — this

        slice does not yet read persisted SIO actions.'
    ExecutionResolveOutcome:
      type: string
      enum:
      - created
      - not_created
      title: ExecutionResolveOutcome
      description: What the user found when they checked the tracker for a parked action.
    ExecutionResolveRequest:
      properties:
        outcome:
          $ref: '#/components/schemas/ExecutionResolveOutcome'
          description: Whether the tracker issue was actually created.
        external_id:
          anyOf:
          - type: string
          - type: 'null'
          title: External Id
          description: The found issue's id (when outcome=created).
        external_url:
          anyOf:
          - type: string
          - type: 'null'
          title: External Url
          description: Link to the found issue (when outcome=created).
      type: object
      required:
      - outcome
      title: ExecutionResolveRequest
      description: 'The user''s verdict on a parked (``needs_reconciliation``) execution.


        When the outcome is ``created`` the caller supplies the issue the dispatch

        actually produced (found by checking the tracker), so the card can link it;

        ``external_url`` is required in that case.'
    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.
    ActionExecutionStatus:
      type: string
      enum:
      - pending
      - in_progress
      - succeeded
      - failed
      - needs_reconciliation
      title: ActionExecutionStatus
      description: 'Lifecycle of a single dispatched action, tracked for idempotency.


        ``in_progress`` is the claim that serializes concurrent/retried dispatches:

        exactly one caller transitions a row out of ``pending``/``failed`` into

        ``in_progress`` and runs the adapter; others see the claim and back off.


        ``needs_reconciliation`` is a *terminal-until-resolved* state: the dispatch

        failed without a confirming response, so the action may or may not have taken

        effect downstream. Unlike ``failed`` it is **not** auto-retried — re-running a

        non-idempotent operation could duplicate the side effect — until it is

        reconciled against the tool.'
    ErrorSchema:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      type: object
      required:
      - error
      title: ErrorSchema
    ActionSeverity:
      type: string
      enum:
      - critical
      - warning
      - info
      title: ActionSeverity
      description: 'Severity of an SIO suggested action; maps to the dispatched issue''s priority.


        Single source for the action-severity vocabulary: the dispatch layer

        (``app/sio_actions``) imports this rather than redefining it.'
  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)