Grocy REST API
Agent-ready OpenAPI document · curated by JenticProductivityTask ManagementapiKey86 EndpointsREST
Know of an official OpenAPI document? Contribute it →
For Agents
Read and update household inventory, chores, tasks, and recipes on a self-hosted Grocy instance through one object-oriented REST API.
Use for: List all products in my Grocy inventory, Create a new chore in Grocy, Update the quantity of an inventory item, Delete a Grocy task by id
Not supported: Does not handle online grocery purchasing, payment, or smart-device control - use for managing data on a self-hosted Grocy household ERP only.
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.
Install Jentic One Beta
Connect the Grocy REST API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Grocy REST API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fgrocy.info%2Fgrocy" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fgrocy.info%2Fgrocy" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Grocy REST API.
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
Patterns agents use Grocy REST API for, with concrete tasks.
★ 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.
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.
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.
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.
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
86 endpoints — jentic publishes the only available openapi specification for grocy rest api, keeping it validated and agent-ready.
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
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
Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Grocy REST API through Jentic.
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.
GET STARTED