# Create a warehouse source

Creates a new Warehouse source.

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

[[body_param]]
name = "name"
description = "The name of the new Warehouse source. Can contain letters, numbers, spaces, and special characters. Source names do not need to be unique."
required = true
type = "string"

[[body_param]]
name = "data_region"
description = """
The data region or cluster name where the source's data will be stored.
Possible values include `us_east`, `germany`, `singapore`, or a specific cluster name like `us-east-9`.
The actual region created may differ slightly due to dynamic load balancing.
"""
required = false
type = "string"

[[body_param]]
name = "events_retention"
description = "The retention period for event data in days. Default is 9999999 days (effectively infinite)."
required = false
type = "integer"

[[body_param]]
name = "time_series_retention"
description = "The retention period for time series data in days. Default is 9999999 days (effectively infinite)."
required = false
type = "integer"

[[body_param]]
name = "live_tail_pattern"
description = "A display template for live tail messages. Default is `\"{status} {message}\"`."
required = false
type = "string"

[[body_param]]
name = "vrl_transformation"
description = "A VRL program for real-time data transformation. Read more about [VRL transformations](https://betterstack.com/docs/logs/using-logtail/transforming-ingested-data/logs-vrl/)."
required = false
type = "string"

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

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

[[header]]
name = "Content-Type"
description = "application/json"
required = true
type = "string"
[/endpoint]

[responses]
[[response]]
status = 201
description = '''The newly created Warehouse source.'''
body = '''{
  "data": {
    "id": "5678",
    "type": "warehouse_source",
    "attributes": {
      "warehouse_source_group_id": null,
      "team_id": 123456,
      "team_name": "example-team",
      "name": "new_user_events",
      "table_name": "new_user_events",
      "token": "abc123def456ghi789jkl012",
      "ingesting_paused": false,
      "ingesting_host": "s5678.us-east-9.betterstackdata.com",
      "created_at": "2025-10-06T09:24:10Z",
      "updated_at": "2025-10-21T16:38:50Z",
      "events_retention": 9999999,
      "time_series_retention": 9999999,
      "live_tail_pattern": "{status} {message}",
      "data_region": "us-east-9",
      "custom_bucket": null,
      "vrl_transformation": ""
    }
  }
}'''

[[response]]
status = 401
description = '''Unauthorized'''
body = '''{
  "errors":"Invalid Team API token. How to find your Team API token: https://betterstack.com/docs/logs/api/getting-started/#obtaining-a-logtail-api-token"
}'''

[[response]]
status = 422
description = '''Unprocessable Entity - Validation Errors'''
body = '''{
  "errors":"Sorry, you are missing some required attributes",
  "required_attributes":["name"]
}'''
[/responses]

#### Example cURL

```shell
[label Example]
curl --request POST \
  --url https://warehouse.betterstack.com/api/v1/sources \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "New User Events",
    "data_region": "us_east",
    "events_retention": 30
  }'
```