Documentation

Agent API reference

One endpoint runs a Nexus Hub agent, lets it use its actions, and returns both the reply and a log of what it did.

Authentication

Send your key as a bearer token on every request. While the platform is in demo mode the key nexus_demo_key is accepted so the examples run as-is. Keep production keys server-side.

Run an agent

request
POST /api/public/agent
Authorization: Bearer <NEXUS_API_KEY>
Content-Type: application/json

{
  "agent": "support",                 // agent role name
  "message": "Customer message here", // required
  "context": "Business facts the agent should rely on",
  "history": [
    { "role": "user", "content": "Earlier message" },
    { "role": "assistant", "content": "Earlier reply" }
  ]
}

Agent actions

  • send_email

    Sends a transactional email (to, subject, body) from your verified domain.

  • place_call

    Places an outbound call (to in E.164 format, script) and speaks the message.

  • capture_lead

    Stores a qualified lead: name, contact, interest, urgency.

  • escalate_to_human

    Queues the conversation for a teammate with a reason and priority.

Each action returns mode: "live" when the channel is connected, or "simulated" when it is prepared and logged only.

Server-side example

python
import requests

res = requests.post(
    "https://your-nexus-hub.app/api/public/agent",
    headers={"Authorization": "Bearer " + NEXUS_API_KEY},
    json={
        "agent": "operations",
        "message": "Call +2348012345678 and confirm tomorrow's 10am delivery",
        "context": "Nexus Logistics dispatch desk.",
    },
    timeout=60,
)
print(res.json()["reply"])

Drop-in website widget

html
<script>
  async function askNexus(message) {
    const res = await fetch("https://your-nexus-hub.app/api/public/agent", {
      method: "POST",
      headers: { "Content-Type": "application/json", Authorization: "Bearer " + KEY },
      body: JSON.stringify({ agent: "support", message }),
    });
    const data = await res.json();
    document.querySelector("#nexus-reply").textContent = data.reply;
  }
</script>

Errors

  • 400The request body failed validation. The response lists the invalid fields.
  • 401Missing or wrong API key in the Authorization header.
  • 502The agent run failed upstream. Safe to retry once after a short pause.