---
title: "Set or clear the agent's job title"
method: PATCH
path: "/agents/{id}/role"
tags: ["Agents"]
---

# Set or clear the agent's job title

`PATCH /agents/{id}/role`

## Request

- Base URL: `https://api.atako.ai`
- URL: `https://api.atako.ai/agents/{id}/role`
- Auth: HTTP bearer

Owner of the agent, or an admin of the owner's company. A plain teammate (who can still view and chat with the agent) gets 404. `role: null` (or a blank string) CLEARS the title — a titleless agent is a normal state, not an error. The org chart the agent reads every turn uses `team_positions.title` first and falls back to this. Nothing is pushed: the change reaches the agent on its next turn.

## Path parameters

- `id` string, required

## Request body

- object
  - `role` string, nullable, required

## Response `200`

- object
  - `role` string, nullable

## Other responses

- `400`: role must be a string or null / role must be at most 120 characters
- `401`: Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).
- `404`: Unknown agent, or the caller is neither its owner nor an admin of the owner's company.

---

[API](https://skmtc.dev/atako/apis/atako-api.md) · [All operations](https://skmtc.dev/atako/apis/atako-api/llms.txt) · [OpenAPI document](https://skmtc.dev/atako/apis/atako-api/revisions/aa555c56fbd7?raw)