Skip to main content
POST /api/v2/storefront/inventory-sources/{sourceId}/agent-binding connects a Sales Agent your organization owns to an Inventory Source your organization owns — the first-party counterpart to the SuperAdmin-only reconciliation path. It requires the same directly authenticated organization account admin session as Create an Agent. Binding is first-party only, and direct only. The Agent must belong directly to your organization — the same organization your caller is authenticated as, not a parent or sibling organization. The endpoint always resolves the Agent’s actual owning organization itself; it never accepts an owner id from the caller, and it rejects the request before writing anything if the Agent belongs to any other organization, including one that shares a parent with yours. Hierarchy-wide (shared-parent) first-party binding is a real platform pattern elsewhere, but this endpoint intentionally does not support it yet — that is deferred to the org entity-model work (AI-6543 family). Cross-organization (Partner) connections are set up by Scope3 for now — see Agents for the Agent/Source ownership model. If the Agent’s operator was mapped by Scope3 but never explicitly claimed, binding your own Source to it also claims the operator for your organization in the same request — you do not need a separate claim step first. An operator that belongs to a different organization is never claimable this way. Only AGENT-execution Inventory Sources can carry a customer Agent binding. ESA and other platform-managed sources are not eligible and return a typed validation error.

​
Request

​
Parameters

The binding is already naturally idempotent on (agentId, sourceId) — repeating the exact same request returns the same connection rather than creating a second one, so no separate idempotency key is needed or accepted.

​
Response

Returns the same shape the Powered-by Agent projection would then produce:

​
Errors

  • 400 VALIDATION_ERROR — the request is malformed; the Source is not an AGENT-execution Source; or, for an Agent your organization does own, it is not a SALES Agent, or its operator has not been claimed and is not an eligible Scope3-mapped record.
  • 403 ACCESS_DENIED — the caller is not a directly authenticated organization account admin, or the Agent does not belong directly to the caller’s organization (first-party check) — including a parent or sibling organization’s Agent. Ownership is checked before type or claim status, so an Agent that belongs to another organization always returns this — never the 400 reasons above, which would otherwise leak facts about an Agent you don’t own.
  • 404 NOT_FOUND — the Source or the Agent does not exist, is archived, or is not visible to the caller.
  • 409 CONFLICT — the Source is already actively bound to a different Agent.
This operation is idempotent: if you receive a server error after a bind attempt, retry the same request. If the binding already committed on the first attempt, the retry returns the committed binding as the ACTIVE state, not a conflict — a conflict is only ever returned for a different Agent already bound to the Source. See Errors for the full error contract.

Agent tasks

All agent operations

Create an Agent

Register a private Agent first

Agents concepts

The Agent/Source ownership model