InstantMLDocs

Artifacts API

Create artifact metadata, upload bytes, list artifacts, and download stored bytes.

Open .md

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.

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.

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