Attestry API Documentation

v1Base URL: https://attestry.ai/api/v1

Authentication

All authenticated endpoints require an API key passed via the x-api-key header. You can generate API keys from the RegSeal dashboard under Settings → API Keys.

Example Header

curl -H "x-api-key: rs_live_abc123..." \
  https://attestry.ai/api/v1/registry/stats

Public endpoints (Lookup, Search, Stats) do not require authentication but are rate-limited by IP address.

Register Model

POST/api/v1/registry/registerAuth required

Registers a single AI model in the public registry. Generates a SHA-256 fingerprint that can be used for verification.

Request

POST /api/v1/registry/register
Content-Type: application/json
x-api-key: rs_live_abc123...

{
  "systemId": "550e8400-e29b-41d4-a716-446655440000",
  "modelVersion": "gpt-4o-2024-05-13",
  "modelArchitecture": "transformer-decoder",
  "weightsHash": "a1b2c3d4e5f6..."
}

Response (201)

{
  "success": true,
  "data": {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "fingerprint": "e3b0c44298fc1c149afbf4c8996fb924...",
    "systemId": "550e8400-e29b-41d4-a716-446655440000",
    "modelVersion": "gpt-4o-2024-05-13",
    "modelArchitecture": "transformer-decoder",
    "registeredAt": "2026-03-30T12:00:00.000Z",
    "verificationUrl": "https://attestry.ai/api/v1/registry/lookup?fingerprint=e3b0c44..."
  }
}

Parameter	Type	Required	Description
`systemId`	string (UUID)	Yes	ID of the AI system (must belong to your org)
`modelVersion`	string	Yes	Version identifier (1-200 chars)
`modelArchitecture`	string	No	Architecture description (max 500 chars)
`weightsHash`	string	No	SHA-256 hash of model weights (64 hex chars)

Batch Register

POST/api/v1/registry/batch-registerAuth required

Register up to 50 models in a single request. Duplicates (same systemId + modelVersion) are reported as successes with the existing fingerprint.

Request

POST /api/v1/registry/batch-register
Content-Type: application/json
x-api-key: rs_live_abc123...

{
  "models": [
    {
      "systemId": "550e8400-e29b-41d4-a716-446655440000",
      "modelVersion": "v2.1.0",
      "modelArchitecture": "transformer-decoder"
    },
    {
      "systemId": "550e8400-e29b-41d4-a716-446655440000",
      "modelVersion": "v2.2.0"
    }
  ]
}

Response (201)

{
  "success": true,
  "data": {
    "results": [
      { "index": 0, "success": true, "fingerprint": "a1b2c3..." },
      { "index": 1, "success": true, "fingerprint": "d4e5f6..." }
    ],
    "summary": {
      "total": 2,
      "succeeded": 2,
      "failed": 0
    }
  }
}

Parameter	Type	Required	Description
`models`	array	Yes	Array of 1-50 model objects (same fields as Register)

Lookup

GET/api/v1/registry/lookup

Look up a registered model by fingerprint, system name, or organization name. Public endpoint (no auth required).

Fingerprint Lookup

GET /api/v1/registry/lookup?fingerprint=e3b0c44298fc1c149afbf4c8996fb924...

Response (200)

{
  "success": true,
  "data": {
    "found": true,
    "fingerprint": "e3b0c44298fc1c149afbf4c8996fb924...",
    "modelVersion": "gpt-4o-2024-05-13",
    "modelArchitecture": "transformer-decoder",
    "registeredAt": "2026-03-30T12:00:00.000Z",
    "systemName": "Customer Support AI",
    "organizationName": "Acme Corp",
    "versionCount": 3,
    "attestations": [
      {
        "certificateHash": "abc123...",
        "frameworks": ["eu-ai-act", "nist-ai-rmf"],
        "status": "active",
        "issuedAt": "2026-03-15T00:00:00.000Z",
        "zkVerified": true,
        "domains": ["ai-compliance"]
      }
    ]
  }
}

Parameter	Type	Required	Description
`fingerprint`	string	No	64-character hex SHA-256 fingerprint (exact match)
`systemName`	string	No	Partial match on AI system name
`orgName`	string	No	Partial match on organization name

Search

GET/api/v1/registry/lookup

The lookup endpoint doubles as a search when using systemName or orgName parameters. Returns up to 20 matching models with their latest fingerprints and attestation status.

Search by Organization

GET /api/v1/registry/lookup?orgName=Acme

Response (200)

{
  "success": true,
  "data": {
    "results": [
      {
        "fingerprint": "e3b0c44298fc1c...",
        "modelVersion": "v2.1.0",
        "modelArchitecture": "transformer-decoder",
        "registeredAt": "2026-03-30T12:00:00.000Z",
        "systemName": "Customer Support AI",
        "organizationName": "Acme Corp",
        "attestations": []
      }
    ],
    "total": 1
  }
}

Stats

GET/api/v1/registry/stats

Returns aggregate statistics for the public registry. Public endpoint, cached for 1 hour.

Request

GET /api/v1/registry/stats

Response (200)

{
  "success": true,
  "data": {
    "totalModels": 1247,
    "totalVerified": 893,
    "domainDistribution": {
      "ai-compliance": 750,
      "pqc": 98,
      "cross-domain": 45
    },
    "frameworkDistribution": {
      "eu-ai-act": 621,
      "nist-ai-rmf": 503,
      "iso-42001": 312,
      "colorado-ai-act": 187
    },
    "recentRegistrations": 84
  }
}

Webhooks

POST/api/v1/registry/webhooksAuth required

Register a webhook to receive notifications for registry events. Webhooks are delivered via HTTP POST with an HMAC-SHA256 signature in the x-regseal-signature header.

Create Webhook

POST /api/v1/registry/webhooks
Content-Type: application/json
x-api-key: rs_live_abc123...

{
  "url": "https://your-app.com/webhooks/regseal",
  "events": ["model.registered", "attestation.issued"],
  "secret": "whsec_your_secret_key_min_16_chars"
}

Response (201)

{
  "success": true,
  "data": {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "url": "https://your-app.com/webhooks/regseal",
    "events": ["model.registered", "attestation.issued"],
    "createdAt": "2026-03-30T12:00:00.000Z"
  }
}

GET/api/v1/registry/webhooksAuth required

List all webhooks registered for your organization.

Response (200)

{
  "success": true,
  "data": {
    "webhooks": [
      {
        "id": "d290f1ee-...",
        "url": "https://your-app.com/webhooks/regseal",
        "events": ["model.registered", "attestation.issued"],
        "status": "active",
        "createdAt": "2026-03-30T12:00:00.000Z",
        "updatedAt": "2026-03-30T12:00:00.000Z"
      }
    ],
    "total": 1
  }
}

Available Events

Parameter	Type	Required	Description
`model.registered`	event	No	Fired when a new model is registered in the registry
`model.claimed`	event	No	Fired when an unclaimed registry entry is claimed by an org
`model.verified`	event	No	Fired when a model passes compliance verification
`attestation.issued`	event	No	Fired when a new attestation certificate is issued

Rate Limits

All endpoints are rate-limited. Limits are returned in response headers.

Endpoint	Limit	Window
Register / Batch Register	120 requests	1 minute
Lookup / Search / Stats	10 requests	1 minute
Webhooks	120 requests	1 minute

Rate limit headers included in every response:

Rate Limit Headers

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1711800000

Response Formats

All responses follow a consistent JSON envelope.

Success Response

{
  "success": true,
  "data": { ... }
}

Error Response

{
  "success": false,
  "error": "Human-readable error message",
  "details": [
    { "path": "models.0.systemId", "message": "systemId must be a valid UUID" }
  ]
}

HTTP Status Codes

Code	Meaning
`200`	Success
`201`	Created (registration succeeded)
`400`	Bad request (invalid parameters)
`401`	Unauthorized (missing or invalid API key)
`403`	Forbidden (system does not belong to your org)
`404`	Not found
`422`	Validation error (Zod schema failure)
`429`	Rate limit exceeded
`500`	Internal server error

← Back to Registry

Attestry API Documentation

v1Base URL: https://attestry.ai/api/v1

Authentication

All authenticated endpoints require an API key passed via the x-api-key header. You can generate API keys from the RegSeal dashboard under Settings → API Keys.

Example Header

curl -H "x-api-key: rs_live_abc123..." \
  https://attestry.ai/api/v1/registry/stats

Public endpoints (Lookup, Search, Stats) do not require authentication but are rate-limited by IP address.

Register Model

POST/api/v1/registry/registerAuth required

Registers a single AI model in the public registry. Generates a SHA-256 fingerprint that can be used for verification.

Request

POST /api/v1/registry/register
Content-Type: application/json
x-api-key: rs_live_abc123...

{
  "systemId": "550e8400-e29b-41d4-a716-446655440000",
  "modelVersion": "gpt-4o-2024-05-13",
  "modelArchitecture": "transformer-decoder",
  "weightsHash": "a1b2c3d4e5f6..."
}

Response (201)

{
  "success": true,
  "data": {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "fingerprint": "e3b0c44298fc1c149afbf4c8996fb924...",
    "systemId": "550e8400-e29b-41d4-a716-446655440000",
    "modelVersion": "gpt-4o-2024-05-13",
    "modelArchitecture": "transformer-decoder",
    "registeredAt": "2026-03-30T12:00:00.000Z",
    "verificationUrl": "https://attestry.ai/api/v1/registry/lookup?fingerprint=e3b0c44..."
  }
}

Parameter	Type	Required	Description
`systemId`	string (UUID)	Yes	ID of the AI system (must belong to your org)
`modelVersion`	string	Yes	Version identifier (1-200 chars)
`modelArchitecture`	string	No	Architecture description (max 500 chars)
`weightsHash`	string	No	SHA-256 hash of model weights (64 hex chars)

Batch Register

POST/api/v1/registry/batch-registerAuth required

Register up to 50 models in a single request. Duplicates (same systemId + modelVersion) are reported as successes with the existing fingerprint.

Request

POST /api/v1/registry/batch-register
Content-Type: application/json
x-api-key: rs_live_abc123...

{
  "models": [
    {
      "systemId": "550e8400-e29b-41d4-a716-446655440000",
      "modelVersion": "v2.1.0",
      "modelArchitecture": "transformer-decoder"
    },
    {
      "systemId": "550e8400-e29b-41d4-a716-446655440000",
      "modelVersion": "v2.2.0"
    }
  ]
}

Response (201)

{
  "success": true,
  "data": {
    "results": [
      { "index": 0, "success": true, "fingerprint": "a1b2c3..." },
      { "index": 1, "success": true, "fingerprint": "d4e5f6..." }
    ],
    "summary": {
      "total": 2,
      "succeeded": 2,
      "failed": 0
    }
  }
}

Parameter	Type	Required	Description
`models`	array	Yes	Array of 1-50 model objects (same fields as Register)

Lookup

GET/api/v1/registry/lookup

Look up a registered model by fingerprint, system name, or organization name. Public endpoint (no auth required).

Fingerprint Lookup

GET /api/v1/registry/lookup?fingerprint=e3b0c44298fc1c149afbf4c8996fb924...

Response (200)

{
  "success": true,
  "data": {
    "found": true,
    "fingerprint": "e3b0c44298fc1c149afbf4c8996fb924...",
    "modelVersion": "gpt-4o-2024-05-13",
    "modelArchitecture": "transformer-decoder",
    "registeredAt": "2026-03-30T12:00:00.000Z",
    "systemName": "Customer Support AI",
    "organizationName": "Acme Corp",
    "versionCount": 3,
    "attestations": [
      {
        "certificateHash": "abc123...",
        "frameworks": ["eu-ai-act", "nist-ai-rmf"],
        "status": "active",
        "issuedAt": "2026-03-15T00:00:00.000Z",
        "zkVerified": true,
        "domains": ["ai-compliance"]
      }
    ]
  }
}

Parameter	Type	Required	Description
`fingerprint`	string	No	64-character hex SHA-256 fingerprint (exact match)
`systemName`	string	No	Partial match on AI system name
`orgName`	string	No	Partial match on organization name

Search

GET/api/v1/registry/lookup

The lookup endpoint doubles as a search when using systemName or orgName parameters. Returns up to 20 matching models with their latest fingerprints and attestation status.

Search by Organization

GET /api/v1/registry/lookup?orgName=Acme

Response (200)

{
  "success": true,
  "data": {
    "results": [
      {
        "fingerprint": "e3b0c44298fc1c...",
        "modelVersion": "v2.1.0",
        "modelArchitecture": "transformer-decoder",
        "registeredAt": "2026-03-30T12:00:00.000Z",
        "systemName": "Customer Support AI",
        "organizationName": "Acme Corp",
        "attestations": []
      }
    ],
    "total": 1
  }
}

Stats

GET/api/v1/registry/stats

Returns aggregate statistics for the public registry. Public endpoint, cached for 1 hour.

Request

GET /api/v1/registry/stats

Response (200)

{
  "success": true,
  "data": {
    "totalModels": 1247,
    "totalVerified": 893,
    "domainDistribution": {
      "ai-compliance": 750,
      "pqc": 98,
      "cross-domain": 45
    },
    "frameworkDistribution": {
      "eu-ai-act": 621,
      "nist-ai-rmf": 503,
      "iso-42001": 312,
      "colorado-ai-act": 187
    },
    "recentRegistrations": 84
  }
}

Webhooks

POST/api/v1/registry/webhooksAuth required

Register a webhook to receive notifications for registry events. Webhooks are delivered via HTTP POST with an HMAC-SHA256 signature in the x-regseal-signature header.

Create Webhook

POST /api/v1/registry/webhooks
Content-Type: application/json
x-api-key: rs_live_abc123...

{
  "url": "https://your-app.com/webhooks/regseal",
  "events": ["model.registered", "attestation.issued"],
  "secret": "whsec_your_secret_key_min_16_chars"
}

Response (201)

{
  "success": true,
  "data": {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "url": "https://your-app.com/webhooks/regseal",
    "events": ["model.registered", "attestation.issued"],
    "createdAt": "2026-03-30T12:00:00.000Z"
  }
}

GET/api/v1/registry/webhooksAuth required

List all webhooks registered for your organization.

Response (200)

{
  "success": true,
  "data": {
    "webhooks": [
      {
        "id": "d290f1ee-...",
        "url": "https://your-app.com/webhooks/regseal",
        "events": ["model.registered", "attestation.issued"],
        "status": "active",
        "createdAt": "2026-03-30T12:00:00.000Z",
        "updatedAt": "2026-03-30T12:00:00.000Z"
      }
    ],
    "total": 1
  }
}

Available Events

Parameter	Type	Required	Description
`model.registered`	event	No	Fired when a new model is registered in the registry
`model.claimed`	event	No	Fired when an unclaimed registry entry is claimed by an org
`model.verified`	event	No	Fired when a model passes compliance verification
`attestation.issued`	event	No	Fired when a new attestation certificate is issued

Rate Limits

All endpoints are rate-limited. Limits are returned in response headers.

Endpoint	Limit	Window
Register / Batch Register	120 requests	1 minute
Lookup / Search / Stats	10 requests	1 minute
Webhooks	120 requests	1 minute

Rate limit headers included in every response:

Rate Limit Headers

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1711800000

Response Formats

All responses follow a consistent JSON envelope.

Success Response

{
  "success": true,
  "data": { ... }
}

Error Response

{
  "success": false,
  "error": "Human-readable error message",
  "details": [
    { "path": "models.0.systemId", "message": "systemId must be a valid UUID" }
  ]
}

HTTP Status Codes

Code	Meaning
`200`	Success
`201`	Created (registration succeeded)
`400`	Bad request (invalid parameters)
`401`	Unauthorized (missing or invalid API key)
`403`	Forbidden (system does not belong to your org)
`404`	Not found
`422`	Validation error (Zod schema failure)
`429`	Rate limit exceeded
`500`	Internal server error