> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interchange.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Bind your Agent to a Source

> Connect an Agent your organization owns to your own inventory Source

`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](/v2/storefront/agents/tasks/create-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](/v2/concepts/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.

```http theme={null}
POST https://api.interchange.io/api/v2/storefront/inventory-sources/{sourceId}/agent-binding

{
  "agentId": "20000000-0000-4000-8000-000000000001"
}
```

## Request

```bash theme={null}
curl -X POST "https://api.interchange.io/api/v2/storefront/inventory-sources/src_optimera_wholesale/agent-binding" \
  -H "Authorization: Bearer $INTERACTIVE_USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "20000000-0000-4000-8000-000000000001"
  }'
```

## Parameters

| Field      | Type   | Required | Notes                                                                                                                  |
| ---------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `sourceId` | string | Yes      | Inventory Source identifier (path parameter).                                                                          |
| `agentId`  | UUID   | Yes      | The Agent to bind. Must be a `SALES` Agent owned directly by your organization — not a parent or sibling organization. |

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](/v2/concepts/agents#see-which-agent-powers-a-source)
projection would then produce:

```json theme={null}
{
  "state": "ACTIVE",
  "agent": {
    "agentId": "20000000-0000-4000-8000-000000000001",
    "displayName": "Acme Sales Agent",
    "role": "SALES"
  }
}
```

## 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](/v2/reference/errors) for the full error contract.

## Related

<CardGroup cols={2}>
  <Card title="Agent tasks" href="/v2/storefront/agents/tasks" icon="list-check">
    All agent operations
  </Card>

  <Card title="Create an Agent" href="/v2/storefront/agents/tasks/create-agent" icon="plus">
    Register a private Agent first
  </Card>

  <Card title="Agents concepts" href="/v2/concepts/agents" icon="robot">
    The Agent/Source ownership model
  </Card>
</CardGroup>