HTTP ingestion API

​

Endpoint and authentication

POST {endpoint}/v1/events
Authorization: Bearer <api_key>
Content-Type: application/json
Content-Encoding: gzip        # optional

​

Send your first event

curl -X POST "https://ingest.yourcompany.com/v1/events" \
  -H "Authorization: Bearer $KEEPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sent_at": "2026-07-03T12:00:01.000Z",
    "events": [
      {
        "event_id": "0197a3f0-5e7a-7000-8000-3f6b2a91c001",
        "asset_id": "job_8412",
        "ts": "2026-07-03T12:00:00.123Z",
        "model": "fal-ai/flux-pro/v1.1",
        "provider": "fal",
        "status": "completed",
        "inputs": {"prompt": "a red bicycle on a beach"},
        "outputs": [{"kind": "image", "url": "https://cdn.example.com/out.png",
                     "content_type": "image/png", "width": 1024, "height": 1024}],
        "usage": {"n": 1, "duration_s": 6.2},
        "properties": {"tier": "pro", "generation_id": "req_abc123"}
      }
    ]
  }'

{"accepted": 1, "rejected": []}

​

The batch

{"events": [ … ], "sent_at": "2026-07-03T12:00:00.000Z"}

​

The event object

{
  "schema_version": 1,
  "event_id":   "0197a3…",                  // REQUIRED — idempotency/dedupe key
  "asset_id":   "0197a3…",                  // REQUIRED — your correlation key
  "ts":         "2026-07-03T12:00:00.123Z", // REQUIRED — when the event happened
  "user_id":    "u_42",
  "model":      "fal-ai/flux-pro/v1.1",     // bare provider-native id
  "provider":   "fal",                      // lowercase vendor slug
  "status":     "completed",
  "inputs":     { "prompt": "…" },
  "outputs":    [ { "kind": "image", "url": "…" } ],
  "error":      { "message": "…", "type": "…", "code": "…", "http_status": 422 },
  "usage":      { "duration_s": 6.2, "n": 1 },
  "properties": { "tier": "pro", "session_id": "s_1" },
  "truncated":  ["inputs"]                  // fields you cut client-side, if any
}

​

Identity fields

• asset_id is yours: every event carrying the same asset_id (within your project) folds into one asset. Derive it from a stable internal key (your job id, your row id). Stick to [A-Za-z0-9._:-] — a / in the id makes GET /v1/assets/{id} unreachable.
• event_id must be unique within (project, asset_id) and is the dedupe key: delivery is at-least-once, so resend freely on timeouts — a redelivered event_id must be byte-identical to the original. UUIDv7 is recommended because monotonic ids make equal-ts tie-breaks follow emit order.

​

Fields the server stamps (never wire inputs)

​

Timestamps

• Format: RFC 3339 with millisecond precision and an explicit offset (Z or ±hh:mm): 2026-07-03T12:00:00.123Z. A naive timestamp (no offset) is accepted and interpreted as UTC — never the server’s local zone.
• Unparseable ts rejects that event (bad_ts). The server never substitutes its own time: ts decides every fold, and a fabricated timestamp would decide winners silently.
• Floor: ts before 2020-01-01 rejects (bad_ts) — epoch-zero garbage would permanently win the “earliest” aggregates.
• Future clamp: ts more than 5 minutes past the server clock is clamped to that ceiling; the original string is retained server-side. One ts=2050 event must not permanently win every “latest” fold for its asset.
• Skew correction: when the batch carries sent_at, every ts is shifted by received_at − sent_at, quantized to whole seconds and only beyond ±5 s (see The batch). Omit sent_at when backfilling.

​

Status and what the fold promises

• Terminal (closed set): completed · failed · cancelled. The spelling canceled is normalized to cancelled at ingest.
• Non-terminal: submitted, queued, processing, and every string the server doesn’t recognize. Unknown statuses fold as the asset’s current status but never mark it finished (they never set completed_at).

• Every field folds latest-non-empty-wins, ordered by (ts, event_id) — bytewise event_id order breaks equal-ts ties deterministically.
• Status is terminal-sticky. Once an asset has a terminal status, no non-terminal event can flip it back to in-flight, regardless of arrival order or ts. Among terminal events, the latest (ts, event_id) wins.
• Consequence: one attempt = one asset_id. Never resubmit an asset_id. A retry is a new asset, linked to its predecessor via the reserved reroll_of property (and numbered with attempt).
• A terminal completed clears the folded error, so a fail-then-succeed asset never shows a stale error. A properties-only annotation on a failed asset does not clear its error.
• properties fold per key: each event updates only the keys it carries.
• The asset’s anchor timestamps: submitted_at is the earliest status="submitted" event, completed_at the latest terminal event, and first_seen_at the earliest event of any kind — set even for one-shot captures that never sent submitted.

​

Empty means absent

​

Value encodings

• Property values are stored as strings with one canonical encoding. String values pass through verbatim; every non-string value is JSON-encoded: true/false lowercase, numbers as JSON renders them, containers as compact JSON ({"x":1}), never language reprs like True or {'x': 1}. Note 1 and 1.0 are different stored values — send strings if you need cross-type equality. For flag-like tags, send true/false or "1".
• inputs / outputs / error / usage are stored as canonical JSON — the server re-encodes them compactly, so the stored form is always exactly-once-encoded JSON. If you send a top-level JSON string for one of these fields, it is parsed and re-dumped rather than stored verbatim; a string that doesn’t parse is stored as a JSON-encoded string scalar.

​

Field shapes

• inputs — a JSON object, captured verbatim. There is no server-side redaction: hash or strip sensitive values before you send them. inputs.prompt is the reserved key the dashboard reads for the prompt.
• outputs — always a JSON array of reference objects; a bare object is wrapped into a one-element array, never rejected. References, not bytes: each ref needs a url unless it carries "inline": true. Reserved optional ref keys: kind, content_type, width, height, duration_s, size_bytes, seed.
• error — a JSON object carrying the provider’s error verbatim. Conventional keys (never enforced): message (expected), type, code, http_status, provider_raw.
• usage — a flat map of finite numbers: the provider-reported billing meters, verbatim. They exist only in the provider’s response at call time — capture them or lose them. Reserved key names: n, duration_s, tokens_in, tokens_out, compute_seconds, characters, megapixels, width, height, audio (0/1). Non-numeric values are dropped per key.

​

model and provider

​

Reserved names

• group: prefix — contests. The key group:<your_group_id> marks the asset as a member of that contest (a pick-of-N batch, a shot’s candidates, a head-to-head); the value is the asset’s verdict in that contest: candidate, then picked when chosen (or your own vocabulary — ranks like "1", rejected, …). Because properties fold per key, one asset can sit in many contests with independent verdicts, a contest can have zero or many winners, and membership can be asserted any time later by an annotation event. Group ids and values are yours; keeps never rewrites this family.
• keeps: prefix — server-derived properties. Client-sent keeps:* keys are dropped at ingest, so a platform-derived tag can never be clobbered by (or clobber) one of yours.
• __*__ (dunder-wrapped) — SDK sentinel markers (__bytes__, __truncated__, __dropped__, __unserializable__). Never use them as your own keys.
• error_kind — reserved for the server-side error taxonomy; client-supplied values are dropped at ingest.

​

Responses

​

202 — per-event outcomes

{"accepted": 2, "rejected": [{"index": 1, "reason": "bad_ts"}]}

​

Error statuses

​

A complete Node integration

const ENDPOINT = "https://ingest.yourcompany.com/v1/events";

async function send(events) {
  const res = await fetch(ENDPOINT, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.KEEPS_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ events, sent_at: new Date().toISOString() }),
  });
  if (res.status === 503) throw new Error("transient — retry with backoff");
  if (!res.ok) throw new Error(`ingest rejected the request: ${res.status}`);

  const body = await res.json(); // { accepted, rejected: [{index, reason}] }
  for (const r of body.rejected) {
    // Terminal — retrying the same bytes cannot succeed. Log and fix.
    console.warn(`keeps: event ${r.index} rejected: ${r.reason}`);
  }
  return body;
}

// One generation = one asset_id, minted by YOU and reused on every event.
const assetId = crypto.randomUUID();

// 1. Submission.
await send([{
  event_id: crypto.randomUUID(),
  asset_id: assetId,
  ts: new Date().toISOString(),
  model: "fal-ai/flux-pro/v1.1",
  provider: "fal",
  status: "submitted",
  inputs: { prompt: "a red bicycle on a beach" },
  user_id: "u_42",
}]);

// … your provider call runs, untouched …

// 2. Completion on the SAME asset_id — plus the provider's request id,
//    tagged as the reserved `generation_id` property.
await send([{
  event_id: crypto.randomUUID(),
  asset_id: assetId,
  ts: new Date().toISOString(),
  status: "completed",
  outputs: [{ url: "https://cdn.example.com/out.png", width: 1024, height: 1024 }],
  usage: { n: 1, duration_s: 6.2 },
  properties: { generation_id: providerRequestId, tier: "pro" },
}]);

​

Related