Audit Log

GET /v1/audit

Retrieve the append-only audit log for your tenant. Entries are written for every sign, verify, lookup, recipe creation, key creation, and billing event. Requires admin-scoped key.

GET https://api.verbitas.io/v1/audit
Authorization: Bearer vb_admin_...

Query parameters

Parameter	Type	Description
`from`	ISO 8601	Start of time range (inclusive)
`to`	ISO 8601	End of time range (exclusive)
`event_type`	string	Filter by event type (see below)
`asset_id`	string	Filter by specific asset ID
`limit`	int	Max entries per page (default 100, max 1000)
`cursor`	string	Pagination cursor from previous response
`format`	string	`json` (default) or `ndjson` (for streaming export)

curl "https://api.verbitas.io/v1/audit?from=2026-05-01T00:00:00Z&to=2026-05-09T00:00:00Z&format=ndjson" \
  -H "Authorization: Bearer $VERBITAS_API_KEY"

Response: 200 OK (JSON)

{
  "entries": [
    {
      "id": "audit_01j...",
      "event_type": "asset.signed",
      "timestamp": "2026-05-09T10:00:00Z",
      "tenant_id": "t_01j...",
      "actor_key_id": "key_01j...",
      "request_id": "req_01j...",
      "data": {
        "asset_id": "a_01j...",
        "recipe_id": "image-genai-v1",
        "file_type": "image/jpeg",
        "file_size_bytes": 204800
      }
    },
    {
      "id": "audit_02k...",
      "event_type": "asset.verified",
      "timestamp": "2026-05-09T10:05:00Z",
      "data": {
        "asset_id": "a_01j...",
        "status": "verified_manifest_and_watermark_match",
        "confidence": 0.97
      }
    }
  ],
  "cursor": "cur_01j...",
  "has_more": true
}

Event types

Event type	Triggered by
`asset.signed`	Successful `POST /v1/sign`
`asset.sign_failed`	Failed sign attempt (includes error code)
`asset.verified`	`POST /v1/verify`
`asset.lookup`	`POST /v1/lookup`
`anchor.batch_submitted`	Anchor batch sent to OTS/Arbitrum
`anchor.confirmed`	Anchor batch confirmed on-chain
`recipe.created`	`POST /v1/recipes`
`key.created`	New API key minted
`key.revoked`	API key revoked
`billing.quota_exceeded`	Plan quota hit
`billing.payment_failed`	Stripe payment failure
`webhook.delivered`	Webhook successfully delivered
`webhook.failed`	Webhook delivery failed after all retries

NDJSON export

For SIEM integration or large date ranges, use format=ndjson. Each line is a JSON object.

curl "https://api.verbitas.io/v1/audit?from=2026-01-01T00:00:00Z&format=ndjson" \
  -H "Authorization: Bearer $VERBITAS_API_KEY" \
  > audit-2026.ndjson

S3 continuous export (Enterprise)

Enterprise tenants can configure continuous S3 export in the admin console. Audit events are streamed to your S3 bucket in NDJSON format, partitioned by year/month/day. This is the recommended pattern for SIEM integration (Splunk, Elastic, Datadog).

Retention

Audit log entries are retained for:

Plan	Retention
Free / Developer	30 days
Growth	365 days
Enterprise	7 years (2555 days)

Enterprise retention is configurable up to 7 years. Entries cannot be deleted or modified — the log is append-only.

Error codes

HTTP	Code	Meaning
401	`verbitas.auth.invalid_key`	API key invalid
403	`verbitas.auth.insufficient_scope`	`admin` scope required
400	`verbitas.audit.invalid_date_range`	`from` is after `to`, or range exceeds 365 days for non-enterprise

SDK example

import verbitas
from datetime import datetime, timezone

client = verbitas.Client()

entries = client.audit.list(
    from_dt=datetime(2026, 5, 1, tzinfo=timezone.utc),
    to_dt=datetime(2026, 5, 9, tzinfo=timezone.utc),
    event_type="asset.signed"
)

for entry in entries:
    print(entry.timestamp, entry.data.get("asset_id"))