Developer documentation

Is my key alive? Returns key, bridge, and scoped project ids.

Key identity, bridge (lifecycle, connection mode), scoped projects.

Projects in the key's scope.

Datasets of a scoped project: id, name, slug, description, lifecycle_status, sample_depth, current quality-check version, open-draft pointer.

Dataset detail: the list fields plus project_id and quality_checks_published_at. The object is the delivery contract only — what a delivery must satisfy comes from the quality-check version, never from a descriptive label (`data_type`, `data_domain` and `metadata_mode` are all gone — see the Dataset schema).

Declare at which folder depth a sample sits (PRD §4.3) — the only dataset write a partner has. Body: { sample_depth: 0-5 }. You own your output structure, so you declare the depth your deliveries use; everything else about a dataset is created and described by the client in the portal. Idempotent: re-declaring the current value succeeds with changed:false, so a pipeline can assert its depth on every run. Locks once any batch in the dataset leaves draft — after that the value is frozen so sample-scoped quality verdicts stay comparable across deliveries. Set it BEFORE your first submit.

The delivery contract: the published quality-check snapshot preflight/submit will evaluate, each check carrying a plain-language assertion, its quality dimension, whether it can be checked BEFORE upload, and a pass/fail example.

List scoped batches. Filter by dataset_id/status; cursor pagination.

Batch detail: status, whose-move, round number, files with upload state, submit-readiness.

Delete a draft batch (files, rows, and staging blobs). Draft only.

Quality findings; in changes_requested also per-file reviewer verdicts + request-changes comment.

Batch timeline (submitted, review_started, changes_requested, …).

Create OR resume the dataset's draft batch (one draft per dataset).

Declare files (single {path, size_bytes, checksum?} or {files: [...]} ≤500). Mints storage paths, creates 'queued' rows, returns the S3-multipart upload descriptor (protocol, part_size, max_parts_per_sign). Get presigned part URLs per file from /files/{id}/upload-parts. Re-declaring identical files is idempotent; a different size at an existing path needs replace=true.

Mint presigned S3 multipart UploadPart URLs for a declared file (SEC-TOKEN-01: no bearer token — each URL authorizes exactly one part of one object for a few minutes). Body: { part_numbers: number[] } (1-based, ≤ max_parts_per_sign). Returns the upload_id, the part_size, which parts already landed (resume), and a presigned url per still-missing requested part. PUT each part to its url; the ETag response header is what confirm needs. Gated to draft/changes_requested batches.

Finalize the upload: completes the S3 multipart upload from its parts, then verifies the staging object exists with the declared size, then flips the row to uploaded (audit batch.file_uploaded / file_reuploaded). Body: { upload_id, parts: [{part_number, etag}], checksum?, checksum_algorithm? }.

Remove a file (row + staging blob) from a draft / changes_requested batch.

Submit (or resubmit from changes_requested): round snapshot, frozen fields, synchronous auto-checks, status flip, reviewer notification. Blocks while declared files are still un-uploaded.

Recall a submitted batch (only before review starts). Restores draft or changes_requested and invalidates the submit snapshots.

Evaluate a file list ({files: [{path, size_bytes}]}, ≤10k) against the dataset's published quality checks BEFORE uploading. Read-only, no audit. Returns per-check verdicts with remediation hints; content-dependent checks come back in `deferred` (they run at submit), manual checks in `manual`.

Partner-side test transfer, API mode: multipart `file` ≤10 MB (hosting platform may cap request bodies earlier, ~4.5 MB on Vercel — a small sample file is the point). Satisfies the same activation checklist item as the portal sandbox (same tracking row, same audit event). Works while the bridge is still configuring.

List this bridge's webhook endpoints (url, events, active, failure_count, last delivery) plus the available event_types.

Create an endpoint: {url (HTTPS, public host), events?} — empty events = all partner events. The HMAC signing secret is returned ONCE. Deliveries carry `Myelin-Signature: t=<unix>,v1=<hmac_sha256(secret, t + "." + body)>` (5-min replay window recommended) and `Myelin-Event-Id` for dedup. Retries at +5 min/+30 min/+24 h, terminal after 4 attempts; endpoints auto-disable after 30 consecutive terminal failures.

Remove an endpoint (pending deliveries to it are dropped).

Queue and immediately attempt a synthetic test.ping delivery (signed like a real event).

Polling fallback for shops without an HTTPS receiver: ascending cursor over batch timeline events across the key's projects. Pass next_cursor back VERBATIM (it carries microsecond precision).