API Reference (v1)

Base URL

https://api.pulseap.xyz/v1

Authentication

  • JWT for users and dashboards.

  • Wallet challenge for sensitive actions.

  • Device keys for robots and IoT sensors.

Auth

Start wallet challenge

POST /auth/wallet/challenge
{ "address": "So1anaPubKeyBase58" }

Verify wallet signature

POST /auth/wallet/verify
{ "address": "So1anaPubKeyBase58", "signature": "base58sig", "nonce": "6c7e12..." }

Issue device key

POST /devices/keys/issue
{ "device_name": "FieldDrone-A1", "project_id": "prj_abc" }

Devices

Register device

POST /devices
Headers: x-device-key
{
  "name": "FieldDrone-A1",
  "class": "drone",
  "capabilities": ["camera.capture", "geo.locate", "job.run"]
}

Device heartbeat

POST /devices/{device_id}/heartbeat
Headers: x-device-key
{ "battery": 0.82, "lat": 51.045, "lng": -114.057 }

Jobs

Create a job

POST /jobs
{
  "type": "sensor.read",
  "payload": { "sensor": "soil_moisture" },
  "project_id": "prj_abc",
  "max_price_credits": 0.05,
  "timeout_ms": 10000,
  "device_id": "dev_123"
}

Get job status

GET /jobs/{job_id}

Cancel job

POST /jobs/{job_id}/cancel

Nodes

Register node

POST /nodes
{
  "name": "edge-gpu-west-1",
  "capabilities": ["sensor.read", "image.resize"],
  "hardware": { "cpu": "8-core", "gpu": "RTX 3060" }
}

Pull jobs

POST /nodes/{node_id}/pull

Report progress

POST /nodes/{node_id}/jobs/{job_id}/progress
{ "message": "reading sensor", "pct": 30 }

Complete job with receipt

POST /nodes/{node_id}/jobs/{job_id}/complete
{
  "result": { "value": 0.41, "units": "fraction" },
  "receipt": {
    "scheme": "bls_sig_v1",
    "payload_hash": "sha256:ab12...",
    "signature": "bls:0xabc..."
  }
}

Receipts

Get receipt

GET /receipts/{receipt_id}

Verify receipt

POST /receipts/verify
{
  "scheme": "bls_sig_v1",
  "payload_hash": "sha256:ab12...",
  "signature": "bls:0xabc..."
}

Billing

Get balance

GET /billing/balance

Buy credits

POST /billing/credits/purchase
{ "amount": 10.0, "method": "test" }

Estimate job cost

POST /billing/estimate
{ "type": "image.resize", "payload": { "width": 640, "height": 640 } }

Projects

Create project

POST /projects
{ "name": "North Farm Pilot", "network": "devnet" }

Rotate API key

POST /projects/{project_id}/rotate-key

Events & WebSockets

Subscribe to job events

GET /ws?topic=jobs&project_id=prj_abc

Example events:

{ "type": "job.queued", "job_id": "job_789" }
{ "type": "job.progress", "job_id": "job_789", "pct": 50 }
{ "type": "job.succeeded", "job_id": "job_789", "receipt_id": "rcp_555" }

⚠Errors

Errors return:

{
  "error": {
    "code": "JOB_TIMEOUT",
    "message": "Job exceeded timeout_ms",
    "hint": "Increase timeout_ms to 15000"
  }
}
PreviousRoadmapNextConclusion

Last updated