Using cURL with the PacketFabric API

If you prefer to use a GUI interface, see Using Postman with the PacketFabric API.

cURL is installed by default on most Unix distributions and is also available on Windows 10 version 1803 and later. If you are working with an earlier version of Windows, you will need to install it from here: https://curl.se/download.html.

Authenticating

Most PacketFabric API calls require authentication. Therefore, most of your calls must include a bearer token in the following format:

-H "accept: */*" -H "Authorization: Bearer <token string>".

For example:

curl -X GET https://api.packetfabric.com/v2/activity-logs  -H "accept: */*" -H "Authorization: Bearer abcd-1234-56789-defg-1234"

So the first thing you need to do is obtain a bearer token.

Bearer token via API key

You can use the PacketFabric portal to generate an API key. For more information, see API Keys.

Bearer token via API session token

Alternatively, you can use a session token that you obtain via the API.

Unix-based

For unix-based systems, use the following:

curl -X POST https://api.packetfabric.com/v2/auth/login \
-d '{"login":"caitlin@packetfabric.com","password":"iloveknowledgebases!!"}' -H 'Content-Type: application/json'

Copy the token value that is returned in the response.

NOTE: The \ character above creates a line break, making lengthier commands easier to read. You can keep or remove line breaks when entering your own commands.

Windows-based

The Windows cmd.exe command line does not accept single quote (') characters. You will either need to escape double-quotes or use a JSON file.

For example:

curl -X POST https://api.packetfabric.com/v2/auth/login ^ 
-d "{\"login\":\"caitlin@packetfabric.com\",\"password\":\"iloveknowledgebases!!\"}" -H "Content-Type: application/json"

Copy the token value that is returned in the response.

NOTES:

  • The ^ character above creates a line break, making lengthier commands easier to read. You can keep or remove line breaks when entering your own commands.
  • These examples use commands executed from Windows cmd.exe. Powershell accepts a different syntax and uses curl as an alias for the Invoke-Webrequest cmdlet. This can result in different formatting and requirements, which will not be covered here.

Executing API calls in a Unix-based environment

Basic API calls (Unix)

For basic calls, you can use the command line. For example, the following retrieves the activity log:

curl -X GET https://api.packetfabric.com/v2/activity-logs \
-H "accept: */*" -H "Authorization: Bearer abcd-1234-56789-defg-1234"
NOTE: The \ character above creates a line break, making lengthier commands easier to read. You can keep or remove line breaks when entering your own commands.
TIP: Use | json_pp at the end to make the output more readable.

Depending on the API call, you can use parameters to specify what you want retrieved. For example, the following would retrieve only login events:

curl -X GET https://api.packetfabric.com/v2/activity-logs?event=login  \
-H "accept: */*" -H "Authorization: Bearer abcd-1234-56789-defg-1234"

If you want to append additional parameters, you will need to escape the ampersand character (&) using a backslash \. For example:

curl -X GET https://api.packetfabric.com/v2/activity-logs?event=login\&page_size=5\&sort_order=desc  \
-H "accept: */*" -H "Authorization: Bearer abcd-1234-56789-defg-1234"

Sending requests with JSON data (Unix)

Many calls also require additional attribute information in the request body.

For simple requests, you can use the data flag (-d) to include that information in JSON format. For example, the following POST request creates a new technical contact using only the required fields:

curl -X POST https://api.packetfabric.com/v2/contacts  \
-d '{"email":"tony@packetfabric.com","first_name":"Tony","last_name":"deHamster","phone":"123-456-7890","admin":false,"tech":true,"billing":false}' \
-H "accept: */*" -H "Authorization: Bearer abcd-1234-56789-defg-1234"

But as the list of attributes grows, you might find it easier to create a JSON file to use instead. For example:

curl -X POST https://api.packetfabric.com/v2/contacts  \
-d @hamster.json \
-H "accept: */*" -H "Authorization: Bearer abcd-1234-56789-defg-1234"

Where the contents of the JSON file are:

{
  "email":"tony@packetfabric.com",
  "first_name":"Tony",
  "last_name":"deHamster",
  "phone":"123-456-7890",
  "admin":false,
  "tech":true,
  "billing":false
 }

Executing API calls in a Windows environment

Basic API calls (Windows)

For basic calls, you can use the command line. Just ensure that you are not using single quotes (').

For example, the following retrieves the activity log:

curl -X GET https://api.packetfabric.com/v2/activity-logs ^
-H "accept: */*" -H "Authorization: Bearer abcd-1234-56789-defg-1234"

NOTES:

  • The ^ character above creates a line break, making lengthier commands easier to read. You can keep or remove line breaks when entering your own commands.
  • These examples use commands executed from Windows cmd.exe. Powershell accepts a different syntax and uses curl as an alias for the Invoke-Webrequest cmdlet. This can result in different formatting and requirements, which will not be covered here.
TIP: There are various utilities that you can install and which will allow you to pretty print the JSON output in a Windows command line. If you would prefer not to install a utility, you can save the output to a file by appending -o output.json to the cURL command. From there you can open the file with an editor that has pretty print capabilities.

Depending on the API call, you can use parameters to specify what you want retrieved. For example, the following would retrieve only login events:

curl -X GET https://api.packetfabric.com/v2/activity-logs?event=login  ^
-H "accept: */*" -H "Authorization: Bearer abcd-1234-56789-defg-1234"

If you want to append additional parameters, you will need to enclose the API call in quotation marks. For example:

curl -X GET "https://api.packetfabric.com/v2/activity-logs?event=login&page_size=5&sort_order=desc"  ^
-H "accept: */*" -H "Authorization: Bearer abcd-1234-56789-defg-1234"

Sending requests with JSON data

Many calls also require additional attribute information in the request body.

With Windows, you will need to use a backslash (\) to escape the quotation marks around each string if you want to submit JSON schema via the command line. For this reason, it is much easier to submit JSON data using a file.

In the following example, we will create a new technical contact:

  1. Create a test folder and open it in Windows Explorer.

  2. Right-click in the Explorer address bar and click Copy address as text:

    Copy address in Windows Explorer

  3. Open a command prompt. Enter cd and then right-click to paste the address. Press Enter.

  4. Open a text editor such as Notepad and enter some JSON data. In this example, we are creating a new technical contact using only the required fields. Your JSON data would look similar to following (make sure you include the curly brackets as well):

    {
  "email":"tony@packetfabric.com",
  "first_name":"Tony",
  "last_name":"deHamster",
  "phone":"123-456-7890",
  "admin":false,
  "tech":true,
  "billing":false
 }

  5. Save the file in your working folder with a .json extension (ensure you select All Files under Save as type):

    Save json

  6. Then enter the following command, replacing the bearer token and demo.json with the file name you chose:

    curl -X POST https://api.packetfabric.com/v2/contacts  ^
-d @demo.json ^
-H "accept: */*" -H "Authorization: Bearer abcd-1234-56789-defg-1234"

“Not authorized” error

This has several causes:

  • Your bearer token is no longer valid. Generate a new session token or API key (see above).
  • You forgot to include a bearer token with your API request.
  • You might not have permission to complete the API request. For more information on what actions users can take, see User Permissions.
  • Occasionally this error is from a malformed API request. Check to ensure there are no formatting errors in your parameters.

“Invalid value” error

This is typically due to entering a string parameter in the JSON body without enclosing it in quotes. Boolean (true/false) and integers do not need surrounding quotes.

For example, the API call to create a dedicated Google connection includes strings, a boolean value, and an integer.

{
  "account_uuid": "a2115890-ed02-4795-a6dd-c485bec3529c",
  "description": "Connection for uploading cute cat pics",
  "zone": "A",
  "pop": "DAL1",
  "subscription_term": 24,
  "service_class": "longhaul",
  "autoneg": false,
  "speed": "10Gbps"
}

Our API reference lists each parameter type:

screenshot of reference docs with the param type highlighted

Updated on 10 Jul 2022