API Reference

This section provides detailed documentation for all HEIR API endpoints.

Base URL

https://api.heir.es/api/v1/

Authentication

All requests require an API key via one of these methods:

# Authorization header (recommended)
curl -H "Authorization: Bearer heir_pk_xxx..." https://api.heir.es/api/v1/...

# X-API-Key header
curl -H "X-API-Key: heir_pk_xxx..." https://api.heir.es/api/v1/...

See Authentication Guide for details.

Response Format

All responses follow this structure:

Success Response

{
  "success": true,
  "data": { ... },
  "meta": {
    "requestId": "req_abc123xyz",
    "timestamp": "2024-01-15T12:00:00.000Z",
    "pagination": {  // Optional, for list endpoints
      "page": 1,
      "limit": 20,
      "total": 150,
      "pages": 8
    }
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid beneficiary address",
    "details": [
      { "field": "beneficiaries[0].address", "reason": "Invalid checksum" }
    ]
  },
  "meta": {
    "requestId": "req_abc123xyz",
    "timestamp": "2024-01-15T12:00:00.000Z"
  }
}

Error Codes

Code	HTTP Status	Description
API_KEY_MISSING	401	No API key provided
API_KEY_INVALID	401	Invalid or expired API key
UNAUTHORIZED	401	Authentication required
INSUFFICIENT_SCOPE	403	API key lacks required scope
TIER_NOT_ALLOWED	403	Feature requires higher tier
IP_NOT_ALLOWED	403	IP not in whitelist
NOT_FOUND	404	Resource not found
VALIDATION_ERROR	400	Invalid request parameters
RATE_LIMIT_EXCEEDED	429	Too many requests
INTERNAL_ERROR	500	Server error

Rate Limits

Requests are rate limited based on your API key tier:

Tier	Requests/15min	Contract Gen	AI Chat
Public	100	10	5
Partner	1,000	100	50
Internal	10,000	1,000	200

Rate limit headers are included in all responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 2024-01-15T12:30:00.000Z

Endpoints

API Keys

• GET /api-keys - List your API keys
• POST /api-keys - Create a new API key
• GET /api-keys/:id - Get API key details
• PATCH /api-keys/:id - Update an API key
• DELETE /api-keys/:id - Revoke an API key

Contracts

• GET /contracts/templates - List inheritance templates
• POST /contracts/generate - Generate a contract
• POST /contracts/compile - Compile source code
• POST /contracts/estimate-gas - Estimate deployment gas

Webhooks

• GET /webhooks/subscriptions - List webhooks
• POST /webhooks/subscriptions - Create webhook
• GET /webhooks/events - List available events
• POST /webhooks/subscriptions/:id/test - Test a webhook

Embed

• GET /embed/wizard - Embeddable wizard iframe
• GET /embed/sdk.js - JavaScript SDK

OpenAPI Specification

Download the complete OpenAPI 3.0 specification:

• openapi.json
• Interactive Docs

SDKs

Official SDKs are available for:

• JavaScript/TypeScript
• Python
• Go

Or generate a client from the OpenAPI spec using OpenAPI Generator.