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

# Invoke a Flow function

> Route application traffic through Flow

Invocation requires an ECS API key with `flow:invoke`.

## Invocation route

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
ALL /flow/functions/:name/*
```

The wildcard path and query string are forwarded to your function. GET, HEAD, POST, PUT, PATCH, DELETE, and OPTIONS are supported.

Example:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.cloudservices.ecowestern.net/v1/flow/functions/hello/events \
  -H "Authorization: Bearer $ECS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event":"created"}'
```

The function receives the application path `/events`.

## Request forwarding

* Query parameters are preserved.
* Request bodies are forwarded for methods other than GET and HEAD.
* Application headers are forwarded when possible.
* The ECS `Authorization` header is removed before forwarding.
* The function response is returned directly without an ECS response wrapper.

Do not rely on the ECS API key being available to function code. If your function needs application authentication, use a separate application credential or signed request scheme.

## Build application routes

Treat the function as an HTTP server rather than a single operation. For example:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
/health
/webhooks/provider
/v1/orders
```

Call those routes through the same ECS function name:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
/v1/flow/functions/<function-name>/health
/v1/flow/functions/<function-name>/webhooks/provider
/v1/flow/functions/<function-name>/v1/orders
```

## Permission errors

`flow:read` does not allow invocation. If a caller receives `permission_denied`, add `flow:invoke` for the required function resource.

## Production patterns

* Use a dedicated invocation key for each application.
* Scope the key to the function name when possible.
* Keep deployment keys out of runtime applications.
* Return clear status codes and content types from the function.
* Put health checks on a lightweight route that does not trigger expensive work.