NAV
cURL

Introduction

Base URL:

https://api.terminusapp.com/

Terminus's RESTful API allows you to perform various operations on your Terminus account.

All responses (including errors) are returned with standard HTTP response codes and JSON-formatted data.

Authentication

Authenticated Request :

curl "https://api.terminusapp.com/v1/projects" \
  -u YOUR_API_KEY:
# The colon prevents curl from asking for a password.

The Terminus API uses API keys to authenticate requests. You can create and manage your API keys in your Terminus account.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Object IDs

Object data responses will include JSON keys such as id, project_id and others. Before storing or using these IDs, consider the following:

Links

Request Endpoint

curl -g "https://api.terminusapp.com/v1/projects/prj_rTptUizwYr/links" -X GET \
    -u YOUR_API_KEY:

GET /v1/projects/:project_id/links

Parameters

Name Description
project_id required Project ID starting with prj_
created_at[gt] Return items created after a certain date. The value should be an integer Unix timestamp.
updated_at[gt] Return items updated after a certain date. The value should be an integer Unix timestamp.
items Number of items to be returned. This can range between 1 and 100. Default is 10.
page Specify the page number to get items that cannot be returned in a single request. Default is 1.

Response

{
  "data": [
    {
      "id": 6778,
      "url": "https://www.example.com/",
      "long_url": "https://www.example.com/?coupon=50p_off&cid=monthly-date_20200911-head_nowwork-ads&utm_source=linkedin&utm_medium=social&utm_campaign=summer_promotion",
      "description": "Blog links",
      "campaign": {
        "value": "summer_promotion",
        "fields_map": [
          {
            "prefix": null,
            "suffix": null,
            "field_id": 467,
            "final_value": "monthly",
            "input_value": "monthly"
          },
          {
            "prefix": "date_",
            "suffix": "",
            "field_id": 477,
            "final_value": "date_20200911",
            "input_value": "20200911"
          },
          {
            "prefix": "head_",
            "suffix": "",
            "field_id": 479,
            "final_value": "head_nowwork",
            "input_value": "nowwork"
          },
          {
            "prefix": null,
            "suffix": null,
            "field_id": 478,
            "final_value": "ads",
            "input_value": "ads"
          }
        ],
        "parameter_format_id": 12345
      },
      "medium": {
        "value": "social",
        "fields_map": [

        ],
        "parameter_format_id": null
      },
      "source": {
        "value": "linkedin",
        "fields_map": [

        ],
        "parameter_format_id": null
      },
      "content": null,
      "term": null,
      "custom_parameter_values": [
        {
          "custom_parameter": {
            "name": "coupon"
          },
          "value": "50p_off",
          "fields_map": [

          ],
          "parameter_format_id": null
        },
        {
          "custom_parameter": {
            "name": "cid"
          },
          "value": "monthly-date_20200911-head_nowwork-ads",
          "fields_map": [
            {
              "prefix": null,
              "suffix": null,
              "field_id": 467,
              "final_value": "monthly",
              "input_value": "monthly"
            },
            {
              "prefix": "date_",
              "suffix": "",
              "field_id": 477,
              "final_value": "date_20200911",
              "input_value": "20200911"
            },
            {
              "prefix": "head_",
              "suffix": "",
              "field_id": 479,
              "final_value": "head_nowwork",
              "input_value": "nowwork"
            },
            {
              "prefix": null,
              "suffix": null,
              "field_id": 478,
              "final_value": "ads",
              "input_value": "ads"
            }
          ],
          "parameter_format_id": 56789
        }
      ],
      "info_field_values": [
        {
          "value": "Bob Smith",
          "info_field": {
            "name": "Requester"
          }
        },
        {
          "value": "Buy Now",
          "info_field": {
            "name": "Ad Headline"
          }
        }
      ],
      "labels": [
        {
          "name": "urgent"
        },
        {
          "name": "blog"
        }
      ],
      "short_url": {
        "clicks": 0,
        "url": "https://shor.ty/ggq30m"
      },
      "created_at": 1605052800,
      "created_by": {
        "email": "abc@example.com"
      }
    }
  ],
  "meta": {
    "page": 1,
    "has_more": false
  }
}
Name Description
data An array of items
meta[page] Current page number
meta[has_more] true if more items are available on the next page. Otherwise false

Parameter Formats

Get a parameter format

Request Endpoint

curl -g "https://api.terminusapp.com/v1/projects/prj_GMBbPjHQOt/parameter_formats/255" -X GET \
    -u YOUR_API_KEY:

GET /v1/projects/:project_id/parameter_formats/:parameter_format_id

Parameters

Name Description
project_id required Project ID starting with prj_
parameter_format_id required Parameter format id

Response

{
  "id": 255,
  "name": "Email Campaign Format",
  "separator": "-",
  "fields": [
    {
      "id": 507,
      "name": "Interval",
      "type": "OptionField",
      "date_format": null,
      "constant_value": null,
      "prefix": null,
      "suffix": ":int",
      "option_values": [
        {
          "name": "weekly",
          "description": "Weekly newsletter",
          "position": 1
        },
        {
          "name": "monthly",
          "description": "Monthly newsletter",
          "position": 2
        },
        {
          "name": "yearly",
          "description": "",
          "position": 3
        }
      ]
    },
    {
      "id": 508,
      "name": "Date",
      "type": "DateField",
      "date_format": "YYYY_MM_DD",
      "constant_value": null,
      "prefix": "date_",
      "suffix": null,
      "option_values": [

      ]
    },
    {
      "id": 509,
      "name": "Headline",
      "type": "TextField",
      "date_format": null,
      "constant_value": null,
      "prefix": null,
      "suffix": null,
      "option_values": [

      ]
    },
    {
      "id": 510,
      "name": "Headline",
      "type": "TextField",
      "date_format": null,
      "constant_value": null,
      "prefix": null,
      "suffix": null,
      "option_values": [

      ]
    }
  ]
}
Name Description
id Parameter format id
name Given name of the parameter format
separator Separator character used to join the fields
fields An array of field objects

List parameter formats

Request Endpoint

curl -g "https://api.terminusapp.com/v1/projects/prj_3G9nRoTOeH/parameter_formats" -X GET \
    -u YOUR_API_KEY:

GET /v1/projects/:project_id/parameter_formats

Parameters

Name Description
project_id required Project ID starting with prj_
items Number of items to be returned. This can range between 1 and 100. Default is 10.
page Specify the page number to get items that cannot be returned in a single request. Default is 1.

Response

{
  "data": [
    {
      "id": 254,
      "name": "Email Campaign Format",
      "separator": "-",
      "fields": [
        {
          "id": 503,
          "name": "Interval",
          "type": "OptionField",
          "date_format": null,
          "constant_value": null,
          "prefix": null,
          "suffix": ":int",
          "option_values": [
            {
              "name": "weekly",
              "description": "Weekly newsletter",
              "position": 1
            },
            {
              "name": "monthly",
              "description": "Monthly newsletter",
              "position": 2
            },
            {
              "name": "yearly",
              "description": "",
              "position": 3
            }
          ]
        },
        {
          "id": 504,
          "name": "Date",
          "type": "DateField",
          "date_format": "YYYY_MM_DD",
          "constant_value": null,
          "prefix": "date_",
          "suffix": null,
          "option_values": [

          ]
        },
        {
          "id": 505,
          "name": "Headline",
          "type": "TextField",
          "date_format": null,
          "constant_value": null,
          "prefix": null,
          "suffix": null,
          "option_values": [

          ]
        },
        {
          "id": 506,
          "name": "Headline",
          "type": "TextField",
          "date_format": null,
          "constant_value": null,
          "prefix": null,
          "suffix": null,
          "option_values": [

          ]
        }
      ]
    }
  ],
  "meta": {
    "page": 1,
    "has_more": false
  }
}
Name Description
data An array of items
meta[page] Current page number
meta[has_more] true if more items are available on the next page. Otherwise false

Projects

List projects

Request Endpoint

curl -g "https://api.terminusapp.com/v1/projects/" -X GET \
    -u YOUR_API_KEY:

GET /v1/projects/

Parameters

Name Description
items Number of items to be returned. This can range between 1 and 100. Default is 10.
page Specify the page number to get items that cannot be returned in a single request. Default is 1.

Response

{
  "data": [
    {
      "id": "prj_YelSd6fyTQ",
      "name": "My project"
    }
  ],
  "meta": {
    "page": 1,
    "has_more": false
  }
}
Name Description
data An array of items
meta[page] Current page number
meta[has_more] true if more items are available on the next page. Otherwise false

Errors

The Terminus API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- You are not allowed to access this resource.
404 Not Found -- The specified resource could not be found.
429 Too Many Requests -- Your have hit the API rate limit. Try after some time.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.