Quickstart

Connect an agent and send your first message in 5 minutes

Overview

This guide walks you through creating an agent, authenticating, and sending your first message — all with plain HTTP calls. No SDK required.

1. Create an agent

Create an agent in the Nod app (mobile or web). You'll get two credentials:

Credential	Format	Example
Agent ID	agt_<16 hex chars>	agt_a1b2c3d4e5f6g7h8
Secret	nod_<40 hex chars>	nod_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

The secret is shown only once. Store it securely — it cannot be retrieved later.

2. Send a message

Use the agent event endpoint to send a message. This example uses cURL, but any HTTP client works.

Bash

curl -X POST https://api.asknod.ai/api/agent/events \
  -H "Content-Type: application/json" \
  -H "X-Nod-Agent-Id: agt_a1b2c3d4e5f6g7h8" \
  -H "X-Nod-Secret: nod_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0" \
  -d '{"type":"message","text":"Hello from my agent!"}'

Open the Nod app — you'll see "Hello from my agent!" in the conversation.

Node.js

TypeScript

const AGENT_ID = "agt_a1b2c3d4e5f6g7h8";
const AGENT_SECRET = "nod_a1b2c3d4...";
const API_URL = "https://api.asknod.ai";

async function sendEvent(event: Record<string, unknown>) {
  const res = await fetch(`${API_URL}/api/agent/events`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Nod-Agent-Id": AGENT_ID,
      "X-Nod-Secret": AGENT_SECRET,
    },
    body: JSON.stringify(event),
  });
  return res.json();
}

// Send a message
await sendEvent({ type: "message", text: "Hello from my agent!" });

Python

import requests

AGENT_ID = "agt_a1b2c3d4e5f6g7h8"
AGENT_SECRET = "nod_a1b2c3d4..."
API_URL = "https://api.asknod.ai"

def send_event(event: dict):
    return requests.post(
        f"{API_URL}/api/agent/events",
        headers={
            "Content-Type": "application/json",
            "X-Nod-Agent-Id": AGENT_ID,
            "X-Nod-Secret": AGENT_SECRET,
        },
        json=event,
    ).json()

# Send a message
send_event({"type": "message", "text": "Hello from my agent!"})

3. Ask for approval

Send a decision request. The user sees it as an interactive card in the Nod app.

Node.js

await sendEvent({
  type: "decision",
  title: "Deploy to production?",
  description: "Build #42 is ready. All tests passed.",
  kind: "approval",
});
// => { "status": "ok", "decision_id": "dec_xyz" }

Python

send_event({
    "type": "decision",
    "title": "Deploy to production?",
    "description": "Build #42 is ready. All tests passed.",
    "kind": "approval",
})
# => {"status": "ok", "decision_id": "dec_xyz"}

The user taps Approve or Reject on their phone. To receive the response, you can either:

WebSocket — listen for decision_resolved events (see Connections)
Webhook — Nod delivers the resolution to your webhook_url(see Webhooks)

4. Ask a question

You can also send choice or free-text requests:

Choice request

await sendEvent({
  type: "decision",
  title: "Database?",
  description: "Which database should I use for this project?",
  kind: "choice",
  options: ["PostgreSQL", "SQLite", "MongoDB"],
});

Free-text question

await sendEvent({
  type: "decision",
  title: "Project name?",
  description: "What should I name the new project?",
  kind: "question",
});

Next steps

You've sent a message and created a request. Here's where to go next:

Connections — Set up a persistent WebSocket connection for real-time communication
Requests & Decisions — Learn about all four request types and how they work
Tasks — Schedule recurring agent work or trigger tasks from external webhooks
API Reference — Full endpoint documentation
CLI — See our open-source reference implementation for Claude Code