# Connector files

A connector: one HTTP endpoint, described once. Its method and URL, its parameters, the shape of its request and response, and the kind of credential it needs. Agents never call a connector directly: a tool points at it.

What connectors are for, and how to use them: [Tools](https://docs.maitento.com/concepts/tools.md).

## Where the file goes

`connectors/open-api/`, or any sub-folder of it. The file name without `.mtr` is the connector's name. Other files refer to it as `@ref("<name>")`.

A resource's name is its file name without `.mtr` (an app's is its folder's name). Use letters, digits, `_`, `-` and `.` (but not `..`), at most 128 characters. Two files of the same kind may not have the same name, even in different sub-folders or with different capitals.

## Properties

A file must set `method`, `url` and `description`. Everything else is optional.

### `method`

**Required.** HTTP method.

The HTTP method.

Usually one of `GET`, `POST`, `PUT`, `PATCH`, `DELETE`.

```hcl
method = "GET"
```

### `url`

**Required.** URL.

The endpoint's full URL. `{name}` in it marks a path parameter, declared in `parameters.path`.

```hcl
url = "https://api.open-meteo.com/v1/forecast"
```

### `description`

**Required.** Text.

What the endpoint does, in a sentence (500 characters at most).

```hcl
description = "Current weather for a latitude and longitude, from Open-Meteo"
```

### `parameters.path`

Optional. [List of blocks](#each-item-of-parameterspath).

The parameters in the URL's path, one for each `{name}` in `url`.

### `parameters.query`

Optional. [List of blocks](#each-item-of-parameterspath).

The query-string parameters.

### `schema.request`

Optional. JSON text.

The JSON Schema of the request body, usually `@json("name")`. The model's arguments are checked against it before the call is made. Without one, no body is sent, even for a POST.

```hcl
schema.request = @json("refund-request")
```

### `schema.response`

Optional. JSON text.

The JSON Schema the endpoint's response must match, usually `@json("name")`.

```hcl
schema.response = @json("order")
```

### `postProcessResponseUnicodeCharacters`

Optional. `true` or `false`. Default: `false`.

Replace typographic characters in the response (curly quotes, dashes, bullets, the ellipsis) with plain ones before it is read. Applies when `schema.response` is set.

```hcl
postProcessResponseUnicodeCharacters = true
```

### `auth`

Optional. One of the values below. Default: `"None"`.

The kind of credential the endpoint needs. The credential itself is given where a tool uses the connector.

| Value | Meaning |
|---|---|
| `None` | No credential is sent. |
| `Header` | A secret's value, sent in an HTTP header that the tool names. |
| `Maitento` | A short-lived Maitento token, for connectors that call Maitento's own API. |

```hcl
auth = "Header"
```

## Each item of `parameters.path`

A path or query parameter of a connector: `{ name = "latitude" description = "Latitude in decimal degrees" type = "number" }`.

The same block is used for `parameters.query`.

### `parameters.path` › `description`

**Required.** Text.

What the parameter means. The model reads it to choose a value.

```hcl
description = "The order id, for example A-1001"
```

### `parameters.path` › `name`

**Required.** Text.

The parameter's name, as the endpoint expects it. A path parameter's matches `{name}` in the URL.

```hcl
name = "orderId"
```

### `parameters.path` › `type`

Optional. One of the values below. Default: `"String"`.

The type of value the model must give.

| Value | Meaning |
|---|---|
| `String` | Text. |
| `Number` | A number that may have a fractional part. |
| `Integer` | A whole number. |
| `Boolean` | true or false. |

```hcl
type = "number"
```

### `parameters.path` › `required`

Optional. `true` or `false`. Default: `true`.

Whether a call must give the parameter.

```hcl
required = false
```

## A complete example

From the [15-files-for-agents](https://github.com/maitento/maitento/tree/main/examples/15-files-for-agents) example project:

```hcl title="connectors/open-api/vfs-write.mtr"
method = "PUT"
url = "https://api.maitento.com/vfs/by-id/{id}/files/write/text"
description = "Writes a text file to a virtual file system, replacing it if it exists"
auth = "Maitento"
schema.request = @json("vfs-write-request")
parameters.path = [
  {
    name = "id"
    description = "The virtual file system id"
  }
]
parameters.query = [
  {
    name = "path"
    description = "The file to write, for example /shopping.md"
  }
]
```