---
title: "Create artifact bundle"
method: POST
path: "/v1/artifacts"
---

# Create artifact bundle

`POST /v1/artifacts`

## Request

- Base URL: `https://api.turos.app`
- URL: `https://api.turos.app/v1/artifacts`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Builds one derived bundle for the selected issuer or comparison workflow, persists it to the authenticated organization, and returns the persisted record. For filing bundles, the default form is `10-K`; `sectionKey` selects one extracted section when available. This is an asynchronous-style acceptance response (`202`) even when the returned record is ready.

## Request body

- CreateArtifactRequest: Issuer selectors and optional bundle settings for POST /v1/artifacts. Query-string ticker or cik are accepted when their body counterparts are absent.
  - `ticker` string: Issuer ticker for a filing-derived or compensation-comparison bundle.
  - `cik` string: Issuer CIK for a filing-derived or ownership-comparison bundle.
  - `form` string: SEC form for a filing-derived bundle. Defaults to 10-K when omitted.
  - `sectionKey` string: Optional canonical filing section key, such as item_1a, to include in the bundle.
  - `kind` string: Optional artifact kind. ownership_compare_bundle requires cik; compensation_compare_bundle uses the issuer selector.

## Response `202`

Persisted artifact record, including its retrieval paths and manifest.

- ArtifactCreateResponse
  - `object` 'artifact', required
  - `id` string, required
  - `createdAt` string, date-time, required
  - `livemode` boolean, required
  - `kind` 'markdown_bundle' | 'csv_tablet' | 'json_bundle' | 'duckdb_pack' | 'ownership_compare_bundle' | 'compensation_compare_bundle', required
  - `status` 'ready', required
  - `downloadUrl` string, required
  - `provenance` object, required
  - `freshness` FreshnessMetadata: Freshness of the record. For SEC filings, freshness measures the delay between SEC acceptance (`sourcePublishedAt`) and when the record became available in the API — not the age of the document. Statuses: `current` (recently published and available promptly), `archival` (an immutable historical document held in full; its availability delay is not a freshness signal), `degraded`/`stale` (a recently published filing that became available later than the freshness thresholds allow), `fresh` (continuously refreshed datasets recently observed at source), `unknown` (no timestamps). An old immutable filing is never `stale` simply because it was published long ago. `lagMs` is the publish-to-availability delay in milliseconds.
    - `status` 'fresh' | 'current' | 'archival' | 'stale' | 'degraded' | 'unknown', required
    - `asOf` string, required
    - `sourcePublishedAt` string, nullable
    - `lagMs` integer, nullable
  - `materialization` MaterializationMetadata
    - `parserVersion` string, required
    - `materializationVersion` string, required
  - `validation` ValidationStatus
    - `status` 'validated' | 'unvalidated' | 'degraded', required
    - `confidence` 'high' | 'medium' | 'low', nullable
    - `validatedAt` string, nullable
    - `validationPipeline` string, nullable
    - `exceptions` string[]
  - `bundle` object
  - `manifest` ArtifactManifest, required
    - `object` 'artifact_manifest', required
    - `id` string, required
    - `artifactId` string, required
    - `kind` string, required
    - `status` string, required
    - `filename` string, required
    - `contentType` string, required
    - `storageMode` 'local' | 'r2', required
    - `objectKey` string, nullable, required
    - `byteLength` integer, required
    - `lineCount` integer, required
    - `checksumSha1` string, required
    - `filing` object, nullable, required
    - `section` object, nullable, required
    - `exportedFormats` string[], required
    - `createdAt` string, date-time, required
    - `entity` object, nullable
    - `links` object
    - `citation` object
  - `storageMode` 'local' | 'r2', required
  - `requestId` string, required
  - `traceparent` string, required

## Other responses

- `default`: Contract-aware error response

---

[API](https://skmtc.dev/turos/apis/turos-api.md) · [All operations](https://skmtc.dev/turos/apis/turos-api/llms.txt) · [OpenAPI document](https://skmtc.dev/turos/apis/turos-api/revisions/a68d3ec80a56?raw)