CoreStory Artifacts API

The artifacts API from CoreStory — 2 operation(s) for artifacts.

GitHub OpenAPI

Operations 5

GET /api/projects/{project_id}/artifacts List artifacts for a project #
POST /api/projects/{project_id}/artifacts Create an artifact from a source entity #
GET /api/projects/{project_id}/artifacts/{artifact_id} Get a single artifact by ID #
DELETE /api/projects/{project_id}/artifacts/{artifact_id} Delete an artifact by ID #
PATCH /api/projects/{project_id}/artifacts/{artifact_id} Update an artifact by ID #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/corestory:corestory-artifacts-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

corestory-artifacts-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Crowdbotics API Documentation Artifacts 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: Artifacts
paths:
  /api/projects/{project_id}/artifacts:
    get:
      tags:
      - Artifacts
      summary: List artifacts for a project
      description: Retrieve a list of artifacts associated with a specific project with pagination
      operationId: list_artifacts
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - 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: page_size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Number of items per page
          default: 10
          title: Page Size
        description: Number of items per page
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListArtifactsResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
    post:
      tags:
      - Artifacts
      summary: Create an artifact from a source entity
      description: Generate and export an artifact (e.g., PDF) from a source entity like a conversation. The export runs asynchronously in the background.
      operationId: create_artifact
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateArtifactRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateArtifactResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/projects/{project_id}/artifacts/{artifact_id}:
    get:
      tags:
      - Artifacts
      summary: Get a single artifact by ID
      description: Retrieve a specific artifact with its full content
      operationId: get_artifact
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: artifact_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Artifact Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetArtifactResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
    delete:
      tags:
      - Artifacts
      summary: Delete an artifact by ID
      description: Delete a specific artifact associated with a project
      operationId: delete_artifact
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: artifact_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Artifact Id
      responses:
        '204':
          description: Successful Response
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
    patch:
      tags:
      - Artifacts
      summary: Update an artifact by ID
      description: Update specific fields of an artifact associated with a project
      operationId: update_artifact
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: artifact_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Artifact Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArtifactUpdateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactItem'
        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
    ArtifactItem:
      properties:
        id:
          type: string
          title: Id
          description: UUID of the artifact
        title:
          type: string
          title: Title
          description: Title of the artifact
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Description of the artifact
        source_type:
          type: string
          title: Source Type
          description: Type of source entity (e.g., 'conversation')
        source_id:
          type: string
          title: Source Id
          description: ID of the source entity
        status:
          $ref: '#/components/schemas/Status'
          description: Current status of the artifact
        mode:
          anyOf:
          - $ref: '#/components/schemas/Mode'
          - type: 'null'
          description: Export mode for conversation artifacts
        created_by:
          type: string
          title: Created By
          description: UUID of the user who created the artifact
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Timestamp when the artifact was created
      type: object
      required:
      - id
      - title
      - description
      - source_type
      - source_id
      - status
      - mode
      - created_by
      - created_at
      title: ArtifactItem
      description: Individual artifact item in the list response.
      examples:
      - created_at: '2025-10-21T14:30:00Z'
        created_by: user-uuid-123
        description: Artifact exported from conversation 123
        id: 123e4567-e89b-12d3-a456-426614174000
        mode: transcript
        source_id: '123'
        source_type: conversation
        status: completed
        title: My Conversation Export
    ListArtifactsResponse:
      properties:
        artifacts:
          items:
            $ref: '#/components/schemas/ArtifactItem'
          type: array
          title: Artifacts
          description: List of artifacts in the project
        total:
          type: integer
          title: Total
          description: Total number of artifacts
        page:
          type: integer
          title: Page
          description: Current page number
        page_size:
          type: integer
          title: Page Size
          description: Number of items per page
        total_pages:
          type: integer
          title: Total Pages
          description: Total number of pages
      type: object
      required:
      - artifacts
      - total
      - page
      - page_size
      - total_pages
      title: ListArtifactsResponse
      description: Response model for listing artifacts with pagination.
      examples:
      - artifacts:
        - created_at: '2025-10-21T14:30:00Z'
          created_by: user-uuid-123
          description: Artifact exported from conversation 123
          id: 123e4567-e89b-12d3-a456-426614174000
          mode: transcript
          source_id: '123'
          source_type: conversation
          status: completed
          title: My Conversation Export
        page: 1
        page_size: 10
        total: 25
        total_pages: 3
    CreateArtifactRequest:
      properties:
        source_type:
          type: string
          const: conversation
          title: Source Type
          description: Type of source entity (e.g., 'conversation')
        source_id:
          type: integer
          exclusiveMinimum: 0.0
          title: Source Id
          description: ID of the source entity
        mode:
          anyOf:
          - $ref: '#/components/schemas/Mode'
          - type: 'null'
          description: 'Export mode for conversation artifacts: ''transcript'' for raw messages, ''synthesized'' for AI-processed content'
          default: transcript
      type: object
      required:
      - source_type
      - source_id
      title: CreateArtifactRequest
      description: 'Request model for creating an artifact.


        This model defines the input required to generate an artifact from a source entity.

        Currently supports conversations, with extensibility for future source types.'
      examples:
      - mode: transcript
        source_id: 123
        source_type: conversation
      - mode: synthesized
        source_id: 456
        source_type: conversation
    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.
    Status:
      type: string
      enum:
      - not_started
      - pending
      - completed
      - failed
      title: Status
    ErrorSchema:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      type: object
      required:
      - error
      title: ErrorSchema
    GetArtifactResponse:
      properties:
        id:
          type: string
          title: Id
          description: UUID of the artifact
        title:
          type: string
          title: Title
          description: Title of the artifact
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Description of the artifact
        source_type:
          type: string
          title: Source Type
          description: Type of source entity (e.g., 'conversation')
        source_id:
          type: string
          title: Source Id
          description: ID of the source entity
        status:
          $ref: '#/components/schemas/Status'
          description: Current status of the artifact
        mode:
          anyOf:
          - $ref: '#/components/schemas/Mode'
          - type: 'null'
          description: Export mode for conversation artifacts
        created_by:
          type: string
          title: Created By
          description: UUID of the user who created the artifact
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Timestamp when the artifact was created
        markdown_store:
          anyOf:
          - type: string
          - type: 'null'
          title: Markdown Store
          description: Markdown content of the artifact
      type: object
      required:
      - id
      - title
      - description
      - source_type
      - source_id
      - status
      - mode
      - created_by
      - created_at
      - markdown_store
      title: GetArtifactResponse
      description: Response model for getting a single artifact with its content.
      examples:
      - created_at: '2025-10-21T14:30:00Z'
        created_by: user-uuid-123
        description: Artifact exported from conversation 123
        id: 123e4567-e89b-12d3-a456-426614174000
        markdown_store: '# My Conversation


          **[2025-10-21 14:30:00 - user]**


          Hello!'
        mode: transcript
        source_id: '123'
        source_type: conversation
        status: completed
        title: My Conversation Export
    Mode:
      type: string
      enum:
      - synthesized
      - transcript
      title: Mode
    ArtifactUpdateRequest:
      properties:
        markdown_content:
          anyOf:
          - type: string
          - type: 'null'
          title: Markdown Content
          description: The new markdown content for the artifact
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
          description: The new title for the artifact
      type: object
      required:
      - markdown_content
      - title
      title: ArtifactUpdateRequest
      description: Request model for updating an artifact's markdown content.
      examples:
      - markdown_content: '# Updated Artifact Content


          This is the updated content of the artifact.'
        title: Updated Artifact Title
    CreateArtifactResponse:
      properties:
        status:
          $ref: '#/components/schemas/Status'
          description: Status of the artifact generation process
        artifact_id:
          type: string
          title: Artifact Id
          description: UUID of the created artifact
      type: object
      required:
      - status
      - artifact_id
      title: CreateArtifactResponse
      description: 'Response model for artifact creation.


        This model represents the result of an artifact generation request,

        including the artifact ID and processing status.'
      examples:
      - artifact_id: 123e4567-e89b-12d3-a456-426614174000
        status: pending
      - artifact_id: 987e6543-e21b-43c1-b567-524413627001
        status: completed
      - artifact_id: 456e7890-e12b-34d5-c678-625514738002
        status: failed
  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)