# Artifacts API

Attach files, checkpoints, rollouts, and media evidence to a run — as
metadata-only external references, server-managed stored bytes, or immutable
versioned artifacts with manifests, aliases, and lineage.

Authenticate with an `Authorization: Bearer instantml_...` API key or a browser
session. Reads need the `export:read` scope; raw and versioned uploads need
`artifacts:write`; alias, retention, and delete routes need `artifacts:manage`
or an owner/admin browser session.

> **Note:** Rich media objects are modeled through the [objects API](/docs/api/attributes-objects.md) and link to stored artifact bytes; reports are a separate API surface. Raw artifact routes remain available for existing file/media/checkpoint workflows.

## Create metadata

```bash
curl -X POST https://api.instantml.ai/api/runs/{run_id}/artifacts \
  -H "Authorization: Bearer instantml_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "checkpoint",
    "name": "policy.pt",
    "uri": "s3://bucket/policy.pt",
    "step": 1,
    "size_bytes": 12345,
    "sha256": "hex",
    "mime_type": "application/octet-stream",
    "metadata": {},
    "path": "policy.pt"
  }'
```

Requires `artifacts:write` or a writable browser session.

`name` is required. `type` defaults to `file` and accepts `checkpoint`, `file`,
or `rollout`. `step` must be a finite nonnegative number when present, and
`size_bytes` must be a nonnegative integer when present. Use metadata artifacts
when bytes already live in customer storage or when the artifact is too large
for direct upload.

## Upload bytes

```http
POST /api/runs/{run_id}/artifacts/upload
Authorization: Bearer instantml_...
Content-Type: application/json

{
  "type": "file",
  "name": "plot.png",
  "content_base64": "base64-bytes",
  "step": 1,
  "mime_type": "image/png",
  "metadata": {},
  "path": "plots/plot.png"
}
```

The server validates decoded byte size and projected storage usage before
touching the byte backend.

Requires `artifacts:write` or a writable browser session. Hosted deployments can
also disable direct byte uploads by configuration.

`name` and non-empty `content_base64` are required. `type` defaults to `file`
and accepts `checkpoint`, `file`, or `rollout`.

Stored bytes return public metadata with an opaque URI:

```text
instantml://artifacts/<artifact_id>
```

Raw local paths, bucket names, object keys, and signed URLs are not exposed in
public artifact metadata.

## List artifacts

```http
GET /api/runs/{run_id}/artifacts?limit=100
Authorization: Bearer instantml_...
```

API keys need `export:read`; browser sessions need viewer or higher role.

The limit caps at 1,000.

## Download stored bytes

```http
GET /api/artifacts/{artifact_id}/download
Authorization: Bearer instantml_...
```

The API streams local or object-storage bytes with the artifact MIME type.
Hosted object-storage downloads stream through the same-origin API route and
forward valid `Range` requests for media previews. API keys need `export:read`;
browser sessions need viewer or higher role.

```http
GET /api/artifacts/{artifact_id}/download
Authorization: Bearer instantml_...
Range: bytes=0-1048575
```

For hosted object storage, unsatisfiable ranges return `416`. The local file
backend streams the full file and ignores `Range`.

External metadata-only artifact rows are not downloadable through this endpoint.

## Create versioned artifacts

Create versioned artifacts through upload sessions. The SDK uses this route for
`VersionedArtifact`; direct API callers should send the same manifest fields.

```http
POST /api/runs/{run_id}/artifact-uploads
Authorization: Bearer instantml_...
Content-Type: application/json

{
  "collection": {
    "name": "policy-checkpoints",
    "type": "model",
    "metadata": {}
  },
  "manifest": {
    "entries": [
      {
        "path": "checkpoint.pt",
        "kind": "file",
        "size_bytes": 12345,
        "sha256": "64-hex",
        "mime_type": "application/octet-stream"
      }
    ]
  },
  "aliases": ["best"],
  "ttl_days": 30,
  "source_step": 1000
}
```

The response includes an `upload_session` and per-file upload targets. Local
development targets complete inline. Hosted R2 targets return short-lived
presigned multipart UploadPart URLs, including for one-part files; treat those
URLs as bearer secrets and do not log or store them. If a part includes
`required_headers`, send those headers exactly with the corresponding PUT.

After uploading bytes, complete the session:

```http
POST /api/artifact-uploads/{upload_session_id}/complete
Authorization: Bearer instantml_...
Content-Type: application/json

{
  "files": [
    {
      "entry_id": "manifest-entry-uuid",
      "parts": [{ "part_number": 1, "etag": "\"etag\"" }]
    }
  ]
}
```

Completing finalizes provider upload state, validates cheap provider evidence
such as object size against the manifest, commits the immutable version, assigns
a stable `vN` label, moves `latest`, applies requested custom aliases such as
`best`, and records the output lineage edge from the run. SHA-256 is the
client-computed manifest digest used for reproducibility and deduplication; the
API does not re-download hosted objects on the request path just to recompute it.

Use `POST /api/artifact-uploads/{upload_session_id}/abort` to discard an
unfinished session and `POST /api/artifact-uploads/{upload_session_id}/renew`
to refresh expiring upload targets.

## Read and manage versions

```http
GET /api/artifact-collections?project=cartpole&type=model&q=policy
GET /api/artifact-collections/{collection_id}
GET /api/artifact-collections/{collection_id}/versions
GET /api/artifact-versions/resolve?ref=policy-checkpoints:best&type=model&project=cartpole
GET /api/artifact-versions/{version_id}
GET /api/artifact-versions/{version_id}/manifest
GET /api/artifact-versions/{version_id}/lineage
GET /api/artifact-entries/{entry_id}/download
PUT /api/artifact-collections/{collection_id}/aliases/{alias}
DELETE /api/artifact-collections/{collection_id}/aliases/{alias}
PATCH /api/artifact-versions/{version_id}/retention
DELETE /api/artifact-versions/{version_id}
POST /api/runs/{run_id}/artifact-inputs
```

Reads require `export:read` or a browser session. Uploads require
`artifacts:write`; alias, retention, and delete routes require
`artifacts:manage` or an owner/admin browser session.
`POST /api/runs/{run_id}/artifact-inputs` records an input lineage edge from a
consumed version to the run.

Delete is a soft-delete in this slice; soft-deleted or expired versions are
hidden from resolution, manifest, lineage, and download reads. Physical byte
cleanup is handled by later retention/garbage-collection work.

> **Warning:** Alias move/delete request bodies must include `confirm` equal to the alias and a non-empty `reason`; retention and version-delete bodies must include `confirm` equal to the version ID and a non-empty `reason`.

## Preview artifacts in the dashboard

Run Detail and Compare preview safe same-origin images, audio, and video when
stored bytes and supported MIME types are available. Unsupported artifacts still
show metadata and copy/download actions when applicable.

## Next steps

- [Version checkpoints from the SDK](/docs/sdk/artifacts-checkpoints.md)
- [Browse artifacts and files in the dashboard](/docs/dashboard/artifacts-files.md)
- [Track datasets and models](/docs/dashboard/datasets.md)
- [Log rich media objects](/docs/api/attributes-objects.md)
- [Handle errors, pagination, and limits](/docs/api/errors-and-limits.md)

## Agent navigation

- [Docs index](/llms.txt)
- [Full docs bundle](/llms-full.txt)

### Get Started

- [Overview](/docs/index.md)
- [Quickstart](/docs/quickstart.md)
- [Core Concepts](/docs/concepts/core-concepts.md)
- [Pricing](/docs/pricing.md)
- [Benchmarks](/docs/benchmarks.md)
- [Examples](/docs/guides/examples.md)
- [Troubleshooting](/docs/troubleshooting.md)

### SDK

- [Installation Auth](/docs/sdk/installation-auth.md)
- [Logging](/docs/sdk/logging.md)
- [Tracing](/docs/sdk/tracing.md)
- [Metrics Steps](/docs/sdk/metrics-steps.md)
- [Config Tags Notes](/docs/sdk/config-tags-notes.md)
- [Artifacts Checkpoints](/docs/sdk/artifacts-checkpoints.md)
- [Rich Objects](/docs/sdk/rich-objects.md)
- [Distributed Training](/docs/sdk/distributed-training.md)
- [Console System Integrations](/docs/sdk/console-system-integrations.md)
- [Reliability](/docs/sdk/reliability.md)
- [Cli Login](/docs/sdk/cli-login.md)
- [Querying Data](/docs/sdk/querying-data.md)
- [Agent Mcp](/docs/sdk/agent-mcp.md)
- [Examples Patterns](/docs/sdk/examples-patterns.md)

### Integrations

- [Overview](/docs/integrations/overview.md)
- [Pytorch Lightning](/docs/integrations/pytorch-lightning.md)
- [Huggingface Transformers](/docs/integrations/huggingface-transformers.md)
- [Keras](/docs/integrations/keras.md)
- [Wandb](/docs/integrations/wandb.md)

### Dashboard

- [Tour](/docs/dashboard/tour.md)
- [Organizations Workspaces](/docs/dashboard/organizations-workspaces.md)
- [Runs Workspace](/docs/dashboard/runs-workspace.md)
- [Metrics Charts](/docs/dashboard/metrics-charts.md)
- [Run Detail](/docs/dashboard/run-detail.md)
- [Traces](/docs/dashboard/traces.md)
- [Compare Runs](/docs/dashboard/compare-runs.md)
- [Research Dashboards](/docs/dashboard/research-dashboards.md)
- [Artifacts Files](/docs/dashboard/artifacts-files.md)
- [Run Health](/docs/dashboard/alerts.md)
- [Datasets](/docs/dashboard/datasets.md)
- [Checkpoints](/docs/dashboard/checkpoints.md)
- [Reports](/docs/dashboard/reports.md)
- [Settings Api Keys](/docs/dashboard/settings-api-keys.md)
- [Api Tab](/docs/dashboard/api-tab.md)
- [Onboarding Team Billing](/docs/dashboard/onboarding-team-billing.md)

### Data

- [Imports](/docs/guides/imports.md)
- [W&B alternative](/docs/guides/wandb-alternative.md)
- [InstantML vs MLflow](/docs/guides/instantml-vs-mlflow.md)
- [W&B import guide](/docs/guides/wandb-import-guide.md)
- [W&B and Neptune imports](/docs/guides/wandb-neptune-imports.md)
- [Export Usage Limits](/docs/guides/export-usage-limits.md)
- [Pricing Limits Billing](/docs/guides/pricing-limits-billing.md)
- [Auth Billing Storage](/docs/guides/auth-billing-storage.md)
- [Customer Owned Clickhouse](/docs/guides/customer-owned-clickhouse.md)
- [Observability](/docs/guides/observability.md)

### API

**Practical API guides**

- [Authentication](/docs/api/authentication.md)
- [Errors And Limits](/docs/api/errors-and-limits.md)
- [Health Observability](/docs/api/health-observability.md)
- [Projects Runs](/docs/api/projects-runs.md)
- [Metrics Series](/docs/api/metrics-series.md)
- [Attributes Objects](/docs/api/attributes-objects.md)
- [Artifacts](/docs/api/artifacts.md) (current page)
- [Reports](/docs/api/reports.md)
- [Iframe Embeds](/docs/api/iframe-embeds.md)
- [Import Export Usage](/docs/api/import-export-usage.md)
- [Dashboard Control State](/docs/api/dashboard-control-state.md)
**Architecture**

- [System Overview](/docs/architecture/system-overview.md)
- [Service Planes](/docs/architecture/service-planes.md)
- [Storage Model](/docs/architecture/storage-model.md)
- [Google Clickhouse](/docs/architecture/google-clickhouse.md)
- [Auth Tenancy](/docs/architecture/auth-tenancy.md)
- [Schema Reference](/docs/architecture/schema-reference.md)

### API Reference

- [API Reference](/docs/api-reference.md)