Get a presigned URL to upload a large PDF directly

POST

/files/presign

const url = 'https://api.sealpost.app/v1/files/presign';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"name":"example","bytes":1,"mime":"application/pdf"}'
};

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/presign \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "bytes": 1, "mime": "application/pdf" }'

Scope envelopes:write. Returns upload_url and the exact headers to send with the PUT (they carry the server-side encryption under the tenant’s key and are part of the signature). The URL lives 15 minutes. Then call POST /files/{id}/complete.

Authorizations

ApiKey

Request Body^required

application/json

object

name

required

string

<= 255 characters

bytes

required

The file size you will upload.

integer

>= 1 <= 26214400

mime

string

default: application/pdf

Allowed values: application/pdf

Responses

201

Where to PUT the bytes.

application/json

object

file_id

required

string format: uuid

upload_url

required

PUT the bytes here.

string format: uri

headers

required

Send these headers on the PUT exactly; they are part of the signature.

object

key

additional properties

string

expires_at

required

string format: date-time

then

required

The path to POST once the upload is done.

string

Example ^generated

{
  "file_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "upload_url": "https://example.com",
  "headers": {
    "additionalProperty": "example"
  },
  "expires_at": "2026-04-15T12:00:00Z",
  "then": "example"
}

Headers

Sign-Request-Id

string

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

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.

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.

Get a presigned URL to upload a large PDF directly

Authorizations

Request Bodyrequired

Responses

201

Example generated

Headers

400

Example

Headers

401

Example

Headers

403

Example

Headers

422

Example

Headers

429

Example

Headers

500

Example

Headers

Request Body^required

Example ^generated