Upload a PDF, or register one by URL or base64

POST

/files

const url = 'https://api.sealpost.app/v1/files';
const form = new FormData();
form.append('file', 'example');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.sealpost.app/v1/files \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file=example

Scope envelopes:write. Three bodies: multipart/form-data with the PDF in the part named file; JSON {"url": "https://…"} (publicly reachable, fetched once, 25 MB); or JSON {"base64": "…", "name": "x.pdf"} (10 MB). The response carries the SHA-256 of the original bytes, the page count and every page’s visual size in points (page_sizes), which field geometry is checked against. PDF only in this release. An unattached file is kept 30 days, then swept. For larger files use /files/presign. Honours Idempotency-Key.

Authorizations

ApiKey

Parameters

Header Parameters

Idempotency-Key

string

>= 1 characters <= 255 characters

Client-chosen key, 1 to 255 characters, scoped to (tenant, API key, method, path). The first response is stored for 24 hours and replayed for repeats with the same body (Idempotent-Replayed: true). A repeat with a different body is a 422 idempotency_key_reused; a repeat while the first request is still running is a 409 idempotency_in_flight (a request that dies mid-flight releases its lock after 60 seconds).

Request Body^required

object

file

required

string

Exactly one of url or base64 (a multipart body sends the part file instead).

object

url

Publicly reachable http(s) URL of a PDF, fetched once, 25 MB. Addresses inside private networks are refused.

string format: uri

base64

The PDF bytes, up to 10 MB decoded.

string

name

File name shown to signers; defaults to the URL’s last segment or document.pdf.

string

<= 255 characters

Example ^generated

{
  "url": "https://example.com",
  "base64": "example",
  "name": "example"
}

Responses

201

The stored file.

application/json

object

required

string format: uuid

envelope_id

Null until the file is attached to an envelope.

string | null format: uuid

position

1-based order within the envelope.

integer | null

name

required

string

kind

The caller’s label for the document type, e.g. merchant_application; used to split a signed envelope back into its documents.

string | null

mime

required

string

bytes

required

integer

sha256

SHA-256 (hex) of the original bytes, exactly as uploaded. Null while pending.

string | null

pdf_version

string | null

page_count

integer | null

page_sizes

Array<object> | null

One page’s visual size in points (after /Rotate).

object

required

number

required

number

rotate

required

integer

Allowed values: 0 90 180 270

status

required

string

Allowed values: pending converting ready failed

error

string | null

upload_expires_at

When an unattached upload is swept (30 days). Null once attached.

string | null format: date-time

created_at

required

string format: date-time

Example

{
  "page_sizes": [
    {
      "rotate": 0
    }
  ],
  "status": "pending"
}

Headers

Sign-Request-Id

string

Unique id of this request (req_…). Quote it in support requests.

Idempotent-Replayed

boolean

Present and true when the response was replayed from a stored earlier response for the same Idempotency-Key.

400

The request could not be read (malformed JSON, bad header).

application/problem+json

RFC 9457 problem details plus a stable code and the request_id.

object

type

required

https://sealpost.app/errors/{code}

string format: uri

title

required

string

status

required

integer

detail

Human-readable, safe to show to a developer, never contains secrets or signer data.

string

instance

The request path.

string

code

required

Stable machine-readable code from the catalogue (docs/errors.md).

string

request_id

required

string

errors

Field-level detail on validation_failed.

Array<object>

object

param

required

JSON pointer-ish path, e.g. scopes[2].

string

message

required

string

Example

{
  "type": "https://sealpost.app/errors/insufficient_scope",
  "title": "Forbidden",
  "status": 403,
  "detail": "This key lacks the api_keys:write scope.",
  "code": "insufficient_scope",
  "request_id": "req_01J9ZK3V8Q4M2XQ7W0E5D1R6TA"
}

Headers

Sign-Request-Id

string

Unique id of this request (req_…). Quote it in support requests.

401

No key, an unknown key, or a revoked or expired key.

application/problem+json

RFC 9457 problem details plus a stable code and the request_id.

object

type

required

https://sealpost.app/errors/{code}

string format: uri

title

required

string

status

required

integer

detail

Human-readable, safe to show to a developer, never contains secrets or signer data.

string

instance

The request path.

string

code

required

Stable machine-readable code from the catalogue (docs/errors.md).

string

request_id

required

string

errors

Field-level detail on validation_failed.

Array<object>

object

param

required

JSON pointer-ish path, e.g. scopes[2].

string

message

required

string

Example

{
  "type": "https://sealpost.app/errors/insufficient_scope",
  "title": "Forbidden",
  "status": 403,
  "detail": "This key lacks the api_keys:write scope.",
  "code": "insufficient_scope",
  "request_id": "req_01J9ZK3V8Q4M2XQ7W0E5D1R6TA"
}

Headers

Sign-Request-Id

string

Unique id of this request (req_…). Quote it in support requests.

403

The key is valid but lacks the scope, or a test key tried a live-only action.

application/problem+json

RFC 9457 problem details plus a stable code and the request_id.

object

type

required

https://sealpost.app/errors/{code}

string format: uri

title

required

string

status

required

integer

detail

Human-readable, safe to show to a developer, never contains secrets or signer data.

string

instance

The request path.

string

code

required

Stable machine-readable code from the catalogue (docs/errors.md).

string

request_id

required

string

errors

Field-level detail on validation_failed.

Array<object>

object

param

required

JSON pointer-ish path, e.g. scopes[2].

string

message

required

string

Example

{
  "type": "https://sealpost.app/errors/insufficient_scope",
  "title": "Forbidden",
  "status": 403,
  "detail": "This key lacks the api_keys:write scope.",
  "code": "insufficient_scope",
  "request_id": "req_01J9ZK3V8Q4M2XQ7W0E5D1R6TA"
}

Headers

Sign-Request-Id

string

Unique id of this request (req_…). Quote it in support requests.

409

A request with the same Idempotency-Key is still in flight.

application/problem+json

RFC 9457 problem details plus a stable code and the request_id.

object

type

required

https://sealpost.app/errors/{code}

string format: uri

title

required

string

status

required

integer

detail

Human-readable, safe to show to a developer, never contains secrets or signer data.

string

instance

The request path.

string

code

required

Stable machine-readable code from the catalogue (docs/errors.md).

string

request_id

required

string

errors

Field-level detail on validation_failed.

Array<object>

object

param

required

JSON pointer-ish path, e.g. scopes[2].

string

message

required

string

Example

{
  "type": "https://sealpost.app/errors/insufficient_scope",
  "title": "Forbidden",
  "status": 403,
  "detail": "This key lacks the api_keys:write scope.",
  "code": "insufficient_scope",
  "request_id": "req_01J9ZK3V8Q4M2XQ7W0E5D1R6TA"
}

Headers

Sign-Request-Id

string

Unique id of this request (req_…). Quote it in support requests.

413

A file is over 25 MB (10 MB inline as base64); use /files/presign.

application/problem+json

RFC 9457 problem details plus a stable code and the request_id.

object

type

required

https://sealpost.app/errors/{code}

string format: uri

title

required

string

status

required

integer

detail

Human-readable, safe to show to a developer, never contains secrets or signer data.

string

instance

The request path.

string

code

required

Stable machine-readable code from the catalogue (docs/errors.md).

string

request_id

required

string

errors

Field-level detail on validation_failed.

Array<object>

object

param

required

JSON pointer-ish path, e.g. scopes[2].

string

message

required

string

Example

{
  "type": "https://sealpost.app/errors/insufficient_scope",
  "title": "Forbidden",
  "status": 403,
  "detail": "This key lacks the api_keys:write scope.",
  "code": "insufficient_scope",
  "request_id": "req_01J9ZK3V8Q4M2XQ7W0E5D1R6TA"
}

Headers

Sign-Request-Id

string

Unique id of this request (req_…). Quote it in support requests.

422

The request was read but a value is invalid, or an Idempotency-Key was reused with a different body.

application/problem+json

RFC 9457 problem details plus a stable code and the request_id.

object

type

required

https://sealpost.app/errors/{code}

string format: uri

title

required

string

status

required

integer

detail

Human-readable, safe to show to a developer, never contains secrets or signer data.

string

instance

The request path.

string

code

required

Stable machine-readable code from the catalogue (docs/errors.md).

string

request_id

required

string

errors

Field-level detail on validation_failed.

Array<object>

object

param

required

JSON pointer-ish path, e.g. scopes[2].

string

message

required

string

Example

{
  "type": "https://sealpost.app/errors/insufficient_scope",
  "title": "Forbidden",
  "status": 403,
  "detail": "This key lacks the api_keys:write scope.",
  "code": "insufficient_scope",
  "request_id": "req_01J9ZK3V8Q4M2XQ7W0E5D1R6TA"
}

Headers

Sign-Request-Id

string

Unique id of this request (req_…). Quote it in support requests.

429

The key is over its per-minute budget (600 live, 60 test, sliding window).

application/problem+json

RFC 9457 problem details plus a stable code and the request_id.

object

type

required

https://sealpost.app/errors/{code}

string format: uri

title

required

string

status

required

integer

detail

Human-readable, safe to show to a developer, never contains secrets or signer data.

string

instance

The request path.

string

code

required

Stable machine-readable code from the catalogue (docs/errors.md).

string

request_id

required

string

errors

Field-level detail on validation_failed.

Array<object>

object

param

required

JSON pointer-ish path, e.g. scopes[2].

string

message

required

string

Example

{
  "type": "https://sealpost.app/errors/insufficient_scope",
  "title": "Forbidden",
  "status": 403,
  "detail": "This key lacks the api_keys:write scope.",
  "code": "insufficient_scope",
  "request_id": "req_01J9ZK3V8Q4M2XQ7W0E5D1R6TA"
}

Headers

Sign-Request-Id

string

Unique id of this request (req_…). Quote it in support requests.

Retry-After

integer

Seconds to wait before retrying.

RateLimit-Limit

integer

Requests allowed per minute for this key (600 live, 60 test).

RateLimit-Remaining

integer

Requests remaining in the current window.

RateLimit-Reset

integer

Seconds until the window has capacity again.

500

Something failed on our side. The request_id is in our logs.

application/problem+json

RFC 9457 problem details plus a stable code and the request_id.

object

type

required

https://sealpost.app/errors/{code}

string format: uri

title

required

string

status

required

integer

detail

Human-readable, safe to show to a developer, never contains secrets or signer data.

string

instance

The request path.

string

code

required

Stable machine-readable code from the catalogue (docs/errors.md).

string

request_id

required

string

errors

Field-level detail on validation_failed.

Array<object>

object

param

required

JSON pointer-ish path, e.g. scopes[2].

string

message

required

string

Example

{
  "type": "https://sealpost.app/errors/insufficient_scope",
  "title": "Forbidden",
  "status": 403,
  "detail": "This key lacks the api_keys:write scope.",
  "code": "insufficient_scope",
  "request_id": "req_01J9ZK3V8Q4M2XQ7W0E5D1R6TA"
}

Headers

Sign-Request-Id

string

Unique id of this request (req_…). Quote it in support requests.

503

The document service could not be reached; nothing was stored. Retry after Retry-After seconds with the same Idempotency-Key.

application/problem+json

RFC 9457 problem details plus a stable code and the request_id.

object

type

required

https://sealpost.app/errors/{code}

string format: uri

title

required

string

status

required

integer

detail

Human-readable, safe to show to a developer, never contains secrets or signer data.

string

instance

The request path.

string

code

required

Stable machine-readable code from the catalogue (docs/errors.md).

string

request_id

required

string

errors

Field-level detail on validation_failed.

Array<object>

object

param

required

JSON pointer-ish path, e.g. scopes[2].

string

message

required

string

Example

{
  "type": "https://sealpost.app/errors/insufficient_scope",
  "title": "Forbidden",
  "status": 403,
  "detail": "This key lacks the api_keys:write scope.",
  "code": "insufficient_scope",
  "request_id": "req_01J9ZK3V8Q4M2XQ7W0E5D1R6TA"
}

Headers

Sign-Request-Id

string

Unique id of this request (req_…). Quote it in support requests.

Retry-After

integer

Seconds to wait before retrying.

Upload a PDF, or register one by URL or base64

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Example generated

Responses

201

Example

Headers

400

Example

Headers

401

Example

Headers

403

Example

Headers

409

Example

Headers

413

Example

Headers

422

Example

Headers

429

Example

Headers

500

Example

Headers

503

Example

Headers

Request Body^required

Example ^generated