REST API

available

The web application implements the authenticated operation route below.

POST/api/clawdbase/operations/run

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.

Field	Required	Meaning
`operation`	Yes	Canonical operation ID
`subject`	Yes	Subject name, handle, repository or ID
`channel`	No	`api` by default. `mcp` is reserved and returns `501 mcp_not_available`
`idempotency_key`	Yes	Unique key for the logical request
`api_key_id`	No	A signed-in Console session may supply an owned, active key for attribution. Access Key callers normally omit it; when supplied, it must exactly match the key derived from the bearer secret or the request returns `403`

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

Field	Meaning
request `subject`	The requested Agent, Skill, Creator, X or Telegram subject. It is available as `result.query.raw` on a fresh success and is not ownership proof
`operation`	The selected canonical subject/evaluation type
`result.scores.trustScore`	Finite Trust value from 0 to 100
`result.scores.confidenceScore`	Finite Confidence value from 0 to 100
`result.verification_status`	`complete` or `partial` for an accepted score. `incomplete` and double-zero results are rejected as `502`
`result.resolved_subject`	Exact canonical Agent/Skill identity selected before metering. Repository URLs, slugs and UUIDs that resolve to the same record return this same `canonical_id`
`result.score_evidence.score_version`	Confirmed canonical score timestamp written to the registry and used by the linked public Page
`ledger_id`	Stable usage receipt for support and reconciliation
`charge_source`	`free`, `gifted`, `included`, `purchased`, or `overage` selected by the server
`balance_after`	Source counters in calls for `free`; all other usage buckets are credits. `null` means unavailable, not zero

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.

On this page