REST API

Account-management endpoints require a Console session, not a developer Access Key. For external integrations, use the operations endpoint and scope-authorized usage reads. GET /api/clawdbase/usage requires billing:usage.read; a valid key without it receives 403 (insufficient_scope).

Code examples

curl --request POST 'https://www.clawdbase.ai/api/clawdbase/operations/run' \
  --header "Authorization: Bearer $CLAWDBASE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "operation": "creator_score",
    "subject": "@github-handle",
    "channel": "api",
    "idempotency_key": "job-482:creator_score:github-handle"
  }'

const response = await fetch(
  'https://www.clawdbase.ai/api/clawdbase/operations/run',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.CLAWDBASE_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      operation: 'creator_score',
      subject: '@github-handle',
      channel: 'api',
      idempotency_key: crypto.randomUUID(),
    }),
    signal: AbortSignal.timeout(50_000),
  },
)

const body = await response.json()
if (!response.ok) throw new Error(body.error)

import os
import uuid
import requests

response = requests.post(
    "https://www.clawdbase.ai/api/clawdbase/operations/run",
    headers={
        "Authorization": f"Bearer {os.environ['CLAWDBASE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "operation": "creator_score",
        "subject": "@github-handle",
        "channel": "api",
        "idempotency_key": str(uuid.uuid4()),
    },
    timeout=50,
)

body = response.json()
if not response.ok:
    raise RuntimeError(body.get("error", "operation failed"))

Every example above authenticates with a server-side claw_live_... Access Key over HTTPS — never a browser-exposed secret. Response values shown throughout this page are illustrative unless otherwise labeled.

Success response

{
  "ok": true,
  "operation": "agent_score",
  "channel": "api",
  "result": {
    "query": {
      "raw": "owner/repository",
      "structured": {
        "firstName": "Example",
        "lastName": "Agent",
        "email": null,
        "city": null,
        "state": null,
        "country": null,
        "company": null,
        "jobTitle": null
      }
    },
    "scores": {
      "trustScore": 72,
      "confidenceScore": 85
    },
    "verification_status": "complete",
    "mode": "fast",
    "resolved_subject": {
      "canonical_id": "00000000-0000-4000-8000-000000000010",
      "type": "agent",
      "name": "Example Agent",
      "repository": "owner/repository",
      "source": "registered_agents",
      "source_id": "00000000-0000-4000-8000-000000000011",
      "public_path": "/a/id/00000000-0000-4000-8000-000000000010"
    },
    "score_evidence": {
      "status": "complete",
      "source": "inverus",
      "score_version": "2026-09-10T12:00:00.000Z",
      "freshness": "2026-09-10T12:00:00.000Z"
    }
  },
  "resolved_subject": {
    "canonical_id": "00000000-0000-4000-8000-000000000010",
    "type": "agent",
    "name": "Example Agent",
    "repository": "owner/repository",
    "public_path": "/a/id/00000000-0000-4000-8000-000000000010"
  },
  "ledger_id": "00000000-0000-4000-8000-000000000001",
  "charge_source": "included",
  "balance_after": {
    "period_kind": "stripe_subscription",
    "period_start": "2026-09-01T00:00:00.000Z",
    "period_end": "2026-10-01T00:00:00.000Z",
    "included_credits": 10000,
    "included_used": 10
  },
  "settled": true
}

This is a sanitized shape example, not a claim that the sample subject received these scores. The route preserves additive inVerus fields, so consumers should ignore unknown fields.

Result fields

Identity results and public Pages

Creator, X and Telegram evaluations include provider, provider_account_id, source, source_id and an exact public_path when registry evidence is available. Provider IDs are strings, including large Telegram IDs. canonical_id identifies an associated registered Page when one exists; it can be null for public sources without a registered Page. A reference matching different provider identities is rejected with 409 identity_subject_ambiguous before any charge. Use the exact source UUID to disambiguate.

An exact public Page URL preserves its source_id and, when supplied, provider_id. A missing exact source returns 404 identity_subject_not_found; conflicting source/provider IDs return 409 identity_evidence_mismatch. Invalid identifiers return 400 identity_subject_invalid. None falls back to scoring the URL's handle or consumes allowance.

These identity evaluations do not overwrite the stored public Page snapshot. score_evidence.persisted_to_page is false; public_snapshot contains the stored pair and its confirmed timestamp where known. Compare that snapshot with the returned evaluation explicitly. Different values do not by themselves establish a scoring error or a new confirmed Page version.

score_evidence.received_at records when Clawdbase received the evaluation, not when its underlying evidence was collected. score_version and freshness stay null when the upstream response does not establish those times. Never substitute received_at for confirmed freshness. If resolution is provider_reference, verify the subject independently before making an identity-dependent decision.

Lineage result

agent_skill_lineage returns the same validated score envelope plus Clawdbase’s canonical association:

{
  "result": {
    "scores": { "trustScore": 72, "confidenceScore": 85 },
    "verification_status": "complete",
    "mode": "fast",
    "lineage": {
      "subject": {
        "id": "canonical-agent-or-skill-id",
        "type": "agent",
        "name": "Example Agent",
        "repository": "owner/repository"
      },
      "creator": {
        "canonical_id": "canonical-creator-id",
        "handle": "owner",
        "trust": 68,
        "confidence": 81,
        "score_status": "scored",
        "scored_at": "2026-09-07T14:45:00.000Z"
      },
      "relationships": [
        { "type": "created_by", "from": "canonical-agent-or-skill-id", "to": "canonical-creator-id" }
      ]
    }
  }
}

The nested Creator pair is independent from the Agent or Skill pair. When no confirmed Creator score exists, trust and confidence are null, score_status is unavailable, and no sample value is inserted. Agent, Skill and Lineage requests resolve exactly one canonical artifact before usage is reserved. An unresolved subject returns 404; an ambiguous label returns 409 and asks for the canonical UUID. Neither response is charged.

Authentication and scope

The first-party Console uses its signed-in session. Server integrations send a claw_live_... Access Key containing the selected operation's scope. channel: "mcp" is rejected with mcp_not_available before any scope check or reservation — MCP is planned, and mcp:invoke is a reserved scope no new key can be issued.

Validation order

The route validates JSON, required fields, channel and operation before billing. It then checks credential ownership, scope, balance state and overage eligibility before reserving usage. Validation or service-availability failures do not reserve usage.

Idempotent replay

{
  "ok": true,
  "operation": "agent_skill_lineage",
  "channel": "api",
  "result": null,
  "idempotent": true,
  "ledger_id": "existing-ledger-uuid",
  "charge_source": "included",
  "balance_after": {}
}

The replay confirms a previous successful settlement and does not invoke inVerus again. The current contract does not retain the original result for replay. If your application lost that response, use the ledger ID to confirm settlement. There is no result-recovery endpoint; submit a new logical request with a new idempotency key only when you need a fresh score, and expect the normal charge.

Upstream failure

{
  "ok": false,
  "operation": "agent_score",
  "channel": "api",
  "error": "The scoring service is temporarily unavailable. No credits were charged. Please try again.",
  "ledger_id": "failed-ledger-uuid"
}

This response uses 502. The reservation is settled as failed and reversed. Log the ledger ID and retry the same logical request with the same idempotency key.

Client requirements

• Set Content-Type: application/json.
• Use a 50-second client deadline. A scoring attempt is bounded at 20 seconds and one 429 retry can extend the full server operation budget.
• Do not retry 400, 401, 402 or 403 unchanged.
• Back off on 429 and honor Retry-After when present.
• Treat additional response fields as backwards-compatible.
• Never expose the Access Key to a browser or public repository.