> For the complete documentation index, see [llms.txt](https://docs.fortifiedid.se/control/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fortifiedid.se/control/configuration-reference/modules/api.md).

# API

Configure HTTP endpoints in Control and connect them to Pipes or DataProxy handlers.

{% hint style="info" %}
**Module name:** `Api`
{% endhint %}

The API module lets Control expose HTTP endpoints for system-to-system integrations. Instead of starting a Forms flow in a browser, a caller can send an HTTP request directly to Control and let the request be processed by Pipes or proxied to another service.

Use the API module when you want to:

* expose a simple integration endpoint under Control's HTTP listener
* validate incoming requests with an authentication pipe
* run a request pipe and return its result directly
* proxy a request and response to another backend service

## Runtime structure

At runtime, the `Api` module is configured in `modules/api.json`. The module defines a shared `http_context` and an array of endpoint definitions.

Each endpoint is registered as:

```
/<http_context>/<context_path>/<path>
```

`context_path` is optional. For every endpoint, Control also exposes a ping endpoint:

```
/<http_context>/<context_path>/<path>/ping
```

## Endpoint processing

An API request is handled in the following order:

1. The request is routed to the endpoint path.
2. If the endpoint is not public, the `auth.pipe` is executed.
3. The request is handled by the configured request handler.
4. The response is built by the configured response handler.

The available handlers are:

* `Pipes` for pipe-based request or response processing
* `DataProxy` when the request or response should be proxied

## DataProxy handler

`DataProxy` is used when Control should behave more like a thin HTTP proxy than a response renderer. The handler still calls a configured pipe, but it expects that pipe to return an HTTP-shaped result that can be forwarded back to the caller.

In practice, `DataProxy` is useful when the pipe calls another backend service and returns:

* `status` or `status_code`
* `status_message`
* `headers`
* `body`

The `DataProxy` response handler reads these fields and writes them directly to the outgoing HTTP response.

## DataProxy compared to Pipes

Both handlers use Pipes internally, but they serve different purposes:

| Handler     | Typical use                                                                        | How the request is built                                                                                                | How the response is built                                                                                     |
| ----------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `Pipes`     | Integration endpoints where Control should interpret, enrich, or reshape data      | Control can forward selected headers and parameters, populate request context, and optionally override session handling | Control renders the HTTP response itself by using `response.type`, `response.template`, and `response.status` |
| `DataProxy` | Proxy-style endpoints where another backend should decide the actual HTTP response | Control forwards the JSON request body as-is, or builds a small JSON object from request parameters                     | Control forwards the pipe result almost as-is by using returned status, headers, and body                     |

Use `Pipes` when Control should own the integration logic and response format. Use `DataProxy` when the downstream service should effectively own the HTTP response and Control should mainly forward it.

## Configuration in Control management

When API endpoints are managed through Control management, each endpoint is stored in its own directory:

```
config/modules/api_endpoints/<id>/
  endpoint.json
  pipes/
```

The endpoint configuration is stored in `endpoint.json`. Endpoint pipes are stored under `pipes/` and are loaded by the shared Pipes module.

The management UI creates a technical endpoint id, a default auth pipe, and a default request pipe for each new endpoint.

## Related documentation

* [Properties](/control/configuration-reference/modules/api/properties.md)
* [Response template](/control/configuration-reference/modules/api/response-template.md)
* [Pipes](/control/configuration-reference/modules/external-modules.md)