APIs Introduction

Urly provides simple APIs to let developers integrate their own applications with Urly’s services. You must be subscribed to Urly Plus in order to use the APIs.

Getting a key

After logging into a Urly Plus account, visit the API Keys page. Enter a name for your new key, in order to recognize it in the future and then click Generate key.

For security reasons, the newly generated key will be shown once. Copy and save it in a safe place.

Revoking a key

Generated keys can be revoked at any time. By revoking a key, any active app integration which uses that key will stop working.

Limitations

In order to prevent abuse, APIs are limited at 1000 links per month. If you need a bigger quota, contact us.

Authentication

Use the API key to authenticate every request. Authentication is made using an HTTP Authorization header, where {token} has to be replaced with your API key, as in the following example:

Authorization: Bearer {token}

Requests and responses format

All the API calls and their responses are encoded as application/json.

The HTTP status code depends on the type of response:

• 200 OK for successfully completed requests;
• 401 Unauthorized for non valid or revoked keys;
• 402 Payment Required if you don’t have an active Urly Plus account;
• 403 Forbidden if you don’t have permission to make a specific request;
• 404 Not Found if you’re trying to access a non-existing resource or endpoint;
• 422 Unprocessable Content if there’s a validation errror;
• 429 Too Many Requests if you’ve reached your monthly limits;
• 500 Server Error in case of an internal server error.

Validation errors

Validation errors are reported with an HTTP status of 422 Unprocessable Content. Their response has the following format:

{
  "message": "The given data was invalid.",
  "errors": {
    "destination": [
      "The destination field is required."
    ]
  }
}

errors is an object with field names as its keys. For each key, an array of printable errors is returned.