Quickstart

Create an agent, send a chat request, and render your first structured response.

This guide uses the chat endpoint because it is the main integration path for Galadri agents. The examples are safe to paste into a server-side Node.js runtime or a terminal.

1. Create an API key

Go to the API Keys page in the Galadri Console and click Create API Key. Copy the key immediately. API keys are shown once and start with gld_.

Keep keys server-side

Call Galadri from your backend, serverless function, or another trusted server-side runtime. Do not put API keys in browser code, mobile apps, or public frontend bundles.

2. Create an agent

Go to the Agents page and create a new agent. Give it a name, add a short system prompt, and copy the agent slug shown in the console. You will use that slug as the agent value in API requests.

Start simple

For the first request, keep Google Maps Search enabled and leave Streaming on. New agents also default to read/write access for managed end-user data, which lets you try the saved vehicle example below.

3. Send your first request

Replace gld_your_api_key with your actual key, and my-agent with your agent's slug.

Use your own application's stable user ID for end_user_id. Galadri automatically creates or resolves the internal end-user record for that ID and scopes stored data to it.

curl streaming request

curl -N -X POST https://api.galadri.com/v1/chat \
  -H "Authorization: Bearer gld_your_api_key" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "agent": "my-agent",
  "message": "Find oil change shops near Phoenix, AZ",
  "end_user_id": "user-123"
}
JSON

JavaScript server-side fetch

async function askGaladri() {
  const response = await fetch("https://api.galadri.com/v1/chat", {
    method: "POST",
    headers: {
      "Authorization": "Bearer gld_your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      agent: "my-agent",
      message: "Find oil change shops near Phoenix, AZ",
      end_user_id: "user-123",
    }),
  });

  if (!response.ok) {
    const errorBody = await response.text();
    throw new Error(`Galadri request failed (${response.status}): ${errorBody}`);
  }

  if (!response.body) {
    throw new Error("Missing response body");
  }

  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let buffer = "";

  while (true) {
    const { done, value } = await reader.read();
    if (done) return;

    buffer += decoder.decode(value, { stream: true });
    const lines = buffer.split("\n");
    buffer = lines.pop() || "";

    for (const line of lines) {
      if (!line.startsWith("data: ")) continue;

      const payload = line.slice(6);
      if (payload === "[DONE]") return;

      const event = JSON.parse(payload);

      if (event.type === "content") {
        process.stdout.write(event.content);
      }

      if (event.type === "tool_result") {
        console.log("\nStructured results:", event.results.length);
      }

      if (event.type === "data_saved") {
        console.log("\nData saved:", event.mutations);
      }
    }
  }
}

await askGaladri();

4. Read the response

If the agent's Streaming capability is enabled, the API returns a streaming response using Server-Sent Events (SSE). You will receive events as they happen: session creation, structured result data, assistant text, saved data, and usage.

Example SSE events

data: {"type":"session","session_id":"550e8400-e29b-41d4-a716-446655440000","is_new":true}

data: {"type":"tool_result","id":"tc_1","results":[{"tool":"google-maps-search","status":"success","data":{"results":[{"_id":"place_0","name":"Valvoline Instant Oil Change","address":"123 Camelback Rd, Phoenix, AZ","rating":"4.6 stars (218 reviews)"}]}}]}

data: {"type":"content","content":"I found several oil change shops near Phoenix, AZ:\n\n"}
data: {"type":"content","content":"1. **Valvoline Instant Oil Change**: 4.6 stars, 2.1 mi away\n"}

data: {"type":"usage","prompt_tokens":1250,"completion_tokens":340,"thinking_tokens":0,"cost_micro_usd":418723,"cost_cents":42}

data: [DONE]

Non-streaming mode

If you prefer a single JSON response, set "overrides": { "streaming": false } in the request body. Agents with Streaming disabled already use JSON mode by default. See the Chat endpoint reference for the full response shape.

5. Save user data

Galadri can store end-user data such as vehicles, documents, milestones, and schedules. If your agent has write access to the Vehicles table, ask it to save a vehicle:

curl

curl -N -X POST https://api.galadri.com/v1/chat \
  -H "Authorization: Bearer gld_your_api_key" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "agent": "my-agent",
  "message": "Add my 2020 Toyota Camry SE, VIN 4T1BF1FK5LU123456, with 45000 miles",
  "end_user_id": "user-123"
}
JSON

On success, the stream includes a data_saved event with the saved record. You can also manage the same data directly through the REST endpoints.

Common errors

Field	Type	Description
`401`	`Unauthorized`	Missing, malformed, revoked, or disabled API key. Check the Authorization header.
`402`	`Payment Required`	The organization has no available credits. Add credits in the console billing page.
`404`	`Not Found`	The agent slug is wrong, the agent is inactive, or the session_id does not belong to this end user.
`429`	`Rate Limited`	Too many requests for this API key. Wait for the Retry-After value before retrying.

Next steps

Authentication - API key management, rate limits, and error codes
Chat endpoint reference - Full request/response docs, streaming events, sessions
Rich Results - Render maps, cards, route views, and saved-data cards
Data Model - Vehicle, document, milestone, and schedule tables
Tools, Skills, and Hooks - Agent capabilities, provider setup, and runtime hooks

AuthenticationNext