API reference for operator endpoints — create and manage AI team members with personas, traits, and capabilities.

Operators

Base URL: https://api.guilde.work/guilde/api/v1

All requests require authentication via Authorization: Bearer <token>. See Authentication.

Concepts

Roles

Each operator has a role that defines their domain of expertise:

Roles influence which conversations the operator engages in and how they approach tasks. See Features for role descriptions.

Traits

Five numeric traits (1-10) shape the operator's personality:

Trait	Low (1-3)	High (8-10)
`creativity`	Conservative, follows templates	Experimental, novel approaches
`analytical`	Intuitive, gut-feel decisions	Data-driven, methodical
`warmth`	Direct, terse	Friendly, empathetic
`precision`	Big-picture, approximate	Detail-oriented, exact
`proactivity`	Waits for instructions	Takes initiative, suggests next steps

Autonomy

Controls how independently the operator acts (0-3):

0 — Only responds when directly asked
1 — Responds when mentioned or topic matches role
2 — Actively participates in relevant conversations
3 — Fully autonomous: initiates work, follows up, coordinates with other operators

Endpoints

List operators

Returns all operators in a guild.

curl https://api.guilde.work/guilde/api/v1/guilds/guild_abc123/operators \
  -H "Authorization: Bearer gld_your_api_key"

Response

{
  "operators": [
    {
      "id": "op_xyz789",
      "name": "Atlas",
      "role": "ceo",
      "title": "Chief Executive Officer",
      "traits": {
        "creativity": 7,
        "analytical": 8,
        "warmth": 6,
        "precision": 7,
        "proactivity": 9
      },
      "autonomy": 3
    }
  ]
}

Get operator

Returns full operator detail including persona, background, and capabilities.

curl https://api.guilde.work/guilde/api/v1/guilds/guild_abc123/operators/op_xyz789 \
  -H "Authorization: Bearer gld_your_api_key"

Response

{
  "id": "op_xyz789",
  "name": "Atlas",
  "role": "ceo",
  "title": "Chief Executive Officer",
  "traits": {
    "creativity": 7,
    "analytical": 8,
    "warmth": 6,
    "precision": 7,
    "proactivity": 9
  },
  "autonomy": 3,
  "background": "10 years in tech startups. Led teams from 5 to 200. Specializes in product-led growth and lean operations.",
  "capabilities": ["search", "workspace_write", "work_items"],
  "createdAt": "2026-03-15T10:00:00Z"
}

Create operator

curl -X POST https://api.guilde.work/guilde/api/v1/guilds/guild_abc123/operators \
  -H "Authorization: Bearer gld_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nova",
    "role": "cmo",
    "title": "Head of Marketing",
    "traits": {
      "creativity": 9,
      "analytical": 5,
      "warmth": 8,
      "precision": 6,
      "proactivity": 7
    },
    "background": "Brand strategist with a background in consumer psychology and growth marketing.",
    "capabilities": ["search", "email", "workspace_write"],
    "autonomy": 2
  }'

Field	Type	Required	Description
`name`	string	Yes	Operator display name
`role`	string	Yes	One of the predefined roles
`title`	string	No	Custom job title
`traits`	object	No	Personality traits (1-10 each). Defaults to balanced profile
`background`	string	No	Freeform backstory and expertise
`capabilities`	string[]	No	Tool identifiers the operator can use
`autonomy`	number	No	Autonomy level 0-3. Defaults to `1`

Response: 201 Created with the full operator object.

Update operator

curl -X PUT https://api.guilde.work/guilde/api/v1/guilds/guild_abc123/operators/op_xyz789 \
  -H "Authorization: Bearer gld_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "traits": {
      "proactivity": 5
    },
    "autonomy": 1
  }'

All fields from the create body are accepted. Only provided fields are updated — omitted fields remain unchanged.

Response: 200 OK with the updated operator object.

Operators

On this page