Developer Basics

What the API does

Gobii exposes APIs for managing persistent AI agents, messaging them, inspecting their timelines, connecting external AI clients through Remote MCP, and receiving event callbacks. For end users those persistent workers are called Gobiis; in API docs they are agents.

The primary developer resource is the persistent agent: a long-lived Gobii with a charter, status, timeline, schedule, contact endpoints, files, and tool configuration. Gobii also supports a legacy browser-use task API for one-off browser automation jobs.

Key Concepts

Choose the integration model based on the product behavior you need:

Need	Use
Long-lived AI employee with state, timeline, files, channels, and settings	Agent API
External AI client should manage or message Gobii agents	Remote MCP
Callback when asynchronous work or events complete	Webhooks And Events
Machine-readable JSON output	Structured Data
One-off browser automation task	Legacy Browser Tasks

Base URLs

• Gobii Cloud: https://gobii.ai/api/v1

• Self-hosted/local: http://localhost:8000/api/v1

  Note: You may configure self-hosted Gobii Platforms with a domain of your choice. For simplicity, our documentation will refer to self-hosted Gobii Platforms as the default localhost:8000

Example curl that hits production with the full path:

curl -X GET \
  -H "X-Api-Key: $GOBII_API_KEY" \
  https://gobii.ai/api/v1/ping/

Authentication

• Send your API key in the X-Api-Key header: X-Api-Key: <api_key>.
• Create and manage keys in the Console under API Keys (/console/api-keys/).

Environments

• Production: Multi-tenant Gobii Cloud at https://gobii.ai with managed upgrades.
• Self-hosted/local: Run the platform yourself; the base URL defaults to http://localhost:8000 and all data stays within your deployment and use the LLM(s) of your choice.

Content & security conventions

• Requests and responses use JSON with UTF-8 encoding; set Content-Type: application/json on writes.
• All timestamps and scheduling use UTC.
• Resource identifiers are UUIDs (for example: <uuid:id> paths on agents and tasks).
• Required header: X-Api-Key for authentication; add Content-Type: application/json when sending bodies.

HTTP patterns

• Agents (/agents/):
  • GET /agents/ lists agents (paginated).
  • POST /agents/ creates an agent (non-idempotent).
  • GET /agents/{agentId}/ retrieves a single agent.
  • PUT/PATCH /agents/{agentId}/ updates agent settings (idempotent).
  • DELETE /agents/{agentId}/ deletes an agent.
• Legacy browser tasks (/tasks/browser-use/ or /agents/browser-use/{agentId}/tasks/):
  • POST submits a task to an agent; use wait for sync responses or poll /result/.
  • GET lists tasks (paginated) or retrieves a task.
  • PUT/PATCH updates mutable fields like metadata; DELETE cancels/removes.
• Remote MCP (/mcp/):
  • POST JSON-RPC requests using X-Api-Key or Authorization: Bearer.
  • Supports initialize, ping, tools/list, and tools/call.
• Pagination: Default page size is 10 with a page_size query param (max 100).

Quickstart: health check

Verify connectivity and your API key with the ping endpoint:

curl -X GET \
  -H "X-Api-Key: $GOBII_API_KEY" \
  https://gobii.ai/api/v1/ping/

Sample response:

{
  "pong": true,
  "user": "[email protected]"
}

If you see pong: true, your key is valid and the API is reachable. Next, create or inspect a persistent agent with the Agent API, or connect an MCP client with Remote MCP.