Sublime Ads

Categories

To organise your ads you can put them into categories. This can be useful for various scenarios like a podcast app, or a feed reading app where you want to separate ads depending on a specific category or section.

Get all categories

Endpoint: https://sublimeads.com/api/categories

As usual, don't forget to pass in your token as a URL parameter.

This will return all your categories, including any ads contained within.

Here is an example response:

{
  "message": "Here are your categories",
  "count": 2,
  "items": [
    {
      "id": 4,
      "public_id": "GrA9YTHfEcv-OQ",
      "name": "My service website",
      "description": "Ads to promote certain services that are relevant to my service website.",
      "is_paused": false,
      "ad_count": 0,
      "items": []
    },
    {
      "id": 20,
      "public_id": "5c3sO4cNrK2Jlg",
      "name": "Personal Site",
      "description": "Ads I want to show on my own site.",
      "is_paused": false,
      "ad_count": 2,
      "items": [
        {
          "id": 34,
          "public_id": "pjc1hPP2tRnpJg",
          "image_url": "wgeenfuh8adu9ss639re64fg8bli",
          "title": "Gluon for Micro.blog",
          "content": "\u003cdiv\u003eA beautiful, lightweight and customisable cross platform app built for Micro.blog.\u003c/div\u003e",
          "redirect_to_url": "https://gluon.app",
          "url": "https://sublimeads.com/tap/pjc1hPP2tRnpJg/5c3sO4cNrK2Jlg",
          "is_paused": false
        },
        {
          "id": 33,
          "public_id": "XjtXY7re_kWmLw",
          "image_url": "1dmbubekywe7h4u3hlcz6a4a650q",
          "title": "Sublime Ads",
          "content": "\u003cdiv\u003eA privacy focused \u003cstrong\u003ead management\u003c/strong\u003e service for your apps, websites and others.\u003c/div\u003e",
          "redirect_to_url": "https://sublimeads.com",
          "url": "https://sublimeads.com/tap/XjtXY7re_kWmLw/5c3sO4cNrK2Jlg",
          "is_paused": false
        }
      ]
    }
  ]
}

The above returned two categories. One with no ads tied to it, and another with two ads tied to it.

You can return only categories, without ads, by adding a no_ads URL parameter. The value can be anything. For example:

https://sublimeads.com/api/categories/?token=yourAwesomeToken&no_ads

This will return categories without ads. So using the above example, you'll see the following:

{
  "message": "Here are your categories",
  "count": 2,
  "items": [
    {
      "id": 4,
      "public_id": "GrA9YTHfEcv-OQ",
      "name": "My service website",
      "description": "Ads to promote certain services that are relevant to my service website.",
      "is_paused": false,
      "ad_count": null,
      "items": []
    },
    {
      "id": 20,
      "public_id": "5c3sO4cNrK2Jlg",
      "name": "Personal Site",
      "description": "Ads I want to show on my own site.",
      "is_paused": false,
      "ad_count": null,
      "items": []
		}
	]
}

As default, any paused category or ad will not be shown. This just makes it easier on the receiving end. However, if you wish, you can add an optional parameter to your call:

Adding a show_paused URL parameter will return paused ads and categories. The value can be anything. For example:

https://sublimeads.com/api/categories/?token=yourAwesomeToken&show_paused

Get a Category by ID

Just like ads, you can grab a category by the ID.

Endpoint: https://sublimeads.com/api/category/:id

Note that you replace :id with the ID of the category you want to grab. Do not use the "public_id" here - it will not work.

The ID of your category can be found in your category list.

The Category object

Categories are easy, here is the object:

{
	"id": 20,
	"public_id": "5c3sO4cNrK2Jlg",
	"name": "Personal Site",
	"description": "Ads I want to show on my own site.",
	"is_paused": false,
	"ad_count": 2,
	"items": [...]
}

id

The ID of your Category - useful if you need to grab it individually.

Type: int

public_id

This is the public facing id of your category, which will be used for the "tap" redirect found in the "url" field in an ad object.

Type: string

name

The name/title of your category.

Type: string

description

The description of your category.

Type: string

is_paused

Tells you if the category is paused or not.

Type: boolean

ad_count

The amount of ads within the category. Note that this returns null when the no_ads URL parameter is used.

Type: int or null

items

An array of ads within the category. Please note that the URL within an ad will also include the public_id of the category in question. This allows the tap to be registered and tied to the category in question. Useful!

Parent & Sub Categories

Paid feature only

Categories can either be parent categories or sub categories. If true, then the category object will be slightly different depending on the category type at the time.

We introduce two new keys to our object:

{
  "id": 20,
  ...,
  "parent_category": 12, // If sub category only
  "has_sub_categories": 3, // If parent category only
  "sub_categories": [...categories] // (optional) If parent category only
}

Both keys might not be present, so check if they exist first.

parent_category

If the category is a sub category, it will show you the id of the parent category so you can easily keep track of this if needed.

Type: int

has_sub_categories

If the category is a parent category, ie it has sub categories, it will show you a count of the available sub categories.

Type: int

sub_categories

To make sure to keep the API data to a minimum, sub categories will not automtically be included in your response.

You can add an optional parameter of show_sub_categories to your query to bring back all the sub categories, which behaves the same way as the main category object, including any additional options you have added.

Type: array of categories

Last Updated: