# Create a collector

Creates a new Better Stack collector.

[info]
The `platform`, `data_region`, and `custom_bucket` attributes can only be set during creation and cannot be updated later.
[/info]

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

[[body_param]]
name = "name"
description = "A unique name for the collector."
required = true
type = "string"

[[body_param]]
name = "platform"
description = "The platform where the collector will be installed. Valid options are `docker`, `swarm`, and `kubernetes`."
required = true
type = "string"

[[body_param]]
name = "note"
description = "An optional note for the collector."
required = false
type = "string"

[[body_param]]
name = "team_name"
description = "Required if using a [global API token](https://betterstack.com/docs/logs/api/getting-started/#get-a-global-api-token) to specify the team that will own the collector."
required = false
type = "string"

[[body_param]]
name = "data_region"
description = "The data region where the collector's data will be stored. If omitted, the organization's default region is used."
required = false
type = "string"

[[body_param]]
name = "logs_retention"
description = "Custom retention period for logs, in days. This is only available on select plans."
required = false
type = "integer"

[[body_param]]
name = "metrics_retention"
description = "Custom retention period for metrics, in days. This is only available on select plans."
required = false
type = "integer"

[[body_param]]
name = "ingesting_paused"
description = "Set to `true` to create the collector in a paused state, preventing it from ingesting data."
required = false
type = "boolean"

[[body_param]]
name = "source_group_id"
description = "The ID of the resource group to assign the collector's associated sources to."
required = false
type = "integer"

[[body_param]]
name = "live_tail_pattern"
description = """
A custom format for messages displayed in live tail, with columns wrapped in `{column}` brackets.  \nExample: `"PID: {message_json.pid} {level} {message}"`.  \nFor details, see [Live tail docs](https://betterstack.com/docs/logs/using-logtail/formatting-logs/#live-tail-message-format).
"""
required = false
type = "string"

[[body_param]]
name = "source_vrl_transformation"
description = "A [VRL program](https://betterstack.com/docs/logs/using-logtail/transforming-ingested-data/logs-vrl/) to be applied to logs server-side during ingestion."
required = false
type = "string"

[[body_param]]
name = "custom_bucket"
description = "Configuration for storing data in your own S3-compatible bucket. This is only available on select plans."
required = false
type = "object"

[[body_param]]
name = "user_vector_config"
description = "A custom Vector configuration in YAML format to be merged with the collector's generated configuration."
required = false
type = "string"

[[body_param]]
name = "configuration"
description = "An object containing detailed configuration options for the collector."
required = false
type = "object"

[[body_param]]
name = "databases"
description = "An array of database connection objects to be monitored by the collector."
required = false
type = "array"

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

### Configuration Object

The `configuration` object allows for fine-grained control over the collector's behavior.

| Key | Type | Description |
|---|---|---|
| `components` | object | A flat object of boolean flags to enable or disable specific data collection components. See the [Components Object](#components-object) section below for a full list. |
| `logs_sample_rate` | integer | The percentage (0-100) of logs to sample. |
| `traces_sample_rate` | integer | The percentage (0-100) of traces to sample. |
| `vrl_transformation` | string | A [VRL program](https://betterstack.com/docs/logs/using-logtail/transforming-ingested-data/logs-vrl/) to transform telemetry data on the host before sending. |
| `disk_batch_size_mb` | integer | The maximum size (in MB) of on-disk batches. Minimum is 256. |
| `memory_batch_size_mb`| integer | The maximum size (in MB) of in-memory batches. |
| `when_full` | string | The buffer overflow strategy. Valid options are `drop_newest` (default) and `block`. |
| `services_options` | object | Per-service overrides for log sampling and trace ingestion. |
| `namespaces_options` | object | Per-namespace overrides for log sampling and trace ingestion (Kubernetes only).|

### Components Object

The `components` object is a flat map of boolean flags to enable or disable specific data collection features.

| Key | Type | Description |
|---|---|---|
| `ebpf_metrics` | Boolean | Enable eBPF-based metrics collection. |
| `ebpf_red_metrics` | Boolean | Enable service map and RED (Requests, Error rate, Duration) metrics via eBPF. |
| `ebpf_tracing_basic` | Boolean | Enable basic eBPF tracing. |
| `ebpf_tracing_full` | Boolean | Enable full eBPF tracing. |
| `logs_collector_internals` | Boolean | Collect internal collector logs. |
| `logs_docker` | Boolean | Collect Docker container logs. |
| `logs_host` | Boolean | Collect host-level logs. |
| `logs_kubernetes` | Boolean | Collect Kubernetes logs. |
| `metrics_apache` | Boolean | Collect Apache metrics. |
| `metrics_databases` | Boolean | Collect database metrics via the cluster agent. |
| `metrics_nginx` | Boolean | Collect Nginx metrics. |
| `traces_opentelemetry` | Boolean | Accept OpenTelemetry SDK traces on ports 4317 (gRPC) and 4318 (HTTP). |

[responses]
[[response]]
status = 201
description = "The collector was created successfully."
body = '''
{
  "data": {
    "id": "2",
    "type": "collector",
    "attributes": {
      "name": "New API Collector",
      "platform": "kubernetes",
      "note": "Created via API for testing.",
      "status": "offline",
      "secret": "new-collector-secret-goes-here",
      "team_id": 123,
      "team_name": "My Team",
      "data_region": "a3",
      "logs_retention": 30,
      "metrics_retention": 90,
      "configuration": {
        "components": {
          "ebpf_metrics": true,
          "ebpf_red_metrics": true,
          "ebpf_tracing_full": true,
          "logs_kubernetes": true,
          "metrics_databases": true,
          "traces_opentelemetry": true
        },
        "logs_sample_rate": 100,
        "traces_sample_rate": 100,
        "vrl_transformation": null,
        "disk_batch_size_mb": 256,
        "memory_batch_size_mb": 10,
        "when_full": "drop_newest"
      },
      "user_vector_config": null,
      "ingesting_paused": false,
      "source_vrl_transformation": null,
      "source_id": 12345,
      "source_group_id": null,
      "live_tail_pattern": null,
      "pinged_at": null,
      "created_at": "2023-10-28T12:00:00.000Z",
      "updated_at": "2023-10-28T12:00:00.000Z",
      "custom_bucket": null
    }
  }
}
'''
[[response]]
status = 422
description = "Validation failed due to invalid parameters."
body = '''
{
  "errors": [
    "name has already been taken"
  ],
  "invalid_attributes": [
    "name"
  ]
}
'''
[/responses]

#### Example: Basic Collector

```shell
[label cURL]
curl -X POST "https://telemetry.betterstack.com/api/v1/collectors" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "My Docker Collector",
       "platform": "docker",
       "note": "For staging environment services."
     }'
```

#### Example: Collector with Configuration

```shell
[label cURL]
curl -X POST "https://telemetry.betterstack.com/api/v1/collectors" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Configured K8s Collector",
       "platform": "kubernetes",
       "configuration": {
         "components": {
           "ebpf_metrics": true,
           "ebpf_red_metrics": true,
           "ebpf_tracing_full": true,
           "logs_kubernetes": true,
           "metrics_databases": false
         },
         "vrl_transformation": ".message = downcase!(.message)",
         "when_full": "block"
       }
     }'
```