Mellow Ads API documentation: Version 1


This initial version of our API contains only a limited set of functionality - just the ability to create short links!



The base URL for this version of the API is
In general the URL that make your request to will be of the format{method} where {method} is the name of API method as detailed below.

API key authentication

All requests to our API must include your private, individual API key which you can get from API settings (you must be signed in to Mellow Ads to see this). This API key is used to identify and authenticate your account and should be kept secure at all times.


Response format

All of our API methods return JSON data by default. In a small number of cases we can optionally return data in a different format - when this is possible it is detailed in the documentation below.


Our API returns standard HTTP response codes and a message containing more details about the error. Some common examples are...

  • 200: Success
  • 400: Bad Request - for example when one of the required parameters is invalid or missing, or an incorrect API key
  • 401: Unauthorized - this would happen if your API access had been revoked for some reason
  • 500: Internal Server Error - something bad and unexpected happened at our end!

In case of an error the body of the response will contain an error 'result' and 'message'

API methods

Create link

Use this method to create a new short link. If successful, full details of the new link are returned in the response.

You can optionally supply Title, Description and ImageURL which will be displayed on the page when the user visits your short link, before they continue on to the destination URL. If none of Title, Description and ImageUrl are provided, then the system will attempt to automatically look these up from the destination page Open Graph metadata.

Request URL

Required parameters

  • apiKey string
    Your API key
  • url string
    The destination page URL that you wish to create a short link for.
    This should start with either 'http://' or 'https://'

Optional parameters

  • title string
    An optional title for the page. This should be fairly short and relevant to the destination page.
  • description string
    An optional description for the page. If provided this should be longer and more descriptive than the title.
  • imageUrl string
    The URL of an image that will be displayed (along with the title and description) to the user when they visit your short link.
    Again this should start with either 'http://' or 'https://'
  • format string
    If this parameter is supplied with value 'text' then the response will simply be a text short link URL, rather than the usual verbose JSON response.
    (NOTE: The only valid value for this is 'text' - any other value will be ignored)
  • item integer
    When format=text is specified, this parameter will determine which link URL will be returned of the 7 different domains...
    0:, 1:, 2:, 3:, 4:, 5:, 6:
    (NOTE: The only valid value for this is 0 to 6, any other value will be ignored)

Response JSON format

  • result integer
    1. Success
    2. Invalid API Key
    3. API Access Denied
    4. Invalid URL
    5. Invalid Image URL
    6. Invalid Item
  • message string
    A short textual summary of the result of the API call
  • link object
    • ref string
      A unique reference number for the new link
    • status string
      The current status of the link...
      • Active The link has had valid, unique clicks in the last 24 hours
      • Inactive The link has NOT had any valid, unique clicks in the last 24 hours. (This is the inital status when a new link is created)
      • Deleted The link has been deleted by the user.
    • url string
      The URL of the destination page - as specified in the request
    • title string
      The destination page title
    • description string
      The destination page description
    • imageUrl string
      The destination page image URL
    • linkURLs array of strings
      One link URL string for each of the 7 domains:,,,,,,

Request examples

  • Simple GET request with only minimum, required parameters
  • GET request supplying Title, Description and ImageUrl parameters
  • GET request specifying text format response using domain
  • POST request supplying Title, Description and ImageUrl parameters
    Content-Type: application/json
        "apiKey": "APIKEY",
        "url": "URL",
        "title": "TITLE",
        "description": "DESCRIPTION",
        "imageUrl": "IMAGEURL"

Response examples

  • Link created successfully (default JSON format)
    HTTP/1.1 200 OK
    Content-Type: application/json
      "message":"Success: Link XXXX created",
  • Link created successfully (format=text, item=2)
    HTTP/1.1 200 OK
    Content-Type: text/html
  • Error: Missing URL
    HTTP/1.1 400 URL cannot be empty
    Content-Type: application/json
      "message":"URL cannot be empty"