# Artefaktum docs > Core concepts behind Artefaktum, from artifacts and versions to search, lineage, and how bytes move Artefaktum is a multi-tenant artifact store for AI agents and automated workflows that share no filesystem. An agent pushes a file with a descriptor; a different agent, on a different host, hours or days later, finds it by what it is rather than by an ID, and checks whether it is still current before it relies on it. ## Artifact An artifact is the stable identity for a file. Your code sets its title, description, tags, and custom metadata when it pushes; the server fills in content type, size in bytes, and sha256 once the bytes land. Status moves through `pending_upload`, `processing`, `ready`, `failed`, `deleting`, `deleted`. `ready` means the object is verified in storage, not that it is searchable by meaning yet: semantic readiness is tracked separately as `semantic_ready`, so an embedding-provider outage never hides a new artifact from exact or text search, only from semantic. ## Versions An artifact can have more than one version, and bytes are immutable: new content never overwrites a version, it opens one with `artifact_put` and `if_exists: "version"` under a key (`push(if_exists="version")` in the SDKs), and the server records a `supersedes` edge from the new version to the one before it. Search results and `artifact_get` return the latest version's metadata, content type, size, and sha256, by default. Older versions stay addressable by ID. ## external_key `external_key` is a stable name your own code chooses, not one the server hands back, so re-running the same workflow, or a different workflow entirely, lands on the same artifact instead of creating a duplicate. `resolve` is built around it: pass an `external_key` and a `max_age_seconds`, and it returns `hit` when a fresh-enough artifact already exists, `create` with a signed upload URL when you are the caller that should produce it, or `pending` when another caller is already producing it. That is what lets several agents racing for the same expensive upstream response make it exactly once. ## Search modes `artifact_search` supports four modes: `exact` (structured filters only, no query text needed), `text` (full-text over title, description, and tags), `semantic` (over the artifact descriptor), and `hybrid`, which fuses the text and semantic rank lists with Reciprocal Rank Fusion so no score calibration is needed. Scores are not comparable across modes. Any mode can be narrowed with filters on tags, content type, and dates. ## Relations and lineage Artifacts link to each other with five relation types: `derived_from`, `supersedes`, `attachment_of`, `generated_by`, and `related_to`. Tag an upload or download with a `run_id` and the server infers `derived_from` edges automatically, pinned to the exact version that was read; an explicit relation always replaces an inferred one. Two trust signals ride along with search results and `artifact_get`: `superseded`, meaning another artifact has a `supersedes` edge pointing here, or a newer version of this same artifact exists; and `stale_upstream`, meaning something this artifact was derived from has since moved on: a new version, superseded, expired, or deleted. Superseded artifacts leave default search results; pass `exclude_superseded: false` to see the history. ## Projects and tenants Every account or organisation is one tenant. Projects live inside a tenant, and every operation is scoped to a project. API keys carry scopes and can be limited to a single project or left tenant-wide, plus an optional expiry. Organisations share one plan and mint their own keys from the console. The console's Files page lets people browse, search and download what their agents stored. ## How bytes move Uploading is two calls, never one: reserve an upload to get a signed PUT URL and headers, send the bytes straight to object storage, then call complete. Downloading mirrors that: ask for a download and get back a short-lived signed URL, then fetch it yourself. REST responses never carry file bytes, only metadata and URLs. MCP returns text files inline (bounded) and binary files as a URL. The SDKs hash the file locally on push and verify the sha256 digest on pull, raising an integrity error on a mismatch. ## Choose an integration | Integration | Pick it when | Docs | | --- | --- | --- | | MCP | Your agent runs inside a host that speaks MCP, such as Claude Code or Cursor, and you want push, search, and pull as tool calls with nothing to install. | [/docs/mcp/](/docs/mcp/) | | Python SDK | You are writing Python and want typed methods with retries and sha256 verification built in. | [/docs/python/](/docs/python/) | | TypeScript SDK | You are writing Node, or a script for Bun, Deno, or Cloudflare Workers, and want a zero-dependency typed client. | [/docs/typescript/](/docs/typescript/) | | CLI | You are scripting, or baking Artefaktum into a sandbox image or a CI step, and want a plain command. | [/docs/cli/](/docs/cli/) | | n8n | You are building an n8n workflow and want a node with a credential, not a raw HTTP request. | [/docs/n8n/](/docs/n8n/) | | REST | You are on Make, Zapier, anything with an HTTP step, or writing your own client. | [/docs/rest/](/docs/rest/) | ## For agents The whole set is also available in one fetch: [/llms.txt](/llms.txt) is an index of every page, and [/llms-full.txt](/llms-full.txt) concatenates all of them. Every page on this site also exists as plain Markdown at `/docs/.md`. Source: https://artefaktum.dev/docs/ --- # 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 six tools: `artifact_search`, `artifact_get`, `artifact_put`, `artifact_update`, `artifact_delete` and `project_list`. Text content comes back inline and `artifact_put` saves text directly; binary files come as a short-lived download URL. See [the MCP page](/docs/mcp/). ## 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 `push --if-exists reuse` (or `artifact_put` with `if_exists: "reuse"`) 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/). Source: https://artefaktum.dev/docs/quickstart/ --- # MCP server > Connect an MCP host to Artefaktum's hosted server and use six tools to find, read, save and trust artifacts. ## Connecting Artefaktum runs one hosted MCP server over Streamable HTTP: ``` https://api.artefaktum.dev/mcp ``` No stdio entry point; a stdio-only host needs a bridge such as `mcp-remote`. Claude Code: ```sh claude mcp add --transport http artefaktum https://api.artefaktum.dev/mcp ``` Cursor, Windsurf, Cline, or any host that reads an `mcp.json`: ```json { "mcpServers": { "artefaktum": { "url": "https://api.artefaktum.dev/mcp" } } } ``` ### What happens on first use The host opens a browser tab for an OAuth 2.1 sign-in handled by Clerk: sign in with Google or GitHub, approve the connection once, and the host gets an access token it attaches to every call after that. There is no key to paste. Sign-in provisions a tenant the first time it happens, keyed to your personal account or Clerk organisation, with a default project already in place. ## Authentication The endpoint accepts two bearer credentials, checked by the same resolver chain as REST: - **OAuth 2.1 access token**: issued by Clerk after the browser sign-in above. The default for hosts with an OAuth-capable MCP client. - **API key**: the same key used against the REST API, created in the [console](https://artefaktum.dev/console/), sent as `Authorization: Bearer `. Use it for hosts that can't complete a browser flow, or for unattended runs: pass `--header` on `claude mcp add`, or add a header next to `url` in `mcp.json` if the host allows one. Two OAuth caveats: Clerk's tokens carry no audience (`aud`) claim, so audience checking is relaxed rather than strict; and Clerk doesn't know Artefaktum's scope names, so every OAuth caller gets a fixed grant of read, write and search, never delete or admin. An API key carries exactly the scopes it was minted with. Neither matters for normal use, only for auditing what an OAuth agent can reach. ## Tools Six tools. Every tool except `project_list` takes an optional `project` (a slug or UUID). Without it the tools use your API key's project if it is project-scoped, else the project with slug `default`; call `project_list` to see the others. List-shaped results cap at 25 items and long text is truncated. | Tool | Purpose | |---|---| | `artifact_search` | Find artifacts by meaning, text, or structured filters. | | `artifact_get` | Read one artifact by ID or by key: details, trust signals, relations and the content itself. | | `artifact_put` | Save text or JSON, optionally under a key to add a version or reuse an existing result. | | `artifact_update` | Change an artifact's title, description, tags, metadata or expiry. | | `artifact_delete` | Request permanent deletion of an artifact. | | `project_list` | List the projects this credential can use. | ### What changed Text content now comes back inline in `artifact_get`, and `artifact_put` takes text directly, so chat hosts, which cannot make HTTP requests to a signed URL, now work end to end: they can search, read, and save. Binary files still go through a short-lived download URL, and uploading them stays with the SDKs, the CLI and REST. The upload, download-URL, list, resolve, version and relation tools are gone; their jobs are `artifact_put`, `artifact_get` and `artifact_search`. Relations remain readable in `artifact_get`; writing them stays in REST, the SDKs and the CLI. ### Finding artifacts **`artifact_search`** matches descriptors (title, description, tags, metadata), never file contents. `mode` is `exact` (filters only), `text` (full-text), `semantic` (pgvector) or `hybrid` (fuses both; the default). Scores aren't comparable across modes. Superseded artifacts are hidden unless asked for. | Parameter | Type | Default | |---|---|---| | `project` | slug or UUID | `default` | | `query` | string | `""` | | `mode` | string | `"hybrid"` | | `tags_all` | string[] | none | | `content_types` | string[] | none | | `exclude_superseded` | boolean | `true` | | `limit` | integer | `20` (capped at 25) | ```json { "query": "q3 churn analysis", "mode": "hybrid", "tags_all": ["churn"], "limit": 10 } ``` ### Reading **`artifact_get`** returns one artifact: details, lifecycle state, trust signals, up to 25 relations and the content. Give exactly one of `artifact_id` or `key`. | Parameter | Type | Default | |---|---|---| | `artifact_id` | UUID | one of `artifact_id` / `key` | | `key` | string | one of `artifact_id` / `key` | | `project` | slug or UUID | your API key's project if project-scoped, else `default` | | `max_age_seconds` | integer | none; with `key`, an older artifact is reported as not found | | `include_content` | boolean | `true` | | `max_characters` | integer | `50000` | | `version_id` | UUID | latest version | Text-like files up to 5 MiB come back inline as `content`, with `content_truncated`, `content_characters` and `content_version_id` (the version actually read). Anything else returns `content: null` and a `content_reason`: | `content_reason` | Meaning | |---|---| | `binary` | Not text; use `download_url` (with `download_expires_at`). | | `too_large` | Text over 5 MiB; use `download_url`. | | `not_requested` | `include_content` was `false`. | | `not_ready` | The upload is still processing; read again shortly. | ```json { "key": "report:sales", "project": "finance", "max_age_seconds": 86400 } ``` **`project_list`** takes no arguments; it returns every project the credential can use. ### Saving **`artifact_put`** saves text or JSON as an artifact. `content` is at most 1 MiB of UTF-8; larger or binary files go through the SDKs or CLI. The `/mcp` request body limit is 2 MiB; REST stays at 256 KiB. | Parameter | Type | Default | |---|---|---| | `content` | string | required | | `title` | string | required | | `project` | slug or UUID | your API key's project if project-scoped, else `default` | | `key` | string | none | | `if_exists` | `error` / `version` / `reuse` | `error` | | `max_age_seconds` | integer | none (only with `reuse`; an older artifact counts as missing) | | `filename` | string | generated | | `content_type` | string | `text/plain` | | `description` | string | `""` | | `tags` | string[] | none | | `metadata` | object | none | | `expires_in_hours` | integer | none (applied whenever this call stored bytes: a new artifact, a new version, or a reuse that replaced a stale copy; never on a reuse hit) | | `run_id` | string | none | With a `key`, `if_exists` chooses what a repeat does: `error` refuses, `version` adds a new version under the same key, `reuse` returns the existing artifact with `cache: "hit"` and writes nothing, or stores yours with `cache: "created"`. The result may still show `processing`; search finds it once it is `ready`. Field sizes are limited; see [Limits](/docs/rest/#limits). ```json { "title": "Acme enrichment", "key": "company-api/acme/2026-10-24", "if_exists": "reuse", "max_age_seconds": 86400, "content": "{\"employees\": 120}", "content_type": "application/json" } ``` ### Changing and deleting **`artifact_update`** changes title, description, tags, metadata or expiry (`expires_at`, or `clear_expires_at`). Find the artifact by `artifact_id` or by `key` (with `project`). Bytes are immutable: for new content call `artifact_put` with `if_exists: "version"`. **`artifact_delete`** moves the artifact to `deleting`; a worker removes the bytes. Not reversible. Same lookup: `artifact_id`, or `key` with `project`. ### The artifact resource `artefactai://artifacts/{artifact_id}` is a pointer, not a data endpoint. A resource read carries no principal to authorize against, so it returns only the id you gave it plus a nudge to call `artifact_get` instead. ## Typical agent flow A research agent hands a report to a writing agent, neither knowing where the other runs. 1. Research agent calls `artifact_put` with the report text, a `title` and a `key`, `if_exists: "version"`, so reruns add versions. 2. Writing agent, on a separate host, calls `artifact_search` (`hybrid`, same `project`) and picks a hit with `superseded: false` and `stale_upstream: false`. 3. Writing agent calls `artifact_get` and reads `content` inline. If `content_reason` is `not_ready`, it reads again a moment later. 4. Writing agent saves its own output with `artifact_put`, tagged with the same `run_id`. Reading through MCP does not infer lineage, so no `derived_from` edge appears on its own; relations show up in `artifact_get`, and writing one goes through REST, the SDKs or the CLI. Source: https://artefaktum.dev/docs/mcp/ --- # REST API > The plain HTTP API behind the SDKs, for curl, Make, Zapier or any HTTP step. ## Base URL and authentication ``` https://api.artefaktum.dev ``` Every request except `/health/live` and `/health/ready` needs an API key, created in the [console](https://artefaktum.dev/console/), sent as: ``` Authorization: Bearer ``` Requests and responses are JSON: send `Content-Type: application/json` on any body. The OpenAPI document is at `https://api.artefaktum.dev/openapi.json`; interactive docs from it are at `https://api.artefaktum.dev/docs`, useful for a typed client in a language the SDKs don't cover. For an agent reading about the API before it has a key, the same origin serves `https://api.artefaktum.dev/llms.txt` (a one-fetch Markdown index of the docs, the OpenAPI document and the MCP endpoint) and `https://api.artefaktum.dev/.well-known/agent-card.json` (an A2A-shaped agent card naming the MCP server, its skills and how to authenticate). Neither needs authentication. ## Limits Limits apply when you write. Artifacts that are already stored are never re-validated. | Field | Limit | |---|---| | `title` | 1 to 500 characters | | `description` | 10,000 characters | | `tags` | 50 per artifact | | one tag | 1 to 64 characters, not blank | | `metadata` | 16,384 bytes as compact JSON, nested at most 5 levels deep | | `external_key` | 512 characters | | `filename` | 1,024 characters | | `content_type` | 255 characters | | `run_id` | 128 characters | | request body | 262,144 bytes (256 KB) | A field over its limit answers `400 invalid_request`. `detail` starts with the field's path, then says what was sent and what the limit is, for example `body.metadata: Value error, metadata is 20011 bytes as JSON; the limit is 16384`. A tag's path carries its position in the list, as in `body.tags.0`. Branch on `code`, not `detail`: its wording can change. A request body over 256 KB answers `413 request_too_large` before it is read, for example `the request body exceeds the limit of 262144 bytes`. File bytes never pass through the API, so this limit does not apply to your files: those go straight to storage, up to the file size of your plan. Metadata depth counts containers: `{}` is one level, `{"a": {"b": 1}}` is two. Lists count the same as objects. Storage, monthly API calls and file size depend on your plan; see [pricing](/pricing/). ## Errors Errors are `application/problem+json` (RFC 9457): ```json { "type": "https://artefact.ai/errors/artifact_not_found", "title": "Artifact not found", "status": 404, "detail": "artifact 0199198a-... not found", "instance": "/v1/artifacts/0199198a-...", "code": "artifact_not_found", "request_id": "..." } ``` `code` is the stable field to branch on; `type`, `title` and `detail` are for humans. Codes you'll actually see: | Code | Status | Meaning | |---|---|---| | `invalid_request` | 400 | Body or query param failed validation. | | `unauthorized` | 401 | Missing or invalid bearer token. | | `insufficient_scope` | 403 | The key lacks the required scope. | | `artifact_not_found` | 404 | No such artifact, or it belongs to another tenant. | | `run_not_found` | 404 | No such run. | | `artifact_not_ready` | 409 | The artifact's state doesn't support this call. | | `external_key_conflict` | 409 | The external key is already used in this project. | | `idempotency_conflict` | 409 | `Idempotency-Key` reused with a different body. | | `run_sealed` | 409 | The run no longer accepts writes. | | `upload_expired` | 410 | The signed upload window closed before completion. | | `object_verification_failed` | 422 | The uploaded object failed verification. | | `quota_exceeded` | 413 | The file or tenant storage exceeds the plan limit. | | `quota_exceeded` | 429 | The monthly call limit is exhausted. | | `request_too_large` | 413 | The request body is over 256 KB. File bytes never count. | | `upstream_unavailable` | 502 | A dependency Artefaktum calls did not answer. | | `embedding_unavailable` | 503 | The embedding provider could not produce a vector. | `quota_exceeded` is deliberately the same code at two statuses: clients branch on the code, and 429 (not 402) is used so it doesn't collide with a payment-required response. ## Endpoints | Method | Path | Scope | Purpose | |---|---|---|---| | GET | `/health/live` | none | Liveness probe. | | GET | `/health/ready` | none | Liveness plus a database check. | | GET | `/health/whoami` | any | Return the tenant and project the key resolves to. | | GET | `/v1/projects` | `artifacts:read` | List the projects this credential can use. | | POST | `/v1/artifacts/search` | `artifacts:search` | Find artifacts by text, semantic similarity or filters. | | POST | `/v1/artifacts/resolve` | `artifacts:write` | Reuse a fresh artifact by external key, or reserve it. | | POST | `/v1/artifacts/uploads` | `artifacts:write` | Reserve a new artifact; get a signed upload URL. | | POST | `/v1/artifacts/{artifact_id}/versions/{version_id}/complete` | `artifacts:write` | Confirm the bytes were uploaded. | | GET | `/v1/artifacts` | `artifacts:read` | List artifacts in a project, with filters and a cursor. | | GET | `/v1/artifacts/by-external-key/{external_key}` | `artifacts:read` | Look up an artifact by external key. Requires `project_id`; optional `max_age_seconds`. | | GET | `/v1/artifacts/{artifact_id}` | `artifacts:read` | Read one artifact's metadata and lifecycle state. | | GET | `/v1/artifacts/{artifact_id}/versions` | `artifacts:read` | List an artifact's versions. | | GET | `/v1/artifacts/{artifact_id}/download` | `artifacts:read` | Get a short-lived signed download URL. | | PATCH | `/v1/artifacts/{artifact_id}` | `artifacts:write` | Update title, description, tags, metadata or TTL. | | POST | `/v1/artifacts/{artifact_id}/uploads` | `artifacts:write` | Start a new version; get a signed upload URL. | | POST | `/v1/artifacts/{artifact_id}/relations` | `artifacts:write` | Add an explicit lineage relation. | | GET | `/v1/artifacts/{artifact_id}/relations` | `artifacts:read` | List an artifact's direct relations, both directions. | | DELETE | `/v1/artifacts/{artifact_id}` | `artifacts:delete` | Request deletion (`202 Accepted`). | | POST | `/v1/runs` | `artifacts:write` | Create or register a run id. | | POST | `/v1/runs/{run_id}/seal` | `artifacts:write` | Reject further writes to a run. | | GET | `/v1/runs/{run_id}/artifacts` | `artifacts:read` | List artifacts produced in a run. | | POST | `/v1/api-keys` | `artifacts:admin` | Mint a key; the secret is returned once. | | GET | `/v1/api-keys` | `artifacts:admin` | List keys, never their secrets. | | DELETE | `/v1/api-keys/{key_id}` | `artifacts:admin` | Revoke a key. | | GET | `/v1/quota` | `artifacts:read` | Plan, limits and current usage for the tenant. | | GET | `/v1/usage` | `artifacts:admin` | Time-bucketed request and byte counts. | A key can never be granted a scope its creator lacks. ## Worked examples ### Search Exactly the call the homepage's REST panel shows: ```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"}' ``` Request body fields: | Field | Type | Default | |---|---|---| | `project_id` | UUID | required | | `query` | string | `""` | | `mode` | `"exact"` \| `"text"` \| `"semantic"` \| `"hybrid"` | `"hybrid"` | | `filters.tags_all` | string[] | `[]` | | `filters.content_types` | string[] | `[]` | | `filters.status` | string[] | `["ready"]` | | `filters.external_key` | string | none | | `filters.created_after` / `filters.created_before` | date-time | none | | `filters.exclude_superseded` | boolean | `true` | | `limit` | integer, 1-200 | `20` | | `cursor` | string | none | Response items carry the artifact, a `score` and a `match_mode`; scores aren't comparable across modes. ### Create upload, PUT bytes, complete ```sh curl -s -X POST https://api.artefaktum.dev/v1/artifacts/uploads \ -H "Authorization: Bearer $ARTEFAKTUM_API_KEY" -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "project_id": "'"$PID"'", "title": "Acme enrichment response", "filename": "acme.json", "content_type": "application/json", "size_bytes": 5120, "tags": ["company", "enrichment"] }' ``` Request body fields: | Field | Type | Default | |---|---|---| | `project_id` | UUID | required | | `filename` | string | required | | `content_type` | string | required | | `size_bytes` | integer | required | | `title` | string | required | | `description` | string | `""` | | `tags` | string[] | `[]` | | `metadata` | object | `{}` | | `external_key` | string | none | | `expires_at` | date-time | none | | `run_id` | string | none | | `infer_lineage` | boolean | `true` | `summary` was removed on 2026-09-27. A request that still sends the key is refused with `400 invalid_request`, like any other unknown key, and responses no longer carry it. Clients published before then (Python SDK 0.1.1, TypeScript SDK 0.1.0, n8n node 0.1.3) send the key only when you set a summary; stop setting it or upgrade. This is the one endpoint that accepts an `Idempotency-Key` header, so a retried request doesn't create a second reservation. Response: ```json { "artifact": { "id": "...", "version_id": "...", "status": "pending_upload" }, "upload": { "method": "PUT", "url": "...", "headers": {"content-type": "application/json"}, "expires_at": "..." } } ``` `PUT` the bytes to `upload.url` with the given headers, then complete: ```sh curl -s -X PUT "$UPLOAD_URL" -H "Content-Type: application/json" --data-binary @acme.json curl -s -X POST "https://api.artefaktum.dev/v1/artifacts/$AID/versions/$VID/complete" \ -H "Authorization: Bearer $ARTEFAKTUM_API_KEY" ``` Safe to repeat. The artifact is `ready` once the server verifies the object; embedding for semantic search happens afterwards, tracked separately as `semantic_ready`. ### Get a download URL ```sh curl -s "https://api.artefaktum.dev/v1/artifacts/$AID/download" \ -H "Authorization: Bearer $ARTEFAKTUM_API_KEY" ``` Optional params: `version_id` (defaults to latest) and `run_id` (for lineage inference on a later upload). The response is a short-lived signed URL; the API never proxies the bytes, and fetching it records a usage event. ### Resolve by external key ```sh curl -s -X POST https://api.artefaktum.dev/v1/artifacts/resolve \ -H "Authorization: Bearer $ARTEFAKTUM_API_KEY" -H "Content-Type: application/json" \ -d '{ "project_id": "'"$PID"'", "external_key": "company-api/acme/2026-09-17", "max_age_seconds": 86400, "filename": "acme.json", "content_type": "application/json", "size_bytes": 5120, "title": "Acme enrichment" }' ``` Request body fields: | Field | Type | Default | |---|---|---| | `project_id` | UUID | required | | `external_key` | string | required | | `max_age_seconds` | integer | none (any existing artifact counts as fresh) | | `filename` | string | required | | `content_type` | string | required | | `size_bytes` | integer | required | | `title` | string | required | | `description` | string | `""` | | `tags` | string[] | `[]` | | `metadata` | object | `{}` | | `run_id` | string | none | `status` is `hit` (an artifact is returned, no upload needed), `create` (you hold the reservation: `PUT` to `upload.url`, then complete), or `pending` (retry after `retry_after_seconds`). For a plain lookup with no side effect, use `GET /v1/artifacts/by-external-key/{external_key}?project_id=...`. A key lookup requires `project_id` (omitting it is a `400`) and takes an optional `max_age_seconds` (a positive integer; `0` or a negative value is a `400`). An artifact last updated longer ago than that answers `404 artifact_not_found`, with a detail such as `artifact under key 'K' is 7200s old, older than max_age_seconds=3600`: ```sh curl -s "https://api.artefaktum.dev/v1/artifacts/by-external-key/openweather%2Fvilnius?project_id=$PROJECT_ID&max_age_seconds=3600" \ -H "Authorization: Bearer $ARTEFAKTUM_API_KEY" ``` ### Add a relation ```sh curl -s -X POST "https://api.artefaktum.dev/v1/artifacts/$OUT_ID/relations" \ -H "Authorization: Bearer $ARTEFAKTUM_API_KEY" -H "Content-Type: application/json" \ -d '{"to_artifact_id": "'"$IN_ID"'", "relation_type": "derived_from"}' ``` Body: `to_artifact_id` (required), `relation_type` (required: `derived_from`, `supersedes`, `attachment_of`, `generated_by` or `related_to`), optional `to_version_id`, optional `metadata`. Explicit relations replace inferred ones. When an upload names a `run_id`, the server infers `derived_from` edges from whatever that key downloaded earlier in the run; pass `"infer_lineage": false` on the upload to suppress it. ## Quota and usage `GET /v1/quota` never counts against the monthly call limit, so a key can always see why it was refused. It returns the plan name, `storage: {used_bytes, limit_bytes}`, `calls: {used, limit, resets_at}`, and `max_file_bytes`. `GET /v1/usage` takes `start`, `end`, `granularity` (`hour` or `day`), `metric`, `project_id` and `principal_id`, returning time-bucketed counts for `requests`, `requests_error`, `storage_bytes`, `bytes_uploaded` and `bytes_downloaded`. Source: https://artefaktum.dev/docs/rest/ --- # Python SDK > Push, pull, search, and manage artifacts from Python with the official artefaktum package ## Install ```sh pip install artefaktum ``` Python 3.10+. The only dependency is `httpx`. For the CLI, see [CLI](/docs/cli/). ## Configure Resolved in order: constructor argument, then environment variable, then default. | Argument | Environment variable | Default | |---|---|---| | `api_key` | `ARTEFAKTUM_API_KEY` | *(required)* | | `base_url` | `ARTEFAKTUM_BASE_URL` | `https://api.artefaktum.dev` | | `project` | `ARTEFAKTUM_PROJECT` | `"default"` | ```python client = Artefaktum(api_key="ak_...", base_url="http://localhost:3000", project="default", timeout=30.0) ``` API keys are created in the [console](/console/). `MissingApiKey` (a `ValueError`) is raised locally, before any request, if no key is found anywhere. `project` is a slug or a UUID. A slug is resolved to an ID through `GET /v1/projects` once, then cached. `push`, `search`, `list`, `get_by_external_key`, `pull_by_key`, and a few others also take a per-call `project=` override. ## Five-minute example ```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/") # sha256 verified ``` ## Pushing `push` hashes, reserves, uploads, and (by default) waits for the artifact to be ready: 1. Hashes and sizes the source locally, streamed; guesses a content type from the filename unless one is given. 2. Reserves an upload (`create_upload`), returning a signed PUT URL. 3. Uploads the bytes directly to object storage, over a client with no `Authorization` header, so the API key never reaches the storage host. 4. Marks the version complete (`complete_upload`) with the digest and size. 5. By default, polls every 0.5s until `ready`, raising `ProcessingFailed` or `ProcessingTimeout`. `wait=False` returns right after step 4, with status `processing` or `ready`. ```python client.artifacts.push( "report.pdf", title="Q3 churn", description="Churn breakdown by segment", tags=["churn", "q3"], external_key="reports/q3-churn", ) ``` | Argument | Default | Meaning | |---|---|---| | `source` | required | path (streamed) or `bytes` (needs `filename`) | | `title` | required | artifact title | | `description` | `""` | | | `tags` | `()` | sequence of tags | | `metadata` | `None` | mapping of custom fields | | `external_key` | `None` | your own unique key within the project; see `if_exists` | | `if_exists` | `"error"` | what a repeated `external_key` does: `"error"`, `"version"` or `"reuse"` | | `max_age` | `None` | with `"reuse"`: an older artifact counts as missing (`int`, `float` or `timedelta` seconds) | | `expires_at` | `None` | `datetime` after which the artifact expires | | `run` | `None` | attach to a run ID | | `infer_lineage` | `True` | let the server infer relations | | `content_type` | `None` | guessed from `filename` if omitted | | `filename` | `None` | required for `bytes`; else the path's name | | `wait` | `True` | poll until `ready` | | `timeout` | `30.0` | seconds to wait | | `project` | `None` | override the default project | Field sizes are limited; see [Limits](/docs/rest/#limits). `create_version(artifact_id, source, ...)` runs the same flow for a new version of an existing artifact: `run`, `infer_lineage`, `content_type`, `filename`, `wait`, `timeout`, but no title/tags/metadata, since those belong to the artifact, not the version. ## Pulling ```python path = client.artifacts.pull(artifact_id, "out/") ``` `pull(artifact_id, dest, *, verify=True)` streams the latest version to `dest` and returns the final `Path`. `dest` is a directory when it already is one, or when it is a *string* ending in `/`, which `pull` creates. A `pathlib.Path` cannot express that intent, since `Path("out/")` is just `Path("out")`. Into a directory, the file is named after the version's stored filename, reduced to a basename, so an uploader cannot steer the write outside it. The download runs on a client with no `Authorization` header. `verify=True` (the default) checks the sha256 digest and raises `IntegrityError` on a mismatch, deleting the partial file; a version the server recorded no digest for is written unverified regardless. `verify=False` skips the check. ## Finding ```python hits = client.artifacts.search("q3 churn", mode="hybrid", tags_all=["churn"]) page = client.artifacts.list(tag="churn", limit=50) one = client.artifacts.get(artifact_id) one = client.artifacts.get_by_external_key("reports/q3-churn", max_age=timedelta(hours=1)) ``` `search` returns a `SearchPage` of `SearchHit` (`.artifact`, `.score`, `.match_mode`). Key arguments: `query`, `mode` (`hybrid` default, or `text`, `semantic`, `exact`), `limit` (20), `cursor`, `content_types`, `tags_all`, `status` (default `("ready",)`), `external_key`, `created_after`/`created_before`, `exclude_superseded` (`True` by default), `project`. `list` returns a `Page[Artifact]`, with the same filters as `search` minus `query`/`mode`, plus `expires_before` and default `limit=50`. `iter_all(...)` takes the same filters and is a generator that follows `next_cursor` page by page, yielding every matching `Artifact`; on the async client, `iter_all` is an async generator instead. `get(artifact_id)` and `get_by_external_key(key, *, project=None, max_age=None)` each return a single `Artifact`, raising `NotFound` if there is none, or, with `max_age`, if the artifact under the key is older than that. ## Reuse or replace by key Give `push` an `external_key` and say what a repeat should do with `if_exists`: ```python from datetime import timedelta # Reuse: an artifact under this key younger than an hour is returned, nothing is uploaded. a = client.artifacts.push( body, filename="weather.json", title="Vilnius weather", external_key="openweather/vilnius", if_exists="reuse", max_age=timedelta(hours=1), ) print(a.reused) # True when an existing artifact came back (set by the SDK, not the API) # Replace: add a version to the artifact holding the key, or create it when the key is new. client.artifacts.push( body, filename="weather.json", title="Vilnius weather", external_key="openweather/vilnius", if_exists="version", ) # Read it back by key; a `max_age` older artifact is NotFound. client.artifacts.pull_by_key("openweather/vilnius", "out/", max_age=timedelta(hours=1)) ``` `if_exists` is `"error"` (the default: an existing key is a `Conflict`), `"version"` or `"reuse"`; both of the latter need `external_key`, and `max_age` only applies to `"reuse"`. With `"version"`, the descriptor fields you pass (title, description, tags, metadata, `expires_at`) are applied to the existing artifact after the new version lands. With `"reuse"`, a `push` that finds another producer already making the artifact waits up to `timeout` seconds, then raises `ProcessingTimeout`; `expires_at` is applied whenever this call stored bytes (never on a hit), and `infer_lineage` is not sent on this path. `pull_by_key(key, dest, *, project=None, max_age=None, verify=True)` is `pull` addressed by key. `resolve`, `fulfil` and `create_version` remain as low-level calls for callers who manage the reservation and upload themselves: `resolve` returns a `Resolution` whose `status` is `hit`, `create` (pass it and the bytes to `fulfil`) or `pending`. ## Versions and relations ```python versions = client.artifacts.versions(artifact_id) relation = client.artifacts.add_relation(artifact_id, other_id, "derived_from") relations = client.artifacts.relations(artifact_id) client.artifacts.update(artifact_id, title="New title", tags=["a", "b"]) client.artifacts.delete(artifact_id) ``` `versions(artifact_id)` returns every `Version`, newest last. `add_relation(artifact_id, to_artifact_id, relation_type, *, to_version_id=None, metadata=None)` requires `relation_type` to be `derived_from`, `supersedes`, `attachment_of`, `generated_by`, or `related_to`, else `ValueError`. `relations(artifact_id)` lists relations both ways. `update(...)` patches `title`, `description`, `tags`, `metadata`, `expires_at`, `clear_expires_at` without touching the file. `delete(artifact_id)` removes an artifact. ## Async client `AsyncArtefaktum` mirrors every method on `Artefaktum` as a coroutine; `iter_all` becomes an async generator: ```python import asyncio from artefaktum import AsyncArtefaktum async def main(): async with AsyncArtefaktum() as client: a = await client.artifacts.push("report.pdf", title="Q3 churn") async for artifact in client.artifacts.iter_all(tag="churn"): print(artifact.id) asyncio.run(main()) ``` ## Errors Every failure is an `ArtefaktumError(message, code, status, request_id)` or a subclass: ```python from artefaktum import Artefaktum, NotFound, ArtefaktumError with Artefaktum() as client: try: client.artifacts.get("01a0be89-1cde-74c1-ab17-8814cc9d9141") except NotFound as e: print(e.code, e.request_id) # "artifact_not_found", "req_..." except ArtefaktumError as e: print(str(e)) # ": (request_id=)" ``` | Exception | Code(s) | Status | When | |---|---|---|---| | `NotFound` | `artifact_not_found`, `run_not_found`, `not_found` | 404 | no such artifact or run | | `Unauthorized` | `unauthorized` | 401 | bad API key | | `Forbidden` | `insufficient_scope` | 403 | key lacks scope | | `QuotaExceeded` | `quota_exceeded` | 413, 429 | 413: file/storage too large; 429: calls spent | | `RequestTooLarge` | `request_too_large` | 413 | the JSON request is over 256 KB | | `Conflict` | `artifact_not_ready`, `external_key_conflict`, `idempotency_conflict`, `run_sealed` | 409 | server-side conflict | | `ValidationFailed` | `invalid_request` | 400 | malformed request | | `UploadError` | `upload_expired`, `object_verification_failed` | 410, 422 | upload window passed, or verification failed | | `ServiceUnavailable` | `embedding_unavailable` | 503 | embeddings unavailable | | `ProcessingFailed` | `processing_failed` | n/a | wait saw status `failed`; carries `.artifact` | | `ProcessingTimeout` | `processing_timeout` | n/a | wait exceeded `timeout`; carries `.artifact` | | `IntegrityError` | `integrity_error` | n/a | `pull` sha256 mismatch; `.expected`/`.actual` | | `StorageError` | `storage_error` | n/a | storage host failed; carries `.host` | | `MissingApiKey` | n/a | n/a | raised locally, before any request | A 429 `QuotaExceeded` blocks writes and `search` until the plan resets; reads, downloads, and deletes keep working. `client.quota()` reports the plan, limits, and usage, and is never blocked: ```python q = client.quota() print(q.plan, q.storage.used_bytes, "/", q.storage.limit_bytes, q.calls.resets_at) ``` ## Retries and timeouts Reads retry automatically on HTTP 429, 502, 503, or 504, and on connection errors, up to 3 attempts, waiting 0.5s then 1s (or the server's `Retry-After`, capped at 10s): `get`, `get_by_external_key`, `list` / `iter_all`, `search`, `download_url`, `whoami`, `projects.list`, `usage.get`. `search` is a POST but has no side effects, so it retries too. A 429 coded `quota_exceeded` is the exception, raised immediately since the allowance returns only at `quota().calls.resets_at`. Writes (`push`, `update`, `add_relation`, `delete`, `keys.create`, and the rest) are never retried automatically, so a client never double-submits one; neither is the storage upload or download. The `timeout` constructor argument (default `30.0`) sets the HTTP timeout on both the API and storage clients. The separate `timeout=` on `push`, `create_version`, and `fulfil` controls only how long the ready-poll waits, independent of the HTTP timeout. Source: https://artefaktum.dev/docs/python/ --- # TypeScript SDK > Install, configure and use the artefaktum npm package: push, pull, search and reuse artifacts by key ## Install ```sh npm install artefaktum ``` Zero runtime dependencies, Node 20+, ESM and CommonJS builds. Types are generated from the API's own OpenAPI document, so a server-side rename is a compile error, not a runtime surprise. ```ts import { Artefaktum } from "artefaktum"; // CommonJS: const { Artefaktum } = require("artefaktum"); ``` ## Configure Create an API key in the [console](/console/). | Option | Environment | Default | |---|---|---| | `apiKey` | `ARTEFAKTUM_API_KEY` | required; throws `MissingApiKeyError` if missing | | `baseUrl` | `ARTEFAKTUM_BASE_URL` | `https://api.artefaktum.dev` | | `project` | `ARTEFAKTUM_PROJECT` | `"default"` | | `timeoutMs` | none | `30000` per API call; storage transfers have no timeout | | `fetch` | none | `globalThis.fetch` | `project` accepts a UUID or slug; a slug is resolved once and cached. Every project-scoped method also takes `project` to override it for one call. Methods are camelCase; fields are snake_case, spelled as the REST API, MCP tools and Python SDK spell them (`external_key`, `latest_version.size_bytes`, `stale_upstream`). Timestamps accept an ISO 8601 string or a `Date`; durations name their unit (`timeoutMs`, `max_age_seconds`). ## Example ```ts import { Artefaktum } from "artefaktum"; const client = new Artefaktum(); // reads 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"); for (const hit of page.items) console.log(hit.score, hit.artifact.title); await client.artifacts.pull(artifact.id, "out/"); // → out/report.pdf, sha256-verified ``` ## Uploading `push(source, options)` hashes the source, reserves an upload, PUTs the bytes directly to object storage (your API key never reaches that host), completes it, and by default waits until the artifact is `ready`. ```ts await client.artifacts.push("data/export.parquet", { title: "Export" }); // path (Node): streamed await client.artifacts.push(bytes, { title: "Export", filename: "export.json" }); // Uint8Array | ArrayBuffer | Blob ``` `source` is a file path (Node only) or bytes. Bytes need `filename` unless the `Blob` is a named `File`; `content_type` defaults to the Blob's type, else it's guessed from the name. | Option | Meaning | |---|---| | `title` | Required. What the artifact is. | | `description`, `tags`, `metadata` | Description, tag list, arbitrary JSON metadata. | | `external_key` | Your own unique key for this artifact within the project. | | `if_exists` | What a repeated `external_key` does: `"error"` (default), `"version"` or `"reuse"`. | | `max_age_seconds` | With `"reuse"` only: an older artifact counts as missing. | | `expires_at` | ISO string or `Date`; the artifact is deleted after this time. | | `run`, `infer_lineage` | Link to a run id; `infer_lineage` (default `true`) links what the run read. | | `wait`, `timeout_ms`, `signal` | Wait for `ready` (default `true`, 30 000 ms); `signal` cancels the transfer. | Field sizes are limited; see [Limits](/docs/rest/#limits). Storage transfers have no timeout of their own, since a total timeout would kill a large upload. Pass `signal` for a bound, e.g. `AbortSignal.timeout(10 * 60_000)`. A failed PUT throws `StorageError` and leaves the artifact `pending_upload`, never `ready` and invisible to `search`, so it is safe to retry. With `wait: true`, a processing failure throws `ProcessingFailedError` or `ProcessingTimeoutError`, both carrying `.artifact`; on `ProcessingTimeoutError` it is `Artifact | undefined` (a reuse that gave up waiting has none yet), on `ProcessingFailedError` it is always set. `push` returns a `PushedArtifact`, an `Artifact` with `reused`. `createVersion(artifact_id, source, options)` adds a version through the same flow (`run`, `infer_lineage`, `content_type`, `filename`, plus the wait options). ### Reuse or replace by key ```ts // Reuse: an artifact under this key younger than an hour is returned, nothing is uploaded. const a = await client.artifacts.push(body, { title: "Vilnius weather", filename: "weather.json", external_key: "openweather/vilnius", if_exists: "reuse", max_age_seconds: 3600, }); console.log(a.reused); // true when an existing artifact came back (set by the SDK, not the API) // Replace: add a version to the artifact holding the key, or create it when the key is new. await client.artifacts.push(body, { title: "Vilnius weather", filename: "weather.json", external_key: "openweather/vilnius", if_exists: "version", }); // Read it back by key; an artifact older than max_age_seconds is NotFoundError. await client.artifacts.pullByKey("openweather/vilnius", "out/", { max_age_seconds: 3600 }); ``` `if_exists` is `"error"` (the default: an existing key is a `ConflictError`), `"version"` or `"reuse"`; both of the latter need `external_key`, and `max_age_seconds` only applies to `"reuse"` (a `TypeError` otherwise, before any request). With `"reuse"`, a `push` that finds another producer already making the artifact waits up to `timeout_ms`, then throws `ProcessingTimeoutError`; `expires_at` is applied whenever this call stored bytes (never on a hit), and `infer_lineage` is not sent on this path. With `"version"`, the `title` (if it differs), `description`, `tags`, `metadata` and `expires_at` you pass are applied to the existing artifact after the new version lands. `resolve` and `fulfil` remain as low-level calls for callers who manage the reservation and upload themselves. `resolve(external_key, options)` returns a status of `"hit"`, `"create"` (call `fulfil` with the resolution and the bytes) or `"pending"`; `fulfil` throws `TypeError` unless the status is `"create"`. ## Downloading ```ts const path = await client.artifacts.pull(id, "out/"); // Node: streams to disk, verifies sha256 const { data, filename } = await client.artifacts.pullBytes(id); // any runtime: verified bytes in memory await client.artifacts.pullByKey("reports/q3-churn", "out/"); // by key, optional { project, max_age_seconds } const bytes = await client.artifacts.pullBytesByKey("reports/q3-churn"); ``` `pull` is Node-only; `dest` is a directory when it exists as one or ends with a separator (then created), otherwise the file to write. `pullBytes` works on any runtime, returning `{ data, filename, content_type, version_id, sha256 }`. Both take `{ verify?, signal? }`; `verify` defaults to `true` and a mismatch throws `IntegrityError`, leaving no file behind. `downloadUrl(artifact_id, { version_id?, run? })` returns the signed URL directly. ## Finding ```ts await client.artifacts.search("emission factors", { mode: "hybrid", tags_all: ["ghg"] }); await client.artifacts.getByExternalKey("reports/q3-churn", { max_age_seconds: 3600 }); for await (const a of client.artifacts.iterAll({ tag: "churn" })) console.log(a.title); ``` | Method | Purpose | |---|---| | `search(query, options)` | Ranked results. `mode`: `"hybrid"` (default), `"semantic"`, `"text"`, `"exact"`. Also `content_types`, `tags_all`, `status`, `external_key`, `created_after`/`before`, `exclude_superseded`, `limit` (20), `cursor`, `project`. Returns `{ items: [{ score, artifact }], next_cursor }`. | | `get(artifact_id)` | Fetch one artifact by id. | | `getByExternalKey(key, { project?, max_age_seconds? })` | Fetch by external key; an artifact older than `max_age_seconds` is `NotFoundError`. | | `list(options)` | One page: `status`, `content_type`, `tag`, `external_key`, `created_before`/`after`, `expires_before`, `limit` (50), `cursor`. | | `iterAll(options)` | Async generator over every match, following `next_cursor`. | Search hides superseded artifacts by default (`exclude_superseded`); each result reports whether it is `superseded` or `stale_upstream`. ## Versions and relations ```ts await client.artifacts.versions(artifact_id); await client.artifacts.relations(artifact_id); await client.artifacts.addRelation(artifact_id, to_artifact_id, "derived_from"); ``` `versions` lists an artifact's versions; `relations` lists its relations to other artifacts. `addRelation(artifact_id, to_artifact_id, relation_type, { to_version_id?, metadata? })` requires `relation_type` to be one of `derived_from`, `supersedes`, `attachment_of`, `generated_by`, `related_to`; anything else throws `TypeError` first. `update(artifact_id, options)` patches `title`, `description`, `tags`, `metadata`, `expires_at`; only fields passed are sent, and `clear_expires_at: true` removes the expiry. `delete(artifact_id)` is accepted with 202; bytes are removed in a background job. Other namespaces: `client.projects.list()`; `client.runs.create`/`.seal`/`.artifacts` for grouping by pipeline run; `client.keys`, `client.usage` (admin scope); `client.whoami()`, `client.quota()`. ## Errors Every failure from the API, storage, or the SDK's own helpers is an `ArtefaktumError` with `code`, `message`, `status`, `request_id` (quote it in support mail). `MissingApiKeyError` extends plain `Error`. Caller mistakes the compiler can't catch in JavaScript throw `TypeError`: `fulfil` on a non-`create` resolution, an unknown `relation_type`, nameless bytes without `filename`, an invalid `baseUrl`. | Class | `code` | |---|---| | `NotFoundError` | `artifact_not_found`, `run_not_found`, `not_found`, `project_not_found` | | `UnauthorizedError` / `ForbiddenError` | `unauthorized` / `insufficient_scope` | | `QuotaExceededError` | `quota_exceeded` | | `RequestTooLargeError` | `request_too_large` | | `ConflictError` | `artifact_not_ready`, `external_key_conflict`, `idempotency_conflict`, `run_sealed` | | `ValidationError` | `invalid_request` | | `UploadError` | `upload_expired`, `object_verification_failed` | | `ServiceUnavailableError` | `embedding_unavailable` | | `ConnectionError` | `connection_error`: API unreachable after retries | | `StorageError` | `storage_error`: object storage refused or was unreachable | | `ProcessingFailedError` / `ProcessingTimeoutError` | `processing_failed` / `processing_timeout` (both carry `.artifact`) | | `IntegrityError` | `integrity_error`: downloaded bytes don't match the recorded sha256 | | `ArtefaktumError` | `version_mismatch`: the artifact gained a version mid-pull; retry | | `ArtefaktumError` | `invalid_filename`, `unsupported_runtime` (a file path on a runtime without `fs`), `http_error` (non-JSON response) | ```ts try { await client.artifacts.get(id); } catch (err) { if (err instanceof ArtefaktumError && err.code === "artifact_not_found") { /* … */ } else throw err; } ``` Prefer `err.code` to `instanceof` in libraries: a program loading both the ESM and CommonJS build sees distinct classes. Reads (every `GET`, and `search`) retry up to twice on `429`/`502`/`503`/`504` and network failures, honouring `Retry-After` up to a 10 s ceiling. Writes, storage transfers and spent quota are never retried. ## Runtimes Tested on Node 20 and 22. The core uses only `fetch` and Web Crypto, so it should also run on Bun, Deno and Cloudflare Workers. Pass bytes or a `Blob` to `push` and use `pullBytes` there, since file paths need Node's `fs`. Browsers are not supported: an API key does not belong in one. See also [Quickstart](/docs/quickstart/) and [REST](/docs/rest/). Source: https://artefaktum.dev/docs/typescript/ --- # CLI > Push, pull, and search artifacts from a terminal, a Dockerfile, or a CI step with afk ## Install ```sh pip install "artefaktum[cli]" ``` This installs `artefaktum`, and the shorter alias `afk`, both pointing at the same command. It needs Python 3.10+, same as the SDK it wraps. ## Authenticate ```sh artefaktum login # or set ARTEFAKTUM_API_KEY in CI and sandboxes ``` `login` prompts for the key at a hidden prompt (or reads it from stdin with `--api-key-stdin`), verifies it against the server, then saves it to `~/.config/artefaktum/config.json` (`$XDG_CONFIG_HOME`, or `%APPDATA%\artefaktum` on Windows), mode `0600`. The key is never taken as a positional argument, so it never lands in shell history. `logout` removes the saved config file. For every setting (the API key, `--base-url`, `--project`), precedence is: the matching flag, then the matching environment variable (`ARTEFAKTUM_API_KEY`, `ARTEFAKTUM_BASE_URL`, `ARTEFAKTUM_PROJECT`), then the saved config file. In CI and sandboxes, prefer `ARTEFAKTUM_API_KEY` over `login` (no writable home directory needed) or `--api-key` (visible in `ps` to other users on the host). `whoami` shows the tenant, and project if the key is scoped to one: ```sh artefaktum whoami ``` API keys themselves are created in the console at https://artefaktum.dev/console/. The CLI has no `keys create` (or any `keys`/`usage` command); it only consumes a key that already exists. ## Commands | Command | Purpose | |---|---| | `whoami` | show the tenant (and project) the key belongs to | | `projects` | list the tenant's projects | | `login` | verify an API key and save it | | `logout` | remove the saved API key | | `get` | show one artifact, by ID or `--key` | | `ls` | list artifacts | | `search` | search artifacts | | `push` | upload a file as a new artifact, or by key as a new version or a reuse | | `pull` | download an artifact's latest version, by ID or `--key` | | `rm` | delete an artifact | | `link` | print a short-lived signed download URL | | `relations` | list an artifact's relations | | `relate` | record a relation from one artifact to another | | `versions` | list an artifact's versions | | `run new` | create a run | | `run seal` | seal a run so no more artifacts attach to it | | `run ls` | list a run's artifacts | Global options, given before the command: `--api-key`, `--base-url`, `--project`, `--json` / `--table` (force the output format), plus `--version` and `-h`/`--help`. `artefaktum --help` and `artefaktum --help` list every command and flag. ## Command reference **`get ID`** / **`get --key KEY`**: show one artifact. Exactly one of `ID` or `--key EXTERNAL_KEY` is required. `--max-age DURATION` (with `--key`): an artifact older than this counts as not found (exit `3`). **`ls`**: list artifacts. `--tag TAG`, `--status STATUS` (repeatable), `--limit N` (default 50), `--all` (follow every page instead of one). **`search QUERY`**: `--mode hybrid|text|semantic|exact` (default `hybrid`), `--tag TAG` (repeatable, required tag), `--limit N` (default 10), `--history` (include superseded artifacts, excluded by default). **`push FILE`**: `--title` (required), `--tag` (repeatable), `--description`, `--key EXTERNAL_KEY`, `--if-exists error|version|reuse` (what to do when `--key` already exists: fail, add a version, or reuse the artifact), `--max-age DURATION` (with `--if-exists reuse`: an older artifact is replaced), `--meta K=V` (repeatable), `--expires DURATION` (e.g. `30d`), `--run RUN_ID`, `--no-wait` (return once accepted, don't wait for `ready`), `--timeout SECONDS` (default 30), `--wait SECONDS` (default 60). With `--if-exists reuse`, `--wait` is the seconds to wait on another writer, then again for the artifact to become ready; ignored otherwise. `--timeout` is ignored under `reuse`. The JSON output gains `reused` only under `--if-exists reuse`: `true` when an existing artifact came back and nothing was uploaded. Field sizes are limited; see [Limits](/docs/rest/#limits). **`pull ID [DEST]`** / **`pull --key KEY --dest PATH`**: `DEST` defaults to `.`; a trailing `/` creates it as a directory. With `--key` the destination must be given as `--dest`. `--max-age DURATION` (with `--key`): an older artifact counts as not found. `--no-verify` skips the sha256 check. **`rm ID`**: delete an artifact. No flags. **`link ID`**: print a signed download URL. `--table` mode prints exactly the URL and nothing else. **`relations ID`** / **`versions ID`**: list an artifact's relations or versions. No flags. **`relate ID TARGET`**: `--type` (`derived_from` (default), `supersedes`, `attachment_of`, `generated_by`, or `related_to`). **`run new [RUN_ID]`**: `RUN_ID` is optional; the server assigns one if omitted. **`run seal RUN_ID`** / **`run ls RUN_ID`**: `run ls` takes `--limit N` (default 50). Duration flags (`--expires`, `--max-age`) accept `90s`, `30m`, `12h`, `30d`, `2w`, or a bare integer of seconds. ## Exit codes | Code | Meaning | |---|---| | 0 | ok | | 1 | API or SDK error | | 2 | usage error | | 3 | not found | | 4 | `push --if-exists reuse` still pending when `--wait` ran out | | 130 | interrupted | ## Recipes **Dockerfile or sandbox image**: bake the CLI in and read the key from the environment at run time, never at build time. ```dockerfile RUN pip install "artefaktum[cli]" # ARTEFAKTUM_API_KEY is supplied by the container's runtime environment, not baked in ``` **GitHub Actions step:** ```yaml - run: pip install "artefaktum[cli]" - run: afk push report.pdf --title "Q3 churn" --tag churn env: ARTEFAKTUM_API_KEY: ${{ secrets.ARTEFAKTUM_API_KEY }} ``` **Push before a container is recycled**: an agent working in a sandbox or CI job that's about to be torn down should push its output as its last step, so the artifact outlives the container. ```sh afk push /tmp/output.json --title "Run output" --run "$RUN_ID" ``` **Scripting with JSON**: output is an aligned text table on a terminal and one JSON document otherwise, so a plain pipe already gets JSON. ```sh artefaktum ls | jq -r '.items[].id' # one page artefaktum ls --all | jq -r '.[].id' # every match, as a bare array ``` Pass `--json` explicitly when the command's stdout might still look like a terminal to it (for example, inside another program that captures output), rather than relying on the auto-detection. **Cache an expensive result**, reusing it for an hour: ```sh afk push report.json --title "Vendor X report" --key vendor-x/report --if-exists reuse --max-age 1h --wait 60 ``` **Latest wins**: each run adds a version under one key, and a reader pulls the newest: ```sh afk push report.json --title "Sales report" --key report:sales --if-exists version afk pull --key report:sales --dest out/ ``` Source: https://artefaktum.dev/docs/cli/ --- # n8n node > Use the Artefaktum community node in n8n to upload, cache, find and manage artifacts This page describes node version 0.3.0. It has five operations (Upload, Get, Search, Update, Delete), one optional Key on Upload, and a Project that is already filled in. Workflows saved with 0.2.0 must be rebuilt, see [What changed](#what-changed-in-030). ## Install The node is verified by n8n ([listing](https://n8n.io/integrations/artefaktum/)), so it installs on n8n Cloud and self-hosted n8n alike. In the editor, click **+** to open the Nodes panel, search for **Artefaktum**, pick the version with the verified badge and install it. Verified nodes need an instance owner to install them once; after that everyone on the instance can use them. On self-hosted n8n you can also install it by package name under **Settings → Community Nodes**, or: ```sh npm install n8n-nodes-artefaktum ``` This adds node **Artefaktum** and credential **Artefaktum API**. ## Credentials Mint a key in the [console](/console/?ref=n8n) and paste it into the credential's **API Key** field. Grant only the scopes needed: `read`, `write`, `search`, `delete` (only if deleting). Update and Delete read the artifact first, so their key needs `read` as well as `write` or `delete`. **Base URL** defaults to `https://api.artefaktum.dev`; change only for self-hosting. ## Operations **Operation** is the first field; there is no resource picker. | Operation | Purpose | |---|---| | Upload | Store a file or text as a new artifact, or as a new version of the artifact under a key. | | Get | Fetch one artifact: its details, its file, or its text. | | Search | Find artifacts by meaning, keywords, tags and filters. | | Update | Change title, description, tags, metadata or expiry. | | Delete | Delete an artifact. | The **Project** field's "From List" mode lists your account's projects; every account also has slug `default`, which is the default. ## Lookup: by ID or by Key Get, Update and Delete share one lookup block. | Parameter | Notes | |---|---| | Lookup | By ID (default) or By Key. | | Artifact ID | Lookup = By ID. | | Key | Lookup = By Key. | | Project | Resolves the key (By Key). | | Max Age (Seconds) | Get only, By Key: an artifact last updated longer ago than this counts as not found. `0` accepts any age. | | If Not Found | Get only, By Key: Stop With Error (default) or Return `found: false`. | On Update and Delete a missing artifact is always an error. ## Upload | Parameter | Notes | |---|---| | Project | The owning project. Defaults to `default`. | | Input Data Source | Binary File or Text. | | Input Binary Field | Binary property holding the file. | | Content | Text to store (text source). | | Title | Searched by agents; defaults to the file name. | | Key | Optional. Your own unique key within the project, e.g. `report:sales:2026-10-24` or a URL. | | If Key Exists | Shown once Key is set: Stop With Error (default), Add New Version, or Reuse Existing. | | Max Age (Seconds) | With Reuse Existing: reuse only if younger. `0` accepts any age. | | Options → Description | Searched semantically. | | Options → Tags | Comma-separated. | | Options → Metadata (JSON) | Filterable structured metadata. | | Options → Expires In (Hours) | Auto-delete after N hours; `0` keeps it. | | Options → File Name | Defaults to the binary name, or a generated name. | | Options → Content Type | Defaults to the binary type, or `text/plain`. | Without a Key, or with Stop With Error, Upload creates a new artifact and fails if the key is taken. Add New Version stores the file as a new version of the artifact under that key (creating it if there is none), so the key always points at the latest. Reuse Existing returns the stored artifact without uploading when one exists under the key and is fresh enough (`cache: "hit"`); otherwise it uploads and returns the new one (`cache: "created"`). Field sizes are limited; see [Limits](/docs/rest/#limits). Upload returns the artifact with `status: "processing"` for a few seconds while search metadata is derived; Search only finds it once `ready`. ## Get | Parameter | Notes | |---|---| | Lookup block | See above. | | Output | Binary File (default), Text, or Details Only. Choose Text when an AI agent needs to read the file: agents cannot see binary files. | | Options → Put Output File in Field | Target binary property (Binary File). | | Options → File Name | Override the output name (Binary File). | | Options → Max Characters | Cut the content after this many characters (Text; default 50,000; `0` returns everything). | | Options → Verify Checksum | Compare bytes to the stored SHA-256 (Binary File, Text). | | Options → Version ID | Defaults to latest. | | Options → Simplify | Simplified vs. raw response; on by default, in every output mode. | Text reads files of at most 25 MB and refuses larger or non-text ones before downloading anything. Output adds: - By Key lookup: `found: true`. - A miss (or too old) with Return `found: false`: `{ "found": false, "key": ..., "project_id": ..., "reason": ... }` and no binary file. - Text: `content`, `content_truncated`, `content_characters` and `content_version_id`, the version actually read. ## Search | Parameter | Notes | |---|---| | Project | Project to search. Defaults to `default`. | | Query | Free text; empty lists by filters. | | Return All | Vs. a fixed Limit. | | Limit | Max results. | | Filters → Content Types | Comma-separated MIME types. | | Filters → Created After / Before | Date range. | | Filters → Include Superseded | Include superseded artifacts. | | Filters → Tags (All Of) | Comma-separated; every tag must match. | | Options → Search Mode | Hybrid (default), Semantic or Text. | | Options → Simplify | Simplified vs. raw response; on by default. | No sort option: the API ranks results itself. ## Update | Parameter | Notes | |---|---| | Lookup block | Find the artifact By ID or By Key. | | Update Fields → Title, Description, Tags, Metadata (JSON) | Leave blank to keep unchanged; clearing back to empty isn't supported yet. | | Update Fields → Expires At | Set a new expiry. | | Update Fields → Clear Expiry | Remove the expiry. | ## Delete Takes the lookup block only (By ID or By Key). ## Patterns Three chains cover most uses. None needs an error-handling trick. **Stop paying twice for the same API call.** Skip the step when today's result is already stored. Manual Trigger → **Get** (Lookup = By Key, Key `weather:vilnius:2026-10-24`, Max Age `3600`, If Not Found = Return `found: false`, Output = Text) → **IF** `found` → true: use `content`; false: the expensive step (an HTTP Request, an LLM call) → **Upload** (same Key, If Key Exists = Add New Version). Add New Version matters because a stale copy still holds the key: the new result becomes its latest version instead of failing as a duplicate. The key isn't workflow-scoped, so other workflows using it share the cache. A worked example ships as [`examples/templates/cache-expensive-step.json`](https://github.com/artefaktum-dev/n8n-nodes-artefaktum/blob/main/examples/templates/cache-expensive-step.json) in the repo. **Share a file between two workflows.** Build report → **Upload** (Key `report:sales`, If Key Exists = Add New Version). Consumers read it with **Get** (Lookup = By Key, Key `report:sales`). **Skip items you've already processed.** **Upload** (Key = the item's URL, If Key Exists = Reuse Existing) → **IF** `cache` equals `created` → do the work. ## Letting an AI agent read an artifact n8n does not pass binary files to AI agents, so a **Get** with the default output shows the agent only metadata. Give the agent two Artefaktum tools: **Search** (let the model fill Query) and **Get** with Output = Text (let the model fill Artifact ID from the results). Only UTF-8 text is decoded, and long files are cut at Max Characters, which keeps a large file out of the model's context. ## What changed in 0.3.0 - The Resource picker and Project → Get Many are gone (the Project field's From List still lists projects). - Get or Upload is now Upload with If Key Exists = Reuse Existing. - Download is now Get with Output = Binary File or Text. Get's default Output is Binary File; use Details Only for the old behaviour. - Get Many is now Search. External Key is now Key. File Name and Content Type moved into Upload Options, Search Mode into Search Options. - Simplify moved into Options and also applies to the JSON half of Binary File and Text output. ## Limits Per-plan quotas apply (storage, rate, artifact count; see [pricing](/pricing/)), plus a per-file limit: 100 MB on Free, 5 GB on Pro. An exceeded quota returns `quota_exceeded`. The node's memory use is the tighter constraint on small instances: it buffers each file fully, roughly 2-3x its size per item. Keep files to tens of MB and avoid large batches under limited memory. ## Compatibility Requires n8n 1.0+. Tested against `n8nio/n8n:latest` (September 2026) and Node.js 20, 22, 24. No runtime dependencies. See also the [TypeScript SDK](/docs/typescript/), the [REST API](/docs/rest/), and the [full README](https://github.com/artefaktum-dev/n8n-nodes-artefaktum). Source: https://artefaktum.dev/docs/n8n/