Quick start

Get an API key, then push, search, and pull an artifact in under five minutes

Get an API key

Sign in with Google or GitHub at artefaktum.dev/console and create a key. Set it as ARTEFAKTUM_API_KEY in your shell, sandbox image, or CI secret.

Fastest path: the CLI

pip install "artefaktum[cli]"
export ARTEFAKTUM_API_KEY=ak_...
artefaktum push report.pdf --title "Q3 churn" --tag churn
artefaktum search "q3 churn"
artefaktum pull 0199198a-8f21-... out/

afk is the short alias for artefaktum. pull verifies the sha256 digest by default and writes into out/, creating it if needed.

Python

pip install artefaktum

from artefaktum import Artefaktum

client = Artefaktum()  # ARTEFAKTUM_API_KEY, project "default"
a = client.artifacts.push("report.pdf", title="Q3 churn", tags=["churn"])
hits = client.artifacts.search("q3 churn")
client.artifacts.pull(hits.items[0].artifact.id, "out/")

TypeScript

npm install artefaktum

import { Artefaktum } from "artefaktum";

const client = new Artefaktum(); // ARTEFAKTUM_API_KEY, project "default"
const artifact = await client.artifacts.push("report.pdf", {
  title: "Q3 churn analysis", tags: ["churn", "q3"], external_key: "reports/q3-churn",
});
const page = await client.artifacts.search("q3 churn");
await client.artifacts.pull(page.items[0].artifact.id, "out/"); // sha256 verified

REST

curl -s -X POST https://api.artefaktum.dev/v1/artifacts/search \
  -H "Authorization: Bearer $ARTEFAKTUM_API_KEY" -H "Content-Type: application/json" \
  -d '{"project_id": "…", "query": "latest enriched competitor list", "mode": "hybrid"}'

Pushing over raw REST is a signed-upload flow: POST /v1/artifacts/uploads reserves the artifact and returns a PUT URL, you upload the bytes directly to that URL, then you call the completion endpoint. Downloading is a signed GET URL from GET /v1/artifacts/{artifact_id}/download. See /docs/rest/ for the full request and response shapes.

Connect an MCP host

claude mcp add --transport http artefaktum https://api.artefaktum.dev/mcp

Cursor, or any host that reads an mcp.json:

{ "mcpServers": { "artefaktum": { "url": "https://api.artefaktum.dev/mcp" } } }

Sign in with Google or GitHub when the host asks; there is no key to paste. The host then has project_list, artifact_search, artifact_get, artifact_list, artifact_resolve, artifact_create_upload, artifact_complete_upload, artifact_create_version, artifact_get_download_url, artifact_add_relation, artifact_update_metadata, and artifact_delete as tools. File bytes never enter a tool response; the host fetches a short-lived URL instead.

What to do next

• Read the docs index for the concepts behind artifacts, versions, search modes, and lineage.
• Pick your integration in detail: /docs/mcp/, /docs/python/, /docs/typescript/, /docs/cli/, /docs/n8n/, or /docs/rest/.
• Use resolve instead of push when several workflows might fetch the same expensive result; see the external_key section on the docs index.
• Check plan limits and what happens over them at /pricing/.

This page as Markdown: /docs/quickstart.md