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

# Agents

An **agent** is an AI system you run — a support bot, a coding assistant, an autonomous workflow. Govern and Secure both accept an agent identity so decisions and incidents can be attributed to the right agent.

{% hint style="success" %}
**Registering agents is optional.** You can call every endpoint with just a free-text `agent_name`. Registering an agent gives you a stable `agent_id` and richer reporting — but it is never a prerequisite for using the API.
{% endhint %}

### Registered vs. unregistered

Every Govern and Secure call takes two optional identity fields:

| Field        | Use it when…                                                                         | Example                       |
| ------------ | ------------------------------------------------------------------------------------ | ----------------------------- |
| `agent_name` | The agent isn't registered (or you just want to label the caller).                   | `"agent_name": "billing-bot"` |
| `agent_id`   | The agent **is** registered in Maetra and you want checkpoints/incidents tied to it. | `"agent_id": "agt_5Ab2"`      |

You can send either, both, or neither. Passing `agent_id` links activity to the registered agent; `agent_name` is a human-readable label. Start with `agent_name`, and switch to `agent_id` once you register.

#### When to register

* You want per-agent dashboards, findings, and audit trails.
* You want to scope rules or policies to specific agents.
* You're onboarding an agent to formal governance.

#### When you don't need to

* You're integrating quickly or prototyping.
* The caller is a one-off script or a product surface, not a tracked agent.

### Registering an agent

Register agents in the dashboard under **Discover → Agent registry → Register agent**. Only a **name** is required; everything else (owner, environment, framework, autonomy level, tools) is optional context. On save, Maetra assigns the `agent_id` you pass to the API.

### List agents

`GET /v1/agents` — returns the agents in your workspace, newest first, with a minimal public projection. Requires the `discover:agents:read` scope.

**Query parameters**

| Param    | Description                                                                          |
| -------- | ------------------------------------------------------------------------------------ |
| `status` | Filter by `pending_review`, `registered`, `under_review`, `governed`, or `archived`. |
| `limit`  | Max agents to return, `1`–`200`. Defaults to `50`.                                   |

{% tabs %}
{% tab title="cURL" %}

```bash
curl "https://api.maetra.io/v1/agents?limit=20" \
  -H "Authorization: Bearer $MAETRA_API_KEY"
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const res = await fetch("https://api.maetra.io/v1/agents?limit=20", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.MAETRA_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`Maetra API ${res.status}`);
const data = await res.json();
console.log(data);
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
const res = await fetch("https://api.maetra.io/v1/agents?limit=20", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.MAETRA_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`Maetra API ${res.status}`);
const data = (await res.json());
```

{% endtab %}

{% tab title="Python" %}

```python
import os, requests

res = requests.get(
    "https://api.maetra.io/v1/agents?limit=20",
    headers={"Authorization": f"Bearer {os.environ['MAETRA_API_KEY']}"},
)
res.raise_for_status()
print(res.json())
```

{% endtab %}

{% tab title="Rust" %}

```rust
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let key = std::env::var("MAETRA_API_KEY")?;
    let client = reqwest::Client::new();
    let res = client
        .get("https://api.maetra.io/v1/agents?limit=20")
        .bearer_auth(&key)
        .send()
        .await?;
    let data: serde_json::Value = res.json().await?;
    println!("{data:#}");
    Ok(())
}
```

{% endtab %}

{% tab title="C++" %}

```cpp
#include <curl/curl.h>
#include <cstdlib>
#include <string>

int main() {
    CURL* curl = curl_easy_init();
    std::string auth = "Authorization: Bearer " + std::string(std::getenv("MAETRA_API_KEY"));
    struct curl_slist* headers = nullptr;
    headers = curl_slist_append(headers, auth.c_str());
    curl_easy_setopt(curl, CURLOPT_URL, "https://api.maetra.io/v1/agents?limit=20");
    curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
    curl_easy_perform(curl);   // response is written to stdout by default
    curl_slist_free_all(headers);
    curl_easy_cleanup(curl);
    return 0;
}
```

{% endtab %}

{% tab title="Java" %}

```java
import java.net.URI;
import java.net.http.*;

var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.maetra.io/v1/agents?limit=20"))
    .header("Authorization", "Bearer " + System.getenv("MAETRA_API_KEY"))
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```

{% endtab %}
{% endtabs %}

#### Response

```json
{
  "agents": [
    {
      "id": "agt_5Ab2",
      "name": "billing-bot",
      "description": "Handles customer refunds.",
      "status": "registered",
      "autonomy_level": "L3",
      "risk_level": "medium",
      "environment": "production",
      "created_at": "2026-07-01T09:12:00.000Z",
      "updated_at": "2026-07-06T22:04:00.000Z"
    }
  ]
}
```

| Field                       | Type           | Description                                                             |
| --------------------------- | -------------- | ----------------------------------------------------------------------- |
| `id`                        | string         | The agent's ID — pass as `agent_id` to other endpoints.                 |
| `name`                      | string         | Human-readable name.                                                    |
| `description`               | string \| null | Optional description.                                                   |
| `status`                    | enum           | `pending_review`, `registered`, `under_review`, `governed`, `archived`. |
| `autonomy_level`            | enum           | `L0`–`L5`.                                                              |
| `risk_level`                | enum           | `low`, `medium`, `high`, `critical`, `unknown`.                         |
| `environment`               | enum           | `production`, `staging`, `development`, `unknown`.                      |
| `created_at` / `updated_at` | string         | ISO 8601 timestamps.                                                    |