Push API vs. Stream API

This is for:

Developer System Administrator

item indexing is a critical part of any Coveo implementation. Choosing the method that fits your needs is essential for workflow efficiency and performance. One way to send items to Coveo for indexing is by using APIs that push content into your sources. There are two APIs that you can use for this purpose: the Push API and the Stream API.

While both APIs are used to ingest content, they’re designed for different types of data and workflows. This article provides a conceptual overview to help you understand their differences and determine which one is best for your use case.

Tip
Quick decision

API overviews

Push API

The Push API handles both item ingestion and security management, making it ideal when you need flexibility across content types and permission models.

The Push API supports:

Stream API

The Stream API is designed for e-commerce use cases, allowing efficient full and partial updates of product catalogs, variants, and availability channels.

The Stream API supports:

  • Full catalog updates using update and load operations

  • Partial item updates for specific fields only

  • Shallow merge operations

  • Commerce-optimized workflows

Key differences

This table summarizes the key differences between the Push API and Stream API.

Feature Push API Stream API

Source type

Push sources

Catalog sources

Update types

Security identities

Item-level permissions

When to use the Push API

Use the Push API when:

  • You need to index general content such as web pages or other non-commerce items.

  • Your content requires complex permission models with user and group relationships.

  • You’re working with Push sources across different content types.

  • You need to manage security identities and their relationships.

When to use the Stream API

Use the Stream API when:

  • You’re working with catalog data in Catalog sources.

  • You need to perform partial updates (for example, inventory or pricing) without re-indexing entire items.

  • You’re processing high volumes of product updates.

  • You want to use commerce-specific operations such as shallow merge.

FAQ about the APIs

This section answers common questions about using the Push API and Stream API:

Can both APIs be used in the same organization?

Yes, both APIs can be used within the same organization. Use the Push API for general content sources and the Stream API for Catalog sources.

Each API operates on different source types, so there’s no conflict between using both.

Can I migrate commerce data from a Push source to a Catalog source?

Yes. If you currently index commerce data in a Push source using the Push API, you can migrate to a Catalog source using the Stream API.

This migration is beneficial because Catalog sources offer commerce-specific features such as partial updates, shallow merge operations, and optimized performance for high-volume product catalog updates.

To migrate, you need:

Which API is faster?

Performance depends on your use case:

  • For full item updates, both APIs have similar performance when using batch operations.

  • For partial field updates, the Stream API is significantly faster because it updates only specific fields rather than re-indexing entire items.

  • For high-volume commerce updates, the Stream API’s specialized operations provide better throughput.

Can the Stream API be used with non-Catalog sources?

The Stream API works with Catalog sources and other commerce-enabled source types such as Database, REST API, or GraphQL API sources that are configured for catalog data.

To use the Stream API with non-Catalog sources, the source must be commerce-enabled and linked to a Commerce add-on.

However, to index general non-commerce content, use the Push API with a Push source instead.

What’s next

Learn more about the Push API and Stream API.