# 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](/console/) and create a key. Set it as `ARTEFAKTUM_API_KEY` in your shell, sandbox image, or CI secret.

## Fastest path: the CLI

```sh
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

```sh
pip install artefaktum
```

```python
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

```sh
npm install artefaktum
```

```ts
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

```sh
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/](/docs/rest/) for the full request and response shapes.

## Connect an MCP host

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

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

```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](/docs/) for the concepts behind artifacts, versions, search modes, and lineage.
- Pick your integration in detail: [/docs/mcp/](/docs/mcp/), [/docs/python/](/docs/python/), [/docs/typescript/](/docs/typescript/), [/docs/cli/](/docs/cli/), [/docs/n8n/](/docs/n8n/), or [/docs/rest/](/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](/docs/).
- Check plan limits and what happens over them at [/pricing/](/pricing/).