Using curl

While Swagger UI provides a visual interface into the API, it is often desirable to send API calls via the command line. For this, curl can be used.

Required information

To send a curl request to the API, two things are required:

• An API key

• The curl command string

Obtaining an API key

If an API key is not already available from previous API usage, the following steps should be followed.

1. Log into the planet console using a Link11 WAAP account (i.e., without using SSO). The account must have an Access Level of Editor or higher.

2. Navigate to Account by selecting the user icon on the top right of the page

3. Navigate to Account Details -> API Keys. (If Account Details is not displayed in the Account menu, verify that the login was done directly into the planet using an L11WAAP account. If SSO is used, Account Details will not be available in the interface.)

4. Select "New" -> Enter a name for the key -> "Confirm"

5. Copy the value of that key for use within curl. (Note: this is the string that the system generated, not the name you supplied.)

Using Swagger UI to construct the curl command string

Sending an API request via Swagger UI will also construct and display its curl command string:

1. Navigate to the planet's instance of Swagger UI.
2. Expand the desired namespace, and then the desired route within the namespace.

3. Select the "Try it Now" button

4. Edit the input fields (if any), providing all required inputs

5. Select the "Execute" button

6. After sending the request, Swagger UI will display the curl command string. Copy this.

To send this request using curl, edit the command string to include an additional header (Authorization:Basic) for the API key obtained earlier.

Example

When Swagger UI is used to get a list of configurations via GET /api/v4/conf/configs, it will also display this curl command:

curl -X 'GET' \
  'https://www.mysite.com/api/v4/conf/configs' \
  -H 'accept: application/json'

To submit this command directly via curl, the following header must be added:

-H 'Authorization:Basic <api-key-obtained-earlier>'

...without the <>, and where api-key-obtained-earlier is the string obtained above.

Manually constructing the curl command string

API calls using curl are constructed according to these requirements:

• The API key is included, as explained above

• Input parameters defined as query are encoded into the URL

• Input parameters defined as header are included as headers

• Input parameters defined as Request body are included via curl's -d option

Example: query and header parameters

A route to retrieve traffic data has this definition:

Note that limit, offset, filters, and debug are marked as query parameters, and therefore, will be encoded into the URL. However, syntax and provider are marked as header parameters.

The resulting curl command will look like this:

curl -X 'GET' \
  'https://mysite.com/api/v4.0/data/logs?limit=100&offset=0&filters=%7B%22AND%22%3A%5B%7B%22field%22%3A%20%22timestamp%22%2C%20%22value%22%3A%20%5B%222024-06-02T00%3A00%3A00%22%2C%20%222024-06-03T00%3A00%3A00%22%5D%2C%22op%22%3A%20%22between%22%7D%20%5D%7D&debug=false' \
  -H 'accept: application/json' \
  -H 'syntax: json' \
  -H 'provider: bigquery' \
  -H 'Authorization:Basic kFiudeEIOSd18dDineS2wn98sIO'

Example: request body

The POST /api/v4.0/data/timeline/parse call includes this input:

Let's say that an admin wants to submit the string timestamp between 2024-06-06 09:31:00 and 2024-06-06 09:36:00, status=301. The curl command would look like this:

curl -X 'POST' \
  'https://mysite.com/api/v4.0/data/timeline/parse' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization:Basic kFiudeEIOSd18dDineS2wn98sIO' \
  -d '{
  "query": "timestamp between 2024-06-06 09:31:00 and 2024-06-06 09:36:00, status=301"
}'