Retries and idempotency

A network timeout does not tell you whether the write landed. smry gives you three different ways to retry a write safely, and they work differently. Pick the one that matches the operation you are calling.

Mechanism	Applies to	Guarantee
Natural key	`POST /v1/library/items`	A retry with the same `url` or `externalId` updates the existing row instead of creating a second one.
Commit token	`POST /v1/feeds/mutate`	A retry replays the recorded outcome. A concurrent retry gets a `409`.
At-least-once delivery	Managed consumers	Batches redeliver until acknowledged. Your processing must be idempotent.

Everything else — PATCH, DELETE, and every read — is naturally idempotent. Retry those freely under the policy in Errors.

Saves: the natural key

POST /v1/library/items deduplicates on two fields. Send either and a retry is safe:

url — normalized, then matched against the account’s existing items.
externalId — your own identifier, matched exactly. Use this when the same logical document can arrive under different URLs.

The response tells you which happened:

Signal	Meaning
`201` + `"alreadySaved": false`	A new item was created.
`200` + `"alreadySaved": true`	An existing item was found and updated.

A save with neither url nor externalId has no natural key. Every retry creates another item. Always set externalId when you are saving supplied content rather than a URL.

Rule

Every POST /v1/library/items from a retryable pipeline MUST carry a stable externalId derived from your own source record. Do not generate it per attempt.

# Run this twice. The second run returns 200 with alreadySaved: true.
curl -sS -X POST "https://api.smry.ai/v1/library/items" \
  -H "Authorization: Bearer $SMRY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/posts/scaling-postgres",
    "externalId": "crm-doc-8812",
    "tags": ["databases"],
    "status": "inbox"
  }'

import os
import httpx

KEY = os.environ["SMRY_API_KEY"]
BASE = "https://api.smry.ai"

def save(client: httpx.Client, record: dict) -> dict:
    # externalId comes from YOUR record id, so it is identical on every attempt.
    response = client.post(
        BASE + "/v1/library/items",
        json={
            "url": record["url"],
            "externalId": f"crm-doc-{record['id']}",
            "tags": record.get("tags", []),
            "status": "inbox",
        },
    )
    response.raise_for_status()
    body = response.json()

    # 201 = created, 200 = the retry found the existing row. Both are success.
    if body["alreadySaved"]:
        print(f"already saved as {body['item']['id']}")
    return body["item"]

with httpx.Client(headers={"Authorization": f"Bearer {KEY}"}, timeout=60) as client:
    item = save(client, {"id": 8812, "url": "https://example.com/posts/scaling-postgres"})

const KEY = process.env.SMRY_API_KEY!;
const BASE = "https://api.smry.ai";

interface SaveResult {
  item: { id: string; title: string };
  alreadySaved: boolean;
  extraction?: { source: string; cacheHit: boolean };
}

export async function save(record: { id: number; url: string; tags?: string[] }) {
  const response = await fetch(`${BASE}/v1/library/items`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${KEY}`,
      "Content-Type": "application/json",
    },
    // externalId comes from YOUR record id, so it is identical on every attempt.
    body: JSON.stringify({
      url: record.url,
      externalId: `crm-doc-${record.id}`,
      tags: record.tags ?? [],
      status: "inbox",
    }),
  });
  if (!response.ok) throw new Error(`save failed: ${response.status}`);

  // 201 = created, 200 = the retry found the existing row. Both are success.
  const result = (await response.json()) as SaveResult;
  if (result.alreadySaved) console.log(`already saved as ${result.item.id}`);
  return result.item;
}

200 OK — the retry

{
  "item": {
    "id": "3f0b9c2e-5a71-4e2b-9d33-0c8ab1e4f6d2",
    "url": "https://example.com/posts/scaling-postgres",
    "title": "Scaling Postgres to a billion rows",
    "externalId": "crm-doc-8812",
    "status": "inbox",
    "tags": ["databases"],
    "savedAt": "2026-09-11T14:02:18.441Z"
  },
  "extraction": { "source": "smry-fast", "cacheHit": true, "qualityStatus": null },
  "alreadySaved": true
}

Mutations: the commit token

POST /v1/feeds/mutate is a two-phase write. Phase one previews. Phase two commits a token. The rules:

dry_run defaults to true. A call without it changes nothing and hands back a commit_token.
A commit_token executes exactly once. Replaying it returns the recorded outcome, never a second execution.
Tokens live 15 minutes. After that: invalid_request — “commit_token is unknown or expired (15 minute lifetime). Re-run the dry run.”
A token is bound to its op. Sending it with a different op is rejected.
A concurrent replay is a 409 commit_in_progress, and it is retryable. One caller wins the claim and executes; the others are told a commit is in flight.

If commit_in_progress never resolves into a recorded outcome, treat the commit as possibly partial. Query current state before running a fresh dry run. Do not assume nothing happened.

Rule

Retry a commit_token with the identical op. Never mint a new token to retry a commit that may already have run.

# 1. Dry run. Changes nothing, returns commit_token.
curl -sS -X POST "https://api.smry.ai/v1/feeds/mutate" \
  -H "Authorization: Bearer $SMRY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"op": "sources.move", "where": {"collection": ["Unsorted"]}, "set": {"collection": "Research"}}'

# 2. Commit. Retrying this exact call replays the recorded outcome.
curl -sS -X POST "https://api.smry.ai/v1/feeds/mutate" \
  -H "Authorization: Bearer $SMRY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"op": "sources.move", "commit_token": "8b1f6c4e-2a90-4c71-b2ad-19e0c4f77a55"}'

import os, time
import httpx

KEY = os.environ["SMRY_API_KEY"]
BASE = "https://api.smry.ai"

def mutate(client: httpx.Client, op: str, where: dict, changes: dict) -> dict:
    # Phase 1 — preview. dry_run defaults to true, so this changes nothing.
    preview = client.post(
        BASE + "/v1/feeds/mutate",
        json={"op": op, "where": where, "set": changes},
    )
    preview.raise_for_status()
    plan = preview.json()
    print(f"would affect {plan['would_affect']} rows")

    token = plan["commit_token"]

    # Phase 2 — commit. Retry the SAME token; never mint a second one.
    for attempt in range(3):
        response = client.post(
            BASE + "/v1/feeds/mutate",
            json={"op": op, "commit_token": token},
        )
        if response.is_success:
            result = response.json()
            if result["partial"]:
                print("partial: inspect outcomes before continuing")
            return result

        body = response.json()
        if body.get("code") == "commit_in_progress":
            time.sleep(2**attempt)   # Retryable. The same token is still correct.
            continue
        raise RuntimeError(f"{body['code']}: {body['error']}")

    # Three commit_in_progress in a row: the commit may be partial.
    raise RuntimeError("commit unresolved — query current state before retrying")

with httpx.Client(headers={"Authorization": f"Bearer {KEY}"}, timeout=60) as client:
    mutate(client, "sources.move", {"collection": ["Unsorted"]}, {"collection": "Research"})

const KEY = process.env.SMRY_API_KEY!;
const BASE = "https://api.smry.ai";

const post = (body: unknown) =>
  fetch(`${BASE}/v1/feeds/mutate`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });

export async function mutate(
  op: string,
  where: Record<string, unknown>,
  set: Record<string, unknown>,
) {
  // Phase 1 — preview. dry_run defaults to true, so this changes nothing.
  const preview = await post({ op, where, set });
  if (!preview.ok) throw new Error(`preview failed: ${preview.status}`);
  const plan = (await preview.json()) as {
    would_affect: number;
    commit_token: string;
  };
  console.log(`would affect ${plan.would_affect} rows`);

  // Phase 2 — commit. Retry the SAME token; never mint a second one.
  for (let attempt = 0; attempt < 3; attempt++) {
    const response = await post({ op, commit_token: plan.commit_token });
    if (response.ok) {
      const result = (await response.json()) as { partial: boolean };
      if (result.partial) console.warn("partial: inspect outcomes");
      return result;
    }

    const failure = (await response.json()) as { code: string; error: string };
    if (failure.code !== "commit_in_progress") {
      throw new Error(`${failure.code}: ${failure.error}`);
    }
    // Retryable. The same token is still the correct one to send.
    await new Promise((r) => setTimeout(r, 2 ** attempt * 1000));
  }

  // Three commit_in_progress in a row: the commit may be partial.
  throw new Error("commit unresolved — query current state before retrying");
}

200 OK — dry run

{
  "object": "feed_mutation_preview",
  "op": "sources.move",
  "would_affect": 12,
  "sample": ["NASA Breaking News", "ESA Newsroom"],
  "commit_token": "8b1f6c4e-2a90-4c71-b2ad-19e0c4f77a55",
  "expires_in_seconds": 900
}

sample is up to ten labels, not objects. There is no dry_run field in the response — the preview is what object: "feed_mutation_preview" tells you.

POST /v1/feeds/filters/apply uses a related but stricter protocol. Its previewToken is paired with an expectedRevision, and the apply fails with 409 revision_conflict if the Collection changed in between. That is optimistic concurrency, not idempotency: on a conflict you must preview again.

Consumers: at-least-once delivery

A managed consumer holds its checkpoint on the server, so a stateless scheduled job needs no local cursor file. The cost is that delivery is at-least-once.

A batch is redelivered until it is acknowledged. Crash after processing but before the ack and you will see the same events again. Your handler MUST be idempotent.

The loop is: poll, process everything, then acknowledge — in that order.

POST /v1/feeds/changes with consumer_id. Omit cursor and where — the consumer holds both.
Process every event in events.
POST /v1/feeds/consumers/{id}/ack with that response’s next_cursor.

Acknowledge an empty batch too. checkpoint.ack_required tells you when an ack is expected.

Rule

Make the handler idempotent, keyed on event.entry.id. Acknowledge only after every event in the batch is durably processed.

Creating a consumer is itself idempotent

Retrying POST /v1/feeds/consumers with the same name and the same where returns the existing consumer. Names are compared case-insensitively and the predicate is fingerprinted. The same name with a different predicate is a 409 consumer_name_taken. That is deliberate: silently rebinding a name to a new predicate would move a live checkpoint onto a stream it was never reading.

# Create — or, on a retry, get the existing one back.
curl -sS -X POST "https://api.smry.ai/v1/feeds/consumers" \
  -H "Authorization: Bearer $SMRY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Engineering briefing", "where": {"collection": ["Research"]}}'

# Poll. No cursor, no where — the consumer holds both.
curl -sS -X POST "https://api.smry.ai/v1/feeds/changes" \
  -H "Authorization: Bearer $SMRY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"consumer_id": 7, "limit": 50}'

# Acknowledge only after every event is durably processed.
# Substitute the consumer id for {id} in the path below.
curl -sS -X POST "https://api.smry.ai/v1/feeds/consumers/{id}/ack" \
  -H "Authorization: Bearer $SMRY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": 7, "cursor": "Zr7hXc2Nv9kQ4tLm1sPd60"}'

import os
import httpx

KEY = os.environ["SMRY_API_KEY"]
BASE = "https://api.smry.ai"
seen = set()   # In production this is a table, not a set.

def ensure_consumer(client: httpx.Client, name: str, where: dict) -> int:
    # Same name + same where returns the existing consumer, so this is safe to
    # call on every boot. A different where under the same name is a 409.
    response = client.post(
        BASE + "/v1/feeds/consumers", json={"name": name, "where": where}
    )
    response.raise_for_status()
    return response.json()["id"]

def drain(client: httpx.Client, consumer_id: int) -> int:
    # 1. Poll. The consumer holds the cursor and the predicate.
    response = client.post(
        BASE + "/v1/feeds/changes", json={"consumer_id": consumer_id, "limit": 100}
    )
    response.raise_for_status()
    batch = response.json()

    # 2. Process. Redelivery is normal, so dedupe on the entry id.
    # An event is {"type": ..., "entry": {...}}; the id lives on the entry.
    for event in batch["events"]:
        entry_id = event["entry"]["id"]
        if entry_id in seen:
            continue
        handle(event)
        seen.add(entry_id)

    # 3. Acknowledge — last, and even when the batch was empty.
    if batch["checkpoint"]["ack_required"]:
        path = "/v1/feeds/consumers/{id}/ack".replace("{id}", str(consumer_id))
        ack = client.post(
            BASE + path, json={"id": consumer_id, "cursor": batch["next_cursor"]}
        )
        ack.raise_for_status()

    return len(batch["events"])

with httpx.Client(headers={"Authorization": f"Bearer {KEY}"}, timeout=60) as client:
    cid = ensure_consumer(client, "Engineering briefing", {"collection": ["Research"]})
    while drain(client, cid):
        pass

const KEY = process.env.SMRY_API_KEY!;
const BASE = "https://api.smry.ai";

const post = (path: string, body: unknown) =>
  fetch(BASE + path, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });

// Same name + same where returns the existing consumer, so this is safe to call
// on every boot. A different where under the same name is a 409.
export async function ensureConsumer(name: string, where: Record<string, unknown>) {
  const response = await post("/v1/feeds/consumers", { name, where });
  if (!response.ok) throw new Error(`create failed: ${response.status}`);
  return ((await response.json()) as { id: number }).id;
}

export async function drain(
  consumerId: number,
  handle: (event: { type: string; entry: { id: number } }) => Promise<void>,
  seen: Set<number>, // In production this is a table, not a Set.
) {
  // 1. Poll. The consumer holds the cursor and the predicate.
  const response = await post("/v1/feeds/changes", {
    consumer_id: consumerId,
    limit: 100,
  });
  if (!response.ok) throw new Error(`poll failed: ${response.status}`);
  const batch = (await response.json()) as {
    events: Array<{ type: string; entry: { id: number } }>;
    next_cursor: string;
    checkpoint: { ack_required: boolean };
  };

  // 2. Process. Redelivery is normal, so dedupe on the entry id.
  // An event is { type, entry }; the id lives on the entry.
  for (const event of batch.events) {
    if (seen.has(event.entry.id)) continue;
    await handle(event);
    seen.add(event.entry.id);
  }

  // 3. Acknowledge — last, and even when the batch was empty.
  if (batch.checkpoint.ack_required) {
    const path = "/v1/feeds/consumers/{id}/ack".replace("{id}", String(consumerId));
    const ack = await post(path, {
      id: consumerId,
      cursor: batch.next_cursor,
    });
    if (!ack.ok) throw new Error(`ack failed: ${ack.status}`);
  }

  return batch.events.length;
}

200 OK — the consumer, created or returned

{
  "id": 7,
  "name": "Engineering briefing",
  "where": { "collection": [12] },
  "acknowledged_cursor": "Zr7hXc2Nv9kQ4tLm1sPd60",
  "created_at": "2026-09-11T09:14:02.117Z",
  "last_delivered_at": null,
  "last_acknowledged_at": null
}

smry canonicalizes the predicate before storing it: collection and source names are resolved to their ids. A consumer created with {"collection": ["Research"]} echoes {"collection": [12]}. Store what the response returned.

A new consumer starts at the current high-water mark, so it receives future discoveries rather than replaying history. To also process the backlog: create the consumer first, query the historical window separately with POST /v1/feeds/query, then start polling. That order closes the race.

Acknowledgements only move forward. A cursor behind the current checkpoint, from another consumer, or from a poll that was superseded is rejected — see invalid_request in Errors.

Cursors and paging

The four cursor dialects, and why a cursor must never be reused across a changed predicate.

Errors

commit_in_progress, consumer_name_taken, and every other code a retry can produce.

Get started

Work with the API

Patterns

Reference

Retries and idempotency

Saves: the natural key

Rule

Mutations: the commit token

Rule

Consumers: at-least-once delivery

Rule

Creating a consumer is itself idempotent

Next

Cursors and paging

Errors

​Saves: the natural key

​Rule

​Mutations: the commit token

​Rule

​Consumers: at-least-once delivery

​Rule

​Creating a consumer is itself idempotent

​Next

Cursors and paging

Errors

Saves: the natural key

Rule

Mutations: the commit token

Rule

Consumers: at-least-once delivery

Rule

Creating a consumer is itself idempotent

Next