# 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!

Last updated: 1/27/2021, 1:33:35 PM