# Run via API

> Call your agents from your own code with an API key.

Source: https://cotera.co/docs/deploy/run-via-api

---

Everything you can do with an agent in the app, you can do over HTTPS: run agents, create conversations, send messages, and read results from your own systems.

## Authenticate

1. In Cotera, open **Settings → API Keys** and create a key (`sk_…`). The key carries your user's org access.
2. Send it as a Bearer token:

```bash
curl https://app.cotera.co/api/v1/resource/agent/{agentId}/invoke \
  -H "Authorization: Bearer sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "input": { "company_name": "Acme Corp" } }'
```

## The core endpoints

* `POST /api/v1/resource/agent/{id}/invoke` runs an agent with input and returns its (structured) result
* `POST /api/v1/resource/chat` creates a conversation
* `POST /api/v1/resource/chat/{id}/messages` sends messages to it
* `GET /api/v1/resource/chat/{id}/status` checks whether a run is still going

## Full reference

The complete guide — the agent object, tools, and worked create → invoke → batch examples — is the **[Agent API reference](https://cotera.co/docs/reference/api.md)**.

If you're generating a client, the machine-readable OpenAPI JSON is at [`app.cotera.co/api/docs/public-json`](https://app.cotera.co/api/docs/public-json).

## Things to know

* Agent runs can take a while. An agent doing real work with tools is not a sub-second RPC. For event-shaped integrations, a [webhook trigger](https://cotera.co/docs/deploy/kick-off-from-a-webhook.md) is usually a better fit than calling and polling.
* Define [structured output](https://cotera.co/docs/quickstart.md#5-define-the-output) on agents you call from code, so you parse fields instead of prose.