Skip to main content
PUT
/
agents
/
{id}
cURL
curl --request PUT \
  --url https://gobii.ai/api/v1/agents/{id}/ \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "name": "<string>",
  "charter": "<string>",
  "schedule": "<string>",
  "schedule_snapshot": "<string>",
  "is_active": true,
  "life_state": "active",
  "whitelist_policy": "default",
  "preferred_contact_endpoint": "<string>",
  "proactive_opt_in": true,
  "template_code": "<string>",
  "enabled_personal_server_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}
'
{
  "name": "<string>",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "charter": "<string>",
  "short_description": "<string>",
  "schedule": "<string>",
  "schedule_snapshot": "<string>",
  "is_active": true,
  "life_state": "active",
  "whitelist_policy": "default",
  "last_interaction_at": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "user_id": 123,
  "organization_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "browser_use_agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "preferred_contact_endpoint_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "proactive_opt_in": true,
  "proactive_last_trigger_at": "2023-11-07T05:31:56Z",
  "available_mcp_servers": [
    {}
  ],
  "personal_mcp_server_ids": [
    "<string>"
  ]
}

Authorizations

​
X-Api-Key
string
header
required

Path Parameters

​
id
string<uuid>
required

Unique identifier for the agent.

Body

​
name
string
required

Human-readable name for this agent.

Maximum string length: 255
​
charter
string

The assigned objectives of the agent.

​
schedule
string | null

Cron-like schedule expression or interval (e.g., '@daily', '@every 30m').

Maximum string length: 128
​
schedule_snapshot
string | null

Snapshot of cron schedule for restoration.

Maximum string length: 128
​
is_active
boolean

Whether this agent is currently active

​
life_state
enum<string>

Lifecycle state for soft-expiration. 'paused' is represented by is_active=False.

  • active - Active
  • expired - Expired
Available options:
active,
expired
​
whitelist_policy
enum<string>

Controls who can message this agent and who the agent may contact. Manual: only addresses/numbers listed on the agent's allowlist (includes owner/org members by default).

  • default - Default (Owner or Org Members)
  • manual - Allowed Contacts List
Available options:
default,
manual
​
preferred_contact_endpoint
string | null

Preferred contact endpoint to use for the agent. Must be either 'email' or 'sms' or a valid endpoint id.

​
proactive_opt_in
boolean

Enable Gobii to proactively start conversations offering related help for this agent.

​
template_code
string | null
​
enabled_personal_server_ids
string<uuid>[]

List of enabled MCP servers to use for the agent.

Response

200 - application/json
​
name
string
required

Human-readable name for this agent.

Maximum string length: 255
​
id
string<uuid>

ID of the persistent agent.

​
charter
string

The assigned objectives of the agent.

​
short_description
string

Generated short summary of the agent charter for listings.

​
schedule
string | null

Cron-like schedule expression or interval (e.g., '@daily', '@every 30m').

Maximum string length: 128
​
schedule_snapshot
string | null

Snapshot of cron schedule for restoration.

Maximum string length: 128
​
is_active
boolean

Whether this agent is currently active

​
life_state
enum<string>

Lifecycle state for soft-expiration. 'paused' is represented by is_active=False.

  • active - Active
  • expired - Expired
Available options:
active,
expired
​
whitelist_policy
enum<string>

Controls who can message this agent and who the agent may contact. Manual: only addresses/numbers listed on the agent's allowlist (includes owner/org members by default).

  • default - Default (Owner or Org Members)
  • manual - Allowed Contacts List
Available options:
default,
manual
​
last_interaction_at
string<date-time> | null

Timestamp of the last user interaction (reply, edit, etc.).

​
created_at
string<date-time>

Timestamp of when this agent was created.

​
updated_at
string<date-time>

Timestamp of when this agent was last updated.

​
user_id
integer

ID of the user that owns the agent.

​
organization_id
string<uuid> | null

ID of the organization that owns the agent, if any.

​
browser_use_agent_id
string<uuid>

ID of the browser-use agent used by the agent.

​
preferred_contact_endpoint_id
string<uuid> | null

ID of the preferred contact endpoint used by the agent.

​
proactive_opt_in
boolean

Enable Gobii to proactively start conversations offering related help for this agent.

​
proactive_last_trigger_at
string<date-time> | null

Timestamp of the most recent proactive outreach trigger.

​
available_mcp_servers
object[]
​
personal_mcp_server_ids
string[]