addMemoryEntries

Add conversation records from another system to your memory, idempotent on externalId. Your people's words (FROM_ACCOUNT) are learned from; the other side's are context. Hidden records, typed notes and calendar emails are refused.

curl https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer $GOLIATH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "operationId": "addMemoryEntries",
    "variables": {
      "entries": [
        {
          "externalId": "<String>",
          "occurredAt": "2026-01-01T00:00:00.000Z",
          "kind": "MESSAGE",
          "text": "<String>",
          "sourceLabel": "<String>"
        }
      ]
    }
  }'

import { GoliathClient } from '@goliath-data/sdk'

const goliath = new GoliathClient({
  apiKey: process.env.GOLIATH_API_KEY!,
  baseUrl: 'https://server.goliathdata.com',
})

// Enum values as strings: the SDK's enum types aren't exported yet, so assert to the method's variables type.
const variables = {
  entries: [
    {
      externalId: '<String>',
      occurredAt: '2026-01-01T00:00:00.000Z',
      kind: 'MESSAGE',
      text: '<String>',
      sourceLabel: '<String>'
    }
  ]
} as Parameters<typeof goliath.memory.addMemoryEntries>[0]

const result = await goliath.memory.addMemoryEntries(variables, { idempotencyKey: crypto.randomUUID() })

const res = await fetch('https://server.goliathdata.com/api/v1/call', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.GOLIATH_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    operationId: 'addMemoryEntries',
    variables: {
      entries: [
        {
          externalId: '<String>',
          occurredAt: '2026-01-01T00:00:00.000Z',
          kind: 'MESSAGE',
          text: '<String>',
          sourceLabel: '<String>'
        }
      ]
    }
  }),
})
const { data, errors } = await res.json()

Variables

The example sends only what the schema requires. Some operations also need one of several optional variables (one filter or another, say); the description above says which.

entries[MemoryEntryInput!]!required

externalIdString!required

Your id for the record (at most 256 characters); sending it again adds nothing.

occurredAtDateTime!required

When it was said; in the past.

kindMemoryEntryKind!required

CALL_SUMMARY: A recap of a minute or longer is a conversation, so it counts as the organization's words whoever wrote the recap or placed the call. MEETING_SUMMARY: Holds both sides of a meeting, so it counts as the organization's words whoever wrote the recap. NOTE: Only the source's own system's; a person's typed note is refused.

MESSAGEEMAILCALL_SUMMARYMEETING_SUMMARYNOTE

directionMemoryEntryDirection

Required for MESSAGE, EMAIL and CALL_SUMMARY; ignored otherwise.

FROM_ACCOUNTTO_ACCOUNT

authorMemoryEntryAuthorInput

subjectString

textString!required

At most 50,000 characters.

durationSecondsInt

sourceLabelString!required

The source's name, e.g. Zendesk (at most 80 characters).

hiddenBoolean

The source hid it: refused.

Every field, all the way down

variables

[
  {
    "name": "entries",
    "type": "[MemoryEntryInput!]!",
    "required": true,
    "description": null,
    "defaultValue": null,
    "fields": [
      {
        "name": "externalId",
        "type": "String!",
        "required": true,
        "description": "Your id for the record (at most 256 characters); sending it again adds nothing.",
        "defaultValue": null
      },
      {
        "name": "occurredAt",
        "type": "DateTime!",
        "required": true,
        "description": "When it was said; in the past.",
        "defaultValue": null
      },
      {
        "name": "kind",
        "type": "MemoryEntryKind!",
        "required": true,
        "description": "CALL_SUMMARY: A recap of a minute or longer is a conversation, so it counts as the organization's words whoever wrote the recap or placed the call. MEETING_SUMMARY: Holds both sides of a meeting, so it counts as the organization's words whoever wrote the recap. NOTE: Only the source's own system's; a person's typed note is refused.",
        "defaultValue": null,
        "enumValues": [
          "MESSAGE",
          "EMAIL",
          "CALL_SUMMARY",
          "MEETING_SUMMARY",
          "NOTE"
        ]
      },
      {
        "name": "direction",
        "type": "MemoryEntryDirection",
        "required": false,
        "description": "Required for MESSAGE, EMAIL and CALL_SUMMARY; ignored otherwise.",
        "defaultValue": null,
        "enumValues": [
          "FROM_ACCOUNT",
          "TO_ACCOUNT"
        ]
      },
      {
        "name": "author",
        "type": "MemoryEntryAuthorInput",
        "required": false,
        "description": null,
        "defaultValue": null,
        "fields": [
          {
            "name": "name",
            "type": "String",
            "required": false,
            "description": null,
            "defaultValue": null
          },
          {
            "name": "kind",
            "type": "MemoryEntryAuthorKind",
            "required": false,
            "description": "Default PERSON. AUTOMATION: The source's own system (a drip text, an automated note): a MESSAGE, EMAIL or NOTE it wrote is context, never your people's words. A summary is judged by the conversation it records instead.",
            "defaultValue": null,
            "enumValues": [
              "PERSON",
              "AUTOMATION"
            ]
          },
          {
            "name": "userId",
            "type": "ID",
            "required": false,
            "description": "The member who said it, if one did.",
            "defaultValue": null
          }
        ]
      },
      {
        "name": "subject",
        "type": "String",
        "required": false,
        "description": null,
        "defaultValue": null
      },
      {
        "name": "text",
        "type": "String!",
        "required": true,
        "description": "At most 50,000 characters.",
        "defaultValue": null
      },
      {
        "name": "durationSeconds",
        "type": "Int",
        "required": false,
        "description": null,
        "defaultValue": null
      },
      {
        "name": "sourceLabel",
        "type": "String!",
        "required": true,
        "description": "The source's name, e.g. Zendesk (at most 80 characters).",
        "defaultValue": null
      },
      {
        "name": "hidden",
        "type": "Boolean",
        "required": false,
        "description": "The source hid it: refused.",
        "defaultValue": null
      }
    ]
  }
]

Response

What comes back under data: a list shows as one entry, and a value as its type.

response shape

{
  "data": {
    "memoryEntryMutation": {
      "addEntries": {
        "organizationId": "<ID>",
        "added": 0,
        "alreadyAdded": 0,
        "excluded": [
          {
            "externalId": "…",
            "reason": "HIDDEN"
          }
        ]
      }
    }
  }
}

Errors

400unknown_variable

A variable the operation does not declare. A typo is refused rather than silently dropped.

401unauthorized

No bearer header, or the key is invalid or revoked.

403insufficient_scope

The key lacks the scope the operation requires.

403forbidden

A referenced record does not exist, was deleted, or is outside your organization. The gateway cannot tell those apart.

409idempotency_conflict

A request with this Idempotency-Key is still in flight.

Idempotency

Send an Idempotency-Key of 1 to 255 characters. A finished request retried with the same key replays its stored response, marked Idempotency-Replayed: true; one still in flight returns 409 idempotency_conflict. Keys expire after 24 hours. Write without fear →

Variables

Response

Errors

Idempotency

Related