PureStamp API Quickstart

Overview

PureStamp’s API secures your content with tamper-evident provenance. Follow these steps: ① Get a pre-signed S3 upload URL, ② Upload your file, ③ Issue or verify a stamp.

POST /upload-url

Generate a pre-signed URL for secure S3 uploads.

POST /purestamp/issue

Add a cryptographic stamp to your file, returning a watermarked URL.

POST /purestamp/verify

Validate provenance and signature for any file or text.

API Endpoints

POST /upload-url

Auth: x-api-key

Request: { "filename": string, "contentType": string }
Response: { "uploadUrl": string, "s3Uri": string, "contentType": string }

curl -X POST "$BASE/upload-url" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename":"sample.pdf","contentType":"application/pdf"}'

POST /purestamp/issue

Auth: x-api-key

Request: { "s3_uri": string, "mime_type": string, "who": "Human | AI | Unknown", "model"?: string }
Response: { "download_url": string, "receipt_id": string }

curl -X POST "$BASE/purestamp/issue" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "s3_uri": "s3://bucket/key.pdf",
    "mime_type": "application/pdf",
    "who": "AI",
    "model": "PureVector"
  }'

POST /purestamp/verify

Auth: x-api-key

Request: { "s3_uri": string, "mime_type": string }
Response: { "status": "trusted | untrusted", "who": string, "model"?: string, "signature_valid": boolean, "receipt_id"?: string }

curl -X POST "$BASE/purestamp/verify" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "s3_uri": "s3://bucket/key.pdf",
    "mime_type": "application/pdf"
  }'

Code Examples

Try these examples with your API credentials. Update the hero inputs to customize.

export BASE="https://qer7w7y40c.execute-api.us-east-1.amazonaws.com/prod"
export API_KEY="<YOUR_API_KEY>"

# Get pre-signed URL
curl -X POST "$BASE/upload-url" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename":"file.pdf","contentType":"application/pdf"}'

# Upload file (use uploadUrl from response)
# curl -X PUT "" -H "Content-Type: application/pdf" --data-binary @file.pdf

# Issue stamp
curl -X POST "$BASE/purestamp/issue" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"s3_uri":"s3://bucket/key.pdf","mime_type":"application/pdf","who":"AI","model":"PureVector"}'

# Verify content
curl -X POST "$BASE/purestamp/verify" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"s3_uri":"s3://bucket/key.pdf","mime_type":"application/pdf"}'

const BASE = "https://qer7w7y40c.execute-api.us-east-1.amazonaws.com/prod";
const KEY = "<YOUR_API_KEY>";

async function presign(filename, type) {
  const response = await fetch(`${BASE}/upload-url`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'x-api-key': KEY },
    body: JSON.stringify({ filename, contentType: type })
  });
  return response.json();
}

async function issue(s3Uri, mime, who = 'AI', model = 'PureVector') {
  const response = await fetch(`${BASE}/purestamp/issue`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'x-api-key': KEY },
    body: JSON.stringify({ s3_uri: s3Uri, mime_type: mime, who, model })
  });
  return response.json();
}

async function verify(s3Uri, mime) {
  const response = await fetch(`${BASE}/purestamp/verify`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'x-api-key': KEY },
    body: JSON.stringify({ s3_uri: s3Uri, mime_type: mime })
  });
  return response.json();
}

// Example usage
(async () => {
  const { uploadUrl, s3Uri } = await presign('file.pdf', 'application/pdf');
  // Upload file to uploadUrl using PUT
  const issueResult = await issue(s3Uri, 'application/pdf');
  console.log('Stamped URL:', issueResult.download_url);
  const verifyResult = await verify(s3Uri, 'application/pdf');
  console.log('Verification:', verifyResult);
})();

import os
import json
import requests

BASE = "https://qer7w7y40c.execute-api.us-east-1.amazonaws.com/prod"
KEY = os.getenv("API_KEY")
HEADERS = {"x-api-key": KEY, "Content-Type": "application/json"}

def presign(filename, content_type):
    response = requests.post(
        f"{BASE}/upload-url",
        headers=HEADERS,
        data=json.dumps({"filename": filename, "contentType": content_type}),
    )
    return response.json()

def issue(s3_uri, mime_type, who="AI", model="PureVector"):
    response = requests.post(
        f"{BASE}/purestamp/issue",
        headers=HEADERS,
        data=json.dumps({"s3_uri": s3_uri, "mime_type": mime_type, "who": who, "model": model}),
    )
    return response.json()

def verify(s3_uri, mime_type):
    response = requests.post(
        f"{BASE}/purestamp/verify",
        headers=HEADERS,
        data=json.dumps({"s3_uri": s3_uri, "mime_type": mime_type}),
    )
    return response.json()

# Example usage
if __name__ == "__main__":
    upload_data = presign("file.pdf", "application/pdf")
    # Upload file to upload_data["uploadUrl"] using requests.put
    issue_data = issue(upload_data["s3Uri"], "application/pdf")
    print("Stamped URL:", issue_data.get("download_url"))
    verify_data = verify(upload_data["s3Uri"], "application/pdf")
    print("Verification:", verify_data)

Tip: Enter your API credentials in the hero section to customize examples. Try the demo UI.

Status Codes & Errors

Common Errors

400 Bad Request: Missing or invalid input (e.g., no s3_uri, unsupported mime_type)
401 Unauthorized: Invalid or missing x-api-key
403 Forbidden: API key lacks permission or plan limit exceeded
429 Too Many Requests: Rate limit hit; retry with exponential backoff
5xx Server Error: Transient issue; retry with exponential backoff

CORS Configuration

Endpoints support permissive CORS with Access-Control-Allow-* headers for browser compatibility. For custom setups, ensure OPTIONS responses include these headers.

Start Building with PureStamp

Secure your AI and human content with our API. Sign up for a free API key or explore the demo UI.

Get API Key Try Demo