API Reference

Choose your intake

Both accept the same EVIDE JSON payload and finalize the intake at once. The ESB endpoint also accepts two optional ESB fields, which the Standard endpoint refuses. The difference is what happens after intake.

ESB Buffer (Epistemic Stabilization Buffer) Operational Intake Profile

When to use ESB instead of standard intake

Standard intake (/api/intake/json) anchors the submitted object immediately: the evidentiary boundary is crossed at the moment of submission. ESB (/api/intake/esb) anchors it in the same way, at the same moment, and is for cases where the source system also needs to declare, over a declared period, how a condition evolves and then declare a stabilization verdict. The same payload schema applies to both. What stays open with ESB is the observation window, not the intake: the intake and its first EAR version are final from submission, and the closure adds a new EAR version without changing them.

Endpoints

Intake-time fields

buffer/update and buffer/close fields

Both endpoints require buffer_id. Each other field belongs to one phase, stated in its description: a field sent to the other endpoint is rejected with 422 wrong_phase_field, and a field unknown to the system with 422 unknown_field. Nothing is silently ignored. All values are declarations of the source system: EVIDE records them, it does not verify them.

Timeline — a complete lifecycle

// 1. Open — POST /api/intake/esb
{
  "evide_schema": "2.1",
  // ... same payload fields as standard intake ...
  "buffer_window_hours": 2,
  "buffer": { "stabilization_source": "human_review" }
}
// → { "success": true, "profile": "esb", "esb_status": "active", "evide_id": "...", "intake_hash": "...",
//     ...Standard intake response fields..., "buffer": { "ok": true, "buffer_id": 1 } }
// The intake is already finalized: its first EAR version shows the window OPEN / PENDING.

// 2. Observe — POST /api/buffer/update (any number of times)
{
  "buffer_id": 1,
  "stability_trend": "improving",
  "continuity_state": "coherent",
  "causal_persistence_signal": "present"
}
// → { "success": true, "buffer_id": 1, "updated_fields": 3 }

// 3. Close — POST /api/buffer/close
{
  "buffer_id": 1,
  "buffer_verdict": "stable",
  "closure_trigger": "manual_close",
  "stabilization_score": 88.5
}
// → { "success": true, "buffer_id": 1, "buffer_verdict": "stable", "buffer_open_at": "...", "buffer_close_at": "...",
//     "window_seconds": 196, "closure_trigger": "manual_close", "stabilization_score": 88.5,
//     "causal_persistence_signal": "present",
//     "semantic_note": "crossing-sufficient, NOT absolute epistemic truth" }
// semantic_note is returned only with "stable"; it is null for "unstable" and "deferred".
// The closure generates the next EAR version of the intake (trigger_reason: esb_closed);
// earlier EAR versions are not modified.

Authorization and errors

buffer/update and buffer/close use the same API key checks as intake (active key, activated plan, active account). The buffer must belong to an intake deposited by the user bound to the key. For an intake deposited for an organization, that user must also be a current member of the organization at the time of the call, whatever key is used. Error responses have the shape {"success": false, "error": "...", "message": "..."}.

Requests sent with an Idempotency-Key header can also receive the responses described in Idempotent requests below.

Idempotent requests (Idempotency-Key) Optional header API v2.2

The header

• Idempotency-Key: <value> — 1 to 128 characters from A–Z a–z 0–9 . _ : -, case-sensitive. Use a UUID v4, generated once for each event you deposit and stored by your system before the first attempt. An empty or malformed value is refused with 400 invalid_idempotency_key and has no effect.
• Do not put personal data or confidential information in the key: it is kept as a technical record for the retention period.
• The key is scoped to your API key: the same value used with another API key is an independent key.

What counts as the same request. The endpoint plus the JSON body, compared in canonical form (the same canonicalization used for intake_hash): property order and whitespace do not matter. content_hash is part of the comparison. Any other difference in the body, or a different endpoint, makes it a different request.

Outcomes of a request sent with a key

Two identical requests with the same key that arrive at the same time are executed once: the other receives 409 idempotency_request_in_progress or the stored response.

Authentication is always checked first

Every retry goes through the full API key checks (status, client activation, account, organization membership, IP allow-list, rate limit) before any stored response is considered. A revoked or expired key receives 401, never a stored response. Retries count toward the per-minute rate limit. On buffer/update and buffer/close the buffer ownership check also comes first: the buffer of a deleted intake receives 404 buffer_not_found, the same response as a buffer that does not exist or belongs to someone else.

ESB and buffer operations

ESB intake whose buffer could not be opened. 500 esb_initialization_failed with "request_recorded": true is a final outcome: the intake exists. A retry with the same key returns the same response and never opens a buffer later.

Buffer operations. With the same key, a repeated buffer/update records the observation once, and a repeated buffer/close returns the original closure response. Without a key, a second buffer/update records a second observation, and a second buffer/close receives 409 already_closed.

Usage and billing

A replayed response does not create a deposit and is not counted toward plan usage: each deposit is counted once. A deposit completed by a recovery retry is counted when the recovery completes, which may fall in the following billing month.

What idempotency does not do

It prevents duplicates caused by retrying the same request, within the limits above. It does not merge deposits sent with different keys, with different bodies, without a key or after the retention period, and it does not establish whether two deposits describe the same event. The key never appears in the intake record, the intake_hash, the EAR or a FEDIS.

Response headers

Error codes

All use the usual error shape {"success": false, "error": "...", "message": "..."}.

Example

// 1. First request — POST /api/intake/json
curl -X POST https://app.certifywebcontent.com/api/intake/json \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -H "Idempotency-Key: 577fdea8-0f64-458e-b96a-f4ca3978fd9b" \
  -d @payload.json
// → HTTP 200 { "success": true, "evide_id": "...", "intake_hash": "...", ... }

// 2. Same request again (for example after a timeout)
// → HTTP 200, header Idempotency-Replayed: true, identical body: same evide_id, same intake_hash

// 3. Same key, different body
// → HTTP 409 { "success": false, "error": "idempotency_key_reused", "message": "..." }

// 4. Same request after the intake was deleted by an administrator
// → HTTP 410, header Idempotency-Replayed: true
//   { "success": false, "error": "idempotency_record_deleted", "message": "..." }

Practical guidance

How to deposit