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

# API Endpoints

An API Endpoint exposes a [Flow](https://docs.appfarm.io/reference/flows.md) [action](https://docs.appfarm.io/reference/actions.md) as an HTTP endpoint that can be called by external systems. API Endpoints allow Flows to receive requests from outside the solution — for example, webhook callbacks from third-party integrations or queries from external applications.

Each API Endpoint is a Flow action with its own endpoint configuration. When the endpoint is called, the action runs and (optionally) returns a response.

{% hint style="warning" %}
**Important**

For API Endpoints to be reachable in a given environment, the **Enable Flow endpoints and schedules** checkbox must be selected in the [Environment Configuration](https://docs.appfarm.io/reference/configuration/environments.md#general-settings).
{% endhint %}

### Usage

To create a Flow with API Endpoints:

* Click **Create Flow**.
* Select **API Endpoints**.
* Set the API root path. This becomes part of the endpoint URL.

To add an API Endpoint to an existing Flow:

* Open the Flow.
* Click **+ Create API Endpoint** in the **Actions** panel.
* Enter a name for the endpoint.

To call an endpoint from an external system, including tools like [Postman](https://www.postman.com/), construct an endpoint URL as follows:\
https\://`SOLUTION-HOSTNAME`/api/flows/`API-ROOT-PATH/ENDPOINT-PATH`.

For example, if the API root path is `orders` and the endpoint path is `create`, the URL would be:\
<https://your-solution.appfarm.app/api/flows/orders/create>.

To authenticate the request, include an API key as a Bearer token in the `Authorization` header. Read more on how to access a Flow endpoint from an external system [here](https://docs.appfarm.io/how-to/integrations/integrate-with-external-systems.md).

To set the time zone the run uses, for example for **Date Today** and date formatting, send the `x-time-zone` request header with a time zone name such as `Europe/Oslo`. Without the header, the run uses UTC. See [Date and time](https://docs.appfarm.io/reference/platform-concepts/date-and-time.md).

To view and test your API Endpoints, use the [API Explorer](https://docs.appfarm.io/reference/flows/api-explorer.md).

### Endpoint config

When you create an API Endpoint, the action has a separate **Endpoint config** tab where the HTTP configuration is defined.

#### General

| Property    | Description                                                                                                                                                                                                                                                                                    |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Methods** | The HTTP request methods that the endpoint will support. The available options are: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`. Read more about [HTTP request methods on MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods).                                                |
| **Path**    | <p>The path used in the endpoint URL. If not set, we will fall back to a technical ID, which is not very human-readable. Must consist of valid URL characters.<br><br><strong>Note:</strong> We automatically enforce uniqueness and remove illegal characters after the value is entered.</p> |

#### Path params

| Property        | Description                                                                                                                                                                                                          |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Path Params** | Add variable path segments that are required parts of the endpoint URL. For example `/customer/{customerId}` has a path param `customerId` Path params are available as contextual parameters in the action's logic. |

#### Inputs

These properties enable you to parse and map data sent as part of a request to the endpoint.

| Property            | Description                                                                                                                                                                                                                                                                                                                                 |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Query Params**    | Map values from query string parameters.                                                                                                                                                                                                                                                                                                    |
| **Request Headers** | Map values from request headers.                                                                                                                                                                                                                                                                                                            |
| **Body Parser**     | Parse body data into JSON. If the request contains body data that is not in JSON format, you can use the function editor to create a JSON object containing the data so that it can be mapped. The function gets the raw request body as `rawBodyData`, and `DOMParser` and `generateObjectId` are also available. Not available for *GET*. |
| **Body Data**       | Map request body data in JSON format. Body data must use the [schema](https://docs.appfarm.io/reference/platform-concepts/schemas.md) data type, and the request body is [validated](#body-validation) against it. Not available for *GET*.                                                                                                 |

{% hint style="info" %}
**Good to know**

A JSON request body can be up to 1 MB. To allow larger bodies, up to 50 MB, set **Max payload size for Flow endpoints** in the [Environment Configuration](https://docs.appfarm.io/reference/configuration/environments.md#general-settings). If the body is larger than the limit, the action doesn't run and the endpoint responds with status `413` and the error `RequestEntityTooLargeError` (code `14413`).
{% endhint %}

{% hint style="info" %}
**Good to know**

API Endpoint actions receive their input from the endpoint configuration — path params, query params, request headers, and body data — rather than from [action params](https://docs.appfarm.io/reference/actions/action-params.md). Action params are not shown on API Endpoint actions.
{% endhint %}

#### Body validation

When an endpoint has body data with a schema, the request body is checked against the schema before the action runs. The check applies to every method except *GET*. If a **Body Parser** is set, its output is what gets checked.

* Each value must match the data type of its schema property. Integers must be whole numbers. Date-time values must be ISO 8601 date-times or dates, for example `2026-09-17T10:00:00Z` or `2026-09-17`.
* Objects are checked property by property, and arrays item by item. Arrays can't contain `null` items.
* Properties that are missing or `null` are accepted, and so are properties that aren't in the schema.
* Formats aren't checked. For example, a URL property accepts any string.

If the body doesn't match, the action doesn't run and the endpoint responds with status `400`. The response lists up to three failing values, each with its path in the body:

{% code overflow="wrap" collapsedlinecount="10" %}

```json
{
  "name": "ValidationError",
  "message": "Input validation failed",
  "metadata": {
    "errors": [
      {
        "param": "Body data",
        "source": "body",
        "message": "items.1.qty: Expected number, received string"
      }
    ]
  }
}
```

{% endcode %}

{% hint style="info" %}
**Good to know**

To turn off body validation for a solution, get in touch with your Appfarm contact.
{% endhint %}

#### Response

These properties enable you to configure the headers and data sent in the response.

| Property                 | Description                                                                                                              |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| **Response Headers**     | Add custom headers or override default headers in the response. Response headers are evaluated after the action has run. |
| **Custom Response Body** | Construct a custom response body using the function editor. This can be used instead of the default response format.     |

By default, the response includes all [action variables](https://docs.appfarm.io/reference/actions/action-variables.md) and [action data sources](https://docs.appfarm.io/reference/actions/action-data-sources.md) that are marked **Return from action**, serialized as JSON. A **Custom Response Body** overrides this.

**Failed runs.** If the run fails, the endpoint responds with the error as the body. **Custom Response Body** and **Response Headers** are not used. The status code is the **Response code** of the [Throw Exception](https://docs.appfarm.io/library/action-nodes/throw-exception.md) node whose exception was not caught, or `500` for any other error. A timeout that no Catch Exception handles responds with `504`.

{% hint style="info" %}
**Good to know**

To keep status `200` for failed runs in a solution, get in touch with your Appfarm contact.
{% endhint %}

#### Advanced

| Property                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Timeout**             | <p>How long the action may run, as a whole number of seconds from 1 to 14,400 (4 hours). Leave it blank for no limit.<br><br>When the time is up, the action node that is running is stopped with a <strong>Flow timeout</strong> exception. A <a href="https://docs.appfarm.io/library/action-nodes/catch-exception.md">Catch Exception</a> in the action can handle it and gets 60 seconds to finish, and its response is sent as normal. An unhandled timeout, or a Catch Exception that needs more than 60 seconds, answers the caller with status <code>504</code>.</p> |
| **Cache Response Data** | *Displayed if `GET` is one of the **Methods**.* Store the response and reuse it for later requests instead of running the endpoint again. Use this when the data is static or not time-sensitive, to reduce server load. Responses are cached separately for each caller, each environment, and each combination of path param, query param and mapped request header values.                                                                                                                                                                                                |
| **Cache Timeout**       | *Displayed if **Cache Response Data** is set.* How long, in seconds, a cached response is reused before the endpoint runs again. Default is 3600 (1 hour).                                                                                                                                                                                                                                                                                                                                                                                                                   |
| **Enable Rate Limiter** | Limit how often the endpoint can be called within a time window, set with **Rate Limit Points** and **Rate Limit Window**.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| **Rate Limit Points**   | *Displayed if **Enable Rate Limiter** is set.* The number of requests allowed per window. Default is 15.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| **Rate Limit Window**   | *Displayed if **Enable Rate Limiter** is set.* The length of the window, in seconds. Default is 30, maximum is 3600.                                                                                                                                                                                                                                                                                                                                                                                                                                                         |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.appfarm.io/reference/flows/api-endpoints.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
