Explore documentation
  1. Welcome to Warehouse 👋
  2. Ingesting data
    1. Ingesting events
    2. S3 vs NVMe hosted data
    3. Host events in your S3 bucket
  3. Querying data
    1. Querying events & time series
    2. Writing ClickHouse SQL queries
    3. Query speeds
    4. Ad-hoc SQL API
    5. Generate client-facing APIs
    6. Visualizing data
  4. Vector embeddings
    1. Introduction to embeddings
    2. Using built-in embeddings
    3. Bringing your own embeddings
    4. Data structures and indices
  5. Use cases
    1. Retrieval Augmented Generation
  6. Management
    1. Controlling costs
  7. Warehouse API
    1. Getting an API token
    2. Warehouse sources API
      1. List all sources GET
      2. Get a single source GET
      3. Create a source POST
      4. Update a source PUT
      5. Remove a source DELETE
    3. Warehouse source groups API
    4. Time series API
    5. Embeddings API

Create a warehouse source

Creates a new Warehouse source.

POST https://warehouse.betterstack.com/api/v1/sources

Headers

Authorization
required string

Bearer $TOKEN

Content-Type
required string

application/json

Body parameters

name
required string

The name of the new Warehouse source. Can contain letters, numbers, spaces, and special characters. Source names do not need to be unique.

data_region
string

The data region or cluster name where the source's data will be stored. Possible values include us_east, us_west, germany, singapore, or a specific cluster name like us-east-9. The actual region created may differ slightly due to dynamic load balancing.

events_retention
integer

The retention period for event data in days. Default is 9999999 days (effectively infinite).

time_series_retention
integer

The retention period for time series data in days. Default is 9999999 days (effectively infinite).

live_tail_pattern
string

A display template for live tail messages. Default is "{status} {message}".

vrl_transformation
string

A VRL program for real-time data transformation. Read more about VRL transformations.

source_group_id
string

The ID of the source group this source belongs to.

201

The newly created Warehouse source.

Response 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": ""
    }
  }
}
401

Unauthorized

Response 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"
}
422

Unprocessable Entity - Validation Errors

Response body

{
  "errors": "Sorry, you are missing some required attributes",
  "required_attributes": [
    "name"
  ]
}

Example cURL

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
  }'

Previous article

Get a single warehouse source

Next article

Update a warehouse source