PushizoDocs
API reference

Categories and preferences

Categories and preferences — 6 operations (GET /v1/apps/{appId}/categories, POST /v1/apps/{appId}/categories, PATCH /v1/apps/{appId}/categories/{categoryId}, …). Generated from the OpenAPI 3.1.0 contract.

Subscription categories and per-user channel/category preferences; the preference center is powered by these endpoints.

Base URL: https://api.pushizo.com · Tag: preferences · Interactive docs (Scalar)

Operations

MethodPathOperation
GET/v1/apps/{appId}/categoriesMessage categories
POST/v1/apps/{appId}/categoriesCreate a category
PATCH/v1/apps/{appId}/categories/{categoryId}Update a category
DELETE/v1/apps/{appId}/categories/{categoryId}Delete a category
GET/v1/apps/{appId}/users/by/{label}/{value}/preferencesUser preferences (by alias)
PUT/v1/apps/{appId}/users/by/{label}/{value}/preferencesWrite user preferences (by alias)

Details

Message categories

GET/v1/apps/{appId}/categoriesTry it (interactive API docs, new tab)

Authentication: API key — scope users:read (admin includes every scope).

Parameters

NameInTypeRequiredDescriptionExample
appIdpathstringYes"app_01JD3W5Q7X9K2M4N6P8R0T1V3W"

Responses

200 — Success.

Schema: MessageCategoryList

FieldTypeRequiredDescription
dataarray<object>Yes
data[].idstringYes
data[].app_idstringYes
data[].keystringYes
data[].namemap<string, string>Yes
data[].descriptionmap<string, string>Yes
data[].channelsarray<string> | nullYes
data[].default_opted_inbooleanYes
data[].positionintegerYes
data[].opted_out_usersintegerYes
data[].created_atstringYes
data[].updated_atstringYes

Example response:

{
  "data": [
    {
      "name": {
        "key": "user_42"
      },
      "channels": [
        "web_push"
      ],
      "id": "cat_01JD3W5Q7X9K2M4N6P8R0T1V3W",
      "app_id": "app_01JD3W5Q7X9K2M4N6P8R0T1V3W",
      "key": "key-2026-10",
      "description": {
        "key": "user_42"
      },
      "default_opted_in": true,
      "position": 1,
      "opted_out_users": 1,
      "created_at": "örnek",
      "updated_at": "örnek"
    }
  ]
}

Errors use the common envelope (error.code, message, details, request_id): error catalog. Every response carries X-RateLimit-* headers (rate limits).

Examples

curl -X GET "https://api.pushizo.com/v1/apps/app_01JD3W5Q7X9K2M4N6P8R0T1V3W/categories" \
  -H "Authorization: Bearer $PUSHIZO_API_KEY"

Create a category

POST/v1/apps/{appId}/categoriesTry it (interactive API docs, new tab)

Authentication: API key — scope admin (admin includes every scope).

Parameters

NameInTypeRequiredDescriptionExample
appIdpathstringYes"app_01JD3W5Q7X9K2M4N6P8R0T1V3W"

Request body (required)

Schema: CreateCategoryDto

FieldTypeRequiredDescription
keystringYesLength: 1–64
namemap<string, string>Yes
descriptionmap<string, string>No
channelsarray<enum> | nullNo
default_opted_inbooleanNo
positionintegerNoRange: 0–1000

Example:

{
  "name": {
    "key": "user_42"
  },
  "key": "key-2026-10",
  "channels": [
    "ios_push"
  ],
  "description": {
    "key": "user_42"
  },
  "default_opted_in": true,
  "position": 1
}

Responses

201 — Success.

Schema: MessageCategory

FieldTypeRequiredDescription
idstringYes
app_idstringYes
keystringYes
namemap<string, string>Yes
descriptionmap<string, string>Yes
channelsarray<string> | nullYes
default_opted_inbooleanYes
positionintegerYes
opted_out_usersintegerYes
created_atstringYes
updated_atstringYes

Example response:

{
  "name": {
    "key": "user_42"
  },
  "channels": [
    "web_push"
  ],
  "id": "cat_01JD3W5Q7X9K2M4N6P8R0T1V3W",
  "app_id": "app_01JD3W5Q7X9K2M4N6P8R0T1V3W",
  "key": "key-2026-10",
  "description": {
    "key": "user_42"
  },
  "default_opted_in": true,
  "position": 1,
  "opted_out_users": 1,
  "created_at": "örnek",
  "updated_at": "örnek"
}

Errors use the common envelope (error.code, message, details, request_id): error catalog. Every response carries X-RateLimit-* headers (rate limits).

Examples

curl -X POST "https://api.pushizo.com/v1/apps/app_01JD3W5Q7X9K2M4N6P8R0T1V3W/categories" \
  -H "Authorization: Bearer $PUSHIZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": {
    "key": "user_42"
  },
  "key": "key-2026-10",
  "channels": [
    "ios_push"
  ],
  "description": {
    "key": "user_42"
  },
  "default_opted_in": true,
  "position": 1
}'

Update a category

PATCH/v1/apps/{appId}/categories/{categoryId}Try it (interactive API docs, new tab)

Authentication: API key — scope admin (admin includes every scope).

Parameters

NameInTypeRequiredDescriptionExample
categoryIdpathstringYes"cat_01JD3W5Q7X9K2M4N6P8R0T1V3W"
appIdpathstringYes"app_01JD3W5Q7X9K2M4N6P8R0T1V3W"

Request body (required)

Schema: UpdateCategoryDto

FieldTypeRequiredDescription
namemap<string, string>No
descriptionmap<string, string>No
channelsarray<enum> | nullNo
default_opted_inbooleanNo
positionintegerNoRange: 0–1000

Example:

{
  "name": {
    "key": "user_42"
  },
  "channels": [
    "ios_push"
  ],
  "description": {
    "key": "user_42"
  },
  "default_opted_in": true,
  "position": 1
}

Responses

200 — Success.

Schema: MessageCategory

FieldTypeRequiredDescription
idstringYes
app_idstringYes
keystringYes
namemap<string, string>Yes
descriptionmap<string, string>Yes
channelsarray<string> | nullYes
default_opted_inbooleanYes
positionintegerYes
opted_out_usersintegerYes
created_atstringYes
updated_atstringYes

Example response:

{
  "name": {
    "key": "user_42"
  },
  "channels": [
    "web_push"
  ],
  "id": "cat_01JD3W5Q7X9K2M4N6P8R0T1V3W",
  "app_id": "app_01JD3W5Q7X9K2M4N6P8R0T1V3W",
  "key": "key-2026-10",
  "description": {
    "key": "user_42"
  },
  "default_opted_in": true,
  "position": 1,
  "opted_out_users": 1,
  "created_at": "örnek",
  "updated_at": "örnek"
}

Errors use the common envelope (error.code, message, details, request_id): error catalog. Every response carries X-RateLimit-* headers (rate limits).

Examples

curl -X PATCH "https://api.pushizo.com/v1/apps/app_01JD3W5Q7X9K2M4N6P8R0T1V3W/categories/cat_01JD3W5Q7X9K2M4N6P8R0T1V3W" \
  -H "Authorization: Bearer $PUSHIZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": {
    "key": "user_42"
  },
  "channels": [
    "ios_push"
  ],
  "description": {
    "key": "user_42"
  },
  "default_opted_in": true,
  "position": 1
}'

Delete a category

DELETE/v1/apps/{appId}/categories/{categoryId}Try it (interactive API docs, new tab)

Authentication: API key — scope admin (admin includes every scope).

Parameters

NameInTypeRequiredDescriptionExample
categoryIdpathstringYes"cat_01JD3W5Q7X9K2M4N6P8R0T1V3W"
appIdpathstringYes"app_01JD3W5Q7X9K2M4N6P8R0T1V3W"

Responses

200 — Success.

Schema: Ok

FieldTypeRequiredDescription
oktrueYes

Example response:

{
  "ok": true
}

Errors use the common envelope (error.code, message, details, request_id): error catalog. Every response carries X-RateLimit-* headers (rate limits).

Examples

curl -X DELETE "https://api.pushizo.com/v1/apps/app_01JD3W5Q7X9K2M4N6P8R0T1V3W/categories/cat_01JD3W5Q7X9K2M4N6P8R0T1V3W" \
  -H "Authorization: Bearer $PUSHIZO_API_KEY"

User preferences (by alias)

GET/v1/apps/{appId}/users/by/{label}/{value}/preferencesTry it (interactive API docs, new tab)

Authentication: API key — scope users:read (admin includes every scope).

Parameters

NameInTypeRequiredDescriptionExample
labelpathstringYes"external_id"
valuepathstringYes"user_42"
appIdpathstringYes"app_01JD3W5Q7X9K2M4N6P8R0T1V3W"

Responses

200 — Success.

Schema: UserPreferences

FieldTypeRequiredDescription
user_idstringYes
dataarray<object>Yes
data[].categorystringYes
data[].channelstring | nullYes
data[].opted_inbooleanYes
data[].explicitbooleanYes
data[].sourcestring | nullYes
data[].updated_atstring | nullYes
categoriesarray<object>Yes
categories[].idstringYes
categories[].app_idstringYes
categories[].keystringYes
categories[].namemap<string, string>Yes
categories[].descriptionmap<string, string>Yes
categories[].channelsarray<string> | nullYes
categories[].default_opted_inbooleanYes
categories[].positionintegerYes
categories[].opted_out_usersintegerYes
categories[].created_atstringYes
categories[].updated_atstringYes
consentsarray<object>Yes
consents[].purposeenumYesValues: "ads_personalization"
consents[].grantedbooleanYes
consents[].sourcestring | nullYes
consents[].updated_atstring | nullYes

Example response:

{
  "data": [
    {
      "channel": "web_push",
      "category": "örnek",
      "opted_in": true,
      "explicit": true,
      "source": "örnek",
      "updated_at": "örnek"
    }
  ],
  "user_id": "usr_01JD3W5Q7X9K2M4N6P8R0T1V3W",
  "categories": [
    {
      "name": {
        "key": "user_42"
      },
      "channels": [
        "web_push"
      ],
      "id": "cat_01JD3W5Q7X9K2M4N6P8R0T1V3W",
      "app_id": "app_01JD3W5Q7X9K2M4N6P8R0T1V3W",
      "key": "key-2026-10",
      "description": {
        "key": "user_42"
      },
      "default_opted_in": true,
      "position": 1,
      "opted_out_users": 1,
      "created_at": "örnek",
      "updated_at": "örnek"
    }
  ],
  "consents": [
    {
      "purpose": "ads_personalization",
      "granted": true,
      "source": "örnek",
      "updated_at": "örnek"
    }
  ]
}

Errors use the common envelope (error.code, message, details, request_id): error catalog. Every response carries X-RateLimit-* headers (rate limits).

Examples

curl -X GET "https://api.pushizo.com/v1/apps/app_01JD3W5Q7X9K2M4N6P8R0T1V3W/users/by/external_id/user_42/preferences" \
  -H "Authorization: Bearer $PUSHIZO_API_KEY"

Write user preferences (by alias)

PUT/v1/apps/{appId}/users/by/{label}/{value}/preferencesTry it (interactive API docs, new tab)

Authentication: API key — scope users:write (admin includes every scope).

Parameters

NameInTypeRequiredDescriptionExample
labelpathstringYes"external_id"
valuepathstringYes"user_42"
appIdpathstringYes"app_01JD3W5Q7X9K2M4N6P8R0T1V3W"

Request body (required)

Schema: SetPreferencesDto

FieldTypeRequiredDescription
preferencesarray<object>YesItems: 1–100
preferences[].categorystringYesLength: 1–64
preferences[].channelenum | nullNo
preferences[].opted_inbooleanYes

Example:

{
  "preferences": [
    {
      "category": "örnek",
      "opted_in": true,
      "channel": "ios_push"
    }
  ]
}

Responses

200 — Success.

Schema: UserPreferences

FieldTypeRequiredDescription
user_idstringYes
dataarray<object>Yes
data[].categorystringYes
data[].channelstring | nullYes
data[].opted_inbooleanYes
data[].explicitbooleanYes
data[].sourcestring | nullYes
data[].updated_atstring | nullYes
categoriesarray<object>Yes
categories[].idstringYes
categories[].app_idstringYes
categories[].keystringYes
categories[].namemap<string, string>Yes
categories[].descriptionmap<string, string>Yes
categories[].channelsarray<string> | nullYes
categories[].default_opted_inbooleanYes
categories[].positionintegerYes
categories[].opted_out_usersintegerYes
categories[].created_atstringYes
categories[].updated_atstringYes
consentsarray<object>Yes
consents[].purposeenumYesValues: "ads_personalization"
consents[].grantedbooleanYes
consents[].sourcestring | nullYes
consents[].updated_atstring | nullYes

Example response:

{
  "data": [
    {
      "channel": "web_push",
      "category": "örnek",
      "opted_in": true,
      "explicit": true,
      "source": "örnek",
      "updated_at": "örnek"
    }
  ],
  "user_id": "usr_01JD3W5Q7X9K2M4N6P8R0T1V3W",
  "categories": [
    {
      "name": {
        "key": "user_42"
      },
      "channels": [
        "web_push"
      ],
      "id": "cat_01JD3W5Q7X9K2M4N6P8R0T1V3W",
      "app_id": "app_01JD3W5Q7X9K2M4N6P8R0T1V3W",
      "key": "key-2026-10",
      "description": {
        "key": "user_42"
      },
      "default_opted_in": true,
      "position": 1,
      "opted_out_users": 1,
      "created_at": "örnek",
      "updated_at": "örnek"
    }
  ],
  "consents": [
    {
      "purpose": "ads_personalization",
      "granted": true,
      "source": "örnek",
      "updated_at": "örnek"
    }
  ]
}

Errors use the common envelope (error.code, message, details, request_id): error catalog. Every response carries X-RateLimit-* headers (rate limits).

Examples

curl -X PUT "https://api.pushizo.com/v1/apps/app_01JD3W5Q7X9K2M4N6P8R0T1V3W/users/by/external_id/user_42/preferences" \
  -H "Authorization: Bearer $PUSHIZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "preferences": [
    {
      "category": "örnek",
      "opted_in": true,
      "channel": "ios_push"
    }
  ]
}'

On this page