# Create a collector metric target

Creates a new monitoring target on a collector.

[info]
Each target kind accepts a specific set of connection fields. Sending a field that does not apply to the chosen kind (for example, `ssl_mode` on a `redis` target) will return a validation error.
[/info]

[endpoint]
base_url = "https://telemetry.betterstack.com"
path = "/api/v1/collectors/{collector_id}/targets"
method = "POST"

[[url_param]]
name = "collector_id"
description = "The ID of the collector."
required = true
type = "string"

[[body_param]]
name = "kind"
description = "The type of target. Valid options are `postgres`, `mysql`, `redis`, `mongodb`, `memcached`, `elasticsearch`, `nginx`, `apache`, `kafka`, and `prometheus`."
required = true
type = "string"

[[body_param]]
name = "host"
description = "The hostname or IP address of the target."
required = true
type = "string"

[[body_param]]
name = "port"
description = "The port number. Required for database kinds, optional for process kinds."
required = false
type = "integer"

[[body_param]]
name = "service"
description = "The service or container name. Required for process kinds (`nginx`, `apache`, `kafka`, `prometheus`)."
required = false
type = "string"

[[body_param]]
name = "listen_ip"
description = "The IP address the process listens on. Only accepted for `nginx`, `apache`, and `kafka`."
required = false
type = "string"

[[body_param]]
name = "endpoint"
description = "The full scrape URL (e.g. `http://10.0.0.5:9090/metrics`). Required for `prometheus` targets."
required = false
type = "string"

[[body_param]]
name = "username"
description = "The username for authentication. Only accepted for database kinds and `elasticsearch`."
required = false
type = "string"

[[body_param]]
name = "password"
description = "The password for authentication. Only accepted for database kinds and `elasticsearch`. Write-only — never returned in responses."
required = false
type = "string"

[[body_param]]
name = "api_key"
description = "An API key for authentication. Only accepted for `elasticsearch`. Write-only — never returned in responses."
required = false
type = "string"

[[body_param]]
name = "ssl_mode"
description = "The SSL mode for the connection. Required for `postgres`. Valid options are `disable`, `require`, and `verify-ca`."
required = false
type = "string"

[[body_param]]
name = "tls"
description = "The TLS mode for the connection. Required for `mysql`. Valid options are `false`, `true`, `skip-verify`, and `preferred`."
required = false
type = "string"

[[body_param]]
name = "scheme"
description = "The connection scheme. Only accepted for `elasticsearch`. Valid options are `http` and `https`. Defaults to `http` if omitted."
required = false
type = "string"

[[body_param]]
name = "enabled"
description = "Set to `false` to create the target in a disabled state. Defaults to `true`."
required = false
type = "boolean"

[[header]]
name = "Authorization"
description = "Bearer `$TOKEN`"
required = true
type = "string"
[/endpoint]

### Fields accepted per kind

| Kind | Required fields | Optional fields |
|---|---|---|
| `postgres` | `host`, `port`, `ssl_mode` | `username`, `password` |
| `mysql` | `host`, `port`, `tls` | `username`, `password` |
| `redis` | `host`, `port` | `username`, `password` |
| `mongodb` | `host`, `port` | `username`, `password` |
| `memcached` | `host`, `port` | `username`, `password` |
| `elasticsearch` | `host`, `port` | `username`, `password`, `api_key`, `scheme` |
| `nginx` | `host`, `service` | `port`, `listen_ip` |
| `apache` | `host`, `service` | `port`, `listen_ip` |
| `kafka` | `host`, `service` | `port`, `listen_ip` |
| `prometheus` | `host`, `service`, `endpoint` | — |

[responses]
[[response]]
status = 201
description = "The target was created successfully."
body = '''
{
  "data": {
    "id": "10",
    "type": "collector_target",
    "attributes": {
      "kind": "postgres",
      "host": "db.example.com",
      "port": 5432,
      "service": null,
      "listen_ip": null,
      "endpoint": null,
      "scheme": null,
      "username": "monitor",
      "ssl_mode": "require",
      "tls": null,
      "status": "pending",
      "enabled": true,
      "container": null,
      "detected_host": null,
      "autogenerated": false,
      "paused_until": null,
      "consecutive_failure_count": 0,
      "last_ping_at": null,
      "created_at": "2025-06-15T12:00:00.000Z",
      "updated_at": "2025-06-15T12:00:00.000Z"
    }
  }
}
'''
[[response]]
status = 422
description = "Validation failed due to invalid parameters."
body = '''
{
  "errors": [
    "Ssl mode can't be blank"
  ],
  "invalid_attributes": [
    "ssl_mode"
  ]
}
'''
[/responses]

#### Example: PostgreSQL target

```shell
[label cURL]
curl -X POST "https://telemetry.betterstack.com/api/v1/collectors/1/targets" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "kind": "postgres",
       "host": "db.example.com",
       "port": 5432,
       "username": "monitor",
       "password": "secret",
       "ssl_mode": "require"
     }'
```

#### Example: Elasticsearch target with API key

```shell
[label cURL]
curl -X POST "https://telemetry.betterstack.com/api/v1/collectors/1/targets" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "kind": "elasticsearch",
       "host": "es.example.com",
       "port": 9200,
       "scheme": "https",
       "api_key": "VnVhQ19fb29CT0hraHQyVEhhV0M6..."
     }'
```

#### Example: Nginx process target

```shell
[label cURL]
curl -X POST "https://telemetry.betterstack.com/api/v1/collectors/1/targets" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "kind": "nginx",
       "host": "collector-host-1",
       "service": "edge-nginx",
       "listen_ip": "10.0.0.1",
       "port": 80
     }'
```

#### Example: Prometheus target

```shell
[label cURL]
curl -X POST "https://telemetry.betterstack.com/api/v1/collectors/1/targets" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "kind": "prometheus",
       "host": "collector-host-1",
       "service": "my-app",
       "endpoint": "http://10.0.0.5:9090/metrics"
     }'
```

#### Example: Create disabled

```shell
[label cURL]
curl -X POST "https://telemetry.betterstack.com/api/v1/collectors/1/targets" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "kind": "redis",
       "host": "r.example.com",
       "port": 6379,
       "enabled": false
     }'
```