CoreStory Artifacts API
The artifacts API from CoreStory — 2 operation(s) for artifacts.
The artifacts API from CoreStory — 2 operation(s) for artifacts.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
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.curl "https://apis.io/api/v1/apis/corestory:corestory-artifacts-api"
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.
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: 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)