Receptacle Inventory

Use the Receptacle External API only for the authenticated user's own inventory.

Setup

Read these settings from the agent runtime's secret or environment-variable store. Do not ask users to paste an API key into chat and never include it in a response, log, or generated file.

RECEPTACLE_BASE_URL=https://receptacle-server.maozla.com
RECEPTACLE_API_KEY=<personal Receptacle API key>

The user obtains the key in the Receptacle app from External API. The API is available to members. A key that is already created cannot be displayed again; the user must regenerate it to obtain a new value. Regeneration invalidates every existing agent integration using the old key.

For every API call, send:

Authorization: Bearer $RECEPTACLE_API_KEY
Content-Type: application/json

Use $RECEPTACLE_BASE_URL when configured; otherwise use https://receptacle-server.maozla.com.

Search Goods

Use this for questions about what the user owns, stock checks, and item lookups. Searching is read-only and does not need confirmation.

POST /external/api/v1/goods/query

Request body:

{
  "search": "optional keyword",
  "page": 1,
  "pageSize": 20,
  "includeImages": false,
  "includeAttributes": false
}

Rules:

• Use the user's keywords as search; omit it when they request a general list.
• Default to page: 1 and pageSize: 20.
• Keep image and attribute fields disabled unless the user asks for them.
• State clearly when no matching item is found. Do not infer that an item is absent when the request failed.
• Summarize returned items with name, quantity, and price when present. Avoid exposing unnecessary raw records.

Create Goods

Use this only when the user asks to add or record a new physical item in Receptacle.

POST /external/api/v1/goods/save

Request body:

{
  "name": "required item name",
  "remark": "optional note",
  "number": 1,
  "price": 0,
  "images": [],
  "attributes": {},
  "currencyId": 1,
  "minNumber": -1,
  "pId": 0
}

Rules:

• name is required. Ask a focused follow-up when it is missing or ambiguous.
• Default number to 1 and price to 0 only when the user did not provide them.
• Do not invent an image URL, attribute, currency ID, parent ID, or low-stock threshold.
• Before sending the request, show a compact summary of the item and ask for confirmation. Execute only after the user confirms in a subsequent message.
• After success, report the created item name and returned identifier if available.
• If the service reports an authentication, membership, quota, or validation error, state the actionable cause without revealing credentials or internal error details.

Boundaries

This version does not adjust quantities, delete goods, edit existing goods, access inventories/locations, or create diary entries. Explain that the integration currently supports only searching and creating goods when users request other operations.

Never use the user's login token with this API. The API key is sufficient and is bound to the owner's Receptacle account by the server.