Reference

The REST API.

Thin wrappers over the same functions the dashboard calls, so a behavior cannot exist in one and not the other. Base URL https://app.getsendframe.com/api/v1. GET /api/v1 returns this route table as JSON.

Authentication and scopes

API keys and nothing else: Authorization: Bearer sf_live_…. A dashboard session never works on the API, and a key never works on the dashboard. Keys are minted at Settings → API keys and shown once.

• read Every GET.

• send Every write, including upload and process. A leaked read key cannot consume storage, start conversions, or mail anything to a customer.

Conventions

• Requests camelCase. Unknown fields are REFUSED, not ignored — and on the multipart uploads, an unrecognized PART is refused the same way.

• Responses camelCase.

• Upload is multipart only. A file part and an optional title; any other part is refused. process must run before share: upload leaves an artifact pending on purpose.

• notify defaults to true. A share emails its recipients unless told not to.

Errors

Every refusal is JSON with an error code and, where there is something to do, a message saying what. Render the message rather than mapping the code to your own copy; it is kept in step with what the server actually did.

• 401 unauthorized No key, or a revoked one.

• 403 insufficient_scope The route needs send and the key has read. 403 account_closed says the organization is closed and how to reopen it.

• 400 unknown_fields Names the fields, the allowed ones, and the spelling you probably meant.

• 4xx integrity_* The artifact is not sent, masked or otherwise: malware, unprocessed, or zero pages. The message names the exact call to make next.

• 429 rate_limited with a scope. burst is a short ceiling (100 requests a minute per key; wait retryAfterSeconds and continue). quota is the day's allowance of artifact operations (30 on free, 200 on paid); nothing frees up until resetsAt, so stop and tell the person who asked.

• 503 database_timeout Transient, with Retry-After. On a write it also says retrySafe and, when it cannot be sure, verifyWith: the read that shows whether the send happened.

Retries and idempotency

Both send routes accept an optional idempotencyKey (8–255 characters, yours to choose). The same key replays the original send — 200 with replayed: true instead of 201 — and also finishes a send that was interrupted partway through emailing. Reusing a key for a different request is a 409. KEYS STOP DEDUPLICATING AFTER 24 HOURS.

Artifacts

• GET /artifacts read

  Every artifact, with status and finding counts. Start here.

• POST /artifacts send

  Upload. multipart/form-data with a file part; optional title. Those are the only parts accepted — an unrecognized one is REFUSED, not ignored, the same as an unknown JSON field.

• GET /artifacts/{id} read

  One artifact and where it stands: its status, its versions with the served one marked, findings by severity, and the shares sent from it. The single call that answers "can I send this yet, and what is in it" — the id-shaped counterpart to GET /artifacts, which every other artifact route already required and this one did not answer.

• POST /artifacts/{id}/process send

  Convert, scan and detect the NEWEST version. REQUIRED before an artifact can be shared. ASYNCHRONOUS: it returns without waiting, the version stays pending, and you learn the outcome by polling GET /artifacts/{id}/versions for ready or failed. Do not treat a response as a finished conversion.

• POST /artifacts/{id}/versions send

  Upload a new version of an existing artifact, so that shares already sent can serve it without a new link. multipart/form-data with a file part. Like the first upload it leaves the version pending: call process, poll GET /artifacts/{id}/versions until it is ready, then release it. Existing recipients, their verification and the state they wrote all carry over.

• GET /artifacts/{id}/versions read

  Every version of one artifact, newest first, saying which one recipients are being served right now.

• GET /artifacts/{id}/findings read

  The safety review, and what is currently redacted.

• POST /artifacts/{id}/share send

  Send. Body: recipients[], optional expiresAt, optional notify, optional idempotencyKey. PASS AN IDEMPOTENCY KEY IF YOU MIGHT RETRY: a 503 here can mean the send happened, and without a key the only safe move is to read GET /shares before trying again. With one, the retry returns the original send and mails anyone the first attempt missed.

• POST /artifacts/{id}/findings/{findingId}/unredact send

  Clear one redaction, so the recipient sees it from now on.

• POST /artifacts/{id}/findings/{findingId}/redact send

  Hide one finding again. Takes effect on the next fetch (a viewer with the bytes already open keeps them; page images are cached for five minutes). Answers with an exposure report: every viewing session that overlapped the window it was visible, and whether that session was on its page -- 'opened while it was visible', never 'saw it'.

Shares

• GET /shares read

  Every share this organization has sent, with how many recipients have opened each one.

• GET /shares/{id} read

  Recipients, status and engagement for one share.

• POST /shares/{id}/access send

  Turn download or print on or off for one share. Body: optional allowDownload, optional allowPrint (booleans). Both are off by default on a new share unless the organization's default says otherwise; a recipient sees both controls and a refused one is greyed. Download is never the original file.

• GET /shares/{id}/delivered read

  EXACTLY what a verified recipient receives, produced by the same function the viewer calls. Use this to check that redacted content is absent from the served bytes without needing a recipient link.

• GET /shares/{id}/state read

  Interactive state recipients wrote. Viewer-written, and typed as such.

• GET /shares/{id}/events read

  The unified event feed. Pass ?since= the previous cursor.

• POST /shares/{id}/release send

  Release a share held under require_human_release.

• POST /shares/{id}/recipients send

  Add recipients to a share that already exists, so "loop in their boss" does not need a second send. Body: recipients[], optional notify. Existing recipients keep their links, their verification and the state they wrote; only the new ones are emailed. Refused as a batch if any address is already on the share.

• POST /shares/{id}/revoke send

  Kill a share. Every recipient link stops resolving immediately. Idempotent: revoking twice reports the state rather than failing.

• POST /shares/{id}/expiry send

  Set or clear the expiry on a live share. Body: expiresAt as ISO 8601, or null to remove it.

Recipients

• POST /recipients/{id}/revoke send

  Kill one recipient's link, leaving the rest live.

• POST /recipients/{id}/erase send

  Erase everything about one named recipient — their address, their link, every view and everything they wrote. REVOKE THEM FIRST: this is refused on a live recipient, deliberately, because it is permanent. It records the request and the deletion happens on the next purge run, so the response says scheduled rather than pretending it is done. What survives is listed in the response: de-attributed document state, audit records naming an internal id, and the bounce suppression.