Toad API Docs

Getting started

The documentation and examples are provided in JavaScript using axios.

  • 1. Make an account on https://toadli.co.
  • 2. Subscribe to the "Standard Plan" for API access.
  • 3. Get your API Key from the dashboard under the "Developer" section.
  • 4. Come back to the API documentation and create your first link with the instructions below.

Authentication

All requests to the API request your API Key in a the header `api-key`.

Errors

A list of all the possible errors you could receive.

Status CodeDescription
200The request succeeded.
201The request succeeded and the new resource was created.
401The API key was invalid.
404The resource that was requested could not be found.
422Data was invalid or missing required parameters.
500Our server encountered an error while processing your request. We will be notified and work on a fix immediately.

Example error response

{
  "errors": {
    "code": "resource_not_found",
    "message": "Resource not found"
  }
}

Request

await axios.get('https://toadli.co/api/links/a3fsc3', {
  headers: {
    'api-key': '<api-key>'
  },
});

Response

{
  "id": "835f37b7-3eb5-4028-a464-80a0ebad43be",
  "url": "https://google.com",
  "slug": "a3fsc3",
  "long_url": "https://toad.li/a3fsc3",
  "inserted_at": "2021-01-10T19:31:48.254Z",
  "updated_at": "2021-01-10T19:31:48.254Z",
}

Arguments

KeyTypeDescription
sizenumber (optional)The number of lists to return
offsetnumber (optional)The offset from the start of the list to return

Request

await axios.get('https://toadli.co/api/links?size=5&offset=0', {
  headers: {
    'api-key': '<api-key>'
  },
});

Response

{
  "metadata": {
    "offset": 0,
    "size": 5,
    "count": 2,
  },
  "links": [
    {
      "id": "13988514-3de7-4de7-9071-a4d800f39174",
      "url": 'https://google.com',
      "slug": 'a3fd3',
      "long_url": 'https://toad.li/a3fd3',
      "inserted_at": '2021-01-10T19:31:48.254Z',
      "updated_at": '2021-01-10T19:31:48.254Z',
    },
    {
      "id": "13988514-3de7-4de7-9071-a4d800f39174",
      "url": 'https://google.ca',
      "slug": 'h2hsss',
      "long_url": 'https://toad.li/h2hsss',
      "inserted_at": '2021-01-09T21:31:48.254Z',
      "updated_at": '2021-01-09T21:31:48.254Z',
    },
  ],
}

Arguments

KeyTypeDescription
sizenumber (optional)The number of lists to return
offsetnumber (optional)The offset from the start of the list to return

Request

await axios.get('https://toadli.co/api/links/a3fsc3/visits?size=5&offset=0', {
  headers: {
    'api-key': '<api-key>'
  },
});

Response

{
  "metadata": {
    "offset": 0,
    "size": 5,
    "count": 2,
  },
  "links_visits": [
    {
      "id": "835f37b7-3eb5-4028-a464-80a0ebad43be",
      "link_id": "13988514-3de7-4de7-9071-a4d800f39174",
      "inserted_at": '2021-01-10T19:31:48.254Z',
      "updated_at": '2021-01-10T19:31:48.254Z',
      "headers": {
        "host": "localhost:3001",
        "accept": "text/html,application/xhtml+xml,application/xml",
        "user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 11_2_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/89.0.4389.82 Safari/537.36",
        "accept-encoding": "gzip, deflate, br",
        "accept-language": "en-US,en;q=0.9,la;q=0.8",
      },
      "location_data": {
        "zip": "02492",
        "city": "Needham",
        "region_code": "MA",
        "region_name": "Massachusetts",
        "country_code": "US",
        "country_flag": "http://assets.ipstack.com/flags/us.svg",
        "country_name": "United States",
        "continent_code": "NA",
        "continent_name": "North America",
        "country_flag_emoji": "πŸ‡ΊπŸ‡Έ",
      },
      "user_agent_data": {
        "os": "iOS",
        "browser": "Mobile Safari",
        "device_type": "mobile",
        "device_vendor": "Apple",
      },
      "query": {
        "utm_source": "facebook",
      },
      "method": "GET",
    },
  ],
}

Arguments

KeyTypeDescription
urlstringMust be a valid URL
slugstring (optional)Must be between 4 and 30 characters and not previously used
domainstring (optional)Domain hostname for a custom domain. You must be between on the professional plan and have the domain set up on your account.

Request

await axios.post('https://toadli.co/api/links', {
  url: 'https://google.com',
  domain: 'short.ln',
}, {
  headers: {
    'api-key': '<api-key>'
  },
});

Response

{
  "id": "835f37b7-3eb5-4028-a464-80a0ebad43be",
  "url": "https://google.com",
  "slug": "a3fsc3",
  "long_url": "https://toad.li/a3fsc3",
  "updated_at": "2021-01-10T19:31:48.254Z",
  "inserted_at": "2021-01-10T19:31:48.254Z",
}

Arguments

KeyTypeDescription
urlstring (optional)Must be a valid URL
slugstring (optional)Must be between 4 and 30 characters and not previously used

Request

await axios.put('https://toadli.co/api/links/a3fsc3', {
  url: 'https://google.ca',
}, {
  headers: {
    'api-key': '<api-key>'
  },
});

Response

{
  "id": "13988514-3de7-4de7-9071-a4d800f39174",
  "url": "https://google.ca",
  "slug": "a3fsc3",
  "long_url": "https://toad.li/a3fsc3",
  "updated_at": "2021-01-10T19:31:48.254Z",
  "inserted_at": "2021-01-10T19:31:48.254Z",
}

Request

await axios.delete('https://toadli.co/api/links/dsf23d', {
  headers: {
    'api-key': '<api-key>'
  },
});

Response

{
  "id": "835f37b7-3eb5-4028-a464-80a0ebad43be",
  "url": "https://google.com",
  "slug": "a3fsc3",
  "updated_at": "2021-01-10T19:31:48.254Z",
  "inserted_at": "2021-01-10T19:31:48.254Z",
}

Get a Domain

Request

await axios.get('https://toadli.co/api/domains/test.com', {
  headers: {
    'api-key': '<api-key>'
  },
});

Response

{
  "id": "835f37b7-3eb5-4028-a464-80a0ebad43be",
  "name": "test.com",
  "inserted_at": "2021-01-10T19:31:48.254Z",
  "updated_at": "2021-01-10T19:31:48.254Z",
}

List Domains

Arguments

KeyTypeDescription
sizenumber (optional)The number of lists to return
offsetnumber (optional)The offset from the start of the list to return

Request

await axios.get('https://toadli.co/api/domains?size=5&offset=0', {
  headers: {
    'api-key': '<api-key>'
  },
});

Response

{
  "metadata": {
    "offset": 0,
    "size": 5,
    "count": 2,
  },
  "links": [
    {
      "id": "13988514-3de7-4de7-9071-a4d800f39174",
      "name": "domain.com";
      "inserted_at": '2021-01-10T19:31:48.254Z',
      "updated_at": '2021-01-10T19:31:48.254Z',
      "team_id": "835f37b7-3eb5-4028-a464-80a0ebad43be";
    },
  ],
}

Create a Domain

Arguments

KeyTypeDescription
namestringDomain to add, must be a base domain or subdomain without a protocol (https) or sub-routes and query params

Request

await axios.post('https://toadli.co/api/domains', {
  name: 'test.com',
}, {
  headers: {
    'api-key': '<api-key>'
  },
});

Response

{
  "id": "835f37b7-3eb5-4028-a464-80a0ebad43be",
  "name": "test.com",
  "updated_at": "2021-01-10T19:31:48.254Z",
  "inserted_at": "2021-01-10T19:31:48.254Z",
}

Get a Domain status

Request

await axios.get('https://toadli.co/api/domains/test.com/status', {
  headers: {
    'api-key': '<api-key>'
  },
});

Response

{
  "verified": true,
}