> 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](/reference/flows.md) [action](/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](/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:\ . 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](/how-to/integrations/integrate-with-external-systems.md). To view and test your API Endpoints, use the [API Explorer](/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** |

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.

Note: We automatically enforce uniqueness and remove illegal characters after the value is entered.

| #### 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. Not available for *GET*. | | **Body Data** | Map request body data in JSON format. Body data must use the [schema](/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](/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](/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" %} ```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](/reference/actions/action-variables.md) and [action data sources](/reference/actions/action-data-sources.md) that are marked **Return from action**, serialized as JSON. A **Custom Response Body** overrides this. #### Advanced | Property | Description | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Cache Response Data** | Enable caching for this endpoint. If the endpoint returns data that is static or not time-sensitive, you can cache the response data to increase performance. | | **Enable Rate Limit** | Set restrictions on how many parallel connections a single IP may have towards this endpoint, within a given time window. | --- # 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=&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.