Getting started

This is the five-minute path: create your Team, choose a surface, create your first schedule, and watch it fire. A schedule is the simplest primitive — "POST this webhook at this future time" — so it's the fastest way to see AIGears work end to end.

Sign up and sign in. When you first sign in, a Team is created for you and you become its first member. The Team is the tenant that owns everything — API Keys, billing, every schedule / deadline / approval / watch, and the audit log. A solo developer is simply a Team of one; there is no separate "individual" concept below it.

Everything you do from here happens inside your Team. Its dashboard lives at /a/<team_slug>/aigears/.

Choose your surface

AIGears has three surfaces onto the same shared Team state. Pick the one that matches who is driving:

A human setting things up by hand → Dashboard. Point-and-click forms, with a live cron preview and the Activity feed for inspection.
Code or a non-MCP agent framework → HTTP API. A plain REST API you call with an API Key.
An MCP-capable agent that should manage its own state → MCP. The hosted MCP server; the operator authenticates over OAuth and the agent calls tools.

You don't have to commit forever — the surfaces share state, so you can create a schedule from code and cancel it from the Dashboard. The worked example below shows all three; the tabs are sticky, so pick your surface once and it follows you across these docs.

Dashboard

After signing in, open your Team and go to AIGears in the navigation. The schedules, deadlines, approvals, watches, Activity feed, and Settings all live under /a/<team_slug>/aigears/. No credential to manage — your login session authenticates you.

HTTP API

The HTTP API authenticates with an API Key as a bearer token. Create one from the Dashboard (the API is not able to mint its own keys):

Go to Settings → API keys (/a/<team_slug>/aigears/api-keys/).
Click New key, give it a label (e.g. prod-agent), and copy the token.

The token looks like aigears_live_XXXXXXXXXXXXXXXXXXXXXXXX and is shown exactly once, at creation — store it as a secret. If you lose it, revoke it and create a new one. Send it on every request:

Authorization: Bearer aigears_live_XXXXXXXXXXXXXXXXXXXXXXXX

The Team is derived from the key — you never pass a team id or slug to the API. Keys are credentials, not identities: a Team can have many keys and they all see and operate on the same shared state. See Teams & API keys.

MCP

Connect your agent to the hosted MCP server. The operator authenticates the session over OAuth — there is no API key on MCP. Because one operator may belong to several Teams, an MCP session starts with no Team selected: call teams_list to see your teams, then set_current_team with the chosen slug before any product tool. Every subsequent tool call is scoped to that Team. For the exact client configuration and OAuth flow, see the MCP server reference.

Your first schedule

Create a one-shot schedule that fires a webhook at a time in the near future, then check it in the Activity feed. Use a webhook_url you control — if you don't have one handy, a request-bin style test endpoint works for a first run; see Receiving webhooks for verifying real deliveries.

Go to AIGears → Schedules (/a/<team_slug>/aigears/schedules/) and click New schedule.

Choose One-shot and pick a fire_at a few minutes from now.
Enter your webhook_url.
Optionally add a JSON payload — it's echoed back to you inside the webhook.
Submit.

(For a recurring schedule you'd choose a cron expression instead; the form shows a live preview of the next few fire times before you commit.)

The new schedule appears in the list as pending.

POST /v1/schedules/ with your fire_at and webhook_url. Send an Idempotency-Key so an accidental retry doesn't create a second schedule:

curl -X POST https://<host>/v1/schedules/ \
  -H "Authorization: Bearer $AIGEARS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "fire_at": "2026-06-01T09:00:00Z",
    "webhook_url": "https://example.com/webhooks/aigears",
    "payload": {"task": "hello-aigears"}
  }'

fire_at is ISO-8601 with an offset and must be in the future; webhook_url is required and validated (must be a public HTTPS host). A 201 returns the full schedule, including its id and pending status.

First bootstrap the session, then create the schedule. A typical operator prompt:

"List my AIGears teams, switch to acme, then schedule a webhook to https://example.com/webhooks/aigears for tomorrow at 09:00 UTC."

The agent makes three tool calls:

teams_list()
  → [{ "slug": "acme", "name": "Acme", "is_active": false }, ...]

set_current_team(team_slug="acme")
  → { "slug": "acme", "is_active": true }

schedule_create(
  webhook_url="https://example.com/webhooks/aigears",
  fire_at="2026-06-01T09:00:00Z",
  payload={"task": "hello-aigears"},
  idempotency_key="<fresh-uuid>",
)
  → { "id": "...", "status": "pending", ... }

If the agent skips the bootstrap, product tools return a no_team_selected error telling it to call teams_list then set_current_team first.

Verify it worked

Open the Activity feed (/a/<team_slug>/aigears/activity/) in the Dashboard. When the schedule fires you'll see a schedule.fired event and the webhook delivery it produced; the schedule's own status moves from pending to fired. On the HTTP API you can poll GET /v1/schedules/{id}/, and on MCP schedule_get returns the same, including the delivery attempts.

The webhook we POST to your endpoint carries the standard signed envelope ({event_id, event_type, team_id, occurred_at, data}). To verify the signature and handle at-least-once delivery correctly, see Receiving webhooks and Webhooks & signing.

From here, dig into the Schedules guide for recurring series and cancellation, or browse the other primitives from the Introduction.