API Overview

Pug exposes a Connect RPC API — Protobuf messages over HTTP/2. Supports Connect, gRPC, and gRPC-Web protocols from any language with a generated client.

Base URL: https://api.pug.sh
Proto source: cotton/proto 

Self-hosted deployments use your own base URL. See Self-hosting.

Quick start

Install the Connect client:

npm install @connectrpc/connect @connectrpc/connect-web @bufbuild/protobuf

Generate TypeScript clients from proto:

buf generate

Make your first request — send an event with SDK auth:

import { createClient } from '@connectrpc/connect'
import { createConnectTransport } from '@connectrpc/connect-web'
import { EventsService } from './gen/events/v1/events_connect'
 
const transport = createConnectTransport({
  baseUrl: 'https://api.pug.sh',
  interceptors: [
    next => async req => {
      req.header.set('Authorization', `Bearer ${process.env.PUG_SDK_API_KEY}`)
      req.header.set('x-project-id', process.env.PUG_PROJECT_ID!)
      return next(req)
    }
  ]
})
 
const client = createClient(EventsService, transport)
 
const response = await client.batchCreate({
  events: [
    {
      name: 'page_view',
      properties: { path: '/home' },
      timestamp: new Date()
    }
  ]
})
 
console.log('Ingested:', response.eventsCreated)

Protocols

Connect RPC supports three wire protocols on the same endpoints:

The Web SDK uses Connect protocol. Server integrations can use any protocol.

Authentication

All requests require x-project-id. See Authentication for the full guide.

Authorization: Bearer <credential>
x-project-id: <project-id>
Content-Type: application/json
Connect-Protocol-Version: 1

Services by auth boundary

Public

Dashboard (JWT + x-project-id)

SDK (API key)

Shared (API key or JWT)

Error handling

All errors are Connect RPC status codes with structured details:

{
  "code": "invalid_argument",
  "message": "validation error",
  "details": [
    {
      "field": "events[0].name",
      "description": "value is required"
    }
  ]
}

Requests are validated with protovalidate at the interceptor layer. Fix the named field and retry.

Validation

All request messages are validated against protobuf schemas with protovalidate annotations. Common failures:

• Missing required fields
• Wrong types (string where number expected)
• Unknown enum values
• String length violations

Well-known event properties are additionally validated against event schemas.

Service pages

Code generation

Proto definitions live in the cotton  repo:

git clone git@github.com:fivebitsio/cotton.git
cd cotton
buf generate

Generated clients are available for TypeScript, Go, Python, and other languages via Buf.

See RPC services reference for the full method index.

Further reading

• Authentication — headers and client setup
• RPC services — all methods
• Self-hosting — run your own API