> For the complete documentation index, see [llms.txt](https://docs.contextual.io/documentation-and-resources/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/agents-api.md).

# Agents API

Start, stop, restart, and check the running deployments of your Agents from code.

The Agents API controls and checks the running deployments of your [Agents](https://docs.contextual.io/documentation-and-resources/components-and-data/agents.md). Use it from scripts and backend services that operate Agents. For example, a maintenance script can stop an Agent and start it again afterward, or a monitoring job can check that its instances are running. The CLI's `ctxl agents instances` and `ctxl agentmeta` commands also use it to check an Agent's instances and to list the available Agent sizes, images, and npm packages.

Agent definitions are Records of the `agent` Object Type. Create, change, and delete them through the [Native Object API](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/native-object-api.md) at `/api/v1/agent`. In the Admin Console, you manage Agents under **Operate > Agents**.

## What you can do

* Check an Agent's instances, their status, and when each started.
* Start, stop, or restart one Agent, or several Agents at once.
* Read and change an Agent's log level.
* List the Agent sizes, runtime image versions, and npm packages available to your tenant.
* Run a scheduled Agent on demand through its `manual-run` [Action](https://docs.contextual.io/documentation-and-resources/components-and-data/object-types/object-type-details/actions.md) in the Native Object API.

The reference also lists operations that the platform calls when an Agent Record changes: `POST /agents`, `PUT /agents/{agentId}`, `DELETE /agents/{agentId}`, and the `[\$]event` operations. These lifecycle callbacks aren't an interface for editing Agents, so don't call them directly. They don't create, change, or delete the Agent Record, and some act on the running deployment without updating the Record. The platform calls them for you when you create, change, or delete an Agent Record through the [Native Object API](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/native-object-api.md).

## Base URL and reference

* **API base URL:** `https://agents.<tenant-id>.my.contextual.io/api/v1`
* **Swagger reference:** [Agents API reference](https://agents.prod-001.prod.contextual.io/api-docs/)
* **Raw OpenAPI:** [openapi.json](https://agents.prod-001.prod.contextual.io/api-docs/openapi.json)

Replace `<tenant-id>` with the [tenant ID from your Tenant Workspace URL](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/authentication-and-permissions.md#identify-the-tenant). On the API base URL, the hostname identifies your tenant, so the `x-org-id` header is optional. If you send it, its value must match the hostname.

Replace `<agent-id>` with the Agent's ID, shown in the **Agent ID** column of the **Agents** list. In an Agent Record, this is the `name` field.

The OpenAPI document uses the relative server `/api/v1`. When you import it into an API client or AI tool, set the server to the API base URL.

## Authentication and permissions

Send an access token from a tenant API Key in the `Authorization: Bearer <access-token>` header. To get one, follow [Get an access token](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/authentication-and-permissions.md#get-and-use-an-access-token), which also explains when you can reuse a token with other APIs.

Set the key's permissions on its [Permissions tab](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/authentication-and-permissions.md#assign-permissions), under **Service components → Agents**. The Native Object API uses the same permissions for Agent Records.

Each Agents API operation on this page that targets a specific Agent reads that Agent's Record with your token. A bulk request reads the Records of the Agents it selects. Include **Read** for these operations.

The `manual-run` Action also needs **Read** in addition to **Execute**: the Action calls the Agents API, which reads the Agent Record using your token.

| Task                                               | Permissions to grant                                   |
| -------------------------------------------------- | ------------------------------------------------------ |
| Check an Agent's instances or read its log level   | **Service components → Agents → Read**                 |
| Change one Agent's log level                       | **Service components → Agents → Read** and **Update**  |
| Run a scheduled Agent with the `manual-run` Action | **Service components → Agents → Read** and **Execute** |

## Request and response details

* Request and response bodies are JSON.
* Start, stop, and restart return `204` when the request is accepted. The Agent then changes state in the background. Check its instances to follow the change. Starting an Agent that isn't stopped, or stopping one that already is, returns `400`. Scheduled Agents can't be restarted.
* `PUT /agents` applies an `action` (`start`, `stop`, `restart`, or `set-log-level`) to the Agents listed in `ids`. **If you omit `ids` or send an empty list, the request selects every Agent returned by the Native Object API for your tenant.** Of the selected Agents, `start` acts only on stopped ones. `stop`, `restart`, and `set-log-level` skip stopped ones, and `restart` also skips scheduled Agents.
* `GET /agents/{agentId}/instances` returns instances in `items`, each with a `name`, `status`, `createdAt`, and `startedAt`. [Operations](https://docs.contextual.io/documentation-and-resources/components-and-data/agents/agent-details/operations.md) explains `status` values such as `Running` and `OOMKilled`.
* To run a scheduled Agent on demand, send `PATCH https://native-object.<tenant-id>.my.contextual.io/api/v1/agent/<agent-id>/actions/manual-run` with the body `{}`. The Agent must not be stopped.

## Example request

This request lists an Agent's instances:

```bash
curl "https://agents.<tenant-id>.my.contextual.io/api/v1/agents/<agent-id>/instances" \
  --header "Authorization: Bearer <access-token>"
```

Replace `<access-token>` with your access token. A successful response has status `200` and one entry in `items` for each instance.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/agents-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
