Call agents from your server

What this is

Two HTTP calls, made with your org API key:

Both answer 202 Accepted with the conversation's ID as soon as Mindset has stored your request. Neither returns the agent's reply. An agent run can take minutes, so Mindset accepts the work and runs it. Stored means it runs even if a Mindset server restarts.

To get the result somewhere, have the agent deliver it: give it a connection to your own HTTP API, to Slack, or to wherever the result belongs, and tell it in the task what to do with what it finds. The run is recorded in Mindset like any other run. See Check what happened.

If you need the reply back in the same call, connect through MCP instead. See Use your agents from Claude and other AI clients.

Before you start

• Tick Outside systems on the agent. In AMS, open the agent's availability and tick Outside systems, with the agent switched on. See Where your agent can be reached.
• An org API key for the right environment. A key works only in the environment it was created in, and it can start every live agent in that environment. See Members and API keys.
• The agent's handle, and your org and environment slugs. The agent's Triggering tab has a How to call using the API link that shows both calls with your host, slugs and handle filled in.

The examples use the host https://eu.mindset.ai, the org acme, the environment production and an agent with the handle billing-help. Replace them with yours.

Start a conversation

POST https://YOUR-MINDSET-HOST/api/v1/orgs/{orgSlug}/envs/{envSlug}/agents/{agent}/conversations

{agent} is the agent's handle, or its ID. The ID keeps working if someone renames the handle.

Send the key in the x-api-key header and the body as JSON. Every body field is optional, and an empty body (or no body) means "run this agent now".

The body is strict. Any other field is a 400.

curl -sS -X POST \
  "https://eu.mindset.ai/api/v1/orgs/acme/envs/production/agents/billing-help/conversations" \
  -H "x-api-key: $MINDSET_ORG_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "task": "Invoice INV-4471 failed to charge. Check the customer account and post what you find to the billing channel.",
    "attribution": { "ticket": "BILL-1421" },
    "idempotencyKey": "bill-1421-start"
  }'

The answer:

HTTP/1.1 202 Accepted

{ "conversationId": "3f0c2b1e-8a5d-4c1e-9b7a-2d6f4e8c1a90" }

Store conversationId if you'll send the agent more messages.

Send a follow-up message

POST https://YOUR-MINDSET-HOST/api/v1/orgs/{orgSlug}/envs/{envSlug}/agents/{agent}/conversations/{conversationId}/messages

{conversationId} is the ID the start call returned. It must be a UUID.

scriptParams belongs to the start call only. Sending it here is a 400.

curl -sS -X POST \
  "https://eu.mindset.ai/api/v1/orgs/acme/envs/production/agents/billing-help/conversations/3f0c2b1e-8a5d-4c1e-9b7a-2d6f4e8c1a90/messages" \
  -H "x-api-key: $MINDSET_ORG_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "task": "The customer has updated their card. Retry the charge.",
    "idempotencyKey": "bill-1421-card-updated"
  }'

It also answers 202 with { "conversationId": ... }, the same ID.

Make retries safe

Networks fail after a request has arrived. Without protection, a retry starts the agent a second time.

Send an idempotencyKey. Mindset runs the first call with a given key once. Every later call with the same key gets the original call's answer, the same conversationId, and runs nothing, even if the rest of the body is different. Calls without a key run every time.

• On the start call, a key belongs to one agent. The same key sent to two different agents starts two conversations.
• On the follow-up call, a key belongs to one conversation. The same key in two conversations is two messages.
• A call that's refused (a 400, 404 or 422) doesn't use up its key, so you can fix the request and retry with the same key.
• A replayed start call doesn't count against the rate limit.

Build the key from something your system already has, such as the ticket number and the step, so a retry naturally reuses it.

Node example

A complete script for Node 18 or later. Save it as start-agent.mjs and run it with MINDSET_ORG_API_KEY=... node start-agent.mjs.

const MINDSET_HOST = "https://eu.mindset.ai";
const ORG_SLUG = "acme";
const ENV_SLUG = "production";
const AGENT = "billing-help";
const API_KEY = process.env.MINDSET_ORG_API_KEY;

const base = `${MINDSET_HOST}/api/v1/orgs/${ORG_SLUG}/envs/${ENV_SLUG}/agents/${AGENT}`;

async function post(url, body) {
  for (let attempt = 1; attempt <= 5; attempt++) {
    let r;
    try {
      r = await fetch(url, {
        method: "POST",
        headers: { "x-api-key": API_KEY, "content-type": "application/json" },
        body: JSON.stringify(body),
      });
    } catch (err) {
      // Network failure: safe to retry, because the body carries an idempotencyKey.
      console.warn(`Attempt ${attempt} failed: ${err.message}`);
      await new Promise((resolve) => setTimeout(resolve, 1000 * attempt));
      continue;
    }

    if (r.status === 202) return r.json();

    const error = await r.json().catch(() => ({}));
    if (r.status === 429) {
      const wait = Number(r.headers.get("retry-after") ?? "5");
      console.warn(`Rate limited. Waiting ${wait}s.`);
      await new Promise((resolve) => setTimeout(resolve, wait * 1000));
      continue;
    }
    if (r.status >= 500) {
      await new Promise((resolve) => setTimeout(resolve, 1000 * attempt));
      continue;
    }
    // 400, 401, 403, 404, 422: retrying the same request won't help.
    throw new Error(`Mindset refused the call: ${r.status} ${error.code ?? ""} ${error.message ?? ""}`);
  }
  throw new Error("Mindset did not accept the call after 5 attempts");
}

const ticket = "BILL-1421";

const { conversationId } = await post(`${base}/conversations`, {
  task: "Invoice INV-4471 failed to charge. Check the customer account and post what you find to the billing channel.",
  attribution: { ticket },
  idempotencyKey: `${ticket}-start`,
});
console.log("Started conversation", conversationId);

await post(`${base}/conversations/${conversationId}/messages`, {
  task: "The customer has updated their card. Retry the charge.",
  idempotencyKey: `${ticket}-card-updated`,
});
console.log("Sent follow-up");

Limits

• 60 new conversations a minute per org. Over that, the start call answers 429 with a Retry-After header in seconds. Nothing was started, so retrying after that wait is a clean first attempt.
• Follow-up messages aren't rate limited. Messages to one conversation queue up and run in turn.
• task is up to 8,000 characters on both calls.

What can go wrong

Every error body is JSON with code, message and sometimes context.

A 202 means the work was accepted. If the run then fails, that shows in the conversation in AMS, not in your HTTP response.

Related

• Where your agent can be reached for the Outside systems box.
• Write a script for script parameters and values a script accepts from outside.
• Create a session for your users for the browser SDK's server call.