# 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": []
		}
	]
}

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