---
title: "Register a pointer artifact or upload a managed artifact."
method: POST
path: "/v1/storage/artifacts"
tags: ["Storage"]
---

# Register a pointer artifact or upload a managed artifact.

`POST /v1/storage/artifacts`

Pointer mode sends a JSON body with `mode: "pointer"` plus a caller-supplied `uri`; the server stores the reference but NEVER fetches the URI. Managed mode sends the raw bytes with `?mode=managed[&disclose_content_hash=true]` and an optional `X-AtomicMemory-Metadata` base64-JSON header. Filecoin direct managed uploads return 501 in v1.

## Request body

- union — Discriminated union over put-artifact mode.
  - object — Pointer-mode artifact registration body. The server stores the URI as a reference; it NEVER fetches the URI itself.
    - `content_hash` string
    - `content_type` string, required
    - `metadata` object — Caller-supplied metadata. Decoded JSON must be ≤4 KiB; encoded header value must be ≤8 KiB when sent via `X-AtomicMemory-Metadata`.
    - `mode` 'pointer', required
    - `size_bytes` integer
    - `uri` string, required
  - object — Managed-mode marker. The route uses query params for the managed-mode contract; the body is raw bytes, not JSON. Included in the discriminated union so a managed-mode JSON body (caller mistake) parses cleanly and is rejected at the route layer.
    - `mode` 'managed', required

## Response `201`

Artifact created.

- object — Public metadata projection of a `storage_artifacts` row. `content_hash` is the plaintext SHA-256 of caller bytes; the internal `stored_hash` column is NEVER surfaced on the wire.
  - `artifact_id` string, uuid, required
  - `content_encoding` 'identity' | 'aes_gcm', required
  - `content_hash` string
  - `content_type` string, nullable, required
  - `created_at` string, required
  - `identifiers` object, required — Provider-native identifiers (CID, etc.); allowlisted per provider.
  - `lifecycle` object, required — Provider-agnostic summary of availability + delete-semantics. Both fields are optional so a row whose lifecycle is not yet known to the API surface validates cleanly.
    - `availability` 'immediate' | 'delayed' | 'scheduled' | 'best_effort' — Coarse availability category for the backend.
    - `deleteSemantics` 'delete' | 'unpin' | 'tombstone' | 'provider_retained' — What the backend does on delete. `delete` issues provider removal; `unpin` removes the AtomicMemory reference only; `tombstone` stops managing without provider removal (typical for decentralized providers); `provider_retained` is reserved.
  - `metadata` object, required — Caller-supplied metadata. Decoded JSON must be ≤4 KiB; encoded header value must be ≤8 KiB when sent via `X-AtomicMemory-Metadata`.
  - `mode` 'pointer' | 'managed', required
  - `provider` string, required
  - `provider_details` object — Allowlisted provider-specific public state.
  - `replication` object — Optional replication state for eventual storage providers.
    - `confirmedCopies` integer
    - `desiredCopies` integer
  - `retrieval` object — Optional retrieval-readiness state.
    - `lastCheckedAt` string
    - `status` 'not_checked' | 'retrievable' | 'not_retrievable' | 'unsupported'
  - `size_bytes` integer, nullable, required
  - `status` 'stored' | 'pending' | 'available' | 'unavailable' | 'deleting' | 'deleted' | 'delete_failed' | 'failed', required
  - `updated_at` string, required
  - `uri` string, nullable, required
  - `verification` object — Optional verification state (provider proofs).
    - `lastVerifiedAt` string
    - `providerProofStatus` 'pending' | 'verified' | 'failed' | 'unsupported'

## Other responses

- `400` — Input validation error
- `411` — Content-Length is required for managed uploads.
- `413` — Managed upload body exceeds the configured cap.
- `500` — Internal server error
- `501` — Direct Filecoin managed upload is not supported in v1.
- `503` — Managed storage is disabled for this deployment.

---

[API](https://skmtc.dev/atomicstrata/apis/atomicmemory-http-api.md) · [All operations](https://skmtc.dev/atomicstrata/apis/atomicmemory-http-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/atomicstrata/atomicmemory-http-api/revisions/d501daa39bb2/schema)