Request an upload URL

Request body CreateFileRequest

Responses

• 201 The pending file and its upload URL
  • file File required

    The reserved file record. It holds no bytes yet.

    • id string required

      The file id.

    • purpose string required

      What the file is for. Purpose decides where it can be used and which size cap applies.

    • status string required

      Where the upload stands. A file is only usable once it has been finalized; a created-but-never-finalized file holds no bytes.

    • name string required

      The file name you supplied.

    • contentType string required

      The MIME type you declared.

    • sizeBytes number | null required

      The real size, measured at finalization. Null before then — the size you declared at creation is a check, not a fact.

    • uploadedBy string | null required

      The member or key that uploaded it. Null when unknown.

    • createdAt string required

      When the file record was created, as an ISO 8601 instant.

    • updatedAt string required

      When it last changed, as an ISO 8601 instant.

  • uploadUrl string required

    PUT your bytes directly to this URL. It carries its own authorization, so do not send your API credential with it.

  • expiresAt string required

    When `uploadUrl` stops working, as an ISO 8601 instant. Create the file again to get a fresh one.

• 400 Invalid input, or larger than your plan allows
  • code string required

    Stable machine-readable error code. Branch on this, never on the numeric status.

    bad_requestunauthorizedsignature_requiredpayment_requiredforbiddennot_foundconflictgonepayload_too_largeunprocessable_entitytoo_many_requestsinternal_errornot_implementedbilling_unavailablenot_contactablemailbox_link_unavailablemailbox_requiredmail_engine_unavailablewebhook_publisher_unavailabledatabase_unavailableclient_error
  • message string required

    Human-readable explanation of the refusal.

  • status integer required

    The HTTP status code, repeated in the body.

  • remedy object

    A self-serve path forward, when one exists (a 402 points at the credit top-up).

    • kind string required

      What kind of remedy this is, so a client can route it: whether the caller can clear the condition through the API, or a person must act in the web app.

      topupconnect_mailbox
    • url string required

      Where to go to clear the condition: an API path, or a web app page when only a person can.

• 401 No or invalid credential
  • code string required

    Stable machine-readable error code. Branch on this, never on the numeric status.

    bad_requestunauthorizedsignature_requiredpayment_requiredforbiddennot_foundconflictgonepayload_too_largeunprocessable_entitytoo_many_requestsinternal_errornot_implementedbilling_unavailablenot_contactablemailbox_link_unavailablemailbox_requiredmail_engine_unavailablewebhook_publisher_unavailabledatabase_unavailableclient_error
  • message string required

    Human-readable explanation of the refusal.

  • status integer required

    The HTTP status code, repeated in the body.

  • remedy object

    A self-serve path forward, when one exists (a 402 points at the credit top-up).

    • kind string required

      What kind of remedy this is, so a client can route it: whether the caller can clear the condition through the API, or a person must act in the web app.

      topupconnect_mailbox
    • url string required

      Where to go to clear the condition: an API path, or a web app page when only a person can.