Start it from your server or a schedule

Ask your coding agent#

When a payment fails in our billing service, start the billing-help agent with the invoice number and have it post what it finds to #billing. Make retries safe.

Run the invoice exceptions agent every weekday at 7am UTC, and let it run on a schedule.

What gets built#

• From your server: two HTTP calls with an org API key, one to start a conversation and one to send it a follow-up. Both answer 202 Accepted with the conversation's ID as soon as Mindset has stored the request. Neither returns the reply, because a run can take minutes.
• A schedule on the agent: every N minutes (30 at the shortest), daily or weekly, at a time of day in UTC.
• A webhook source, for a product you don't control, such as a CRM. It signs each delivery with its secret instead of holding your key. The first delivery teaches Mindset how the vendor signs, and doesn't start the agent.

Each needs its box ticked on the agent's availability: Outside systems, Schedules or Triggers. How agents are started and reached sets every way in side by side.

Start a conversation#

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"
  }'

HTTP/1.1 202 Accepted

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

The agent's Triggering tab has How to call using the API, with your host, org, environment and agent handle filled in. {agent} is the handle, or the ID, which survives a rename.

Every field is optional, and any other field is a 400. To send a follow-up, POST to .../conversations/{conversationId}/messages with a task, and scriptValues for keys the running script accepts from outside.

What you decide#

• The environment. An org API key, created under Settings → API keys, works only in its own environment and can start every live agent there. It's shown once, so put it straight into your secrets manager.
• The idempotency key. Build it from something your system already has, such as the ticket number and the step, so a retry reuses it. A start key belongs to one agent, and a follow-up key to one conversation. A refused call (400, 404 or 422) doesn't use up its key.
• Where the result goes. Give the agent a connection to your API, Slack or email, and say in the task what to do with what it finds. For the reply in the same call, connect over MCP instead: see Use your agents from AI clients.
• How often a schedule runs. Match how often the data changes. Hourly against data that changes daily costs 24 times what it needs to.

Limits and errors#

60 new conversations a minute per org. Over that, the start call answers 429 with a Retry-After header in seconds, and nothing was started. Follow-ups aren't rate limited, and queue up in turn.

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

Done when#

• A run appears in Log with the trigger that started it.
• A retry with the same idempotencyKey returned the same conversation ID and ran nothing.
• The Triggering tab doesn't say "Not running yet" for any schedule you need.
• The result arrived where you told the agent to deliver it.

In the Studio#

On the agent's Triggering tab, add a schedule under Schedules, then save and activate the version. Run now fires it at once: on the active version for real, or on any other saved version as a rehearsal, marked as one in the run history. Let another product start this agent → Set up an inbound source creates a webhook source, whose page holds the delivery address to paste into the vendor's console.