API Request delivery

The API Request node is the end of a flow: pipe an Output into it and every creative that renders through that output is delivered to your endpoint automatically, in the background, without anyone keeping Nubu open. It is how a render lands in your own asset management system.

Setting it up#

1. In Settings > Integrations > API, under Outbound credentials, add the authentication your endpoint expects: a Bearer token, an API key header (you choose the header name) or Basic (a username and password). The secret is stored encrypted and never shown again; Replace secret rotates it. Only the owner can manage credentials.
2. In the flow editor, add an API Request node from the API group and connect an Output to it.
3. On the node, choose the method (POST or PUT), enter the endpoint URL, pick the credential by name, and choose the delivery: Upload actual file or Download URL.

The endpoint URL must be an https address on a public host. The node warns when a setting is missing and shows an error when nothing is piped into it or the credential it names no longer exists.

What your endpoint receives#

Every delivery carries the same JSON metadata:

{
  "success": true,
  "run_id": "...",
  "creative_id": "...",
  "render_id": "...",
  "external_id": "customer-job-48291",
  "filename": "summer-sale-uk.mp4",
  "file": { "bytes": 83211042, "content_type": "video/mp4", "sha256": "..." },
  "manifest": { ... },
  "nubu": { "campaign_id": "...", "flow_id": "...", "output_id": "...", "rendered_at": "..." },
  "delivery": "file"
}

• Upload actual file: one multipart/form-data request with two parts, metadata (the JSON above) and file (the render's bytes, streamed). Large renders arrive as one streamed request, so your endpoint must accept a body of the render's size.
• Download URL: a JSON request with the metadata plus download_url and download_url_expires_at, a secure link to the render that your system fetches itself.

manifest is the creative's manifest: the values that produced the render (market, language, version, the copy, the fields) in the shape the delivery manifest CSV uses.

The automatic fallback#

A render over 2 GiB is sent as a Download URL instead, whatever the node's setting: the request carries "delivery": "download_url", "fallback_reason": "file_too_large" and the download_url. Handle both shapes.

Retries and failures#

• Nubu makes up to three attempts with an increasing delay between them. A 2xx answer ends the delivery as uploaded.
• After the third failure the delivery is failed; the HTTP status and an excerpt of the response are recorded on the creative, and the run reports delivery_failed for that creative. The render itself is unaffected and stays in Nubu.
• Each delivery's state (pending, uploading, uploaded, failed, the attempts, the HTTP status, when it was delivered and how) appears on the creative in the app and in the API (GET /runs/<run_id>, GET /creatives/<id>), and a run callback fires when it changes.

A re-render delivers again once the new render lands.