# API Connectors Canonical: https://useformwork.com/docs/extensions/api-connectors Define, test, and use reusable HTTP API actions in workflows. API Connectors turn HTTP endpoints into reusable FormWork workflow actions. A connector belongs to a project; its action definitions are shared across its Sandbox, Test, or Live environments. ## Create a Connector 1. Open a project and select **Extensions**. 2. Under **API Connectors**, select **Create**. 3. Enter a **Connector name** and **Connector ID**. 4. Select **Create connector**. The connector ID is a lowercase slug and cannot be changed after creation. You can create an empty connector and add environments and actions next, or start with **Import OpenAPI**. ## Import OpenAPI The import flow accepts OpenAPI YAML or JSON in three ways: - Paste the specification. - Upload a file. - Provide a specification URL. Select **Preview operations**, review supported and unsupported operations, and choose the supported ones to import. You can search, filter by support status or HTTP method, and select or clear all visible supported operations before creating the connector or adding actions. A single import supports up to 100 actions. Review generated parameter and response schemas after import. An OpenAPI document is a useful starting point, but descriptions and schemas may still need adjustment for a clear workflow mapping experience. ## Define Actions An action describes one HTTP operation. Select **Add action**, then configure: - Action name and optional description - Method, encoding, and path - Path, query, and header parameters - Optional request body schema - Optional response schema - Whether that endpoint bypasses environment authentication You can build request and response schemas from example JSON or OpenAPI, or define the endpoint and fields manually. Save an action before testing if you want its test history to persist. Actions belong to the connector definition, not to one environment. Editing an action changes it for every environment that uses the connector. ### Action control reference - **Method:** GET, POST, PUT, PATCH, or DELETE. - **Encoding:** `json` or `form`; this action setting determines how its body is sent. - **Path:** begins with `/` and may contain placeholders such as `/contacts/{id}`. FormWork detects each brace placeholder as a required path parameter. - **Bypass auth for this endpoint:** sends this action without the environment credential; default is to inherit environment authentication. - **Query params** and **Header params:** each has a name, type (`string`, `number`, `boolean`, or `object`), Required switch, and workflow-facing description. - **Request schema:** available for non-GET actions and becomes the workflow's body-mapping contract. - **Response schema:** describes JSON response fields exposed beneath `parsed_body`. For either schema, choose **JSON example** or **OpenAPI spec**, then validate and preview the result before applying it to the action draft. The preview can show a visual tree or raw specification. OpenAPI input can be pasted or uploaded, can identify an operation by ID, and can optionally update the action's method, path, and parameters when applied. You can also clear either schema. The **Workflow output** tab summarises every workflow-visible input and response field. Saved actions can be duplicated or deleted; deletion cannot be undone and may break workflow steps that use that action ID. ## Add an Environment Each environment has its own: - **Environment name** and immutable lowercase **Environment ID** - Enabled and default state - **Base URL** - Default `json` or `form` encoding - Request timeout in seconds - Authentication and secret - Default headers New environments start disabled. The first environment becomes the default; you can make another environment the default later. An enabled environment requires a base URL. You can edit the environment name, enabled state, URL, encoding, timeout, authentication, secret replacement, and headers. The environment ID cannot be changed. You can also make an environment default or delete it; workflows using a deleted environment must be reconfigured. ### Authentication Supported authentication types are: | Type | Configuration | |------|---------------| | None | No environment credential | | Bearer token | Token stored as a secret | | API key | Secret plus a header name or query parameter | | Basic auth | Pre-encoded Basic credential stored as a secret | Default headers apply to every action in that environment. Action-specific mapped headers can add to or override the request as configured. ## Test an Action Open a saved action's test area and: 1. Choose an enabled **Environment**. 2. Enter path, query, header, and body values as JSON. 3. Select **Preview request** for a dry run that resolves the request without sending it. 4. Select **Send test** to make the request. 5. Inspect the request, response status, headers, body, duration, and error details. Saved test runs appear in **History**. Select a run to inspect it again or delete it when it is no longer useful. ## Use an Action in a Workflow 1. Add or edit a workflow on a draft form version. 2. Select **+ Add Step**. 3. Choose the API Connector by name and select an enabled environment and action. 4. Map entry values and previous workflow outputs into the action's request fields. 5. Connect **Next** and, when needed, **Error**. 6. Publish the form version and test the real trigger with a test entry. If the selected environment is disabled or the action is deleted, the connector action cannot be added or run until the workflow is reconfigured. ## Response Outputs Downstream steps use the normal workflow reference syntax: ```text workflow:current.steps..outputs.status_code workflow:current.steps..outputs.headers workflow:current.steps..outputs.raw_body workflow:current.steps..outputs.parsed_body workflow:current.steps..outputs.parsed_body. ``` Available outputs are: | Output | Meaning | |--------|---------| | `status_code` | HTTP response status | | `body` | Response body as text | | `raw_body` | Response body as text | | `headers` | Normalised response headers | | `parsed_body` | Parsed JSON, when the response can be parsed | A response schema lets the reference picker expose fields beneath `parsed_body`. Without a parseable JSON body, `parsed_body` is absent. ## Success, HTTP Errors, and Failures When the HTTP request completes: - A success status follows **Next**. - A non-2xx status follows **Error**, where you can inspect the response outputs. Failures before a completed response—such as an invalid reference, missing environment configuration, blocked URL, timeout, DNS failure, or connection failure—fail the workflow run. They do not follow the **Error** path. ## Security and Network Rules Saved authentication secrets are not exposed to respondents or included in form data. API Connectors can call public web APIs; private, loopback, link-local, and other restricted network destinations are not supported. Redirected requests follow the same safety rules. API Connectors are declarative HTTP definitions. They cannot upload or execute custom code, add native extension fields, or register inbound webhook hooks. ## Troubleshooting - Confirm the environment is enabled and has a valid base URL. - Confirm the action path does not duplicate part of the base URL. - Check the authentication placement and replace the stored secret if needed. - Use **Preview request** to inspect URL, headers, and body before sending. - Add or correct the response schema when `parsed_body` fields do not appear in the reference picker. - Inspect connector test history for action-level problems and **Workflow Runs** for mapping or path problems.