---
title: "on api file upload · RUAL Documentation"
description: "Exposes URI on /api/. Accepts a multipart/form-data POST request and saves the attached file. Supports its own rate limit and lock (serialisation) throu…"
canonical: https://docs.rual.nl/block-types/http%20connection/on_startup_register_uri_file
language: en
---

[Cluster](https://docs.rual.nl/cluster)

[Blocks](https://docs.rual.nl/block-types)

[Interfaces](https://docs.rual.nl/interfaces)

[Blueprints](https://docs.rual.nl/blueprints)

[Tutorials](https://docs.rual.nl/tutorials)

[Home automation](https://docs.rual.nl/home-automation)

[Examples](https://docs.rual.nl/examples)

[Reference](https://docs.rual.nl/reference)

[Architecture](https://docs.rual.nl/architecture)

[Troubleshooting](https://docs.rual.nl/troubleshooting)

Other

# on api file upload

This block is part of the [`http connection`](https://docs.rual.nl/block-types/http%20connection) group and was last modified in core [`v15.0.0`](https://docs.rual.nl/core-versions/150000).

Exposes URI on /api/. Accepts a multipart/form-data POST request and saves the attached file. Supports its own rate limit and lock (serialisation) through the pins below.

- file size limit `number` the file size limit in bytes

Default `5242880 bytes (5MB)`

- rate limit `v15.0.0` `number` Maximum number of uploads allowed per timeframe. Leave empty for the cluster default. Must be a fixed value on this block.

- rate limit timeframe `v15.0.0` `number` Length of the rate-limit window in seconds.

Default `60`

- rate limit per `v15.0.0` `value` What the limit is counted per: `url`, `url_user`, `method_url` or `method_url_user`. • Suggestions: `url` `url_user` `method_url` `method_url_user`

Default `method_url_user`

- lock `v15.0.0` `condition` Serialise this endpoint: while one upload is running, another caller with the same lock key waits (or gets a 429 when the timeout is 0).

Default `false`

- lock timeout `v15.0.0` `number` How many seconds a waiting caller may queue for the lock before it gets a 429. `0` fails immediately. Clamped to 30.

Default `0`

- lock per `v15.0.0` `value` What the lock is claimed per: `url`, `url_user`, `method_url` or `method_url_user`. • Suggestions: `url` `url_user` `method_url` `method_url_user`

Default `method_url_user`

- On Request `execute_function`

Startup registration block, not a flow executor: registers a POST /api/{version}/{uri} endpoint that accepts multipart/form-data uploads, saves each file under the entity's temp directory and calls the On Request function with connection, params, query, body and file pins (file entries are {filename, path, type} ready for file_* blocks; JSON-looking form fields are parsed into the body). The filesize pin caps upload bytes (default 5 MB); the rate_limit and lock pins add per-endpoint throttling and serialization and must be fixed values on the block, not wired chains. A route without any scope is LOCKED with 403 : not public; use *public to expose it.

| `register file` |
| --- |

A typical wiring for [on api file upload](https://docs.rual.nl/block-types/http%2520connection/on_startup_register_uri_file): [number](https://docs.rual.nl/block-types/number/number_default) feeds the `filesize` pin; [x](https://docs.rual.nl/block-types/math/number_times) feeds the `rate_limit` pin; the function out pin wires to an [execute](https://docs.rual.nl/block-types/function%2520execution/function_custom_execute_from_trigger) block.

[![Studio canvas example for the on api file upload block: typical wiring for on api file upload.](https://docs.rual.nl/canvas-examples/on_startup_register_uri_file.png)](https://docs.rual.nl/canvas-examples/on_startup_register_uri_file.png?v=3)

## Commonly used with

In production blueprints, this block is most often wired together with:

- [execute](https://docs.rual.nl/block-types/function%20execution/function_custom_execute_from_trigger): this block feeds into it. Executes the given funcion and waits for it to be executed.

- [number](https://docs.rual.nl/block-types/number/number_default): feeds into this block. Generates a valid number from the filled custom value in the blueprint.

- [x](https://docs.rual.nl/block-types/math/number_times): feeds into this block. Multiplication operator produces the product of the operands.

## Version history

Introduced in [`v15.0.0`](https://docs.rual.nl/core-versions/150000).

- [Back to `http connection`](https://docs.rual.nl/block-types/http%20connection): Return to the main group to view all sub-groups

- [Back to `api`](https://docs.rual.nl/block-types/http%20connection?group=api): Return to the group to view all blocks within this group

Was this page helpful? [Tell us what to improve](https://docs.rual.nl/support) · RUAL Docs is an integral component of the [RUAL ecosystem](https://rual.nl)