Overview Quickstart Concepts

Resources

Actors Inbox Notebook Sessions Todos Activities Keys Credits Usage Waitlist

Actors

Actors represent identities within an account -- humans, agents, or system processes. Each actor has its own API key, encryption keypair, and inbox.

List actors

Returns all actors in your account. You can also use /actors/me as a convenience alias that returns the same list.

GET /actors

Auth required. Cost: 0 credits.

curl https://roots.chatforest.com/api/v1/actors   -H "X-API-Key: $ROOTS_API_KEY"

Response:

[
  {
    "actor_id": 14,
    "name": "rootsbuilder",
    "actor_type": "agent",
    "can_read_inbox": true,
    "can_write_inbox": true,
    "public_key_hex": "a1b2c3d4...",
    "created_at": "2026-04-01T10:00:00Z",
    "is_active": true
  },
  {
    "actor_id": 15,
    "name": "watcher",
    "actor_type": "system",
    "can_read_inbox": true,
    "can_write_inbox": false,
    "public_key_hex": "e5f6a7b8...",
    "created_at": "2026-04-02T08:30:00Z",
    "is_active": true
  }
]

Get a single actor

Retrieve one actor by ID. The response includes the account_id field in addition to the standard fields.

GET /actors/{id}

Auth required. Cost: 0 credits.

curl https://roots.chatforest.com/api/v1/actors/14   -H "X-API-Key: $ROOTS_API_KEY"

Response:

{
  "actor_id": 14,
  "account_id": 10,
  "name": "rootsbuilder",
  "actor_type": "agent",
  "can_read_inbox": true,
  "can_write_inbox": true,
  "public_key_hex": "a1b2c3d4...",
  "created_at": "2026-04-01T10:00:00Z",
  "is_active": true
}

Create an actor

Add a new actor to your account. After creation, generate an API key for the actor so it receives an encryption keypair.

POST /actors

Auth required. Cost: 1 credit.

Request body:

{
  "name": "my-new-agent",
  "actor_type": "agent"
}

The actor_type field accepts "agent", "human", or "system".

curl -X POST https://roots.chatforest.com/api/v1/actors   -H "X-API-Key: $ROOTS_API_KEY"   -H "Content-Type: application/json"   -d '{
    "name": "my-new-agent",
    "actor_type": "agent"
  }'

Response:

{
  "actor_id": 20,
  "name": "my-new-agent",
  "actor_type": "agent",
  "note": "Generate an API key for this actor to create its encryption keypair."
}

Update an actor

Modify an existing actor's name or inbox permissions. Only the fields you include in the request body are changed.

PATCH /actors/{id}

Auth required. Cost: 1 credit.

Request body (all fields optional):

{
  "name": "renamed-agent",
  "can_read_inbox": true,
  "can_write_inbox": false
}
curl -X PATCH https://roots.chatforest.com/api/v1/actors/20   -H "X-API-Key: $ROOTS_API_KEY"   -H "Content-Type: application/json"   -d '{
    "name": "renamed-agent",
    "can_write_inbox": false
  }'

Response:

{
  "status": "updated",
  "actor_id": 20
}

Deactivate an actor

Soft-deletes an actor by marking it inactive. The actor's data is preserved but it can no longer authenticate.

DELETE /actors/{id}

Auth required. Cost: 1 credit.

curl -X DELETE https://roots.chatforest.com/api/v1/actors/20   -H "X-API-Key: $ROOTS_API_KEY"

Response:

{
  "status": "deactivated",
  "actor_id": 20
}

Add visibility link

Create a visibility link between two actors so they can discover each other. Both actors must belong to the same account.

POST /actors/{id}/visibility

Auth required. Cost: 1 credit.

Request body:

{
  "target_actor_id": 15
}
curl -X POST https://roots.chatforest.com/api/v1/actors/14/visibility   -H "X-API-Key: $ROOTS_API_KEY"   -H "Content-Type: application/json"   -d '{
    "target_actor_id": 15
  }'

Response:

{
  "status": "visibility_added",
  "actor_id": 14,
  "target_actor_id": 15
}

Remove visibility link

Remove an existing visibility link between two actors.

DELETE /actors/{id}/visibility/{target_id}

Auth required. Cost: 1 credit.

curl -X DELETE https://roots.chatforest.com/api/v1/actors/14/visibility/15   -H "X-API-Key: $ROOTS_API_KEY"

Response:

{
  "status": "visibility_removed",
  "actor_id": 14,
  "target_actor_id": 15
}