API Reference

The Nexwatt REST API lets you create, deploy, and monitor workflow agents programmatically. Base URL: https://api.nexwatts.com/v1

Introduction

All requests must be made over HTTPS. The API uses standard HTTP response codes, accepts JSON request bodies, and returns JSON responses. Rate limits are enforced per workspace.

Authentication

Include your API key in every request. Get your key from Settings → API Keys in the Nexwatt dashboard.

Authorization: Bearer nxwt_live_xxxxxxxxxxxxxxxxxxxx

Errors

The API uses standard HTTP status codes. Error bodies always include error.code and error.message.

agents.create

Create a new agent from a plain-language process description. The agent is created in draft status — call agents.run or deploy via the dashboard to activate.

Request body

POST /v1/agents

{
  "name": "invoice-sync-v1",
  "description": "When a new invoice is marked paid in QuickBooks, update the matching deal in HubSpot to Closed Won and notify the account owner in Slack.",
  "connectors": ["quickbooks", "hubspot", "slack"],
  "confidence_threshold": 0.70
}

Response

{
  "agent_id": "agt_01J8K2M9P3Q4R5S6T7U8V9W0",
  "name": "invoice-sync-v1",
  "status": "draft",
  "steps_extracted": 5,
  "steps_flagged": 1,
  "created_at": "2026-06-27T14:31:00Z"
}

agents.run

Trigger an immediate run of a deployed agent. Use mode: "test" to execute with simulated inputs and no live system writes.

{
  "mode": "live",
  "input": { "invoice_id": "INV-4419" }
}

agents.list

List all agents in your workspace. Supports pagination via cursor parameter.

runs.list

List execution runs for a specific agent or across all agents.

{
  "runs": [
    {
      "run_id": "run_01J8K3N0P1Q2R3S4T5U6V7W8",
      "agent_id": "agt_01J8K2M9P3Q4R5S6T7U8V9W0",
      "status": "completed",
      "steps_completed": 5,
      "started_at": "2026-06-27T09:14:22Z",
      "completed_at": "2026-06-27T09:14:31Z"
    }
  ],
  "next_cursor": "cur_01J8K4P0Q1R2S3T4U5V6W7X8"
}

escalations.list

List open escalations requiring human review. Escalations are created when a step fails, times out, or falls below the confidence threshold.

escalations.resolve

Mark an escalation as resolved. Include an optional resolution_note for the audit trail.

{
  "action": "retry",
  "resolution_note": "API rate limit cleared — retrying step 3"
}