Skip to main content
Sumo Logic

Source API Methods and Examples

The Collector Management API allows you to create, update, and delete Collectors and Sources from an HTTP endpoint. This topic describes the Source API methods, which you can use to create installed or hosted Sources of any type by specifying the sourceType parameter.

See the following topics for additional information:

Response fields

See Use JSON to Configure Sources for a description of Source parameters.

GET methods

List Sources

Gets information about all Sources for a specified Collector.

Method: GET Path: /collectors/[collectorId]/sources

Parameter Type Required? Default Description

collectorId

integer

Yes

NA

Unique Collector identifier.

download boolean No false When set to true, the response will be a JSON array of Sources that can be used to register a new Collector.
Examples

This example gets all Sources for a Collector.

Request:

curl -u 'accessid:accesskey' -X GET https://api.sumologic.com/api/v1/collectors/25/sources

Response:

{
  "sources":[{
    "id":101792472,
    "name":"collector_logs",
    "category":"collector_logs",
    "hostName":"dev-host-1",
    "automaticDateParsing":true,
    "multilineProcessingEnabled":true,
    "useAutolineMatching":true,
    "forceTimeZone":false,
    "filters":[],
    "cutoffTimestamp":0,
    "encoding":"UTF-8",
    "pathExpression":"/usr/logs/collector/collector.log*",
    "blacklist":[],
    "sourceType":"LocalFile",
    "alive":true
  },
  ...
  ]
}

This example gets a ready-to-go JSON configuration of the Sources of a Collector, which can be used to register a new Collector.

Request:

curl -u 'accessid:accesskey' -X GET https://api.sumologic.com/api/v1/collectors/25/sources?download=true

Response:

{
  "api.version": "v1",
  "sources":[{
    "name":"collector_logs",
    "category":"collector_logs",
    "hostName":"dev-host-1",
    "automaticDateParsing":true,
    "multilineProcessingEnabled":true,
    "useAutolineMatching":true,
    "forceTimeZone":false,
    "filters":[],
    "cutoffTimestamp":0,
    "encoding":"UTF-8",
    "pathExpression":"/usr/logs/collector/collector.log*",
    "blacklist":[],
    "sourceType":"LocalFile"
  },
  ...
  ]
}

Get Source by ID

Gets information about a specified Collector and Source.

Method: GET Path: /collectors/[collectorId]/sources/[sourceId]

Parameter Type Required? Default Description

collectorId

integer

Yes

NA

Unique Collector identifier.

sourceId integer Yes NA Unique Source identifier.
download boolean No false When set to true, the response will be a JSON Source object that can be used to create a new Source.
Examples

This example gets data for a Source with a specified ID.

Request:

curl -u 'accessid:accesskey' -X GET https://api.sumologic.com/api/v1/collectors/25/sources/101792472

Response:

{
  "source":{
    "id":101792472,
    "name":"collector_gc",
    "category":"collector_gc",
    "hostName":"nite-receiver-1",
    "automaticDateParsing":true,
    "multilineProcessingEnabled":true,
    "useAutolineMatching":true,
    "forceTimeZone":false,
    "filters":[],
    "cutoffTimestamp":0,
    "encoding":"UTF-8",
    "pathExpression":"/usr/sumo/logs/collector/collector.gc.log*",
    "blacklist":[],
    "sourceType":"LocalFile",
    "alive":true
  }
}

This example gets a ready-to-go JSON configuration of a Source with a specified ID, which can be used when managing a folder of multiple sources, or uploading a new source via the API.

Request:

curl -u 'accessid:accesskey' -X GET https://api.sumologic.com/api/v1/collectors/25/sources/101792472?download=true

Response:

{
  "api.version": "v1",
  "source":{
    "name":"collector_gc",
    "category":"collector_gc",
    "hostName":"nite-receiver-1",
    "automaticDateParsing":true,
    "multilineProcessingEnabled":true,
    "useAutolineMatching":true,
    "forceTimeZone":false,
    "filters":[],
    "cutoffTimestamp":0,
    "encoding":"UTF-8",
    "pathExpression":"/usr/sumo/logs/collector/collector.gc.log*",
    "blacklist":[],
    "sourceType":"LocalFile"
  }
}

POST methods

Create Source

Creates a new Source for a Collector. See Use JSON to Configure Sources for required fields for the request JSON file.

Method: POST Path: /collectors/[collectorId]/sources

Parameter Type Required? Default Description

collectorId

integer

Yes

NA

Unique Collector identifier.

Example

This example creates a new Host Metrics Source on Collector with ID 10 using the parameters in the JSON file.

Request:

curl -u 'accessid:accesskey' -X POST -H "Content-Type: application/json" -T host_metrics.json https://api.sumologic.com/api/v1/collectors/10/sources

Request JSON (host_metrics.json):

{
  "source":{
    "sourceType":"SystemStats",
    "name":"Host_Metrics",
    "interval":60000,
    "hostName":"my_host",
    "metrics":[
      "CPU_User",
      "CPU_Sys"
    ]
  }
}

Response:

{
  "source":{
    "id":101833059,
    "name":"Host_Metrics",
    "hostName":"my_host",
    "automaticDateParsing":true,
    "multilineProcessingEnabled":true,
    "useAutolineMatching":true,
    "contentType":"HostMetrics",
    "forceTimeZone":false,
    "filters":[],
    "cutoffTimestamp":0,
    "encoding":"UTF-8",
    "interval":60000,
    "metrics":["CPU_User","CPU_Sys"],
    "sourceType":"SystemStats",
    "alive":true
  }
}

PUT methods

Update Source

Updates an existing source. All modifiable fields must be provided, and all not modifiable fields must match those existing in the system.

Updating a Source also requires the "If-Match" header to be specified with the "ETag" provided in the headers of a previous GET request.

Method: PUT Path: /collectors/[collectorId]/sources/[sourceId]

Parameter Type Required? Default Description

collectorId

integer

Yes

NA

Unique Collector identifier.

sourceId integer Yes NA Unique Source identifier.
Example

This example updates the Host Metrics Source created in the previous example with "interval" = 15000.

First, use a GET request with -v flag to obtain the "ETag" header value.

Initial GET Request:

curl -v -u 'accessid:accesskey' -X GET https://api.sumologic.com/api/v1/collectors/15/sources/101833059

Initial GET Response:

< HTTP/1.1 200 OK
< ETag: "5f6bbe49f8b5a19dd43c806411225a5f"
...
{
  "source":{
    "id":101833059,
    "name":"Host_Metrics",
    "hostName":"my_host",
    ...

Next, modify the Source's JSON attributes as needed (in this example, setting "interval" to "15000"), and use a PUT request, passing the "ETag" value obtained above with the "If-Match" header.

Request:

curl -u 'accessid:accesskey' -X PUT -H "Content-Type: application/json" -H "If-Match: \"5f6bbe49f8b5a19dd43c806411225a5f\"" -T updated_host_metrics.json https://api.sumologic.com/api/v1/collectors/15/sources/101833059

Request JSON (updated_host_metrics.json)

{
   "source":{
      "id":101833059,
      "name":"Host_Metrics",
      "hostName":"my_host",
      "automaticDateParsing":true,
      "multilineProcessingEnabled":true,
      "useAutolineMatching":true,
      "contentType":"HostMetrics",
      "forceTimeZone":false,
      "filters":[],
      "cutoffTimestamp":0,
      "encoding":"UTF-8",
      "interval":15000,
      "metrics":["CPU_User","CPU_Sys"],
      "sourceType":"SystemStats",
      "alive":true
   }
}

Response:

{
  "source":{
    "id":101833059,
    "name":"Host_Metrics",
    "hostName":"my_host",
    "automaticDateParsing":true,
    "multilineProcessingEnabled":true,
    "useAutolineMatching":true,
    "contentType":"HostMetrics",
    "forceTimeZone":false,
    "filters":[],
    "cutoffTimestamp":0,
    "encoding":"UTF-8",
    "interval":15000,
    "metrics":["CPU_User","CPU_Sys"],
    "sourceType":"SystemStats",
    "alive":true
  }
}

DELETE methods

Deletes the specified Source from the specified Collector.

Method: DELETE Path: /collectors/[collectorId]/sources/[sourceId]

Parameter Type Required? Default Description

collectorId

integer

Yes

NA

Unique Collector identifier.

sourceId integer Yes NA Unique Source identifier.
Example

This example deletes a Source.

curl -u 'accessid:accesskey' -X DELETE https://api.sumologic.com/api/v1/collectors/15/sources/101833059

Response: There will be no response body, only a 200 OK response code.

Error Codes and Messages for Source API

Code Message
BadRequestBladeId Request body contains an invalid Source ID.
CannotModifySources Collector is in JSON mode, user cannot create, delete, or update sources using the API.
CollectorDescriptionTooLong Maximum description length is 1024 characters.
CollectorNameTooLong Maximum name length is 128 characters.
createValidationError The specified ID is invalid.
DuplicateResourceName A resource with the same name already exists.
EmptySourceType Need to specify a source type.
InvalidSourceType Invalid Source type for the requested operation.