# Create a source

Returns a newly created source.

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

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

[[body_param]]
name = "name"
description = "Source name"
required = true
type = "string"

[[body_param]]
name = "ingesting_paused"
description = "Enable or disable ingesting for this source"
required = false
type = "boolean"

[[body_param]]
name = "source_group_id"
description = "The ID of the source group this source belongs to"
required = false
type = "integer"

[[body_param]]
name = "platform"
description = "Source platform. <br>The currently supported platforms are: <br>- `apache2`<br>- `aws`<br>- `aws_cloudwatch`<br>- `aws_ecs`<br>- `aws_elb`<br>- `aws_fargate`<br>- `azure_logs`<br>- `cloudflare_logpush`<br>- `cloudflare_worker`<br>- `datadog_agent`<br>- `digitalocean`<br>- `docker`<br>- `dokku`<br>- `dotnet`<br>- `elasticsearch`<br>- `erlang`<br>- `filebeat`<br>- `flights`<br>- `fluentbit`<br>- `fluentd`<br>- `fly_io`<br>- `go`<br>- `google_cloud_pubsub`<br>- `haproxy`<br>- `heroku`<br>- `http`<br>- `java`<br>- `javascript`<br>- `kubernetes`<br>- `logstash`<br>- `minio`<br>- `mongodb`<br>- `mysql`<br>- `nginx`<br>- `open_telemetry`<br>- `php`<br>- `postgresql`<br>- `prometheus`<br>- `prometheus_scrape`<br>- `python`<br>- `rabbitmq`<br>- `redis`<br>- `render`<br>- `rsyslog`<br>- `ruby`<br>- `syslog-ng`<br>- `traefik`<br>- `ubuntu`<br>- `vector`<br>- `vercel_integration`<br>- `winlogbeat`"
required = true
type = "string"

[[body_param]]
name = "data_region"
description = """
Data region or private cluster name to create the source in.  \nPermitted values for most plans are: `us_east`, `germany`, `singapore`.
"""
required = false
type = "string"

[[body_param]]
name = "live_tail_pattern"
description = """
Live tail message format 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 = "logs_retention"
description = "Data retention for logs in days. There might be additional charges for longer retention."
required = false
type = "integer"

[[body_param]]
name = "metrics_retention"
description = "Data retention for metrics in days. There might be additional charges for longer retention."
required = false
type = "integer"

[[body_param]]
name = "vrl_transformation"
description = "The VRL code that's used to transform events. Read more about [VRL transformations](https://betterstack.com/docs/logs/using-logtail/transforming-ingested-data/logs-vrl/)."
required = false
type = "string"

[[body_param]]
name = "scrape_urls"
description = "URLs to scrape by `prometheus_scrape` platform and similar."
required = false
type = "array"

[[body_param]]
name = "scrape_frequency_secs"
description = "How often to scrape the URLs for `prometheus_scrape` platform and similar. Permitted values are 15, 30, 60, 120 or 300."
required = false
type = "integer"

[[body_param]]
name = "scrape_request_headers"
description = "An array of request headers for `prometheus_scrape` platform and similar, with each object containing `name` and `value` fields."
required = false
type = "array"

[[body_param]]
name = "scrape_request_basic_auth_user"
description = "Basic auth username for `prometheus_scrape` platform and similar."
required = false
type = "string"

[[body_param]]
name = "scrape_request_basic_auth_password"
description = "Basic auth password for `prometheus_scrape` platform and similar."
required = false
type = "string"

[[body_param]]
name = "skip_ssl_verify"
description = "Whether to skip SSL/TLS certificate verification for `prometheus_scrape` platform and similar. Set to `true` to disable verification."
required = false
type = "boolean"

[[body_param]]
name = "custom_bucket.name"
description = """
Configure a custom S3-compatible bucket to host data from this source. This should be the name of the bucket. 

E.g. `storage-bucket`.
"""
required = false
type = "string"

[[body_param]]
name = "custom_bucket.endpoint"
description = """
The full URL endpoint of the S3-compatible bucket. 

E.g. `https://s3.us-east-1.amazonaws.com/storage-bucket`.
"""
required = false
type = "string"

[[body_param]]
name = "custom_bucket.access_key_id"
description = """
The Access Key ID of the key-pair that has permissions to access this bucket.
"""
required = false
type = "string"

[[body_param]]
name = "custom_bucket.secret_access_key"
description = """
The Secret Access Key of the key-pair that has permissions to access this bucket.
"""
required = false
type = "string"

[[body_param]]
name = "custom_bucket.keep_data_after_retention"
description = """
Whether we should keep data in the bucket after the retention period.
"""
required = false
type = "boolean"


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

[responses]
[[response]]
status = 200
description = '''The source was created'''
body = '''{
    "id": "95",
    "type": "source",
    "attributes": {
        "team_id": 123,
        "team_name": "Test team",
        "name": "Nginx",
        "source_group_id": 572,
        "table_name": "nginx",
        "platform": "nginx",
        "token": "FczKcxEhjEDE58dBX7XaeX1q",
        "ingesting_host": "s95.eu-nbg-2.betterstackdata.com",
        "ingesting_paused": false,
        "logs_retention": 7,
        "metrics_retention": 14,
        "live_tail_pattern": "{level} {host} {nginx.status} {nginx.method} {nginx.host} {nginx.path} {nginx.client} {nginx.agent} {message}",
        "vrl_transformation": ".message = upcase!(.message)\n.",
        "custom_bucket": {
          "name": "storage-bucket",
          "endpoint": "https://s3.us-east-1.amazonaws.com/storage-bucket",
          "access_key_id": "AKIAIOSFODNN7EXAMPLE",
          "keep_data_after_retention": false
        },
        "created_at": "2021-05-27T12:30:41.695Z",
        "updated_at": "2021-06-11T14:00:50.756Z"
    }
}'''

[[response]]
status = 422
description = '''Validation failed'''
body = '''{
    "errors": "Your plan doesn't support custom retention",
    "invalid_attributes": ["logs_retention", "metrics_retention"]
}'''
[/responses]

#### Example cURL 

```shell
[label Example]
curl --request POST \
  --url https://telemetry.betterstack.com/api/v1/sources \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "My new HTTP source",
    "platform": "http",
    "data_region": "us_east"
  }'
```