API Reference

Authentication

Every request must include an API key. Generate one in your IVO dashboard under Developer → API Keys. Keys are scoped per-node and per-environment (sandbox / live).

cURL

# All requests require Bearer authentication
curl https://api.ivo.cy/v1/me \
  -H "Authorization: Bearer ivo_live_sk_..." \
  -H "Content-Type: application/json"

ECDSA Signing

Sensitive endpoints (payouts, escrow release, dispute decisions) require an additional X-IVO-Signature header generated with your node's private key. Public keys live in the federation registry; signatures are verified across all nodes.

Rate Limits

Default: 120 requests per minute per API key. Burst up to 240 for 10 seconds. Webhook delivery is exempt. Rate limit state is returned in headers:

X-RateLimit-Limit - the cap
X-RateLimit-Remaining - calls left in the current window
X-RateLimit-Reset - Unix timestamp the window resets

Errors

Standard HTTP codes. Error bodies are JSON with a stable code field for programmatic handling and a human message.

Response

{
  "error": {
    "code": "task_not_found",
    "message": "No task matches id=tsk_018f...",
    "request_id": "req_8c1e2..."
  }
}

Tasks endpoints

List tasks

GET /v1/tasks - paginated. Query by status, worker_id, project_id.

Create task

POST /v1/tasks - requires project_id, title, budget, currency. Funds are held in escrow on creation.

JS / fetch

const res = await fetch('https://api.ivo.cy/v1/tasks', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.IVO_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    project_id: 'prj_018f...',
    title: 'Translate marketing page to Greek',
    budget: 120,
    currency: 'EUR'
  })
});
const task = await res.json();

Wallets & Payouts

GET /v1/wallets/:id - read balance, KYC tier, and pending releases. POST /v1/wallets/:id/payouts - initiate a payout to a verified bank account or Stripe destination. Subject to KYC tier limits.

Webhooks

Configure endpoints in Developer → Webhooks. Delivery is at-least-once with exponential backoff. Each event is signed with HMAC-SHA256 over the raw body.

task.created · task.submitted · task.approved · task.disputed
wallet.deposit · wallet.withdrawal · wallet.kyc_changed
node.health_changed · federation.peer_joined

Federation & Cross-Node

Tasks posted on one node may be fulfilled by workers on a peer node. Cross-node calls use the same API surface but include X-IVO-Origin and X-IVO-Signature. The receiving node verifies the signature against the federation registry before routing.

Peer onboarding is gated. Submit a join request via Contact with your WHMCS instance URL and node operator details.

REST API Reference