Warehouses

A Warehouse is a central repository of data collected from one or more Sources. This is what commonly comes to mind when you think about a relational database: structured data that fits into rows and columns.

Using the Segment Public API, you can create, delete, update, list, validate and connect Warehouses.

Add Connection from Source to Warehouse

Connects a Source to a Warehouse.

• When called, this endpoint may generate the Storage Destination Modified event in the audit trail.

Securitytoken
Request
path Parameters
warehouseId
required
string [ 1 .. 255 ]
Example: kjU72LCJexvrqL7G4TMHHN
sourceId
required
string [ 1 .. 255 ]
Example: rh5BDZp6QDHvXFCkibm1pR
Responses
201

Created

404

Resource not found

422

Validation failure

429

Too many requests

post/warehouses/{warehouseId}/connected-sources/{sourceId}
Request samples
import { configureApis, unwrap } from '@segment/public-api-sdk-typescript'

const api = configureApis('/* Insert your Public API token here */')

try {
  const result = await unwrap(api.warehouses.addConnectionFromSourceToWarehouse('kjU72LCJexvrqL7G4TMHHN', 'rh5BDZp6QDHvXFCkibm1pR'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}

Remove Source Connection from Warehouse

Disconnects a Source from a Warehouse.

Securitytoken
Request
path Parameters
warehouseId
required
string [ 1 .. 255 ]
Example: kjU72LCJexvrqL7G4TMHHN
sourceId
required
string [ 1 .. 255 ]
Example: rh5BDZp6QDHvXFCkibm1pR
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

delete/warehouses/{warehouseId}/connected-sources/{sourceId}
Request samples
import { configureApis, unwrap } from '@segment/public-api-sdk-typescript'

const api = configureApis('/* Insert your Public API token here */')

try {
  const result = await unwrap(api.warehouses.removeSourceConnectionFromWarehouse('kjU72LCJexvrqL7G4TMHHN', 'rh5BDZp6QDHvXFCkibm1pR'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}

Create Validation in Warehouse

Validates input settings against a Warehouse.

• When called, this endpoint may generate the Storage Destination Settings Validation event in the audit trail.

Securitytoken
Request
Request Body schema:
required
metadataId
required
string (metadataId)

The id of the Warehouse metadata type.

required
object (settings)

The settings to check.

Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

post/warehouses/validation
Request samples
{
  • "metadataId": "55d3d3aea3c",
  • "settings": {
    }
}
Response samples
{
  • "data": {
    }
}

Create Warehouse

Creates a new Warehouse.

• When called, this endpoint may generate the Storage Destination Created event in the audit trail.

Securitytoken
Request
Request Body schema:
required
metadataId
required
string (metadataId)

The Warehouse metadata to use.

name
string (name)

An optional human-readable name for this Warehouse.

enabled
boolean (enabled)

Enable to allow this Warehouse to receive data. Defaults to true.

required
object (settings)

A key-value object that contains instance-specific settings for a Warehouse.

Different kinds of Warehouses require different settings. The required and optional settings for a Warehouse are described in the options object of the associated Warehouse metadata.

You can find the full list of Warehouse metadata and related settings information in the /catalog/warehouses endpoint.

Responses
201

Created

404

Resource not found

422

Validation failure

429

Too many requests

post/warehouses
Request samples
{
  • "metadataId": "CCIl4HLQPz",
  • "settings": { }
}
Response samples
{}

List Warehouses

Returns a list of Warehouses.

Securitytoken
Request
query Parameters
required
object (PaginationInput)

Defines the pagination parameters.

This parameter exists in v1.

Example: pagination[count]=3
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/warehouses
Request samples
import { configureApis, unwrap } from '@segment/public-api-sdk-typescript'

const api = configureApis('/* Insert your Public API token here */')

try {
  const result = await unwrap(api.warehouses.listWarehouses({ count: 3 }))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}

Delete Warehouse

Deletes an existing Warehouse.

• When called, this endpoint may generate the Storage Destination Deleted event in the audit trail.

Securitytoken
Request
path Parameters
warehouseId
required
string [ 1 .. 255 ]
Example: tmiTtiPi58udvDAjcxKUJY
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

delete/warehouses/{warehouseId}
Request samples
import { configureApis, unwrap } from '@segment/public-api-sdk-typescript'

const api = configureApis('/* Insert your Public API token here */')

try {
  const result = await unwrap(api.warehouses.deleteWarehouse('tmiTtiPi58udvDAjcxKUJY'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}

Get Warehouse

Returns a Warehouse by its id.

Securitytoken
Request
path Parameters
warehouseId
required
string [ 1 .. 255 ]
Example: kjU72LCJexvrqL7G4TMHHN
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/warehouses/{warehouseId}
Request samples
import { configureApis, unwrap } from '@segment/public-api-sdk-typescript'

const api = configureApis('/* Insert your Public API token here */')

try {
  const result = await unwrap(api.warehouses.getWarehouse('kjU72LCJexvrqL7G4TMHHN'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}

Update Warehouse

Updates an existing Warehouse.

• When called, this endpoint may generate one or more of the following audit trail events:* Storage Destination Modified

  • Storage Destination Enabled
Securitytoken
Request
path Parameters
warehouseId
required
string [ 1 .. 255 ]
Example: kjU72LCJexvrqL7G4TMHHN
Request Body schema:
required
name
string or null (name)

An optional human-readable name to associate with this Warehouse.

enabled
boolean (enabled)

Enable to allow this Warehouse to receive data.

required
object (settings)

A key-value object that contains instance-specific settings for a Warehouse.

Different kinds of Warehouses require different settings. The required and optional settings for a Warehouse are described in the options object of the associated Warehouse metadata.

You can find the full list of Warehouse metadata and related settings information in the /catalog/warehouses endpoint.

Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

patch/warehouses/{warehouseId}
Request samples
{
  • "name": "Redshift Dev",
  • "settings": {
    }
}
Response samples
{
  • "data": {
    }
}

Get Connection State from Warehouse

Verifies the state of Warehouse connection settings.

The rate limit for this endpoint is 200 requests per minute, which is lower than the default due to access pattern restrictions. Once reached, this endpoint will respond with the 429 HTTP status code with headers indicating the limit parameters. See Rate Limiting for more information.

Securitytoken
Request
path Parameters
warehouseId
required
string [ 1 .. 255 ]
Example: kjU72LCJexvrqL7G4TMHHN
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/warehouses/{warehouseId}/connection-state
Request samples
import { configureApis, unwrap } from '@segment/public-api-sdk-typescript'

const api = configureApis('/* Insert your Public API token here */')

try {
  const result = await unwrap(api.warehouses.getConnectionStateFromWarehouse('kjU72LCJexvrqL7G4TMHHN'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}

List Connected Sources from Warehouse

Returns the list of Sources that are connected to a Warehouse.

Securitytoken
Request
path Parameters
warehouseId
required
string [ 1 .. 255 ]
Example: kjU72LCJexvrqL7G4TMHHN
query Parameters
required
object (PaginationInput)

Defines the pagination parameters.

This parameter exists in v1.

Example: pagination[count]=1
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/warehouses/{warehouseId}/connected-sources
Request samples
import { configureApis, unwrap } from '@segment/public-api-sdk-typescript'

const api = configureApis('/* Insert your Public API token here */')

try {
  const result = await unwrap(api.warehouses.listConnectedSourcesFromWarehouse('kjU72LCJexvrqL7G4TMHHN', { count: 1 }))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{}