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¶
- Find calls to
updateMemory,updateOrganization,createAgentandupdateAgentin your code or scripts. - Rename the arguments as in the table, keeping the values.
- 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
refaccepts 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¶
- Find calls to the fields above in your code or scripts.
- Rename the arguments as in the tables, keeping the values — an ID you already send keeps working under the new argument name.
- Send the new names only to a server whose entry here says Deployed.