Skip to content

Breaking API changes

Each entry below is one change that stops an existing call from working. Hadron renames these arguments with no alias: once a change is deployed, a call that uses the old name fails GraphQL argument validation, and an installed client that sends the old name keeps failing until it is upgraded. No compatibility period is promised, and no gap between the deployment of related components is promised either, except where an entry says two components deploy together.

Every entry carries one of two statuses, Planned: not deployed or Deployed. Planned: not deployed means the new names are the agreed design and are not yet accepted by the server you are using. Do not send the new names until the entry says they are deployed.

Entity references: id becomes ref (slice S4)

Status: Planned, not deployed. Source: hadron-server#4140, part of the entity-reference rename in hadron-server#775. No server commit is named here yet because the change is not final. This entry will name the exact server commit and the deployed version once a release exists.

A ref argument accepts the entity's ID or its URN. Four mutation fields change, and no other argument on them does:

Mutation Old argument New argument New type
updateMemory id ref ID!
updateMemory organizationId orgRef ID
updateOrganization id ref ID!
createAgent orgId orgRef ID
createAgent systemMemoryId systemMemoryRef ID
updateAgent systemMemoryId systemMemoryRef ID

Two changes are a type change as well as a rename: the optional systemMemoryRef arguments are typed ID where systemMemoryId was String. updateAgent already takes ref, so only its systemMemoryRef changes. Queries and every other argument on these four fields are unchanged. Payload fields such as Agent.systemMemoryId are results, not arguments, and do not change.

Before and after

Before (current servers):

mutation {
  updateMemory(id: "<memoryId>", vectorIndexEnabled: true, embeddingSource: abstract) {
    id
    vectorIndexEnabled
  }
}

After (planned, not yet accepted by any deployed server):

mutation {
  updateMemory(ref: "<memoryId>", vectorIndexEnabled: true, embeddingSource: abstract) {
    id
    vectorIndexEnabled
  }
}

Who is affected

  • Direct GraphQL callers, including integrations that use an App key: any call to the four fields above that names an old argument. Update the call at the same time the change is deployed; there is no alias to fall back on.
  • The portal and the CLI call these fields and are being changed to match, in hadron-portal#2122 and hadron-cli#2011. The portal is deployed together with the server. An installed CLI binary that sends the old names stops working against a server that has the change, until you upgrade the CLI. The CLI release follows the server deployment, so the CLI release notes name the version that carries the new names.
  • Examples in these docs switch to the new names when this change is deployed, in the same window as the server. If you read an example that shows ref: and your server rejects it, the server predates this change; use the old name from the table. See the GraphQL API for the schema each deployment serves.

What to do

  1. Find calls to updateMemory, updateOrganization, createAgent and updateAgent in your code or scripts.
  2. Rename the arguments as in the table, keeping the values.
  3. Send the new names only to a server whose entry here says Deployed.

Entity references: agentId/memoryId/orgId/appId become ref (slice S6)

Status: Planned, not deployed. Source: hadron-server#4142 (pull request #4219), the next slice of the entity-reference rename in hadron-server#775. No server release carries it yet; this entry will name the deployed version once one exists.

A ref argument accepts the entity's ID or its URN. These mutation arguments are renamed, and no other argument on each field changes:

Mutation Old argument New argument New type
startChat agentId agentRef ID!
joinApp appId appRef ID!
leaveApp appId appRef ID!
linkMemoryToUser memoryId memoryRef ID!
encryptMemory memoryId memoryRef ID!
createMemory orgId orgRef ID
deleteMemory id ref ID!
deleteOrganization id ref ID!
pushMemoryToGit id ref ID!
setMemorySourceToken id ref ID!
syncMemory id ref ID!
createUserInvitation orgId orgRef ID!
linkGithubApp orgId orgRef ID!
unlinkGithubApp orgId orgRef ID!
updateOrgGithubApp orgId orgRef ID!
acquireEditorLock agentId agentRef ID!
releaseEditorLock agentId agentRef ID!
updateAgentAIConfig agentId agentRef ID!
clearAgentAIConfig agentId agentRef ID!
createRevision agentId agentRef ID!
publishRevision agentId agentRef ID!
restoreRevision agentId agentRef ID!

startChat(userId:) is unchanged: it stays the user-PK compare-and-set it has always been. The queries usageEvents, usageEventsPage and memoryAssets are not part of this slice, and replaceSubtree(memoryId:) keeps its existing argument.

Deprecated Id aliases removed

These fields already accepted both spellings, with the Id form marked deprecated. Slice S6 removes the deprecated Id argument, leaving the Ref form — now required and now typed ID! where it was an optional String:

Mutation Argument removed Use instead
createMemorySubscription memoryId, orgId memoryRef, orgRef
updateMemorySubscription memoryId, orgId memoryRef, orgRef
deleteMemorySubscription memoryId, orgId memoryRef, orgRef
ensureAppMember appId, userId appRef, userRef
removeAppMember appId, userId appRef, userRef
revokeAgentSubscription userId, agentId userRef, agentRef
addOrgMember orgId, userId orgRef, userRef
updateOrgMember orgId, userId orgRef, userRef
removeOrgMember orgId, userId orgRef, userRef

Before and after

Before (current servers):

mutation StartChat($agentId: ID!, $userId: String!) {
  startChat(agentId: $agentId, userId: $userId) {
    chatId
  }
}

After (planned, not yet accepted by any deployed server):

mutation StartChat($agentRef: ID!, $userId: String!) {
  startChat(agentRef: $agentRef, userId: $userId) {
    chatId
  }
}

Who is affected

  • App-key integrators (startChat, joinApp, leaveApp, linkMemoryToUser): any call that names an old argument fails validation once the slice is live. The hadron-client README carries the same notice for SDK users.
  • Admin and user-key callers of the memory, organization and agent fields above: rename the arguments as in the table, keeping the values. A ref accepts the ID you already send, or the entity's URN.
  • The portal and the CLI are changed to match in hadron-portal#2122 and hadron-cli#2011. The portal deploys together with the server; an installed CLI binary that sends the old names stops working against a server that has the change, until you upgrade the CLI.

What to do

  1. Find calls to the fields above in your code or scripts.
  2. Rename the arguments as in the tables, keeping the values — an ID you already send keeps working under the new argument name.
  3. Send the new names only to a server whose entry here says Deployed.