> ## Documentation Index
> Fetch the complete documentation index at: https://iii.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP

> Expose functions as HTTP endpoints with the http worker.

The `http` worker turns your functions into REST routes exposed as HTTP endpoints.

## Before adding the worker

`compose::add` is served by a running Compose daemon. Keep the engine and a daemon for this project
running in separate terminals before using any of the commands below. If this project does not have
a Compose file yet, create `worker-compose.yaml` containing `containers: {}` first.

```bash theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
# terminal 1
iii --config config.yaml

# terminal 2, from the directory that contains worker-compose.yaml
iii compose --namespace dev --engine ws://127.0.0.1:49134
```

`iii compose` without a subcommand starts the Compose daemon. `--namespace` selects its namespace,
and `--engine` connects it to the existing engine. These options are listed in the generated
[CLI reference](https://iii.dev/docs/0-25-0/cli-reference/index.md#iii-compose).

Run the remaining commands from a third terminal in that same project directory:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii trigger -n dev compose::add worker=http
```

> [!NOTE]
>
> This page covers the basic endpoint flow. For path patterns, methods, headers, and response handling, see the
> [http worker docs](https://workers.iii.dev/workers/http). The worker's server settings
> (port, host, CORS, timeouts) are managed at runtime through the
> [configuration worker](https://iii.dev/docs/0-25-0/using-iii/configuration.md).

## Create endpoints

The http worker exposes an `http` trigger type that binds a function to an HTTP method and path; the
function then runs on every matching request. Here is the full path from a running engine to a live
endpoint.

> [!NOTE]
>
> `registerTrigger` is deprecated in 0.25, but the http worker still publishes the `http` trigger
> type, so it remains the way to create endpoints. It logs one warning per process. See [Providers
> not migrated yet](https://iii.dev/docs/0-25-0/upgrading/from-0-24-x.md#providers-not-migrated-yet).

1. In a worker, register the function you want to expose and bind an `http` trigger to it. If you do
   not have a worker yet, follow [Create a new worker](https://iii.dev/docs/0-25-0/creating-workers/workers.md#create-a-new-worker), then edit its
   source. The
   handler receives the request (`body`, `headers`, method) and its return value becomes the
   response:

> [tab] Node / TypeScript
>
> ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
> import { registerWorker } from "iii-sdk";
>
> const url = process.env.III_URL;
> if (!url) throw new Error("III_URL must be set");
> const worker = registerWorker(url, {
>   workerName: "my-worker",
>   namespace: "orders",
> });
>
> worker.registerFunction("http::add", async (payload: { body: { a: number; b: number } }) => ({
>   status_code: 200,
>   body: { c: payload.body.a + payload.body.b },
>   headers: { "Content-Type": "application/json" },
> }));
>
> worker.registerTrigger({
>   type: "http",
>   function_id: "http::add",
>   config: { api_path: "/math/add", http_method: "POST" },
> });
> ```

> [tab] Python
>
> ```python theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
> import os
> from iii import register_worker, InitOptions
>
> worker = register_worker(
>     os.environ["III_URL"],
>     InitOptions(worker_name="my-worker", namespace="orders"),
> )
>
> def add(payload: dict) -> dict:
>     body = payload["body"]
>     return {
>         "status_code": 200,
>         "body": {"c": body["a"] + body["b"]},
>         "headers": {"Content-Type": "application/json"},
>     }
>
> worker.register_function("http::add", add)
>
> worker.register_trigger({
>     "type": "http",
>     "function_id": "http::add",
>     "config": {"api_path": "/math/add", "http_method": "POST"},
> })
> ```

> [tab] Rust
>
> ```rust theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
> use iii_sdk::builtin_triggers::{HttpMethod, HttpTriggerConfig};
> use iii_sdk::runtime::WorkerMetadata;
> use iii_sdk::trigger::IIITrigger;
> use iii_sdk::{InitOptions, RegisterFunction, register_worker};
> use schemars::JsonSchema;
> use serde::Deserialize;
> use serde_json::json;
>
> #[derive(Deserialize, JsonSchema)]
> struct AddRequest {
>     body: AddBody,
> }
> #[derive(Deserialize, JsonSchema)]
> struct AddBody {
>     a: i64,
>     b: i64,
> }
>
> let url = std::env::var("III_URL").expect("III_URL must be set");
> let worker = register_worker(
>     &url,
>     InitOptions {
>         metadata: Some(WorkerMetadata {
>             name: "my-worker".into(),
>             ..Default::default()
>         }),
>         namespace: Some("orders".into()),
>         ..Default::default()
>     },
> );
>
> worker.register_function(
>     "http::add",
>     RegisterFunction::new(|req: AddRequest| {
>         Ok(json!({
>             "status_code": 200,
>             "body": { "c": req.body.a + req.body.b },
>             "headers": { "Content-Type": "application/json" }
>         }))
>     }),
> );
>
> worker.register_trigger(
>     IIITrigger::Http(HttpTriggerConfig::new("/math/add").method(HttpMethod::Post))
>         .for_function("http::add"),
> )?;
> ```

The Rust SDK sets the worker name through `InitOptions.metadata.name`; Node uses `workerName`,
and Python uses `worker_name`. All three examples register the name `my-worker`.

2. Add the worker to Compose, pointing at its directory:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii trigger -n dev compose::add worker=./my-worker
```

For path patterns, request and response shapes, and the other configuration options, see the
[http worker docs](https://workers.iii.dev/workers/http).

## Calling the endpoint

Once the trigger is registered, set `HTTP_WORKER_URL` to the address configured for the http worker
and call the endpoint:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
# call the exposed function
curl -X POST "$HTTP_WORKER_URL/math/add" -H 'content-type: application/json' -d '{"a":2,"b":3}'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.