Agents

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 and Conventions. 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.

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.

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.

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.

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. 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.

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": "<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.

Get started

Resources

Events

Build

API reference

Who can see and change an agent

List agents

Create an agent

Change an agent

Test, then publish

Versions

Pause and archive

Give an agent to another person

Oversight list

Memories and lessons

Who can see and change an agent

List agents

Create an agent

Change an agent

Test, then publish

Versions

Pause and archive

Share an agent

Give an agent to another person

Oversight list

Memories and lessons