API Documentation

The Accipiter API enables AI agents and applications to discover, purchase, and consume verified datasets programmatically. Every dataset is SHA-256 hashed and registered on-chain for tamper-proof provenance.

Designed for Agent-to-Agent (A2A) workflows, the API uses a simple credit-based model where 1 credit = $0.01 USD. LLM agents can browse the catalog, estimate query costs, and stream verified results with a standard REST interface.

Base URL: https://api.accipiter.io/v1

Authentication

All API requests require an API key passed in the Authorization header. You can generate an API key from your dashboard after signing up.

Request Header

Authorization: Bearer acc_live_xxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

API keys are prefixed with acc_live_ for production and acc_test_ for sandbox. Never expose your API key in client-side code.

Endpoints

GET/api/v1/catalog

List all available datasets. Supports filtering by sector and keyword search.

Request

curl https://api.accipiter.io/v1/catalog?sector=anime&q=survey \
  -H "Authorization: Bearer acc_live_xxxxx"

Response

{
  "data": [
    {
      "id": "d7a1f2b3-...",
      "name": "Japan Anime Consumer Survey 2025",
      "sector": "anime",
      "record_count": 15000,
      "source_count": 3,
      "price_per_query": 50,
      "data_freshness": "quarterly",
      "geographic_coverage": ["Japan", "South Korea"]
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}

GET/api/v1/catalog/:id

Get detailed information about a dataset including its schema definition, sample data, and data sources.

Response

{
  "id": "d7a1f2b3-...",
  "name": "Japan Anime Consumer Survey 2025",
  "description": "Consumer behavior survey...",
  "schema_definition": {
    "columns": [
      { "name": "gender", "type": "string" },
      { "name": "age", "type": "integer" },
      { "name": "favorite_genre", "type": "string" }
    ]
  },
  "sources": [
    {
      "provider_name": "Tokyo Research Corp",
      "sample_size": 8000,
      "survey_date": "2025-03-15"
    }
  ],
  "data_hash": "a1b2c3d4...",
  "onchain_tx_hash": "0xabc..."
}

POST/api/v1/query

Submit a data query. Returns a cost estimate before execution. The query is not executed until confirmed.

Request

curl -X POST https://api.accipiter.io/v1/query \
  -H "Authorization: Bearer acc_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "dataset_id": "d7a1f2b3-...",
    "query_text": "Average age by favorite anime genre in Tokyo",
    "processing_requirements": {
      "aggregation_type": "average",
      "group_by": "favorite_genre",
      "filter": { "region": "Tokyo" }
    }
  }'

Response

{
  "query_id": "q9e8f7a6-...",
  "status": "pending",
  "estimated_cost": 50,
  "estimated_records": 4200,
  "expires_at": "2026-04-09T12:30:00Z"
}

POST/api/v1/query/:id/confirm

Confirm and execute a pending query. Credits are deducted atomically at this step.

Request

curl -X POST https://api.accipiter.io/v1/query/q9e8f7a6-.../confirm \
  -H "Authorization: Bearer acc_live_xxxxx"

Response

{
  "query_id": "q9e8f7a6-...",
  "status": "processing",
  "credits_charged": 50,
  "remaining_balance": 9950
}

GET/api/v1/query/:id/status

Check the processing status of a confirmed query. Poll this endpoint until status is 'completed' or 'failed'.

Response

{
  "query_id": "q9e8f7a6-...",
  "status": "completed",
  "processing_time_ms": 2340,
  "result_record_count": 12,
  "proof_status": "confirmed",
  "proof_hash": "0xdef..."
}

GET/api/v1/query/:id/result

Retrieve the processed result of a completed query. Results include a ZKP proof hash for verification.

Response

{
  "query_id": "q9e8f7a6-...",
  "data": [
    { "favorite_genre": "Shonen", "avg_age": 24.3, "count": 1850 },
    { "favorite_genre": "Seinen", "avg_age": 31.7, "count": 920 },
    { "favorite_genre": "Isekai", "avg_age": 22.1, "count": 1430 }
  ],
  "proof_hash": "0xdef...",
  "data_hash": "a1b2c3d4...",
  "verified": true
}

GET/api/v1/balance

Check your current credit balance and recent transactions.

Response

{
  "balance": 9950,
  "currency": "credits",
  "usd_equivalent": 99.50,
  "recent_transactions": [
    {
      "type": "charge",
      "amount": -50,
      "query_id": "q9e8f7a6-...",
      "timestamp": "2026-04-09T12:00:05Z"
    }
  ]
}

Query Flow

The typical flow for an AI agent consuming data through the Accipiter API follows these steps:

Search the catalog

Browse datasets by sector or keyword using GET /api/v1/catalog. Inspect schemas to find relevant data.

Submit a query

POST /api/v1/query with the dataset ID and your processing requirements. You receive a cost estimate.

Confirm and pay

POST /api/v1/query/:id/confirm to execute. Credits are deducted atomically.

Poll for status

GET /api/v1/query/:id/status until the status is 'completed'. Typical processing: 1-10 seconds.

Retrieve results

GET /api/v1/query/:id/result for the processed data, complete with ZKP proof hash for on-chain verification.

Rate Limits

API requests are rate-limited per API key to ensure fair usage.

Tier	Limit	Window
Standard	100 requests	Per minute
Burst	10 requests	Per second

Rate limit headers are included in every response: X-RateLimit-Remaining and X-RateLimit-Reset.

Error Codes

All errors follow a consistent JSON format:

Error Response

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Not enough credits to execute this query.",
    "details": {
      "required": 50,
      "available": 12
    }
  }
}

HTTP	Code	Description
400	INVALID_REQUEST	Malformed request body or missing required fields
401	UNAUTHORIZED	Missing or invalid API key
402	INSUFFICIENT_CREDITS	Not enough credits for the requested operation
404	NOT_FOUND	Dataset or query ID does not exist
409	QUERY_EXPIRED	Query estimate expired, submit a new query
429	RATE_LIMITED	Too many requests, retry after cooldown
500	INTERNAL_ERROR	Unexpected server error, contact support