GraphQL API Reference¶

PrimeStamp provides a Strawberry-based GraphQL API with queries, mutations, and real-time subscriptions.

Setup¶

pip install strawberry-graphql[fastapi]

from primestamp.api.graphql import create_graphql_app

app = create_graphql_app()
# GraphQL endpoint available at /graphql

The GraphQL Playground is accessible at /graphql in the browser when the server is running.

Schema¶

Enums¶

enum HashAlgorithm {
  SHA3_256   # "sha3-256"
  SHA256     # "sha256"
}

enum StampStatus {
  PENDING
  CONFIRMED
  ANCHORED
}

Types¶

`Stamp`¶

type Stamp {
  id: String!
  contentHash: String!
  algorithm: HashAlgorithm!
  timestamp: DateTime!
  status: StampStatus!
  description: String
  metadata: JSON
  proof: Proof
  verificationUrl: String!    # Computed: https://primestamp.io/verify/{id}
  ageSeconds: Int!            # Computed: seconds since creation
}

`Proof`¶

type Proof {
  primeSignature: String
  witnesses: [String!]
  chainAnchor: String
  merkleRoot: String
  merkleProof: [String!]
}

`VerificationResult`¶

type VerificationResult {
  verified: Boolean!
  stampId: String!
  contentHash: String!
  timestamp: DateTime
  message: String
}

`BatchStampResult`¶

type BatchStampResult {
  stamps: [Stamp!]!
  successCount: Int!
  failedCount: Int!
  errors: [String!]
}

Pagination (Relay-style)¶

type StampConnection {
  edges: [StampEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type StampEdge {
  node: Stamp!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

`Vault`¶

type Vault {
  id: String!
  state: VaultState!
  createdAt: DateTime!
  deadline: DateTime!
  lastHeartbeat: DateTime
  heartbeatCount: Int!
  contentUris: [String!]!
  allowManualRelease: Boolean!
  metadata: JSON
}

`VaultFees`¶

type VaultFees {
  createFee: String!
  heartbeatFee: String!
  batchDiscount: String!
  currency: String!
  feeRecipient: String!
}

`HeartbeatReceipt`¶

type HeartbeatReceipt {
  vaultId: String!
  heartbeatAt: DateTime!
  nextDeadline: DateTime!
  feeAmount: String!
  feeCurrency: String!
}

`ReleaseResult`¶

type ReleaseResult {
  vaultId: String!
  released: Boolean!
  releasedAt: DateTime
  reason: String
}

`VaultConnection` (Relay-style)¶

type VaultConnection {
  edges: [VaultEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type VaultEdge {
  node: Vault!
  cursor: String!
}

Enums (Vault)¶

enum VaultState {
  ACTIVE
  RELEASED
  BURNED
  EXPIRED
}

Input Types¶

input StampInput {
  contentHash: String!
  algorithm: HashAlgorithm = SHA3_256
  description: String
  metadata: JSON
}

input BatchStampInput {
  items: [StampInput!]!
}

input VerifyInput {
  stampId: String!
  contentHash: String!
}

input StampsFilter {
  after: DateTime
  before: DateTime
  status: StampStatus
  algorithm: HashAlgorithm
}

input CreateVaultInput {
  encryptedKey: String!
  heartbeatDeadline: Int!
  contentUris: [String!]
  allowManualRelease: Boolean = false
  metadata: JSON
}

input HeartbeatInput {
  feeReceipt: String!
}

input ReleaseInput {
  reason: String
}

input VaultsFilter {
  state: VaultState
  after: DateTime
  before: DateTime
}

Queries¶

Get a stamp by ID¶

query GetStamp($id: String!) {
  stamp(id: $id) {
    id
    contentHash
    algorithm
    timestamp
    status
    verificationUrl
    proof {
      primeSignature
      chainAnchor
    }
  }
}

List stamps with pagination and filtering¶

query ListStamps($first: Int!, $after: String, $filter: StampsFilter) {
  stamps(first: $first, after: $after, filter: $filter) {
    edges {
      node {
        id
        contentHash
        timestamp
        status
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

Variables:

{
  "first": 10,
  "after": null,
  "filter": {
    "status": "CONFIRMED",
    "algorithm": "SHA3_256"
  }
}

Verify content against a stamp¶

query Verify($stampId: String!, $contentHash: String!) {
  verify(stampId: $stampId, contentHash: $contentHash) {
    verified
    timestamp
    message
  }
}

Hash content¶

query HashContent($content: String!, $algorithm: HashAlgorithm!) {
  hashContent(content: $content, algorithm: $algorithm)
}

Returns a prefixed hash string such as sha3-256:abc123....

Get a vault by ID¶

query GetVault($id: String!) {
  vault(id: $id) {
    id
    state
    createdAt
    deadline
    lastHeartbeat
    heartbeatCount
    contentUris
    allowManualRelease
    metadata
  }
}

List vaults with pagination and filtering¶

query ListVaults($first: Int!, $after: String, $filter: VaultsFilter) {
  vaults(first: $first, after: $after, filter: $filter) {
    edges {
      node {
        id
        state
        deadline
        heartbeatCount
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

Variables:

{
  "first": 10,
  "after": null,
  "filter": {
    "state": "ACTIVE"
  }
}

Get vault fees¶

query GetVaultFees {
  vaultFees {
    createFee
    heartbeatFee
    batchDiscount
    currency
    feeRecipient
  }
}

Mutations¶

Create a stamp¶

mutation CreateStamp($input: StampInput!) {
  createStamp(input: $input) {
    id
    contentHash
    timestamp
    status
    verificationUrl
  }
}

Variables:

{
  "input": {
    "contentHash": "sha3-256:e3b0c44298fc1c14...",
    "algorithm": "SHA3_256",
    "description": "Quarterly report Q1 2026",
    "metadata": { "department": "finance" }
  }
}

Batch stamp¶

Create multiple stamps in one request.

mutation BatchStamp($input: BatchStampInput!) {
  batchStamp(input: $input) {
    stamps {
      id
      contentHash
    }
    successCount
    failedCount
    errors
  }
}

Variables:

{
  "input": {
    "items": [
      { "contentHash": "sha3-256:aaa...", "description": "Doc A" },
      { "contentHash": "sha3-256:bbb...", "description": "Doc B" }
    ]
  }
}

Create a vault¶

mutation CreateVault($input: CreateVaultInput!) {
  createVault(input: $input) {
    id
    state
    createdAt
    deadline
    contentUris
  }
}

Variables:

{
  "input": {
    "encryptedKey": "<base64-encoded key>",
    "heartbeatDeadline": 259200,
    "contentUris": ["ipfs://Qm...", "arweave://tx123"],
    "allowManualRelease": true,
    "metadata": { "label": "project-keys" }
  }
}

Submit heartbeat¶

mutation SubmitHeartbeat($vaultId: String!, $input: HeartbeatInput!) {
  submitHeartbeat(vaultId: $vaultId, input: $input) {
    vaultId
    heartbeatAt
    nextDeadline
    feeAmount
    feeCurrency
  }
}

Variables:

{
  "vaultId": "vault-a1b2c3d4...",
  "input": {
    "feeReceipt": "tx_receipt_abc123"
  }
}

Manual release¶

mutation ManualRelease($vaultId: String!, $input: ReleaseInput) {
  manualRelease(vaultId: $vaultId, input: $input) {
    vaultId
    released
    releasedAt
    reason
  }
}

Variables:

{
  "vaultId": "vault-a1b2c3d4...",
  "input": {
    "reason": "Project handover"
  }
}

Subscriptions¶

Receive events in real time as stamps are created.

subscription OnStampCreated {
  stampCreated {
    id
    contentHash
    timestamp
    status
  }
}

Use a WebSocket-capable GraphQL client (e.g., Apollo Client, urql) to connect to the subscription endpoint.

Schema Export¶

Export the full SDL schema programmatically:

from primestamp.api.graphql import export_schema

sdl = export_schema()
print(sdl)

Python Client Example¶

import httpx

GRAPHQL_URL = "http://localhost:8800/graphql"

# Create a stamp
response = httpx.post(GRAPHQL_URL, json={
    "query": """
        mutation CreateStamp($input: StampInput!) {
            createStamp(input: $input) {
                id
                contentHash
                verificationUrl
            }
        }
    """,
    "variables": {
        "input": {
            "contentHash": "sha3-256:e3b0c44298fc1c14...",
            "description": "Contract v2.1",
        }
    }
})

data = response.json()
stamp_id = data["data"]["createStamp"]["id"]

# Verify
response = httpx.post(GRAPHQL_URL, json={
    "query": """
        query Verify($stampId: String!, $contentHash: String!) {
            verify(stampId: $stampId, contentHash: $contentHash) {
                verified
                message
            }
        }
    """,
    "variables": {
        "stampId": stamp_id,
        "contentHash": "sha3-256:e3b0c44298fc1c14...",
    }
})

GraphQL API Reference¶

Setup¶

Schema¶

Enums¶

Types¶

Stamp¶

Proof¶

VerificationResult¶

BatchStampResult¶

Pagination (Relay-style)¶

Vault¶

VaultFees¶

HeartbeatReceipt¶

ReleaseResult¶

VaultConnection (Relay-style)¶

Enums (Vault)¶

Input Types¶

Queries¶

Get a stamp by ID¶

List stamps with pagination and filtering¶

Verify content against a stamp¶

Hash content¶

Get a vault by ID¶

List vaults with pagination and filtering¶

Get vault fees¶

Mutations¶

Create a stamp¶

Batch stamp¶

Create a vault¶

Submit heartbeat¶

Manual release¶

Subscriptions¶

Subscribe to new stamps¶

Schema Export¶

Python Client Example¶

`Stamp`¶

`Proof`¶

`VerificationResult`¶

`BatchStampResult`¶

`Vault`¶

`VaultFees`¶

`HeartbeatReceipt`¶

`ReleaseResult`¶

`VaultConnection` (Relay-style)¶