Optional calls

Replace in Protocol

Use the replaceInProtocol mutation to perform a bulk find-and-replace across all agenda item texts in a protocol.

Pass a list of { term, replacement } pairs. Each pair is applied in list order — later pairs act on already-rewritten text, so the sequence matters.

The term must not be empty or whitespace — the API rejects such pairs entirely and writes no changes.
An empty replacement is valid and deletes all occurrences of the term.

GraphQL Mutation

fragment agendaItemDetails on MoveAgendaItemResultItemType {
  id
  title
  textsegments {
    id
    pos
    speakerObj { slug givenName familyName }
    textJson { text startTime endTime }
  }
}

mutation ReplaceInProtocol($protocolSlug: String!, $replacements: [ReplacementInput!]!) {
  replaceInProtocol(protocolSlug: $protocolSlug, replacements: $replacements) {
    success
    replacedCount
    agendaItemList {
      ...agendaItemDetails
    }
  }
}

Mutation Variables

{
  "protocolSlug": "my-protocol-slug",
  "replacements": [
    { "term": "Herr Müller", "replacement": "Bürgermeister Müller" },
    { "term": "KI", "replacement": "Künstliche Intelligenz" },
    { "term": "    ", "replacement": "" }
  ]
}

protocolSlug (String, required) — slug of the protocol to modify.
replacements (Array, required) — list of find-and-replace pairs.
- term (String, required) — the text to search for. Must not be empty or whitespace-only.
- replacement (String, required) — the text to substitute. Empty string is allowed (deletes the term).

Example JavaScript Implementation

import axios from "axios";

const REPLACE_IN_PROTOCOL = `
  mutation ReplaceInProtocol($protocolSlug: String!, $replacements: [ReplacementInput!]!) {
    replaceInProtocol(protocolSlug: $protocolSlug, replacements: $replacements) {
      success
      replacedCount
      agendaItemList {
        id
        title
      }
    }
  }
`;

export async function replaceInProtocol(protocolSlug, replacements) {
  // Guard: reject empty terms before the request
  for (const { term } of replacements) {
    if (!term || !term.trim()) {
      throw new Error("Replacement term must not be empty or whitespace.");
    }
  }

  const res = await axios.post(
    "https://api-v2.speechmind.com/external/v2/graphql",
    {
      query: REPLACE_IN_PROTOCOL,
      variables: { protocolSlug, replacements },
    },
    {
      headers: {
        "Content-Type": "application/json",
        "x-api-key": process.env.SPEECHMIND_API_KEY,
      },
    }
  );

  const { success, replacedCount } = res.data.data.replaceInProtocol;
  console.log(`Replaced in ${replacedCount} text block(s).`);
  return { success, replacedCount };
}

// Example usage
replaceInProtocol("my-protocol-slug", [
  { term: "Herr Müller", replacement: "Bürgermeister Müller" },
  { term: "KI", replacement: "Künstliche Intelligenz" },
]);

Notes

Replacements are applied in list order — if pair A produces text that matches pair B’s term, pair B will also replace it. Order your pairs carefully.
replacedCount is the total number of individual replacements made across all pairs and all text fields.
The mutation uses bulk database updates to minimise round-trips — all pairs for a protocol are applied in a single operation.
After a successful replace, call getResults or getResultsWithEmpty to retrieve the updated text.

Have questions?

Still have questions? Talk to support.