{"uid":"cap_QXPi--x6CWz01iTs5lh3Z","slug":"artefaktum-lookup-artifact-by-external-key-0130e433","name":"Artefaktum - Lookup Artifact by External Key","description":"Look up an artifact by the external_key it was stored under (your own name for it, slashes allowed), in one of the wallet's projects. max_age_seconds turns an artifact older than that into a 404, for caching. Returns the artifact. Costs $0.005 in USDC. No signup: a wallet's first payment creates its account and a default project; the same wallet later reaches the same files.","url":"https://api.artefaktum.dev/v1/artifacts/by-external-key/smoke%2F20261031225256?utm_source=zero.xyz","method":"GET","headers":{},"bodySchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["input"],"properties":{"input":{"type":"object","required":["type","method","pathParams"],"properties":{"type":{"type":"string","const":"http"},"method":{"enum":["GET"],"type":"string"},"pathParams":{"type":"object","required":["external_key"],"properties":{"external_key":{"type":"string"}},"additionalProperties":false},"queryParams":{"type":"object","required":["project_id"],"properties":{"project_id":{"type":"string"},"max_age_seconds":{"type":"string"}}}},"additionalProperties":false},"output":{"type":"object","required":["type"],"properties":{"type":{"type":"string","const":"json"},"example":{"type":"object"}}}}},"responseSchema":null,"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.005","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.005/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.005","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.005","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm__0ml__nzjj8yEWe6h56KV","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.005","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Retrieves an artifact's metadata by its user-defined external key within a wallet's project, with optional freshness enforcement via max_age_seconds.","exampleAgentPrompt":"Fetch the artifact stored under the external key 'smoke/20261031225256' in my Artefaktum project — only return it if it was updated within the last 3600 seconds.","exampleUseCases":[{"title":"CI pipeline artifact cache check","prompt":"Retrieve the build artifact I stored under the key 'builds/main/2026-10-31' in Artefaktum — only give it to me if it's no more than 86400 seconds old, otherwise I need to know it's expired."},{"title":"Agent retrieving its own saved state","prompt":"Pull the artifact I stored under the key 'agent-state/session-42' in my default Artefaktum project so I can resume where I left off."},{"title":"Cross-service artifact reference resolution","prompt":"I need to look up the artifact filed under 'reports/quarterly/Q3-2026' in Artefaktum — my project ID is proj_abc123 — and get its title, tags, and latest version info."}],"resultDescription":"Returns an artifact object containing title, description, tags, metadata, status, expiry date, and latest version details (filename, content type, size, sha256). Returns a 404 if no artifact exists for the given external key, or if the artifact is older than max_age_seconds when that parameter is supplied.","failureModes":["404 Not Found: no artifact stored under the given external_key in the specified project","404 Not Found: artifact exists but is older than max_age_seconds","402 Payment Required: wallet has insufficient USDC balance to cover $0.005 call fee","400 Bad Request: missing required project_id query parameter","403 Forbidden: wallet does not own the project referenced by project_id","500 Internal Server Error: upstream storage failure"],"whenToPreferThis":"Use this endpoint when you already know the user-defined external key under which an artifact was stored (e.g. a slash-separated path like 'smoke/20261031225256') and want to avoid storing or tracking internal artifact IDs. Prefer this over the by-ID endpoint when your workflow manages artifacts by human-readable or system-generated keys. The max_age_seconds parameter makes it ideal for cache-busting scenarios where stale artifacts should be treated as missing.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-11-01T06:49:58.133Z","isFirstParty":false,"canonicalSlug":"artefaktum-lookup-artifact-by-external-key-0130e433"}