Docs
Sign in

API.

Read and drive Koidog from your own programs.

Base URL.

It is served by the control plane you sign in to.

URL
https://app.koi.dog/api/v1

Authentication.

Create an API key in Settings → API. Its token is shown once. Send it on every request. A key holds only the scopes you give it; an endpoint lists every scope it needs.

ScopeLets the key
readRead crews, agents, runs, events and everything else.
crewsLaunch and control crews.
configChange projects, connections, nodes, settings and webhooks.
approveMerge, decide approvals, raise budget limits and do destructive things.
Header
Authorization: Bearer <key>

Events.

Follow the timeline live as server-sent events. It takes the same filters as GET /events. Reconnect with Last-Event-ID to replay what you missed, in order. A key may hold 8 streams at once.

Stream
GET /api/v1/events/stream?crewId=<crewId>

id: 1842
event: event
data: {"seq":1842,"kind":"crew.state","crewId":"<crewId>",…}

Webhooks.

Koidog POSTs matching events to your https endpoint, signed with the endpoint's secret. The secret is shown once.

HeaderWhat it holds
Koidog-TimestampWhen the delivery was signed, in Unix seconds.
Koidog-Signaturev1= and the hex HMAC-SHA256 of the timestamp, a dot and the raw body.
Koidog-Delivery-IdThe same across retries.
Koidog-Webhook-IdThe endpoint's id.
Koidog-Attempt1 on the first try, then 2, 3 and on.
User-AgentKoidog-Webhooks/1
Content-Typeapplication/json. The body holds the delivery: its id, type, createdAt and the timeline event.

Check the signature and refuse old timestamps; the code beside this does both. Answer any 2xx within 10 seconds; anything else is retried for about 21 hours. Koidog switches an endpoint off after 50 failed attempts in a row, or when every attempt has failed for 24 hours, and records a webhook.disabled event.

import { createHmac, timingSafeEqual } from "node:crypto";

// secret: the endpoint's secret. rawBody: the body exactly as it arrived, as a string.
export function verifyKoidog(secret, headers, rawBody) {
  const timestamp = headers["koidog-timestamp"];
  const signature = headers["koidog-signature"] ?? "";
  // Refuse a delivery signed more than five minutes ago.
  if (!timestamp || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = "v1=" + createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  return signature.length === expected.length && timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}
import hashlib
import hmac
import time


# secret: the endpoint's secret. raw_body: the body exactly as it arrived, as bytes.
def verify_koidog(secret: str, headers, raw_body: bytes) -> bool:
    timestamp = headers.get("Koidog-Timestamp", "")
    signature = headers.get("Koidog-Signature", "")
    # Refuse a delivery signed more than five minutes ago.
    if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > 300:
        return False
    signed = timestamp.encode() + b"." + raw_body
    expected = "v1=" + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, expected)

OpenAPI.

OpenAPI 3.1, made from the schemas the server checks with. No key needed.

Errors.

Every error has this shape. Branch on type; code is the stable reason. details lists each problem when there is more than one.

Types: invalid_request, authentication, permission, not_found, conflict, rate_limited, not_built, upstream, internal.

{
  "error": {
    "type": "authentication",
    "code": "invalid_api_key",
    "message": "That API key is not known to this server.",
    "requestId": "req_q8M2x7C4k9TzWb3n"
  }
}
{
  "error": {
    "type": "conflict",
    "code": "launch_blocked",
    "message": "Project \"Landing page\" is archived. Unarchive it to launch a crew on it.",
    "requestId": "req_q8M2x7C4k9TzWb3n",
    "details": [
      {
        "message": "Project \"Landing page\" is archived. Unarchive it to launch a crew on it."
      }
    ]
  }
}