Logo SuperArchive
FAQ API Docs Sign In

Developer API Reference

SuperArchive is the permanent knowledge layer for AI: archive files and URLs permanently on Arweave, and let anyone independently verify them forever. Official developer guidelines and schemas below.

📄 Prefer a machine-readable spec? Full OpenAPI 3.1 definition for every endpoint below, importable into Postman, Swagger UI, or any code generator. View openapi.json ↗
📥 Archiving
POST /api/v1/SuperArchive

Upload and archive a file permanently onto the Arweave blockchain. Supports three distinct encryption schemes (A, B, and C) depending on request parameters and headers. Every archive returns permanent proof information (content hash, transaction ID, timestamp) that can be independently verified forever via /api/v1/verify/{archive_id}.

HTTP Headers
Header Name Type Necessity Description
Authorization String Required Credentials prefix. Must be formatted as: Bearer sa_live_YOUR_API_KEY
X-Encryption-Key String Optional User-Managed symmetric AES-256-GCM passphrase (Option B). Discarded immediately after encryption.
Multipart Form Parameters
Param Name Type Necessity Description
file Binary Required Raw file stream bytes to be archived permanently.
enable_server_encryption Boolean Optional If set to true, applies Server-Managed encryption (Option C). Defaults to false.
custom_tags_json String Optional Custom on-chain metadata tags as a stringified JSON dict, e.g. {"Project": "Phoenix"}.
title String Optional AI-ready metadata: human-readable title. Defaults to the original filename if omitted.
description String Optional AI-ready metadata: short description/summary of the content.
source_url String Optional AI-ready metadata: original source URL the content was captured from, if any.
language String Optional AI-ready metadata: ISO 639-1 language code, e.g. en.
tags_json String Optional AI-ready metadata: JSON array of topical tags, e.g. ["research","AI"].
Code Example (Python)
import requests

url = "https://api.sarchive.saltycat.tw/api/v1/SuperArchive"
headers = {
    "Authorization": "Bearer sa_live_YOUR_API_KEY"
}
files = {
    "file": ("contract.pdf", open("contract.pdf", "rb"), "application/pdf")
}
data = {
    "enable_server_encryption": "true",  # Trigger Server-Managed Option C
    "custom_tags_json": '{"Project": "Phoenix", "Confidential": "true"}',
    "title": "Q3 Vendor Contract",
    "tags_json": '["legal", "contract"]'
}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())
Example Response
{
  "success": true,
  "archive_id": "PRG-nUoKkh-tumHe2pyJSTnrfaAuiWHsanZd7XUDOH4",
  "arweave_tx_id": "PRG-nUoKkh-tumHe2pyJSTnrfaAuiWHsanZd7XUDOH4",
  "arweave_url": "https://arweave.net/PRG-nUoKkh-tumHe2pyJSTnrfaAuiWHsanZd7XUDOH4",
  "sha256": "5ef8433ee79975c72679dd441eb042f114ad4e6664f1efd8ebfb510a6b4de74c",
  "file_size": 123456,
  "content_type": "application/pdf",
  "created_at": "2026-07-14T10:00:00Z",
  "status": "permanent",
  "metadata": {
    "title": "Q3 Vendor Contract",
    "description": null,
    "source_url": null,
    "language": null,
    "content_type": "application/pdf",
    "tags": ["legal", "contract"],
    "created_at": "2026-07-14T10:00:00Z"
  },
  "tx_id": "PRG-nUoKkh-tumHe2pyJSTnrfaAuiWHsanZd7XUDOH4",
  "filename": "contract.pdf",
  "filesize": 123456,
  "points_deducted": 0,
  "upload_method": "turbo"
}
POST /api/v1/archive/url

Archives a live webpage permanently: downloads an HTML snapshot, extracts structured metadata (title, description, language), computes a SHA-256 fingerprint, and uploads it to Arweave — turning any URL into a permanent, verifiable knowledge asset. Ideal for research citations, web evidence, and RAG/AI knowledge sources.

HTTP Headers
Header Name Type Necessity Description
Authorization String Required Credentials prefix. Must be formatted as: Bearer sa_live_YOUR_API_KEY
Content-Type String Required Must be application/json.
JSON Body Parameters
Param Name Type Necessity Description
url String Required The absolute http(s):// URL of the webpage to snapshot and archive.
tags Array<String> Optional AI-ready metadata: topical tags, e.g. ["research", "AI"].
For security, URLs that resolve to private, loopback, or link-local network addresses are rejected (SSRF protection), and redirects are re-validated at every hop. The maximum snapshot size is 20MB.
Code Example (Python)
import requests

url = "https://api.sarchive.saltycat.tw/api/v1/archive/url"
headers = {
    "Authorization": "Bearer sa_live_YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "url": "https://example.com/article",
    "tags": ["research", "AI"]
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())
Example Response
{
  "url": "https://example.com/article",
  "archive_id": "5QVqnCuXKr5wG-E7AsCDiyKuHuZ3EN_cKK9sXkscHho",
  "arweave_tx_id": "5QVqnCuXKr5wG-E7AsCDiyKuHuZ3EN_cKK9sXkscHho",
  "sha256": "ff67a9d764d6a2367a187734e697f6a53217db9a21c101d410a113ca871a299d",
  "title": "Example Article Title",
  "success": true,
  "resolved_url": "https://example.com/article",
  "arweave_url": "https://arweave.net/5QVqnCuXKr5wG-E7AsCDiyKuHuZ3EN_cKK9sXkscHho",
  "file_size": 45210,
  "content_type": "text/html",
  "created_at": "2026-07-14T10:00:00Z",
  "status": "permanent",
  "points_deducted": 0,
  "upload_method": "turbo",
  "metadata": {
    "title": "Example Article Title",
    "description": "A short summary extracted from the page's meta description.",
    "source_url": "https://example.com/article",
    "language": "en",
    "content_type": "text/html",
    "tags": ["research", "AI"],
    "created_at": "2026-07-14T10:00:00Z"
  }
}
🔍 Retrieval & Verification
GET /api/v1/SuperArchive/download/{tx_id}

Retrieves and streams file bytes directly from decentralized Arweave gateways. Supports automated on-the-fly decryption for server-managed files, or user-managed key decrypts.

HTTP Headers
Header Name Type Necessity Description
X-Encryption-Key String Optional Symmetric AES-256-GCM key. Required only for User-Managed encrypted files (Option B).
Code Example (cURL)
# Direct download & stream decrypt for Option B (User-Managed)
curl -X GET "https://api.sarchive.saltycat.tw/api/v1/SuperArchive/download/TX_ID_HERE" \
  -H "X-Encryption-Key: your_secure_passphrase" \
  --output "decrypted_file.pdf"
GET /api/v1/verify/{archive_id} Public · No Auth Required

Allows anyone — not just the uploader — to independently verify that archived content is authentic and unchanged. This endpoint re-fetches the content directly from the Arweave network and recomputes its SHA-256 hash on every call; it never simply trusts the database. verified: true is only ever returned when the database record exists, the on-chain data is retrievable, the recomputed hash matches, and an archive timestamp exists.

Code Example (cURL)
curl -X GET "https://api.sarchive.saltycat.tw/api/v1/verify/TX_ID_HERE"
Example Response
{
  "verified": true,
  "archive_id": "PRG-nUoKkh-tumHe2pyJSTnrfaAuiWHsanZd7XUDOH4",
  "arweave_tx_id": "PRG-nUoKkh-tumHe2pyJSTnrfaAuiWHsanZd7XUDOH4",
  "arweave_url": "https://arweave.net/PRG-nUoKkh-tumHe2pyJSTnrfaAuiWHsanZd7XUDOH4",
  "sha256": "5ef8433ee79975c72679dd441eb042f114ad4e6664f1efd8ebfb510a6b4de74c",
  "sha256_match": true,
  "archive_timestamp": "2026-07-14T10:00:00Z",
  "status": "permanent",
  "filename": "contract.pdf",
  "content_type": "application/pdf",
  "file_size": 123456,
  "metadata": { "title": "Q3 Vendor Contract", "tags": ["legal", "contract"], "...": "..." },
  "checks": {
    "record_exists": true,
    "arweave_data_retrievable": true,
    "content_hash_match": true,
    "timestamp_exists": true
  }
}
status may also be pending (submitted but not yet mined/propagated — typically resolves within ~10-20 minutes) or mismatch (the on-chain content no longer matches the recorded hash).
GET /api/v1/archive/{archive_id} Public · No Auth Required

Returns the permanent proof information together with the structured, AI-ready metadata recorded for an archive (title, description, source URL, language, tags). This is metadata-only — no summarization, embeddings, or LLM processing is performed.

Code Example (cURL)
curl -X GET "https://api.sarchive.saltycat.tw/api/v1/archive/TX_ID_HERE"
Example Response
{
  "archive_id": "PRG-nUoKkh-tumHe2pyJSTnrfaAuiWHsanZd7XUDOH4",
  "arweave_tx_id": "PRG-nUoKkh-tumHe2pyJSTnrfaAuiWHsanZd7XUDOH4",
  "arweave_url": "https://arweave.net/PRG-nUoKkh-tumHe2pyJSTnrfaAuiWHsanZd7XUDOH4",
  "sha256": "5ef8433ee79975c72679dd441eb042f114ad4e6664f1efd8ebfb510a6b4de74c",
  "file_size": 123456,
  "content_type": "application/pdf",
  "created_at": "2026-07-14T10:00:00Z",
  "status": "permanent",
  "metadata": {
    "title": "Q3 Vendor Contract",
    "description": null,
    "source_url": null,
    "language": null,
    "content_type": "application/pdf",
    "tags": ["legal", "contract"],
    "created_at": "2026-07-14T10:00:00Z"
  }
}
GET /api/v1/archive/{archive_id}/markdown Reserved · Coming Soon
GET /api/v1/archive/{archive_id}/summary Reserved · Coming Soon
GET /api/v1/archive/{archive_id}/entities Reserved · Coming Soon

These paths are reserved for upcoming AI-derived views of archived content — clean Markdown conversion, AI-generated summaries, and named-entity extraction — so the API surface is stable for integrators building ahead of time. They currently return 501 Not Implemented (or 404 if the archive_id itself doesn't exist).

Example Response (501)
{
  "detail": "AI summarization is not implemented yet. This endpoint is reserved for future AI-ready content processing."
}
🔑 Account & Key Management
GET /api/v1/developer/points

Query the remaining unspent S-Points balance in the ledger linked to your developer account.

Code Example (Python)
import requests

url = "https://api.sarchive.saltycat.tw/api/v1/developer/points"
headers = {"Authorization": "Bearer sa_live_YOUR_API_KEY"}

response = requests.get(url, headers=headers)
print(response.json()) # Output: {"email": "user@gmail.com", "remaining_s_points": 405, "status": "active"}
GET /api/v1/developer/files

Query a comprehensive registry list of all permanent files uploaded by this user, including archive_id, sha256, original sizes, metadata tags, encryption status, and transaction timestamps.

Code Example (cURL)
curl -X GET "https://api.sarchive.saltycat.tw/api/v1/developer/files" \
  -H "Authorization: Bearer sa_live_YOUR_API_KEY"
GET /api/v1/developer/keys

Query all non-deleted developer API keys belonging to your account alongside their active status, preview strings, last-used telemetry, and the cumulative S-Point spending attributed to each specific key.

Code Example (Python)
import requests

url = "https://api.sarchive.saltycat.tw/api/v1/developer/keys"
headers = {"Authorization": "Bearer sa_live_YOUR_API_KEY"}

response = requests.get(url, headers=headers)
print(response.json())
GET /api/v1/developer/files/{tx_id}/key

Query and retrieve the secure server-managed AES-256-GCM decryption key and salt (Option C) for a given transaction ID. Enforces ownership: only the uploader can request their files keys.

Code Example (cURL)
curl -X GET "https://api.sarchive.saltycat.tw/api/v1/developer/files/TX_ID_HERE/key" \
  -H "Authorization: Bearer sa_live_YOUR_API_KEY"