# Start it from your server or a schedule > Starts an agent from your backend, on a schedule or from another product's webhook, with no person in a chat. **Skill for your coding agent:** [`mindset-server-api/SKILL.md`](https://docs.mindset.ai/skills/mindset-server-api/SKILL.md) An agent is started by a person in the Hub, by your app with the agent embedded, by your server over the API, by a webhook trigger, by a schedule, by another agent, or by an AI client over MCP. ## 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. ``` Skill: [mindset-server-api](https://docs.mindset.ai/skills/mindset-server-api/SKILL.md) ``` Run the invoice exceptions agent every weekday at 7am UTC, and let it run on a schedule. ``` Skill: [mindset-build-agent](https://docs.mindset.ai/skills/mindset-build-agent/SKILL.md) ## 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](https://docs.mindset.ai/docs/how-agents-are-started-and-reached) sets every way in side by side. > **Info:** An org API key starts agents only in its own environment and can't change your org's [compliance settings](https://docs.mindset.ai/docs/compliance). The agents it starts follow the same rules as any other. ## Start a conversation ```bash 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. | Field | What it is | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `task` | The brief, up to 8,000 characters. Leave it out when the agent's script drives the whole run | | `scriptParams` | Start values for the agent's script. Send every parameter it declares. Start call only | | `attribution` | Your own string labels, such as a ticket number. Up to 16 keys. They reach your trace export, every MCP server set to receive them, and the run's functions and scripts as `attribution.`. See [Attribution](https://docs.mindset.ai/docs/session-api#attribution) | | `idempotencyKey` | Up to 200 characters. The same key again returns the first conversation and runs nothing | 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](https://docs.mindset.ai/docs/use-your-agents-from-claude-and-other-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. > **Warning:** Schedules are versioned. Creating, changing or deleting one takes effect when you activate the version that holds it, so a deleted schedule keeps running until then. ## 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. | Status | `code` | What happened | | ------ | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | `validation_error` | An unknown field, a bad `attribution`, a `conversationId` that isn't a UUID, or `scriptParams` on a follow-up | | 401 | `unauthorized` | No `x-api-key` header | | 403 | `agent_not_available_here` | **Outside systems** isn't ticked. The message names the box | | 404 | | Wrong agent, org, environment or key scope, a switched-off or personal agent, or a conversation this key can't reach. They look the same on purpose | | 422 | `params_invalid` or `invalid_write_target` | `scriptParams` or `scriptValues` don't match what the script declares. The response names the keys | | 429 | `rate_limited` | Wait for `Retry-After` | 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. ![The Triggering tab, with Schedules above and Let another product start this agent below.](https://docs.mindset.ai/images/docs/studio/agent-triggering.png)