API Reference ​

REST API reference for the Kitbase SDK endpoints, plus the conventions — authentication, errors, rate limits, versioning — that every Kitbase API operation follows.

OpenAPI specification ​

The full public surface (the same operations the CLI and dashboard use) is published as an OpenAPI 3.0 document. Every operation has a unique operationId, a description, typed parameters, response schemas and typed error responses, so it can be loaded straight into an API client, a code generator or an LLM's function-calling tool set.

Both are served anonymously with Cache-Control: public, max-age=3600, an ETag, and permissive CORS.

curl -s https://api.kitbase.dev/openapi.json | jq '.info.version, (.paths | length)'

Base URL ​

https://api.kitbase.dev

Self-hosted deployments serve the API under https://<your-host>/api.

Authentication ​

SDK endpoints use the x-sdk-key header:

x-sdk-key: <YOUR_SDK_KEY>

Permissions and scoping ​

Every operation is guarded by a named permission (for example analytics.view, webhook.create, aivisibility.manage). A user holds the permissions of their role in the organization — owner, admin, developer, analyst or support. A private API key is created by a user and holds that user's live permissions, limited to the key's project; it can never create or delete credentials (private_api_key.*, sdk_key.*). Revoking a role or a key takes effect on the next request. A permission failure is a 403 with error code PERM_001.

The MCP server is authorized with OAuth 2.1 (PKCE). At consent time the user picks the organization, the project and the exact subset of permissions the connection may use; each tool call is then checked against that subset intersected with the user's live permissions.

Events ​

Track Event ​

Track an event in your application.

POST /sdk/v1/logs

Headers ​

Request Body ​

{
  "event": "New Subscription",
  "channel": "payments",
  "user_id": "user-123",
  "anonymous_id": "550e8400-e29b-41d4-a716-446655440000",
  "icon": "💰",
  "notify": true,
  "description": "User subscribed to premium plan",
  "timestamp": 1705321800000,
  "tags": {
    "plan": "premium",
    "amount": 9.99
  }
}

Parameters ​

Response ​

Status: 202 Accepted

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "New Subscription",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Errors ​

Server-Side Crawler Detection ​

Detect crawlers and AI bots that never run the JavaScript SDK (GPTBot, Googlebot, ClaudeBot, scrapers, …). Install lightweight middleware on your server or edge that forwards each request's signals; Kitbase classifies the actor server-side and stores bot/crawler traffic with full attribution.

POST /ingest/v1/server

Authentication: this is a server-to-server endpoint, so it uses your secret API key (sk_kitbase_…), sent as Authorization: Bearer <API_KEY> (or X-API-Key) — never the browser-exposed SDK key. The key is bound to a project, which is the target for everything you send. This is the generic source in the ingestion family at /ingest/v1/{source}; per-vendor log-drain endpoints (/ingest/v1/vercel, /ingest/v1/cloudfront, /ingest/v1/netlify, /ingest/v1/fastly, …) are added under the same namespace over time.

Why this exists: tag-based analytics only sees clients that execute JS, so non-JS crawlers are invisible. This endpoint observes them in your request path. Human requests are ignored here (the JS SDK already counts them, so this avoids double-counting); detected bot/crawler requests are stored whenever events are enabled for the project. Forwarded human traffic is classified in memory and discarded — not stored; for stored bot events, the raw IP is kept only when IP logging is enabled for the project.

Request Body ​

Send the original visitor's signals (not your server's connection):

{
  "events": [
    {
      "user_agent": "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.1; +https://openai.com/gptbot",
      "ip_address": "203.0.113.5",
      "method": "GET",
      "host": "example.com",
      "path": "/pricing",
      "referrer": "https://www.google.com/",
      "signature": "...",
      "signature_input": "...",
      "signature_agent": "https://chatgpt.com",
      "client_timestamp": 1705321800000
    }
  ]
}

Parameters (per item) ​

Response ​

Status: 202 Accepted — accepted counts how many were stored (bots); humans/disabled are silently skipped.

{ "accepted": 1, "total": 1 }

Stored rows carry the attribution fields documented in Server-Side Tag Enrichment (actor_type, bot_name, bot_vendor, actor_verified, verification_method, etc.) and are flagged is_bot so they're excluded from human visitor and billing counts. (Surfacing these as dedicated dashboard filter dimensions is incremental.)

Platform setup guides ​

Copy-paste setup for each platform lives under Bot & Crawler Detection — pick yours:

Next.jsEdge middlewareTanStack StartRequest middlewareNode.js / ExpressApp middlewareCloudflare Workersfetch handlerVercelLog Drain · zero codeAWS CloudFrontStandard logs → Firehose · zero codenginxAccess-log shipping

Batch requests (up to 500 per call) and send fire-and-forget so analytics never adds latency to your responses.

Vercel Log Drain ​

Hosted on Vercel? Point a Log Drain at Kitbase to capture every request — including crawlers that never run JS — with zero code.

POST /ingest/v1/vercel

Vercel POSTs batches of request logs (JSON array or NDJSON); Kitbase reads each log's proxy object (clientIp, userAgent, method, host, path, referer), classifies the actor, and stores bot/crawler requests (humans ignored). The drain authenticates with your project's secret key (as a custom Authorization: Bearer header), which resolves the target project.

200 OK — { "accepted": <stored bots>, "received": <request logs parsed> }. Non-request logs (build/function output) are ignored.

See the Vercel setup guide for step-by-step Log Drain configuration. The same per-vendor pattern extends to other hosts (CloudFront, Netlify, Fastly) under /ingest/v1/<vendor>.

AWS CloudFront Standard Logs ​

Served through AWS CloudFront (including AWS Amplify sites)? Stream CloudFront standard logs (v2) to Kitbase through Amazon Data Firehose to capture every request — including crawlers that never run JS — with zero code.

POST /ingest/v1/cloudfront

Firehose POSTs batched log records (base64 envelope, JSON output format); Kitbase decodes each CloudFront log's fields (c-ip, cs(User-Agent), cs-method, cs(Host), cs-uri-stem, cs(Referer)), classifies the actor, and stores bot/crawler requests (humans ignored). The stream authenticates with your project's secret key, which Firehose sends in the X-Amz-Firehose-Access-Key header and which resolves the target project.

200 OK — Firehose's required acknowledgement, { "requestId": "…", "timestamp": <ms> }. Rows without a usable IP + User-Agent are ignored; a non-2xx makes Firehose retry then back up to S3.

See the AWS CloudFront setup guide for the CloudFront + Firehose configuration.

Identify User ​

Link an anonymous user to an identified user.

POST /sdk/v1/identify

Request Body ​

{
  "anonymous_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "user-123",
  "traits": {
    "email": "user@example.com",
    "plan": "premium"
  }
}

Parameters ​

Response ​

Status: 200 OK

{
  "success": true
}

Tag Enrichment ​

Events are automatically enriched with these tags:

HTTP Status Codes ​

401 and 403 mean different things and are worth handling differently: 401 says the credential is absent, malformed or expired — presenting a valid one will work. 403 says the credential was accepted and still may not perform this action, so retrying with the same key never helps. A log drain that receives 401 should check that its key is actually being sent.

Error Response ​

Every non-2xx response — from any endpoint, including authentication failures raised before a request reaches a handler — has the same JSON body, the ErrorResponse schema in the OpenAPI spec:

{
  "error": {
    "code": "AUTH_003",
    "message": "Authentication required",
    "details": {}
  },
  "timestamp": "2026-08-22T10:45:52.855Z"
}

Rate Limits ​

Authenticated requests are limited per credential (user, private API key or MCP connection) to 1,000 requests per minute in a fixed one-minute window. Every response carries the IETF rate-limit headers plus the legacy X-RateLimit-* trio, so a client can throttle itself before it is throttled:

RateLimit-Policy: "per-minute";q=1000;w=60
RateLimit: "per-minute";r=997;t=42
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997
X-RateLimit-Reset: 42

Over the limit, the response is 429 with the standard error body (AUTH_014) and a Retry-After header in seconds. Public, unauthenticated endpoints (/public/*) have their own stricter per-IP limits and answer 429 + Retry-After the same way. Event ingestion (/sdk/v1/*, /ingest/v1/*) is not subject to the per-credential limit.

Versioning and Deprecation ​

The API is version 1 (info.version in the spec). Paths are stable and changes are additive: new fields, parameters and endpoints may appear at any time, and clients must ignore fields they do not recognise. Breaking changes ship under a new path prefix (/v2/…) rather than by changing an existing operation.

An operation scheduled for removal is marked deprecated: true in the OpenAPI spec at least 90 days before its sunset, and during that period every response from it carries:

Deprecation: @1767225600
Sunset: Wed, 01 Apr 2026 00:00:00 GMT
Link: <https://docs.kitbase.dev/changelog/>; rel="deprecation"; type="text/html"

Deprecation (RFC 9745) is the date the deprecation was announced, Sunset (RFC 8594) the date after which the operation may stop working, and the Link points at the migration notes. Changes are announced in the changelog.

Next steps ​

• OpenAPI spec — the complete, machine-readable public surface.
• MCP Server — the same data and actions for AI assistants, with a server card for discovery.
• CLI — every endpoint here is also a kitbase command.
• SDKs & Tools — typed SDKs that wrap this API.
• Bot & Crawler Detection — platform guides for the server-side ingestion endpoint.