Dobby REST API Quickstart: 500+ Endpoints in 10 Minutes

Two Ways to Authenticate

Dobby supports two authentication methods. API keys (sk_live_*) are for server-to-server integrations — they have full access to the tenant API. Gateway keys (gk_user_*, gk_svc_*, gk_tmp_*) are for LLM and MCP requests — they go through the policy engine.

• API keys (sk_live_*) — full tenant API access, scoped by permission, IP-whitelisted
• Gateway user keys (gk_user_*) — 100 RPM, for individual developers
• Gateway service keys (gk_svc_*) — 500 RPM, for production agents
• Gateway temporary keys (gk_tmp_*) — 50 RPM, auto-expire, for testing

Creating a Task

import requests

API_URL = "https://dobby-ai.com/api/v1"
API_KEY = "sk_live_your_api_key"

# Create a task
response = requests.post(
    f"{API_URL}/tenants/{TENANT_ID}/tasks",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "title": "Review security configuration",
        "description": "Audit IAM roles and network policies",
        "priority": "high",
        "assigned_agent": "dobby-security-worker-agent"
    }
)

task = response.json()
print(f"Task created: {task['id']}")

Querying Agent Costs

# Get cost breakdown per agent (last 30 days)
response = requests.get(
    f"{API_URL}/tenants/{TENANT_ID}/analytics/agent-costs",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"period": "30d"}
)

costs = response.json()
for agent in costs["cost_by_agent"]:
    print(f"{agent['agent_name']}: ${agent['total_cost']:.2f}")
    print(f"  Tokens: {agent['total_tokens']:,}")
    print(f"  Requests: {agent['total_requests']}")

Key API Domains

• Tasks — CRUD operations, status updates, assignment, timeline events
• Agents — list, configure, enable/disable, fleet status, per-agent metrics
• Approvals — list pending, approve, reject, request changes, approval history
• Gateway — API key management, usage stats, kill-switch, policies
• Analytics — cost by agent/provider/user, daily trends, forecast, FinOps
• Schedules — create recurring/one-time agent runs, pause, resume
• Webhooks — GitHub/GitLab PR, CI, push events

CI/CD Integration Example

A common pattern is triggering Dobby tasks from CI/CD pipelines. When a PR is opened, create a security review task. When CI passes, trigger a deployment task with an approval gate. When a deploy completes, update the task status.

# GitHub Actions: trigger Dobby task on PR open
# .github/workflows/security-review.yml
name: Security Review
on:
  pull_request:
    types: [opened]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - name: Create Dobby security review task
        run: |
          curl -X POST "$DOBBY_API/tenants/$TENANT/tasks" \
            -H "Authorization: Bearer $DOBBY_API_KEY" \
            -H "Content-Type: application/json" \
            -d '{
              "title": "Security review: PR #${{ github.event.number }}",
              "priority": "high",
              "assigned_agent": "dobby-security-worker-agent",
              "metadata": {"pr_url": "${{ github.event.pull_request.html_url }}"}
            }'

Rate Limits, Retries, and Idempotency

• Rate limits are per key type. On 429, wait for the Retry-After header rather than backing off blindly.
• Use Idempotency-Key on POST /tasks to make retries safe — the same key returns the same task instead of creating duplicates.
• All mutating endpoints return the resulting resource so you rarely need a follow-up GET.
• Pagination uses page + page_size with a next_cursor field for stable iteration over large datasets.

When to Use REST vs SDK vs MCP

• REST — for languages without an SDK (Go, Rust, Ruby) or for webhook/CI flows that are already HTTP-native.
• SDK (@dobbyai/sdk, dobby-ai-sdk) — for checked-in code in JS/TS and Python with typed errors and ergonomic helpers.
• MCP tools — for AI agents in Claude Desktop / Cursor / Cline that discover tools at runtime.

Frequently Asked Questions

How do I rotate an API key safely?

Create a new key, deploy it to your workloads, verify traffic on the new key in the Live dashboard, then revoke the old key. Dobby supports overlapping keys so there is zero downtime during rotation.

Are webhook deliveries retried?

Yes. Webhooks retry with exponential backoff for up to 24 hours on non-2xx responses, and every delivery attempt is visible in the webhook logs with the full request/response body for debugging.

Can I scope an API key to specific endpoints?

Yes — every API key has a scope list (e.g., tasks:read, agents:trigger, gateway:admin). Issue the narrowest scope that the integration needs and rotate quickly if scope needs change.