Overview

The Push REST API allows you to send immediate and scheduled push notifications to your audience through the Taboola platform. This service enables editorial and marketing teams to deliver timely content notifications across devices, increasing engagement and driving traffic to your content.

The Push API supports two main types of notifications:

• Immediate Push - Real-time notifications for urgent or high-priority content (e.g., breaking news)
• Scheduled Push - Notifications scheduled for specific times (e.g., daily newsletters, event reminders)

Authentication

The API uses OAuth2 for authentication.

The concept is simple:

1. Obtain an access token from the Authorization Server.
2. Include the access token in the header of each API request.

🚧

Important

Your client_secret is confidential - keep it secret.

Authentication flow

1. Request an access token:

POST https://authentication.taboola.com/authentication/oauth/token
Content-Type: application/x-www-form-urlencoded

client_id={client_id}&client_secret={client_secret}&grant_type=client_credentials

{
  "access_token": "your_access_token_here",
  "token_type": "bearer",
  "expires_in": 3600
}

2. Include the access token in the Authorization header of each subsequent request:

Authorization: Bearer {access_token}

Check authorized applications

(Optional, but recommended if you are unsure which apps/tags you can send to)

Use this endpoint to verify which applications you're authorized to target with push notifications:

GET https://pushcms.taboola.com/epsilon/push/auth-apps
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "1234": "Publisher Name",
  "5678": "Another Publisher",
  "9012": "Third Publisher"
}

📘

Note

The response returns a map of application IDs (keys) to publisher names (values) that you are authorized to target with push notifications.

Field definitions

📘

Modifier Column

• Required - field must be included when creating a new notification
• Read-only - should never be sent to the server. Appears only when fetching a resource.
• Optional - field can be omitted

Push event fields

Target configuration

The target object specifies which applications should receive the notification:

{
  "target": {
    "include": {
      "apps": ["1234", "5678"]
    }
  }
}

📘

Application IDs

Application IDs refer to internal Taboola application identifiers. Use the auth-apps endpoint to see which applications you're authorized to send notifications to.

Task fields (read-only)

These fields appear when retrieving task information:

Endpoints and examples

Send immediate push notification

Send a push notification immediately to your target audience.

POST https://pushcms.taboola.com/epsilon/push
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "pushEvents": [
    {
      "title": "Breaking: Market Update",
      "thumbnailUrl": "https://example.com/news-thumbnail.jpg",
      "icon": "https://example.com/news-icon.png",
      "url": "https://example.com/breaking-news/market-update",
      "performer": "news_editor",
      "itemDescription": "Stock market reaches new highs today with major indices posting significant gains.",
      "target": {
        "include": {
          "apps": ["1234"]
        }
      }
    }
  ]
}

HTTP/1.1 200 OK
Content-Type: application/json

"Task passed validations. Dispatching..."

📘

Response Format

Success responses return a JSON primitive string (not a JSON object). The response body is a simple string value enclosed in quotes.

Send scheduled push notification

Schedule a push notification to be sent at a specific time.

POST https://pushcms.taboola.com/epsilon/push/scheduled
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "pushEvents": [
    {
      "title": "Daily Newsletter: Tech Updates",
      "thumbnailUrl": "https://example.com/newsletter-thumbnail.jpg",
      "icon": "https://example.com/newsletter-icon.png",
      "url": "https://example.com/newsletter/tech-updates-daily",
      "performer": "content_editor",
      "itemDescription": "Your daily dose of technology news and updates.",
      "executionTime": 1763618800000,
      "target": {
        "include": {
          "apps": ["1234"]
        }
      }
    }
  ]
}

HTTP/1.1 200 OK
Content-Type: application/json

"Task passed validations. Dispatching..."

📘

Execution Time

The executionTime field is required for scheduled push notifications and must be a Unix timestamp in milliseconds representing a future time. For immediate push notifications, omit this field or use a past/current timestamp.

Get all tasks

Retrieve all existing push notification tasks for a specific application. Returns all existing tasks under the specified tagId and an optional taskType filter.

GET https://pushcms.taboola.com/epsilon/task?tagId={app_id}&taskType={task_type}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "tagId": 33526,
  "taskId": 13359546,
  "taskType": "scheduled",
  "method": "mmp",
  "taskStatus": "active",
  "userTimeZone": 0,
  "title": "Daily Newsletter: Tech Updates",
  "taskUpdateTime": 1753621627600,
  "taskUpdateTimeFormatted": "2025-07-27T13:10:27.000Z",
  "executionTime": 1763618800000,
  "executionTimeFormatted": "2025-11-20T06:46:40.000Z",
  "url": "https://example.com/newsletter/tech-updates-daily",
  "thumbnailUrl": "https://images.taboola.com/image/fetch/f_jpg%2Cq_auto%2Cw_480%2Cc_fill%2Cg_faces%2Cauto%2Ce_sharpen/https%3A%2F%2Fexample.com%2Fnewsletter-thumbnail.jpg",
  "iconUrl": "https://images.taboola.com/image/fetch/f_jpg%2Cq_auto%2Cw_192%2Cc_fill%2Cg_faces%2Cauto%2Ce_sharpen/https%3A%2F%2Fexample.com%2Fnewsletter-icon.png",
  "videoId": null,
  "forcedItemPolicy": null,
  "performer": "content_editor"
}

Query params

Update scheduled task

Update a future scheduled push notification. Note that already sent notifications cannot be edited.

PATCH https://pushcms.taboola.com/epsilon/task/{taskId}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "title": "Updated Newsletter: Tech & Business Updates",
  "thumbnailUrl": "https://example.com/updated-thumbnail.jpg",
  "icon": "https://example.com/updated-icon.png",
  "userTimeZone": 0,
  "itemDescription": "Your updated daily dose of technology and business news.",
  "executionTime": 1763625600000,
  "performer": "senior_editor"
}

HTTP/1.1 200 OK
Content-Type: application/json

"Task updated successfully"

Delete scheduled task

Cancel a future scheduled push notification. Note that already sent notifications cannot be cancelled.

DELETE https://pushcms.taboola.com/epsilon/task/{taskId}
Authorization: Bearer {access_token}
Content-Type: application/json

HTTP/1.1 200 OK
Content-Type: application/json

"Task deleted successfully"

Error responses

400 Bad Request

Returned when validation fails or request data is malformed.

{
  "httpStatus": 400,
  "message": "title cannot be empty"
}

Common validation messages:

• "title cannot be empty" - Missing required title field
• "url cannot be empty" - Missing required URL field
• "performer cannot be empty" - Missing required performer field
• "thumbnailUrl must be a valid URL" - Invalid thumbnail URL format
• "iconUrl must be an HTTP/HTTPS URL" - Invalid icon URL format
• "title is too long (max 140)" - Title exceeds maximum length
• "Malformed JSON or type mismatch" - Invalid JSON in request body

401 Unauthorized

Returned when authentication fails or access token is invalid/expired.

{
  "httpStatus": 401,
  "message": "Invalid or expired access token"
}

403 Forbidden

Returned when authenticated but not authorized to access the requested resource.

{
  "httpStatus": 403,
  "message": "Not authorized to send notifications for specified application"
}

Guidelines and best practices

🚧

Important

For the latest, up-to-date guidelines, reach out to your Taboola Account Manager.

Image guidelines

• HTTPS: Image URLs should use HTTPS protocol.
• Thumbnail images: Recommended size 300x200 pixels or larger, automatically processed by Taboola's image service.
• Icon images: Recommended size 192x192 pixels (square format), automatically processed by Taboola's image service.
• File size: Optimize images for fast loading (< 200KB recommended).
• Recommended formats: JPEG, PNG, WebP.
• Image optimization: Images are automatically optimized through Taboola's CDN (images.taboola.com). Original URLs you submit will be transformed and served through this CDN with optimized parameters (e.g., w_480 for thumbnails, w_192 for icons).
• Ensure images are accessible and display correctly across different devices and screen sizes.

Content guidelines

• Title: Recommended length: 50-80 characters for optimal display across devices.
• Description: Recommended length: 100-150 characters.
• URLs: Ensure all URLs are valid, accessible, and lead to relevant mobile-friendly content.
• Content policy: All notifications must comply with Taboola's content policies.

Advanced options

Update the service worker path

Update the service worker registration path for your application. This is typically configured once during initial setup.

Use this endpoint when:

• Your service worker file is not at the default location
• You need to use a custom path due to existing service workers
• Your site is in a subdirectory
• You're migrating your service worker to a new location

Request fields:

📘

Service Worker Path

The service worker path must be relative to your domain root. For example, if your site is example.com and you specify /sw.js, the service worker must be accessible at https://example.com/sw.js.

Example request

PATCH https://pushcms.taboola.com/epsilon/container/sw-path
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "containerId": "1234",
  "serviceWorkerPath": "/custom/sw.js",
  "performer": "[email protected]"
}

HTTP/1.1 204 No Content

📘

Success Response

A 204 No Content response indicates the service worker path was updated successfully. This response has no body content.

Possible responses: