---
title: "Developer Basics"
sidebar_label: "Developer Basics"
description: "Learn Gobii API fundamentals: authentication, base URLs, persistent agents, Remote MCP, webhooks, pagination, and legacy browser tasks."
---

## 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](/developers/developer-agents) |
| External AI client should manage or message Gobii agents | [Remote MCP](/developers/mcp-server) |
| Callback when asynchronous work or events complete | [Webhooks And Events](/developers/webhooks) |
| Machine-readable JSON output | [Structured Data](/developers/structured-data) |
| One-off browser automation task | [Legacy Browser Tasks](/developers/developer-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:

```bash
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:

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

Sample response:

```json
{
  "pong": true,
  "user": "you@example.com"
}
```

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](/developers/developer-agents), or connect an MCP client with [Remote MCP](/developers/mcp-server).
