API Keys and API

This page is for regular Kvasyr Cloud (SaaS) users.

An API key is a user-scoped credential for calling Kvasyr’s REST API from your backend, worker, or automation agent.

It is not used for Dashboard login.

What You Can Do With API Keys Today

With Authorization: Bearer <api_key> you can call:

GET /v1/me
POST /v1/subscriptions, GET /v1/subscriptions, PATCH /v1/subscriptions/{id}, DELETE /v1/subscriptions/{id}
GET /v1/events
GET /v1/deliveries
POST /v1/backfill
POST /v1/subscriptions/{id}/verify-webhook
POST /v1/webhook-test

/api/* is currently an alias for /v1/*, but /v1/* is the canonical path.

Quick Check: Is My Key Valid?

export KVASYR_API_KEY="kva_..."
curl -sS https://app.kvasyr.com/v1/me \
  -H "Authorization: Bearer ${KVASYR_API_KEY}" \
  | jq

Create a Subscription by API

curl -sS https://app.kvasyr.com/v1/subscriptions \
  -H "Authorization: Bearer ${KVASYR_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sub-token-transfer-001" \
  -d '{
    "chain_id": 8453,
    "contract_scope": {
      "type": "single",
      "addresses": ["0xYourContractAddressHere"]
    },
    "event_signature": "Transfer(address,address,uint256)",
    "filters": {
      "topic1_in": ["0x0000000000000000000000001111111111111111111111111111111111111111"],
      "topic2_in": ["0x0000000000000000000000002222222222222222222222222222222222222222"]
    },
    "webhook": {
      "url": "https://example.com/kvasyr/webhook",
      "enabled": true
    },
    "stored": {
      "enabled": false
    }
  }' | jq

Notes:

event_signature must be a Solidity event signature string.
Topic filters (topic1_in, topic2_in, topic3_in) are exact 0x-prefixed 32-byte topic values.
Use Idempotency-Key for safe retries on create/backfill requests.

Use the Kvasyr API LLM Skill

This repository includes a reusable LLM skill for API automation at:

skills/kvasyr-api

Install and usage instructions:

LLM Skill: Kvasyr API

Using Codex With Local Contract Files

If your contract ABI/source is local, Codex can parse it and prepare the API payload, then you run the resulting curl.

Example prompt to Codex:

Read ./contracts/MyToken.abi.json and generate a curl command for
https://app.kvasyr.com/v1/subscriptions using env var KVASYR_API_KEY.

Requirements:
- chain_id 8453
- contract scope single, address 0xYourContractAddressHere
- event Transfer(address,address,uint256)
- include topic filters for indexed from/to addresses
- webhook https://example.com/kvasyr/webhook enabled
- stored disabled
- include an Idempotency-Key header

API Design: Explicit Event and Topic Inputs

The public API intentionally accepts normalized subscription inputs:

event_signature
optional topic filters
explicit contract scope

It does not take raw ABI JSON/Solidity source in the REST payload itself.

This makes API automation deterministic and language/tooling agnostic, and it works well with local LLM workflows.

Recommended LLM-assisted flow:

Give your local LLM contract ABI/source, target address, chain, and intent.
Let it extract the event signature and topic values.
Have it produce and run the POST /v1/subscriptions call with explicit fields.

If you prefer UI-assisted extraction, use the Dashboard Contract Event Explorer and copy the resulting values into your API automation.

Getting Started Backfills