Sumo Logic Collector Management APIs

The Collector Management API gives you the ability to manage Collectors and Sources from HTTP endpoints. See the topics below for Collector API and Source API methods and examples, as well as upgrading and downgrading Collectors using the API.

note

Collector Management APIs are not yet built with OpenAPI specifications and therefore not documented with the rest of the APIs. Instead, refer to the instructions below for details.

info

You need the Manage or View Collectors role capability to manage or view Collection configurations.

Before You Begin

See the following topics for additional information:

API Authentication for information on API authentication options.
Sumo Logic Endpoints for a list of API endpoints to use to connect your API client to the Sumo Logic API.
Use JSON to Configure Sources for a description of Source parameters.
View or Download Collector or Source JSON Configuration for instructions on viewing or downloading the current JSON configuration file for a collector or source from the web application.
Troubleshooting APIs

There is a community-supported script available on GitHub that allows you to conduct bulk actions to Collectors, see Collector Management Script.

Sumo Logic endpoints like api.sumologic.com are different in deployments outside us1. You need to specify your deployment in the endpoint. For example api.<strong>YOUR_DEPLOYMENT</strong>.sumologic.com you would specify YOUR_DEPLOYMENT as either au, ca, de, eu, fed, in, jp, us1, or us2. For us1, use api.sumologic.com. For the others, use api.us2.sumologic.com, and so on. For more information, see Sumo Logic Endpoints.

Collector API Methods and Examples

The Collector Management API allows you to manage Collectors and Sources from an HTTP endpoint. This topic describes the Collector API parameters, methods, and lists error codes.

Rate limiting

A rate limit of four API requests per second (240 requests per minute) applies to all API calls from a user.
A rate limit of 10 concurrent requests to any API endpoint applies to an access key.

If a rate is exceeded, a rate limit exceeded 429 status code is returned.

Response fields

The following table lists the API response fields for installed and hosted Collectors.

Parameter	Type	Required?	Default	Description	Access
alive	Boolean	Yes		When a Collector is running it sends Sumo a heartbeat message every 15 seconds. If no heartbeat message is received after 30 minutes this becomes `false`.	Transient
category	String	No	Null	The Category of the Collector, used as metadata when searching data.	Modifiable
collectorType	String			The Collector type: `Installable` or `Hosted`	Not modifiable
collectorVersion	String	Yes		Version of the Collector software installed.	Transient
cutoffRelativeTime	String	No		Can be specified instead of `cutoffTimestamp` to provide a relative offset with respect to the current time. Example: use `"-1h"`, `"-1d"`, or `"-1w"` to collect data that's less than one hour, one day, or one week old, respectively.	Not modifiable
cutoffTimestamp	Long	No	0 (collects all data)	Only collect data from files with a modified date more recent than this timestamp, specified as milliseconds since epoch	Modifiable
description	String	No	Null	Description of the Collector.	Modifiable
ephemeral	Boolean	Yes		When true, the collector will be deleted after 12 hours of inactivity. For more information, see Setting a Collector as Ephemeral.	Modifiable
fields	JSON Object	No		JSON map of key-value fields (metadata) to apply to the Collector. To assign an Ingest Budget to the Collector use the field `_budget` with the Field Value of the Ingest Budget to assign. For example, if you have a budget with a Field Value of `Dev_20GB`, you would add: `fields=_budget=Dev_20GB`	Modifiable
hostName	String	No	Null	Host name of the Collector. The hostname can be a maximum of 128 characters.	Modifiable
id	Long	Yes		Identifier	Not modifiable
lastSeenAlive	Long	No		The last time the Sumo Logic service received an active heartbeat from the Collector, specified as milliseconds since epoch.	Transient
name	String	Yes		Name of the Collector. It must be unique on your account.	Modifiable
sourceSyncMode	String	No	UI	For installed Collectors, whether the Collector is using local source configuration management (using a `JSON` file), or cloud management (using the `UI`)	Modifiable To assign to `JSON` see Local Configuration File Management for Existing Collectors and Sources.
timeZone	String	No	Null	Time zone of the Collector. For a list of possible values, refer to the "TZ" column in this Wikipedia article.	Modifiable
targetCpu	Long	No	Null	When CPU utilization exceeds this threshold, the Collector will slow down its rate of ingestion to lower its CPU utilization. Currently only Local and Remote File Sources are supported. The value must be expressed as a whole number percentage. The collector will adjust resources to attempt to limit the CPU usage to at most 20%. For more information, see Set the Collector CPU Usage Target.	Modifiable

The following table lists additional response fields for Installed Collectors only.

Parameter	Type	Required?	Description	Access
osName	String	Yes	Name of OS that Collector is installed on.	Not modifiable
osVersion	String	Yes	Version of the OS that Collector is installed on.	Not modifiable
osArch		Yes	Architecture of the OS that Collector is installed on.	Not modifiable
osTime	Long	Yes	Time that the Collector has been running, in milliseconds.	Not modifiable

GET methods

List Collectors

Get a list of Collectors with an optional limit and offset.

Method: GET Path: /collectors

Parameter	Type	Required?	Default	Description
filter	String	No	All Collectors	Filter the Collectors returned using one of the available filter types:`installed`, `hosted`, `dead`, or `alive`.
limit	Integer	No	1000	Max number of Collectors to return.
offset	Integer	No	0	Offset into the list of Collectors.

Example

In this example, setting limit=10 limits the responses to 10.

Request:

curl -u '<accessId>:<accessKey>' -X GET https://api.sumologic.com/api/v1/collectors?limit=10

Response:

{  
   "collectors":[  
      {  
         "id":2,
         "name":"OtherCollector",
         "collectorType":"Installable",
         "alive":true,
         "links":[  
            {  
               "rel":"sources",
               "href":"/v1/collectors/2/sources"
            }
         ],
         "collectorVersion":"19.33-28",
         "ephemeral":false,
         "description":"Local Windows Collection",
         "osName":"Windows 7",
         "osArch":"amd64",
         "osVersion":"6.1",
         "category":"local"
      },
      ...
   ]
}

List Offline Collectors

Get a list of Installed Collectors last seen alive before a specified number of days with an optional limit and offset.

Method: GET Path: /collectors/offline

Parameter	Type	Required?	Default	Description
aliveBeforeDays	Integer	No	100	Minimum number of days the Collectors have been offline. Must be at least 1 day.
limit	Integer	No	1000	Max number of Collectors to return.
offset	Integer	No	0	Offset into the list of Collectors.

Example

In this example, setting aliveBeforeDays=10 returns a list of Installed Collectors that have been offline for at least 10 days.

Request:

curl -u '<accessId>:<accessKey>' -X GET https://api.sumologic.com/api/v1/collectors/offline?aliveBeforeDays=10

Response:

{
  "collectors":[{
    "id":101622144,
    "name":"My Installed Collector",
    "timeZone":"Etc/UTC",
    "fields":{
      "_budget":"test_budget"
    },
    "links":[{
      "rel":"sources",
      "href":"/v1/collectors/101622144/sources"
    }],
    "ephemeral":false,
    "targetCpu":-1,
    "sourceSyncMode":"UI",
    "collectorType":"Installable",
    "collectorVersion":"19.162-12",
    "osVersion":"10.12.6",
    "osName":"Mac OS X",
    "osArch":"x86_64",
    "lastSeenAlive":1521143016128,
    "alive":false
  }]
}

Get Collector by ID

Get the Collector with the specified Identifier.

Method: GET Path: /collectors/[id]

Parameter	Type	Required?	Default	Description
id	Integer	Yes	NA	Unique identifier of the Collector.

Example

This example gets the Collector with an ID of 25.

Request:

curl -u '<accessId>:<accessKey>' -X GET https://api.sumologic.com/api/v1/collectors/25

Response:

{
  "collector":{
    "id":25,
    "name":"dev-host-1",
    "timeZone":"UTC",
    "ephemeral":false,
    "sourceSyncMode":"Json",
    "collectorType":"Installable",
    "collectorVersion":"19.162-12",
    "osVersion":"3.13.0-92-generic",
    "osName":"Linux",
    "osArch":"amd64",
    "lastSeenAlive":1471553524302,
    "alive":true
  }
}

Get Collector by Name

Method: GET Path: /collectors/name/[name]

Parameter	Type	Required?	Default	Description
name	String	Yes	NA	Name of the Collector.

Rules

Names with special characters are not supported, such as ; / % \ even if they are URL encoded.
Spaces in names are supported when they are URL encoded. A space character URL encoded is %20. For example, a Collector named Staging Area would be encoded as https://api.sumologic.com/api/v1/collectors/name/Staging%20Area.
Names with a period . need to have a trailing forward slash / at the end of the request URL. For example, a Collector named Staging.Area should be provided as https://api.sumologic.com/api/v1/collectors/name/Staging.Area/.

Example

This example gets the Collector with the name test.

Request:

curl -u '<accessId>:<accessKey>' -X GET https://api.sumologic.com/api/v1/collectors/name/test

Response:

{
  "collector":{
    "id":31,
    "name":"test",
    "timeZone":"UTC",
    "ephemeral":false,
    "sourceSyncMode":"Json",
    "collectorType":"Installable",
    "collectorVersion":"19.162-12",
    "osVersion":"3.13.0-92-generic",
    "osName":"Linux",
    "osArch":"amd64",
    "lastSeenAlive":1471553524302,
    "alive":true
  }
}

POST methods

Create Hosted Collector

Use the POST method with a JSON file to create a new Hosted Collector. The required parameters can be referenced in the Response fields table above. Note that "id" field should be omitted when creating a new Hosted Collector.

21 This method can only be used to create Hosted Collectors. You must install a Collector manually to create an Installed Collector.

Method: POST Path: /collectors

Example

This example creates a new Hosted Collector using the parameters in the JSON file.

Request:

curl -u '<accessId>:<accessKey>' -X POST -H "Content-Type: application/json" -T hosted_collector.json https://api.sumologic.com/api/v1/collectors

Request JSON (hosted_collector.json):

{
  "collector":{
    "collectorType":"Hosted",
    "name":"My Hosted Collector",
    "description":"An example Hosted Collector",
    "category":"HTTP Collection",
    "fields": {
        "_budget":"test_budget"
    }
  }
}

Response:

{
  "collector":{
    "id":102087219,
    "name":"My Hosted Collector",
    "description":"An example Hosted Collector",
    "category":"HTTP Collection",
    "timeZone":"UTC",
    "fields":{
      "_budget":"test_budget"
    },
    "links":[{
      "rel":"sources",
      "href":"/v1/collectors/102087219/sources"
    }],
    "collectorType":"Hosted",
    "collectorVersion":"",
    "lastSeenAlive":1536618284387,
    "alive":true
  }

PUT methods

Update a Collector

Use the PUT method with your JSON file to update an existing Collector. Available parameters can be referenced in the Response fields table above. The JSON request file must specify values for all required fields. Not modifiable fields must match their current values in the system. This is in accordance with HTTP 1.1 RFC-2616 Section 9.6.

Updating a Collector 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/[id]

Parameter	Type	Required?	Default	Description
id	Integer	Yes	NA	ID of the Collector.

Example

This example changes the Collector to set the parameter "ephemeral" to true.

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

Initial GET Response:

< HTTP/1.1 200 OK
< ETag: "f58d12c6986f80d6ca25ed8a3943daa9"
...
{
  "collector":{
    "id":15,
    "name":"dev-host-1",
    "timeZone":"UTC",
    "ephemeral":false,
    "sourceSyncMode":"Json",
    "collectorType":"Installable",
    "collectorVersion":"19.162",
    "osVersion":"3.13.0-92-generic",
    "osName":"Linux",
    "osArch":"amd64",
    "lastSeenAlive":1471553974526,
    "alive":true
  }
* Connection #0 to host api.sumologic.com left intact

Next, modify the Collector's JSON attributes as needed (in this example, setting "ephemeral" to "true"), 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: \"f58d12c6986f80d6ca25ed8a3943daa9\"" -T updated_collector.json https://api.sumologic.net/api/v1/collectors/15

Request JSON (updated_collector.json):

{
 "collector":{
    "id":15,
    "name":"dev-host-1",
    "timeZone":"UTC",
    "ephemeral":true,
    "sourceSyncMode":"Json",
    "collectorType":"Installable",
    "collectorVersion":"19.162",
    "osVersion":"3.13.0-92-generic",
    "osName":"Linux",
    "osArch":"amd64",
    "lastSeenAlive":1471553974526,
    "alive":true
  }
}

Response:

{
  "collector":{
    "id":15,
    "name":"dev-host-1",
    "timeZone":"UTC",
    "ephemeral":true,
    "sourceSyncMode":"Json",
    "collectorType":"Installable",
    "collectorVersion":"19.162",
    "osVersion":"3.13.0-92-generic",
    "osName":"Linux",
    "osArch":"amd64",
    "lastSeenAlive":1471554424736,
    "alive":true
  }
}

DELETE methods

Delete Collector by ID

Use the DELETE method to delete an existing Collector.

Method: DELETE Path: /collectors/[id]

Parameter	Type	Required?	Default	Description
id	Integer	Yes	NA	Unique identifier of the Collector.

This example deletes the Collector with ID 15.

Request:

curl -u '<accessId>:<accessKey>' -X DELETE https://api.sumologic.com/api/v1/collectors/15

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

Delete Offline Collectors

Delete Installed Collectors last seen alive before a specified number of days.

Method: DELETE Path: /collectors/offline

Parameter	Type	Required?	Default	Description
aliveBeforeDays	Integer	No	100	The minimum number of days the Collectors have been offline. Must be at least 1 day.

Example

In this example, setting aliveBeforeDays=10 deletes all the Installed Collectors that have been offline for at least 10 days.

Request:

curl -u '<accessId>:<accessKey>' -X DELETE https://api.sumologic.com/api/v1/collectors/offline?aliveBeforeDays=10

Response:

There will be no response body, only a 200 OK response with the message "The delete task has been initiated.". To check the status make GET requests and see if the Collectors have been deleted.

Error Codes and Messages

Code	Message
BadRequestCollectorId	Request body contains an invalid Collector ID.
CannotModifyCollector	User is not authorized to modify the specified Collector.
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.
InvalidCollector	The specified Collector ID is invalid.
InvalidCollectorType	Invalid Collector type for the requested operation.

Source API Methods and Examples

The Collector Management API allows you to manage 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. When using local configuration file management you can no longer manage Sources through the Collector Management API.

You cannot use the Source API to create Microsoft Office 365 sources, Google Audit sources, or any other sources that require OAuth-based authentication with another vendor.

Rate limiting

A rate limit of four API requests per second (240 requests per minute) applies to all API calls from a user.
A rate limit of 10 concurrent requests to any API endpoint applies to an access key.

If a rate is exceeded, a rate limit exceeded 429 status code is returned.

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*",
    "denylist":[],
    "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*",
    "denylist":[],
    "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*",
    "denylist":[],
    "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*",
    "denylist":[],
    "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.

47 POST creates a single Source per request.

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": [
         {
            "filterType": "Exclude",
            "name": "Filter keyword",
            "regexp": "(?s).*EventCode = (?:700|701).*Logfile = \"Directory Service\".*(?s)"
         }
      ],
      "cutoffTimestamp": 0,
      "encoding": "UTF-8",
      "interval": 60000,
      "metrics": [
         "CPU_User",
         "CPU_Sys"
      ],
      "sourceType": "SystemStats",
      "alive": true
   }
}

Note that the filter value shown above is an example for excluding a keyword. Filter values are specified to do batch edits to Processing Rules for Sources. For details on the different types of filters available, see Creating Processing Rules Using a JSON File.

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.

52 You need to include the id parameter in your JSON file.

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": [
         {
            "filterType": "Exclude",
            "name": "Filter keyword",
            "regexp": "(?s).*EventCode = (?:700|701).*Logfile = \"Directory Service\".*(?s)"
         }
      ],
      "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": [
         {
            "filterType": "Exclude",
            "name": "Filter keyword",
            "regexp": "(?s).*EventCode = (?:700|701).*Logfile = \"Directory Service\".*(?s)"
         }
      ],
      "cutoffTimestamp": 0,
      "encoding": "UTF-8",
      "interval": 15000,
      "metrics": [
         "CPU_User",
         "CPU_Sys"
      ],
      "sourceType": "SystemStats",
      "alive": true
   }
}

DELETE methods

Delete Source

Deletes the specified Source from the specified Collector.

Requests to delete Sources from the Cloud-to-Cloud Integration Framework are asynchronous. When you delete the Source it is placed in a Stopping state, when it has successfully stopped it is deleted from your Hosted Collector. Use a GET request to track the Source's state.

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.

Upgrade or Downgrade Collectors Using the API

View and manage the software versions of your Installed Collectors through HTTP endpoints. Use these HTTP endpoints to upgrade or downgrade Collectors. We recommend you follow our best practices when you upgrade your Collectors.

The upgrade may automatically be done in increments. In this case, you may experience longer upgrade times.

There is a community-supported script available on GitHub that allows you to conduct bulk actions to Collectors, see Collector Management Script.

Timeout

If an upgrade task does not complete successfully after 30 minutes it will automatically timeout with a status of failed.

Get upgradable Collectors

Sends a request to get Collectors you can upgrade.

Method: GET

Path: collectors/upgrades/collectors

Request Headers

Key	Value
Content-Type	`application/json`
Accept	`application/json`

Query Parameters

Parameter	Type	Required	Default	Description
toVersion	String	No	Latest Version	Collector build to upgrade (or downgrade) to. If not specified, upgrades to the latest version.
offset	Int	No	0	Offset into the list of Collectors.
limit	Int	No	50	Maximum number of Collectors to return.

Status Code

Code	Text	Description
200	OK	Upgradable Collectors were retrieved and provided in the response payload.
415	Unsupported Media Type	Content-Type wasn't set to `application/json`.
400	Bad Request	A parameter wasn't valid.

Success Result

A JSON document containing the upgradable collectors.

Sample Session

Sample request:

curl -i -u "<accessId>:<accessKey>" -X GET https://api.sumologic.com/api/v1/collectors/upgrades/collectors

Sample response:

{
    "collectors": [
        {
            "id": 100000000,
            "name": "SumoCollector_Local",
            "hostName": "TestHost",
            "timeZone": "UTC",
            "links": [
                {
                    "rel": "sources",
                    "href": "/v1/collectors/100000000/sources"
                }
            ],
            "ephemeral": false,
            "sourceSyncMode": "UI",
            "collectorType": "Installable",
            "collectorVersion": "20.1-2749",
            "osVersion": "10.11.5",
            "osName": "Mac OS X",
            "osArch": "x86_64",
            "lastSeenAlive": 1465848876035,
            "alive": true
        }
    ]
}

Get available builds

Method: GET

Path: /collectors/upgrades/targets

Request Headers

Key	Value
Content-Type	`application/json`
Accept	`application/json`

Query Parameters

None

Status Code

Code	Text	Description
200	OK	The build information has been returned in the response payload.
415	Unsupported Media Type	Content-Type wasn't set to `application/json`.

Success Result

A JSON document containing the versions of collector builds, which includes the following fields

Field	Description
version	(string) Version of the collector build.
latest	(boolean) Whether it's the latest version.

Sample Session

Sample request:

curl -i -u "<accessId>:<accessKey>" -X GET https://api.sumologic.com/api/v1/collectors/upgrades/targets

Sample response:

{
    "targets": [
        {
            "version": "19.115-37",
            "latest": false
        },
        ...
        {
            "version": "20.1-2749",
            "latest": true
        }
    ]
}

Create an upgrade or downgrade task

Method: POST

Path: /collectors/upgrades

Request Headers

Key	Value
Content-Type	`application/json`
Accept	`application/json`

Query Parameters

None

JSON Payload Parameters

Parameter	Type	Required	Default	Description
collectorId	Long	Yes		Identifier of the Collector to upgrade (or downgrade).
toVersion	String	No	Latest version	Collector build to upgrade (or downgrade) to. If not specified, upgrades to the latest version.

Status Code

Code	Text	Description
202	Accepted	The upgrade task has been created successfully.
415	Unsupported Media Type	`Content-Type` wasn't set to `application/json`.
400	Bad Request	Generic request error by the client.

Success Result

With success, a JSON document is returned containing the ID and link of the newly created upgrade task. This is an opaque string to use for following upgrade status checking API.

Error Result

A status code 400 will be returned with following error codes.

Code	Description
collector.invalid	The Collector ID was not provided, doesn't exist, or the user doesn't have permission to use it.
collector.type.invalid	The Collector is not an Installed Collector (it is a Hosted Collector).
collector.not.alive	The Collector is not running.
collector.in.upgrading	The Collector is currently being upgraded.
collector.version.invalid	The upgrade version was not provided, or the version is not valid.

Sample Session

Sample request:

curl -i -u "<accessId>:<accessKey>" -H "Content-Type: application/json" -X POST -d '{"collectorId":100000000,"toVersion":"19.152-1"}'
https://api.sumologic.com/api/v1/collectors/upgrades

Sample response:

{
    "id": "12345",
    "link": {
        "rel": "self",
        "href": "/v1/collectors/upgrades/12345"
    }
}

Get upgrade task status

After obtaining the upgrade job ID, you can obtain the status of the upgrade task from the status endpoint.

Method: GET

Path: /collectors/upgrades/<upgradeTaskID>

Request Headers

Key	Value
Content-Type	`application/json`
Accept	`application/json`

Query Parameters

Parameter	Type	Required	Description
upgradeTaskID	Long	Yes	Task ID from the upgrade task.

Status Code

Code	Text	Description
200	OK	The upgrade task status has been returned in the response.
415	Unsupported Media Type	Content-Type wasn't set to `application/json`.
404	Not found	The upgrade task ID was not found.

Success Result

A success result generates a JSON document containing the upgrade task status, including the following fields.

Field	Description
collectorId	Collector ID of this upgrade task (long).
toVersion	Target version of this upgrade task (string).
requestedTime	UNIX timestamp when the upgrade task is requested (long).
status	Status code for the upgrade task (integer): 0 - not started 1 - pending, the upgrade is issued awaiting a response from the Collector. 2 - succeeded 3 - failed 6 - Progressing, the upgrade is running on the Collector.
message	Any additional message, normally a failed reason (string).

Sample session

Sample request:

curl -i -u "<accessId>:<accessKey>" -X GET https://api.sumologic.com/api/v1/collectors/upgrades/12345

Sample response:

{
    "upgrade": {
        "id": 12345,
        "collectorId": 100000000,
        "toVersion": "19.152-1",
        "requestTime": 1465855411044,
        "status": 2,
        "message": ""
    }
}

Before You Begin​

Collector API Methods and Examples​

Rate limiting​

Response fields​

GET methods​

List Collectors​

Example​

List Offline Collectors​

Example​

Get Collector by ID​

Example​

Get Collector by Name​

Rules​

Example​

POST methods​

Create Hosted Collector​

Example​

PUT methods​

Update a Collector​

Example​

DELETE methods​

Delete Collector by ID​

Delete Offline Collectors​

Example​

Source API Methods and Examples​

Rate limiting​

Response fields​

GET methods​

List Sources​

Examples​

Get Source by ID​

Examples​

POST methods​

Create Source​

Example​

PUT methods​

Update Source​

Example​

DELETE methods​

Delete Source​

Example​

Error Codes and Messages for Source API​

Upgrade or Downgrade Collectors Using the API​

Timeout​

Get upgradable Collectors​

Get available builds​

Create an upgrade or downgrade task​

Get upgrade task status​

Before You Begin

Collector API Methods and Examples

Rate limiting

Response fields

GET methods

List Collectors

Example

List Offline Collectors

Example

Get Collector by ID

Example

Get Collector by Name

Rules

Example

POST methods

Create Hosted Collector

Example

PUT methods

Update a Collector

Example

DELETE methods

Delete Collector by ID

Delete Offline Collectors

Example

Source API Methods and Examples

Rate limiting

Response fields

GET methods

List Sources

Examples

Get Source by ID

Examples

POST methods

Create Source

Example

PUT methods

Update Source

Example

DELETE methods

Delete Source

Example

Error Codes and Messages for Source API

Upgrade or Downgrade Collectors Using the API

Timeout

Get upgradable Collectors

Get available builds

Create an upgrade or downgrade task

Get upgrade task status