Developer platform

Connect your software to trusted execution.

Use the versioned Nexus API to explore execution capabilities, understand authorization boundaries, and integrate against the contract exposed by your deployment.

Open API specification ↗Open console ↗

Integration path

Start in a controlled environment.

Do not embed operator credentials in browser code or treat a successful API response as proof of a physical outcome. Keep secrets server-side and verify actual deployed feature availability.

1. Inspect the API contract

Fetch the OpenAPI document from the running instance and use it as the source of truth for supported operations and schemas.

GET /v1/openapi.json

2. Check service health

Use the health endpoint to confirm the service responds. Readiness checks may report dependency status separately.

GET /api/health

GET /v1/health/ready

3. Authenticate server-side

Send credentials from a trusted backend, assign least privilege, scope integrations to the intended organization, and rotate credentials using your operational process.

4. Design for review

Handle errors and retries deliberately. Preserve request identifiers, use idempotency where supported, and route uncertain or high-impact outcomes to human review.

Production boundary

Integration is not authorization by itself.

Only expose capabilities enabled and secured in the deployed environment. Keep API keys out of client-side code, use HTTPS in production, test organization isolation, and validate the production readiness gates before live rollout. The API specification is authoritative for the current build.

Integration walkthrough

From task creation to a verified outcome.

Every step below runs against the versioned v1 API with an issued integration credential. All request bodies are JSON; all responses include the task state so your system can reconcile asynchronously.

Step 0 — Issue a sandbox integration

curl -X POST https://your-deployment/v1/integrations \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"acme-erp","scopes":["task.create","task.read","evidence.submit"],"environment":"sandbox"}'

Store the returned client_secret server-side. Sandbox integrations cannot change production state; promotion to live requires an explicit confirmed administrator action with rate limits and a monthly quota.

Step 1 — Create a task

curl -X POST https://your-deployment/v1/tasks \
  -H "Authorization: Bearer nxs_<client-secret>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: erp-order-8412" \
  -d '{"title":"Meter installation — site 4412","action":"meter_installation","requirements":{"capabilities":["meter_installation"]},"location":{"lat":6.4527,"lng":3.3958},"budget_amount_minor":2500000,"deadline_hours":48}'

The idempotency key makes retries safe: the same key returns the original task instead of creating a duplicate. Requirements are validated before any matching happens.

Step 2 — Track execution status

curl https://your-deployment/v1/tasks/<task-id> \
  -H "Authorization: Bearer nxs_<client-secret>"

The task state machine (MATCHING → ASSIGNED → IN_PROGRESS → VERIFYING → COMPLETED) and its audit trail are returned in one read. Subscribe to webhooks instead of polling for production workloads.

Step 3 — Evidence and verification

curl -X POST https://your-deployment/v1/tasks/<task-id>/evidence \
  -H "Authorization: Bearer nxs_<client-secret>" \
  -H "Content-Type: application/json" \
  -d '{"evidence_consent":true,"consent_version":"proof-of-work-disclosure-v1","items":[...]}'

Evidence is machine-verified (shape, timestamps, clock drift, geofence, integrity); anything the engine cannot decide mechanically goes to deterministic human review. A verified outcome is the only state your ERP should reconcile against.

Step 4 — Receive signed webhooks

X-Nexus-Signature: sha256=<hmac>   # sign_event(secret, timestamp, raw-body)

Register a webhook, verify the HMAC signature and timestamp tolerance on receipt, and treat replays as rejected. Delivery history, retries with backoff and manual replay are available at GET /v1/webhooks/deliveries and POST /v1/webhooks/replay.

Step 5 — Voice search the business directory

curl -X POST https://your-deployment/v1/discovery/voice-search \
  -H 'Content-Type: application/json' \
  -d '{"text":"I need AC repair in PH asap","limit":10,"offset":0}'

Public endpoint (rate-limited): parses a spoken transcript into a structured intent — service, location, urgency, availability, sort, budget — and returns the matching directory page with the intent and confidence attached. Transcripts are parsed, never persisted. See docs/VOICE_SEARCH.md.

Step 6 — Push the outcome to your systems

curl -X POST https://your-deployment/v1/enterprise/connectors/<connector-id>/invoke \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{"method":"POST","path":"/api/work-orders/8412/completion","payload":{"task_id":"...","verified":true},"idempotency_key":"outcome-8412"}'

Enterprise connectors (ERP, CRM, accounting, inventory, asset management, maintenance, logistics) move governed data outbound with HTTPS-only transport, bounded retries and a full delivery log. They never carry execution authority.