KnowledgeSyncBody

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/elocuenti-com/json-schema/elocuenti-com-knowledge-sync-body-schema.json",
  "title": "KnowledgeSyncBody",
  "description": "The entries to bring in sync with your system. What is not in the batch is left alone, unless you ask for `prune`.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/elocuenti-com-knowledge-api-openapi.yml#/components/schemas/KnowledgeSyncBody",
  "type": "object",
  "properties": {
    "entries": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "$ref": "#/$defs/KnowledgeEntrySyncItem"
      },
      "description": "The entries to save, from 1 to 100, in a request of at most 1 MiB (`413` past it: with large entries fewer fit, so send the rest in another request). Two entries with the same `external_id` are refused. If one is invalid, nothing is saved and `details` names it (`entries.2.title`).",
      "title": "Entries"
    },
    "prune": {
      "$ref": "#/$defs/KnowledgeSyncPrune"
    }
  },
  "required": [
    "entries"
  ],
  "additionalProperties": false,
  "$defs": {
    "KnowledgeEntrySyncItem": {
      "type": "object",
      "properties": {
        "external_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200,
          "pattern": "^[\\x21-\\x7e]+$",
          "description": "The identifier the entry has in your own system (a post of your CMS, an article of your help center): from 1 to 200 printable characters, with no spaces. It is unique in your business: one identifier is one entry.",
          "title": "External Id"
        },
        "title": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200,
          "description": "The title of the entry, from 1 to 200 characters. The AI reads it as the heading of the entry.",
          "title": "Title"
        },
        "content": {
          "type": "string",
          "minLength": 10,
          "maxLength": 20000,
          "description": "What the AI can say about the topic, in plain text: from 10 to 20000 characters. Write it the way you would explain it to a customer.",
          "title": "Content"
        },
        "category": {
          "anyOf": [
            {
              "type": "string",
              "minLength": 1,
              "maxLength": 100
            },
            {
              "type": "null"
            }
          ],
          "description": "A label to group entries in the dashboard (up to 100 characters). Send `null` to remove it. If you leave it out, the current one stays.",
          "title": "Category"
        },
        "type": {
          "type": "string",
          "enum": [
            "general",
            "faq"
          ],
          "description": "`faq` for a question with its answer, `general` for any other piece of information. If you leave it out, a new entry is `general` and an existing one keeps its type.",
          "title": "Type"
        },
        "status": {
          "type": "string",
          "enum": [
            "published",
            "archived"
          ],
          "description": "`published`: the AI uses the entry. `archived`: it stays in your business, unused, and can be published again. Left out, a new entry is `published` and an existing one keeps its status, except one that a `prune` archived and nobody has changed in the dashboard, published or archived by hand since: sending it brings it back to `published`. Archiving an existing entry (or keeping archived one that a `prune` archived) needs the `knowledge:delete` permission too.",
          "title": "Status"
        }
      },
      "required": [
        "external_id",
        "title",
        "content"
      ],
      "additionalProperties": false,
      "description": "One entry of the batch. It is matched to your business's entry that has the same `external_id`: that one is updated, or a new one is created if there is none.",
      "title": "KnowledgeEntrySyncItem"
    },
    "KnowledgeSyncPrune": {
      "type": "object",
      "properties": {
        "external_id_prefix": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100,
          "pattern": "^[\\x21-\\x7e]+$",
          "description": "Only the entries whose `external_id` starts with this text can be archived (from 1 to 100 characters). Use one prefix per source (for example `wp:`), so a sync of one source never touches the entries of another.",
          "title": "External Id Prefix"
        },
        "confirm": {
          "type": "string",
          "const": "archive_missing",
          "description": "Must be exactly `archive_missing`: it confirms that you want the entries missing from this batch to stop being used by the AI.",
          "title": "Confirm"
        },
        "max_archive": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100,
          "description": "The most entries you expect this request to archive (from 0 to 100). If more would be archived, nothing at all is saved and the answer is `409`: it protects you from archiving the entries of the other pages of a larger source, or from an incomplete export.",
          "title": "Max Archive"
        }
      },
      "required": [
        "external_id_prefix",
        "confirm",
        "max_archive"
      ],
      "additionalProperties": false,
      "description": "Asks to archive the published entries that come from your system (they have an `external_id` that starts with the prefix) and are not in this batch; a draft is never archived by it. Nothing is archived without it, and it needs the `knowledge:delete` permission.",
      "title": "KnowledgeSyncPrune"
    }
  }
}