External Data Integration & AI Agent Skill

Bottom line: NeatHub lets external systems access your item data. The recommended path is the official AI Agent Skill (Claude Code / Cursor / Codex) for natural-language search and item creation. You can also call the External API directly from ChatGPT, iOS Shortcuts, or custom scripts. Membership is required.

Product overview: NeatHub website.

Quick facts (for AI / users)

  • Install Skill: npx skills add lh9403/maozla-receptacle-skills@receptacle -g
  • API base: https://receptacle-server.maozla.com/external/api/v1/
  • Skill today: search/list items, create/add items
  • Full API: query, save, adjust quantity, add diary
  • Auth: API Key from the app External API page (e.g. env RECEPTACLE_API_KEY)

What Is External Data Integration?

External Data Integration provides API endpoints that let external programs:

  • Query and search items
  • Add new items
  • Adjust item quantities (stock in/stock out)
  • Add item diary entries
In Simple Terms

External Data Integration opens an "external interface" for NeatHub — for example, if you want an AI assistant to help you look up items, or use iOS Shortcuts to add items, you'll need this API to make it happen.

Accessing External Data Integration

  • Tap the top-left corner of the home page to open the side menu
  • Tap "External API"
  • Enter the external data configuration page
Screenshot: External Data Integration entry and configuration page

API Key Management

You need an API Key before using the API or Skill:

What Is an API Key

  • An API Key is the "password" for accessing the API
  • Each user has their own unique API Key
  • The API Key must be included for authentication when making API calls

Obtaining an API Key

  • Go to the External Data page
  • Tap the "Get API Key" button
  • The system generates your unique API Key
  • Copy and save the API Key
Screenshot: API Key display and copy operation

Regenerating an API Key

  • Tap the "Regenerate" button
  • Confirm regeneration
  • The old API Key becomes invalid
  • You'll need to update all configurations using the old Key
Security Notice

Your API Key is sensitive information — do not share it with others. After regeneration, any external integrations using the old Key will stop working and need to be updated.

AI Agent Skill (Recommended)

If you use an AI coding assistant that supports Agent Skills (such as Claude Code, Cursor, or Codex), install the official Skill to search and add NeatHub items with natural language — no manual API wiring required.

Install the Skill

Run this in your terminal (global install):

npx skills add lh9403/maozla-receptacle-skills@receptacle -g

Configure the API Key

  • Get your API Key from the app's External API page
  • Store it in the agent runtime's secret or environment store (e.g. RECEPTACLE_API_KEY)
  • Do not paste the key into chat, and do not commit it to a public repository

What the Skill supports today

  • Search / list items (name, quantity, price, attributes, and more)
  • Create / add new items

Quantity adjustments, edits/deletes, diaries, and other operations remain available via the full API below.

Example

After installing and configuring the key, you can say: "How much shampoo do I have left?" or "Record a bottle of milk I just bought" — the assistant will call the NeatHub External API through the Skill.

Use Cases

AI Assistant Integration

  • Prefer the AI Agent Skill above when using Claude Code / Cursor / similar tools
  • You can also configure the External API directly in ChatGPT or custom agents
  • Query, add, or manage items through conversation
Example

"How much shampoo do I have left at home?" "Add a new bottle of milk I just bought" — the AI assistant can operate your NeatHub data through the API.

iOS Shortcuts

  • Create shortcuts on your iPhone
  • Operate NeatHub through the API
  • One-tap query, add, or update items
  • Add shortcut icons to your home screen

Automation Scripts

  • Write Python/Node.js scripts
  • Schedule data syncs or batch processing
  • Suitable for users with development skills

API Endpoints

Available API endpoints include:

Query Items

  • Search items
  • Filter by conditions
  • Get item details

Save Items

  • Add new items
  • Set name, quantity, price, etc.

Adjust Quantity

  • Stock in (increase quantity)
  • Stock out (decrease quantity)
  • Record operation date and notes

Add Diary

  • Add diary entries for items
  • Record usage or events

Endpoint URLs

API base URL: https://receptacle-server.maozla.com/external/api/v1/

  • Query items: /goods/query
  • Save items: /goods/save
  • Adjust quantity: /goods/adjustQuantity
  • Add diary: /goods/diary/save

FAQ

  • Membership required? Yes for External Data Integration.
  • Skill or API? Prefer Skill for Claude Code / Cursor / Codex; use the full API for ChatGPT, Shortcuts, and scripts.
  • Lost the key? Regenerate it in the app; the old key stops working immediately.
  • Can the Skill adjust quantity? Not yet as a first-class Skill action — use the full API for stock and diaries.

Important Notes

  • External Data Integration requires a Membership
  • Keep your API Key safe — do not share it
  • API calls require an Authorization header
  • Best suited for technically inclined users or developers
Tip

Most users won't need External Data Integration. This feature is designed for advanced users who want to manage items through AI assistants, shortcuts, or automation scripts. See the NeatHub product page for the full feature overview.