> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/adapters/configure/actions/reference/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# action.json field definitions

> Reference for all fields available in an adapter action.json file.

Adapter Builder auto-populates `action.json` fields from the provided OpenAPI document. When the builder cannot derive a value, the field is set to its default.

## Fields

| Field                  | Required                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ---------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                 | Yes                          | The unique name of the action within the adapter, corresponding to the method name in `adapter.js`. Adapter Builder uses the `operationId` from the OpenAPI document if available; otherwise it generates a name from the HTTP method and path. When `adapter.js` calls `identifyRequest`, it passes the entity name as the first parameter and this `name` as the second.                                                                                                        |
| `protocol`             | Yes                          | The protocol for the action. `REST` is currently the only supported value. SOAP-based systems also use `REST` since SOAP calls are made as HTTP/HTTPS POST requests.                                                                                                                                                                                                                                                                                                              |
| `method`               | Yes                          | The HTTP method (verb) for the call. Common values are `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`, but others are supported.                                                                                                                                                                                                                                                                                                                                                     |
| `entitypath`           | Yes                          | The path appended to the base API call: `https://host:port/entitypath`. Supports variables such as `{base_path}` that the adapter library replaces at runtime. Can be a string for a single path, or an object with version keys when multiple paths need to be supported for the same action. The active path is selected using the `choosepath` property in theItential Platform service instance configuration. If `choosepath` is not set, the first path is used by default. |
| `schema`               | Yes (if no specific schemas) | The default schema used for both the request and response when no action-specific schemas are defined.                                                                                                                                                                                                                                                                                                                                                                            |
| `requestSchema`        | Yes (if no general `schema`) | A schema specific to the request.                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `responseSchema`       | Yes (if no general `schema`) | A schema specific to the response.                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `timeout`              | No → `0`                     | An action-level timeout in milliseconds that overrides the global `request.attempt_timeout`. If not set or set to `0` or less, the global timeout applies.                                                                                                                                                                                                                                                                                                                        |
| `sendEmpty`            | No → `false`                 | When `true`, sends an empty object (`{}`) to the external system even when there is no data to send. Some systems require this to process a request.                                                                                                                                                                                                                                                                                                                              |
| `sendGetBody`          | No → `false`                 | When `true`, sends a body with GET requests. Most systems do not expect a body on GET requests, but some do.                                                                                                                                                                                                                                                                                                                                                                      |
| `datatype`             | No → `JSON`                  | The data format used for both request and response when no action-specific datatypes are defined. Supported values: `PLAIN`, `XML`, `XML2JSON`, `URLENCODE`, `FORM`, `JSON`. For token requests, `URLQUERY` is also accepted and passes token data in the URL instead of the request body. Unsupported values fall back to `PLAIN`.                                                                                                                                               |
| `requestDatatype`      | No → `JSON`                  | Datatype specific to the request.                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `responseDatatype`     | No → `JSON`                  | Datatype specific to the response.                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `headers`              | No → `{}`                    | Static headers to include on every call for this action. Action-level headers override global request headers set in the service instance configuration. Note that `Content-Type` and `Accept` are set automatically by the adapter library based on the datatype, but they can be overridden here.                                                                                                                                                                               |
| `responseObjects`      | Yes                          | Tells the adapter how to handle the response. Serves two purposes: locating the data within the response thatItential Platform cares about, and pointing to mock data files for standalone testing.                                                                                                                                                                                                                                                                               |
| `responseObjects.type` | Yes                          | Identifies which response object to use. The adapter library works through a hierarchy to find the best match. A `default` response object must always be present as a fallback.                                                                                                                                                                                                                                                                                                  |
| `key`                  | Yes (can be empty)           | A JSONQuery string that locates the relevant data within the response. Use this to strip metadata and return only the fieldsItential Platform needs. Leave empty to return the full response.                                                                                                                                                                                                                                                                                     |
| `mockFile`             | Yes (can be empty)           | The relative path to the mock data file returned when the adapter runs in stub mode. Leave empty if mock data is not needed.                                                                                                                                                                                                                                                                                                                                                      |

## Example

```json
{
  "name": "getIP",
  "protocol": "REST",
  "method": "GET",
  "entitypath": "{base_path}/{version}/addresses/{pathv1}",
  "requestSchema": "schema.json",
  "responseSchema": "schemaReturn.json",
  "timeout": 3000,
  "sendEmpty": true,
  "sendGetBody": false,
  "requestDatatype": "PLAIN",
  "responseDatatype": "XML2JSON",
  "headers": {
    "Content-Type": "application/text"
  },
  "responseObjects": [
    {
      "type": "default",
      "key": "",
      "mockFile": "mockdatafiles/getIP-default.xml"
    }
  ]
}
```

> Reference for all fields available in an adapter action.json file.