> ## Documentation Index > Fetch the complete documentation index at: https://docs.impellabs.tech/llms.txt > Use this file to discover all available pages before exploring further. # Agents > Create and change agents, publish a version, pause, give to another person and share. An agent answers customers or does work for a person. Each change to an agent saves a new fixed version. You test the newest version, then publish it. The live version is the one that answers. All routes are under `https://api.impellabs.tech/api/v1`. Send `Authorization: Bearer imp_...` on each request. See [Authentication](https://docs.impellabs.tech/api/authentication.md) and [Conventions](https://docs.impellabs.tech/api/conventions.md). The API reference lists every field. ## Who can see and change an agent An agent is private to its owner until the owner shares it. A token acts as the person who made it. | Level | How a person gets it | What it allows | | - | - | - | | Owner | They own the agent. | Everything, and sharing. | | Can edit | The owner shared it with "Can edit". | Read, change, publish and restore. | | Can use | The owner shared it with "Can use". | Read it, read its versions, and try it in the test chat. | An agent that a person may not read answers `404` with `This agent does not exist.` Owners and admins keep oversight only. For an agent they cannot read, they see its name, owner, kind, status, sharing mode and spend over 30 days. They never see its instructions or its other content. They can pause it, archive it, give it to another person, and make it private. They cannot edit it by role. When an owner or an admin acts on an agent they do not own, the agent's owner is told. A Chief of Staff is private to its person. It cannot be shared, given away, paused or archived through these routes. Customer-facing work is done by agents that a person creates. ## List agents `GET /agents` returns an array of the agents the person may read. An agent they cannot read is not in it. An owner or an admin gets the other agents from `GET /agents/oversight`. ```bash theme={null} curl "https://api.impellabs.tech/api/v1/agents" \ -H "Authorization: Bearer imp_..." ``` Each agent has `id`, `kind`, `name`, `status` (`draft`, `active` or `paused`), `agent_type`, `category`, `owner_id`, `department_id`, `live_version`, `latest_version`, `unpublished_changes`, `needs_test`, the settings of the newest version (`instructions`, `tone`, `model`, `tools`, `knowledge_scope`, `knowledge_groups`, `guardrails`, `memory`, `sub_agents`, `skills`, `hooks`, `abilities`, `voice`, `channel_prompts`, `handoff` and more), and the access fields below. | Field | Meaning | | - | - | | `my_level` | `owner`, `edit` or `use`. | | `can_edit` | `true` when you may change it. | | `mine` | `true` when you own it. | | `sharing_mode` | `private`, `people` or `everyone`. | | `sharing` | Who has it. Only the owner and people with "Can edit" see it. Others get `null`. | | `owner_name` | The name of the owner. | `GET /agents/types` lists the agent types and categories the create route accepts, each with an `available` flag for a type. ## Create an agent `POST /agents`. The agent starts private, in status `draft`, with a first version. | Field | Meaning | | - | - | | `name` | Required. 60 characters at most. | | `kind` | `personal` (the default), `department` or `company`. A department agent needs `department_id`. | | `agent_type` | A type that is available. The default is `communication`. | | `category` | For a `communication` agent: a slug from `GET /agents/types`. The default is `information`. | | `instructions`, `tone`, `guardrails`, `memory`, `tool_guidance` | Text. `instructions` has 20000 characters at most. | | `model` | A model name. Blank means the workspace default. | | `tools` | A list of capability keys such as `knowledge.read`. | | `knowledge_scope` | `selected`, `all_company` or `none`. | | `knowledge_groups` | A list of knowledge group ids. | | `avatar_key` | A stock portrait, `staff-1` to `staff-50`, or an empty string. | A personal agent needs the right to add agents for yourself. A department agent needs a manager of the department or an admin. A company agent needs an owner or an admin. Others get `403`. ```bash theme={null} curl -X POST "https://api.impellabs.tech/api/v1/agents" \ -H "Authorization: Bearer imp_..." \ -H "Content-Type: application/json" \ -d '{ "name": "Front desk", "kind": "personal", "agent_type": "communication", "category": "information", "instructions": "Answer questions about opening hours and prices. Ask for a person when you are not sure.", "knowledge_scope": "all_company" }' ``` The reply is `201` with the agent. In the reply, `status` is `draft`, `latest_version` is `1`, `live_version` is `null`, `sharing_mode` is `private` and `needs_test` is `true`. ## Change an agent `PATCH /agents/{agent_id}` needs "Can edit" or ownership. Send only the fields you change. A change to instructions, tone, model, tools, knowledge or other version settings saves a new fixed version. `note` (200 characters) labels the change. The name and the reply settings (`pause_when_member_replies`, `resume_after_minutes`, `notify_when_unsure`) apply at once and do not make a version. The `agent_type` is fixed once the agent is no longer a draft. ```bash theme={null} curl -X PATCH "https://api.impellabs.tech/api/v1/agents/5e77a1b0-3c2d-4e8f-9a6b-0d1c2b3a4f55" \ -H "Authorization: Bearer imp_..." \ -H "Content-Type: application/json" \ -d '{"instructions": "Answer questions about opening hours and prices.", "note": "Shorter instructions"}' ``` A value that is not valid answers `400` with the field name. Someone who can read the agent but not edit it gets `403` with `You cannot change this agent.` ## Test, then publish `POST /agents/{agent_id}/publish` makes the newest version the live version and sets the status to `active`. It needs "Can edit" or ownership. The newest version must be tested first: send a message to `POST /agents/{agent_id}/test/messages` with `{ "text": "..." }`, then publish. Without a test the reply is `400` with `detail` like `Test version 2 in the test chat first. Then publish it.` Publish can also fail with `400` when a check of the version fails. ```bash theme={null} curl -X POST "https://api.impellabs.tech/api/v1/agents/5e77a1b0-3c2d-4e8f-9a6b-0d1c2b3a4f55/publish" \ -H "Authorization: Bearer imp_..." ``` ## Versions * `GET /agents/{agent_id}/versions` lists the versions, newest first: `number`, `note`, `created_at`, `by`, `live`, `tested`. Anyone who can read the agent may call it. * `POST /agents/{agent_id}/versions/{number}/restore` copies an earlier version into a new draft version. The live version stays. It answers `201` with the agent. It needs "Can edit". An unknown number answers `404`. ## Pause and archive * `POST /agents/{agent_id}/pause` stops a live agent. Only a live agent can be paused; others get `400`. Publish again to start it. * `DELETE /agents/{agent_id}` archives the agent and answers `204`. The owner, a person with "Can edit", and an owner or an admin (oversight) may use both routes. ## Share an agent `PATCH /agents/{agent_id}/sharing` with `{ "sharing": { ... } }`. | Field | Meaning | | - | - | | `mode` | Required. `private`, `people` or `everyone`. | | `members` | An object of member id and level, for `people`. | | `departments` | An object of department id and level, for `people`. | | `everyone` | The level for `everyone`: `use` or `edit`. The default is `use`. | A level is `use` ("Can use") or `edit` ("Can edit"). Each id must be a person or a department of this workspace. The owner is not listed. A `private` agent has no members. ```bash theme={null} curl -X PATCH "https://api.impellabs.tech/api/v1/agents/5e77a1b0-3c2d-4e8f-9a6b-0d1c2b3a4f55/sharing" \ -H "Authorization: Bearer imp_..." \ -H "Content-Type: application/json" \ -d '{"sharing": {"mode": "people", "members": {"a2c4f1d0-6b3e-4a7d-9e52-1c0b8d7e6f10": "use"}, "departments": {}}}' ``` Who may change sharing: | Caller | Allowed | | - | - | | The owner | Any sharing. | | A person with "Can edit" | Only a sharing that reaches the same people or fewer, at the same levels or lower. Otherwise `403`. | | An owner or an admin, not the owner of the agent | Only `private`. Otherwise `403`. The owner is told. | | Anyone else | `404`, or `403` if they can read the agent. | ## Give an agent to another person `POST /agents/{agent_id}/transfer` with `{ "member_id": "" }`. The owner, or an owner or an admin of the workspace, may do it. The new owner must be an active member and must not own the agent already; otherwise `400`. The new owner is told. ## Oversight list `GET /agents/oversight` is for owners and admins. Others get `403`. It returns a page for every agent except a Chief of Staff, with `id`, `kind`, `name`, `status`, `agent_type`, `owner_id`, `owner_name`, `sharing_mode`, `spent_30d` and the access flags, and never the instructions. Filters: `status`, `sharing`, `q`. Sort: `name`, `owner`, `status`, `sharing`, `spend`, with `order`, `page` and `page_size`. ## Memories and lessons An agent keeps short memories and lessons. These routes need "Can edit" to write and read access to read: `GET` and `POST /agents/{agent_id}/memories`, `PATCH` and `DELETE /agents/{agent_id}/memories/{memory_id}`, `GET` and `POST /agents/{agent_id}/lessons`, and `DELETE /agents/{agent_id}/lessons/{lesson_id}`. A memory has 300 characters at most and a lesson 1000. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.