Events

Base URL: https://api.codespar.dev

Every operation below requires a Bearer token. See Authentication.

GET /v1/events/summary

Count the project's events in a window, by type

Events the calling credential's project recorded inside the window, counted by type. Counts only, never a payload. A test-fire is not counted, whatever type it was sent as.

Query parameters

Responses

Response 200

curl -X GET https://api.codespar.dev/v1/events/summary \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET /v1/events/summary HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.get(
    "https://api.codespar.dev/v1/events/summary",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/events/summary", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/events/summary");

{
  "window": "string",
  "total": 0,
  "by_type": {}
}

POST /v1/events/{event_id}/replay

Re-dispatch a stored event to its subscribers

Re-runs the fan-out for an event that is already stored. The event itself is untouched: no new event row is written, so server-side de-duplication and the audit trail stay intact, and each dispatch appends its own fresh delivery row.

The event resolves only inside the calling credential's org AND project, so an event id from a sibling project is 404 here rather than replayed into the current project's subscribers.

WITHOUT trigger_id the event goes to every ACTIVE subscription in this project whose subscribed event type matches the stored event's and whose condition, if it has one, holds for the stored payload. With it, the fan-out is narrowed to that one subscription, which is the useful shape when debugging a single receiver — and the subscription is checked up front, so a mismatch or a paused subscription is refused before anything is delivered rather than dropped silently downstream.

202, NOT 200, AND THE NUMBERS ARE HANDOFF COUNTS. dispatched is how many active subscriptions the event was handed to and recorded against: each gets a delivery row and settles independently, so a receiver that is down does not lower this number and does not fail the call — its failed delivery is retried. rejected is how many dispatches left NO delivery row — the dispatch failed, or its attempt could not be recorded even in minimal form — so nothing will retry them, and a non-zero rejected is ours to investigate, not the receiver's. dispatched + rejected is the number of matching subscriptions. Both zero means nothing in this project subscribes to this event's type — it is not an error, and it is the answer you get when the subscription you meant lives in another project.

A write-scope refusal while recording a dispatch is never folded into rejected: the rest of the fan-out still runs, and then the call answers with the refusal itself (write_scope_undeclared and its siblings, in their own { error, remediation } envelope), because that is a defect on our side and not a receiver outcome.

Path parameters

Query parameters

Responses

Response 202

curl -X POST https://api.codespar.dev/v1/events/{event_id}/replay \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

POST /v1/events/{event_id}/replay HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.post(
    "https://api.codespar.dev/v1/events/{event_id}/replay",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/events/{event_id}/replay", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.post("/v1/events/{event_id}/replay", {
  path: {
    event_id: "event_0000000000000000"
  }
});

{
  "event_id": "event_0000000000000000",
  "dispatched": 0,
  "rejected": 0,
  "trigger_id": "trg_0000000000000000"
}