Quickstart

This walks you from nothing to a versioned artifact you can pull back down, in three steps.

1. Get an API key

In your workspace, open Settings → API keys and create a key with the artifacts:read and artifacts:write scopes. It’s shown only once — copy it somewhere safe.

The SDK reads the key from the api_key argument or, more commonly, the METRANA_API_KEY environment variable:

export METRANA_API_KEY="your-api-key"

Every example below assumes the key is already in the environment.

2. Install

pip install metrana

Artifacts are part of the base metrana package — no extra needed. (See Installation for platform details.)

3. Upload, then download

import metrana

# Pretend this is your freshly trained checkpoint.
import pathlib
pathlib.Path("checkpoint").mkdir(exist_ok=True)
pathlib.Path("checkpoint/weights.bin").write_bytes(b"\x00" * 1024)
pathlib.Path("checkpoint/config.json").write_text('{"layers": 12}')

# Upload the whole directory as a new version of model/my-first-model.
version = metrana.upload_artifact(
    "checkpoint/",
    type="model",
    name="my-first-model",
    workspace="my-workspace",
    description="First quickstart checkpoint",
)
print(f"committed version {version.version_index} ({version.num_files} files, {version.size_bytes} bytes)")

# ... later, from anywhere with the same workspace ...

# Download the latest version into ./restored/.
paths = metrana.download_artifact(
    "model", "my-first-model", dest="./restored", workspace="my-workspace",
)
print("downloaded:", [str(p) for p in paths])

The first call hashes the files, uploads them, and commits version 0 (the next upload of the same name commits version 1, and so on). download_artifact defaults to the latest alias, so it pulls the version you just committed into ./restored/checkpoint/…, preserving the directory layout.

Skip repeating workspace=

If you’re already inside a logged run, metrana.init(...) sets an active workspace and every artifact call picks it up automatically — you can drop the workspace= argument:

metrana.init(workspace_name="my-workspace", project_name="proj", run_name="run-001")
metrana.upload_artifact("checkpoint/", type="model", name="my-first-model")  # workspace inferred

See Configuration → Workspace.

Next

• Uploading — directories, metadata, aliases, references, idempotency.
• Downloading — pick a version, list before you fetch.
• Versions & aliases — label versions like production.