TLtlmtr
Catalog

Create catalog snapshot diff.

Changed on

Apply the snapshot's saved filters to the current catalog and store channels added or removed relative to the original snapshot, not the previous diff. The original snapshot is not updated. Returns counts; use List diff changes with change_type=added or removed to retrieve channel IDs. Removed means no longer matching the saved result, not necessarily deleted from Telegram.

The saved baseline and current matching set must both fit the maximum from your current API plan or Subscription key settings. Larger sets return 422 without truncation. Each diff expires 30 days after its creation. Your active diff cap applies across all snapshots and is returned as active_limit by List diffs. Reaching it returns 429 DIFF_LIMIT_REACHED. Only one diff creation per user can run at a time; concurrent requests return 429 DIFF_CREATION_IN_PROGRESS. Snapshot mutation conflicts also return 429. Retry temporary conflicts after Retry-After. The source snapshot must be active. Catalog and snapshot access must both be enabled. Credits keys: 0.400 credits per successful creation, including a diff with no changes. No additional base or per-channel fee; 30-day storage is included. Each POST creates and bills a new diff. After a timeout, inspect existing diffs before retrying: creation requests are not deduplicated.

post/v1/catalog/snapshots/{snapshot_id}/diffs

Request

Path parameters

snapshot_idstring required

Unique snapshot identifier. Pass the value returned when creating or listing snapshots unchanged.

Response

diff_idstring required

Unique diff identifier. Pass it unchanged to diff endpoints.

snapshot_idstring required

Unique identifier of the original snapshot. Pass it unchanged to snapshot endpoints.

added_countinteger required

Channels matching at diff creation that were absent from the original snapshot.

removed_countinteger required

Channels in the original snapshot that no longer matched at diff creation. This does not necessarily mean deletion from Telegram.

created_atstring required

Creation timestamp in UTC, formatted as RFC 3339.

expires_atstring required

Expiration timestamp in UTC, formatted as RFC 3339. Resources expire 30 days after their own creation.

Example response

{
  "diff_id": "01900000-0000-7000-8000-000000000002",
  "snapshot_id": "01900000-0000-7000-8000-000000000001",
  "added_count": 25,
  "removed_count": 10,
  "created_at": "2026-09-08T12:00:00Z",
  "expires_at": "2026-10-08T12:00:00Z"
}

Changes

  • 6c2bfd66c5f2Revision changes
    • breaking

      the response's body type changed from object to no type for status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • info

      added subschema #2 to the response body allOf list for the response status

  • 80951ad7b3fbRevision changes
    • info

      endpoint added