# Server API and Node

For the events only your backend knows about: signups, payments, cron jobs, deploys. Server events use a secret key, so they never ship in a browser or an app.

## Keys

Create a secret ingest key in the property's settings, or ask your agent to call `create_api_key`. It starts with `pb_sk_` and is shown once.

## Node

```bash
npm install @pagebee/node
```

```ts title="billing.ts"
import { Pagebee } from "@pagebee/node";

const pagebee = new Pagebee({ secretKey: process.env.PAGEBEE_SECRET_KEY! });

await pagebee.track({
  name: "Subscription started",
  props: { plan: "pro", interval: "month" },
  revenue: { amount: 999, currency: "GBP" },
});

await pagebee.notify("payments", "New subscriber", { icon: "💸", description: "Pro, monthly" });
```

## HTTP

```bash
curl https://api.pagebee.ai/v1/events \
  -H "Authorization: Bearer pb_sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{"events":[{"name":"Signed up","channel":"signups","icon":"👋","notify":true}]}'
```

Up to 100 events per request. A single event without the `events` wrapper is also accepted.

## Fields

| Field | Required | Meaning |
| --- | --- | --- |
| `name` | yes | Event name, 1 to 100 characters |
| `id` | no | Idempotency id; a retried duplicate within 24 hours is dropped |
| `env` | no | Defaults to the key's environment |
| `ts` | no | ISO 8601; defaults to when we received it |
| `path` | no | The page or screen it belongs to |
| `props` | no | Up to 30 keys; strings, numbers or booleans |
| `revenue` | no | `{ "amount": 999, "currency": "GBP" }`, amount in minor units |
| `channel` | no | Live feed channel, created on first use |
| `icon` | no | One emoji for the feed |
| `description` | no | Up to 280 characters |
| `notify` | no | Push to the team |

## Responses

| Status | Meaning |
| --- | --- |
| `202` | `{ "accepted": n, "duplicates": n, "dropped": n }` |
| `400` | Invalid event, with the field named |
| `401` | Wrong or revoked key |
| `413` | More than 100 events |
| `429` | Rate limited; retry after the `Retry-After` header |
