Twilio Segment logo

Sources

In Segment, you create a Source (or more than one!) for each website or app you want to track. While it’s not required that you have a single Source for each server, site or app, Segment recommends that you create a Source for each unique source of data.

Migrate from the Config API

Like the Segment Public API, the Config API has one endpoint to retrieve details about a Workspace. The getSource endpoint returns the following fields:

Config API Public API
name See note on names vs IDs in the migration guide
name slug (workspace/ prefix removed)
display_name name
create_time None

To migrate, replace any use of the Config API endpoints with the Segment Public API counterparts, using the field mappings in the table above.

Add Labels to Source

Adds an existing label to a Source.

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

Securitytoken
Request
path Parameters
sourceId
required
string [ 1 .. 255 ]
Example: rh5BDZp6QDHvXFCkibm1pR
Request Body schema:
required
required
Array of objects (labels)

The labels to associate with a Source.

Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

post/sources/{sourceId}/labels
Request samples
{
  • "labels": [
    ]
}
Response samples
{
  • "data": {
    }
}

Replace Labels in Source

Replaces all labels in a Source.

Securitytoken
Request
path Parameters
sourceId
required
string [ 1 .. 255 ]
Example: rh5BDZp6QDHvXFCkibm1pR
Request Body schema:
required
required
Array of objects (labels)

The list of labels to replace in the Source.

Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

put/sources/{sourceId}/labels
Request samples
{
  • "labels": [
    ]
}
Response samples
{
  • "data": {
    }
}

Create Source

Creates a new Source.

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

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

The slug by which to identify the Source in the Segment app.

enabled
required
boolean (enabled)

Enable to allow this Source to send data. Defaults to true.

metadataId
required
string (metadataId)

The id of the Source metadata from which this instance of the Source derives.

All Source metadata is available under /catalog/sources.

object (settings)

A key-value object that contains instance-specific settings for the Source.

Responses
201

Created

404

Resource not found

422

Validation failure

429

Too many requests

post/sources
Request samples
{
  • "slug": "my-test-source-s3_e9_",
  • "enabled": true,
  • "metadataId": "IqDTy1TpoU",
  • "settings": { }
}
Response samples
{
  • "data": {
    }
}

List Sources

Returns a list of Sources.

Securitytoken
Request
query Parameters
required
object (PaginationInput)

Defines the pagination parameters.

This parameter exists in alpha.

Example: pagination=pagination.count=2
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/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.sources.listSources('pagination.count=2'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{}

Create Write Key for Source

Creates a new Write Key for the Source.

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

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

OK

404

Resource not found

422

Validation failure

429

Too many requests

post/sources/{sourceId}/writekey
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.sources.createWriteKeyForSource('idR4zzU9iGcGJgoAX891nf'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
application/vnd.segment.v1alpha+json
{
  • "data": {
    }
}

Delete Source

Deletes an existing Source.

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

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

OK

404

Resource not found

422

Validation failure

429

Too many requests

delete/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.sources.deleteSource('rYxTjyaPtAELCjnFE5EYfM'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}

Get Source

Returns a Source by its id.

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

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/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.sources.getSource('qQEHquLrjRDN9j1ByrChyn'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{}

Update Source

Updates an existing Source.

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

  • Source Enabled
  • Source Settings Modified
  • Source Disabled

Config API omitted fields:

  • updateMask
Securitytoken
Request
path Parameters
sourceId
required
string [ 1 .. 255 ]
Example: 87jXXk8QSLFPfMDGa6mtS3
Request Body schema:
required
name
string (name)

An optional human-readable name to associate with the Source.

Config API note: equal to displayName.

enabled
boolean (enabled)

Enable to allow the Source to send data.

slug
string (slug)

The slug that identifies the Source.

Config API note: equal to name.

object (settings)

A key-value object that contains instance-specific settings for the Source.

Different kinds of Sources require different kinds of input. The settings input for a Source comes from the options object associated with this instance of a Source.

You can find the full list of required settings by accessing the Sources catalog endpoint under /catalog/sources.

Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

patch/sources/{sourceId}
Request samples
{
  • "name": "My updated source",
  • "enabled": false
}
Response samples
{
  • "data": {
    }
}

List Connected Destinations from Source

Returns a list of Destinations connected to a Source.

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

Required pagination params for the request.

This parameter exists in alpha.

Example: pagination=pagination.count=1
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/sources/{sourceId}/connected-destinations
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.sources.listConnectedDestinationsFromSource('qQEHquLrjRDN9j1ByrChyn', 'pagination.count=1'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}

List Connected Warehouses from Source

Returns a list of Warehouses connected to a Source.

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

Required pagination params for the request.

This parameter exists in alpha.

Example: pagination=pagination.count=2
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/sources/{sourceId}/connected-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.sources.listConnectedWarehousesFromSource('qQEHquLrjRDN9j1ByrChyn', 'pagination.count=2'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}

List Schema Settings in Source

Retrieves the schema configuration settings for a Source. If Protocols is not enabled for the Source, the configurations specific to Protocols will have default values.

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

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/sources/{sourceId}/settings
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.sources.listSchemaSettingsInSource('qQEHquLrjRDN9j1ByrChyn'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}

Update Schema Settings in Source

Updates the schema configuration for a Source. If Protocols is not enabled for the Source, any updates to Protocols-specific configurations will not be applied.

  Config API omitted fields:
  • updateMask
Securitytoken
Request
path Parameters
sourceId
required
string [ 1 .. 255 ]
Example: qQEHquLrjRDN9j1ByrChyn
Request Body schema:
required
object (track)

Track settings.

object (identify)

Identify settings.

object (group)

Group settings.

forwardingViolationsTo
string (forwardingViolationsTo)

Source id to forward violations to.

forwardingBlockedEventsTo
string (forwardingBlockedEventsTo)

Source id to forward blocked events to.

Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

patch/sources/{sourceId}/settings
Request samples
{
  • "group": {
    },
  • "identify": {
    },
  • "track": {
    },
  • "forwardingViolationsTo": "rh5BDZp6QDHvXFCkibm1pR",
  • "forwardingBlockedEventsTo": "rh5BDZp6QDHvXFCkibm1pR"
}
Response samples
{
  • "data": {
    }
}

Remove Write Key from Source

Removes a Write Key from a Source.

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

Securitytoken
Request
path Parameters
sourceId
required
string [ 1 .. 255 ]
Example: idR4zzU9iGcGJgoAX891nf
writeKey
required
string [ 1 .. 255 ]
Example: wk123
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

delete/sources/{sourceId}/writekey/{writeKey}
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.sources.removeWriteKeyFromSource('idR4zzU9iGcGJgoAX891nf', 'wk123'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
application/vnd.segment.v1alpha+json
{
  • "data": {
    }
}
➔ Next to Deletion and Suppression