canonical: https://jentic.com/apis/grocy.info/grocy # Grocy REST API Jentic publishes the only available OpenAPI specification for Grocy REST API, keeping it validated and agent-ready. Grocy is a self-hosted ERP for the home - groceries, chores, recipes, batteries, and household tasks. The REST API exposes the underlying object store via `/objects/{entity}`, plus dedicated endpoints for users, user permissions, user fields, files, system metadata, and the household features the UI is built around. Authentication is a GROCY-API-KEY header issued from the Grocy admin panel. ## For AI agents Read and update household inventory, chores, tasks, and recipes on a self-hosted Grocy instance through one object-oriented REST API. ## Scope Does not handle online grocery purchasing, payment, or smart-device control - use for managing data on a self-hosted Grocy household ERP only. ## Capabilities - List and create records on any Grocy entity via `/objects/{entity}` - Read, update, and delete a specific Grocy object by ID - Manage Grocy users and per-user permissions through /users and `/users/{userId}/permissions` - Read and write user fields attached to objects with `/userfields/{entity}/{objectId}` - Upload, download, and delete files on Grocy file groups via `/files/{group}/{fileName}` - Inspect system info, configuration, and the last DB-changed time - Read the current authenticated user with GET /user and update user settings ## Use cases ### Voice-Driven Household Inventory An agent records groceries as the user speaks. It calls POST `/objects/{entity}` with entity=products to add items and POST `/objects/{entity}` with entity=stock to log a purchase. Grocy's single object endpoint design means one search-and-execute pattern covers every household resource the user owns. Example prompt: On each spoken item, call POST `/objects/products` if the product is new, then POST `/objects/stock` with the matching product_id and quantity to log the purchase. ### Chore and Task Automation Schedule and complete household chores automatically. The agent lists chores with GET `/objects/{entity}` for entity=chores, marks completion through related stock or chore-tracking objects, and logs activity with PUT `/objects/{entity}/{objectId}.` Useful for shared homes where chore status is tracked centrally. Example prompt: List chores via GET `/objects/chores`, find ones due today, and update their next-execution timestamp via PUT `/objects/chores/{objectId}.` ### Recipe and Meal Planning Pull recipes and generate a shopping list against current stock. Recipes, meal plans, and shopping lists are all object types in Grocy reachable via `/objects/{entity}.` Combine recipe data with current stock to compute the missing items and write them back to a shopping list entity. Example prompt: Fetch GET `/objects/recipes` and GET `/objects/stock`, compute the delta, and POST entries to `/objects/shopping_list` for each missing ingredient. ### AI Agent Household Assistant A home assistant agent uses Jentic to interact with the user's self-hosted Grocy instance - adding tasks, logging consumption, and reading inventory on demand. Jentic resolves Grocy's many entity-typed paths into intent-based searches, so the agent author does not need to read the Grocy schema. Example prompt: Search Jentic for 'add a product to Grocy inventory', load the POST `/objects/{entity}` schema with entity=products, and execute with the product attributes. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/objects/{entity}` | List records of any Grocy entity | | POST | `/objects/{entity}` | Create a record on any Grocy entity | | GET | `/objects/{entity}/{objectId}` | Get a single Grocy object | | PUT | `/objects/{entity}/{objectId}` | Update a Grocy object | | DELETE | `/objects/{entity}/{objectId}` | Delete a Grocy object | | GET | `/system/info` | Get Grocy system information | | GET | `/users` | List Grocy users | | PUT | `/files/{group}/{fileName}` | Upload a file to a Grocy file group | ## Key resources - **objects** — Generic CRUD endpoints over every Grocy entity (products, chores, recipes, tasks, batteries, etc.) - **users** — List, create, update, and delete Grocy users and their permissions - **userfields** — Read and write custom user fields attached to objects - **files** — Upload, retrieve, and delete files in Grocy file groups - **system** — Read system info, config, time, localisation strings, and DB-change timestamp - **user** — Current authenticated user and their settings ## Why Jentic - **Setup:** Wiring the Grocy REST API by hand means carrying its GROCY-API-KEY header, pointing at your own self-hosted Grocy host, and mapping the generic `/objects/{entity}` data, file, and user endpoints yourself. Through Jentic you install once, import the Grocy REST API from the API Directory, store the API key once, and your agent calls it. - **Permission scoping:** Grocy puts the entity and object id in the URL path (`/objects/{entity}`, `/objects/{entity}/{objectId}`), so a rule can pin your agent to one entity: it can read and list objects of that entity and nothing else. You choose the operations it may call, so ones like deleting an object are not included unless you add them. - **Credential handling:** Your Grocy API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'list items in the stock' or 'read a shopping list', and Jentic returns the matching Grocy operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Airtable API** — Cloud database often used to track home inventory in spreadsheet form. - **NocoDB API** — Open-source self-hostable database - broader scope than Grocy but no household domain logic. - **Smartsheet API** — Sheet-style commercial work-management platform - heavier than Grocy and not self-hosted. ## FAQ ### Why is there no official OpenAPI spec for Grocy REST API? Grocy does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Grocy REST API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Grocy API use? Grocy accepts an API key in the GROCY-API-KEY header (or as an equivalent query parameter). Keys are managed in the Grocy admin panel. Through Jentic, the key is stored encrypted in your Jentic One instance and the header is injected at call time. ### Can I add a product to inventory through the API? Yes - Grocy uses a single object endpoint pattern. POST `/objects/{entity}` with entity=products creates the product, and POST `/objects/{entity}` with entity=stock logs the on-hand quantity. The same pattern covers chores, tasks, and recipes. ### What are the rate limits for the Grocy API? Grocy is self-hosted, so rate limiting depends on the host's web server configuration rather than a vendor SLA. Most personal deployments have no enforced limit. Agents should still be polite and not poll aggressively. ### How do I list everything in my Grocy inventory through Jentic? Search Jentic for 'list grocy products', load the GET `/objects/{entity}` schema, and execute with entity=products. To read on-hand stock, repeat with entity=stock - Grocy stores quantity in a separate stock entity. ### Does the Grocy API expose recipes and meal plans? Yes - recipes, recipe ingredients, meal plans, and shopping lists are all object entities reachable via `/objects/{entity}.` This lets agents read the user's recipes and generate matching shopping lists. ### Can I check when Grocy data last changed? Yes. GET `/system/db-changed-time` returns the last database modification timestamp, useful for cache invalidation in agents that mirror Grocy data into another system. ### Can I limit what my agent is allowed to do with the Grocy REST API? Yes. Because Grocy puts the entity and object id in the URL path (`/objects/{entity}` and `/objects/{entity}/{objectId}`), a rule in your self-hosted Jentic One can pin the agent to a single entity, letting it list and read those objects with GET `/objects/products` and nothing else. You decide which operations the agent may call, so write and remove actions like PUT and DELETE `/objects/{entity}/{objectId}` are excluded unless you add them. The GROCY-API-KEY is held by your own Jentic One instance and injected only for the operations your rules permit, so the agent never gets broader access than you grant.