The Developer API

Puree has a JSON API that lets you pull your own account’s data into your own scripts, spreadsheets and applications, and, where the account owner allows it, make changes: to your menu and packages, your customers, tasks and enquiries, your delivery run sheet and the rest of the areas listed below. The same access is what lets AI assistants work with your account. If all you want is to connect Claude, ChatGPT or Grok, you don’t need anything on this page: add the Puree connector to your AI app and click Sign in to Puree (see Connecting with an AI Agent). This page explains what the API offers and how to get started. The full, endpoint-by-endpoint reference lives in the interactive API docs.

What You Can Do With It

The API is scoped to a single account: a token only ever sees the data belonging to the account it was created in. It’s designed for keeping Puree in step with your other tools, such as syncing customers from your CRM or into a mailing list, exporting your menu to another site, feeding order data into a reporting dashboard, or sending tomorrow’s deliveries to a routing app. Where you allow it, it can also make changes.

Access is given area by area. Each area can be looked up (Read), and most can also be changed (Write).

Available now

• Orders (read, and some changes) — your quotes and orders, with line items, staff, packages, deliveries and payment totals, and the notes on each one. Each order links to its page in Puree and to a preview of the quote as your customer will see it; both open only for someone signed in to Puree on your account, and neither is the link you send a customer. With write access a tool can add a note to a quote, as Add note does on its Notes panel, set or clear the chef and driver instructions printed on its dockets, and attach or remove documents (from your document library or a new upload). Nothing else about a quote can be changed here: it can’t be created, priced, accepted or cancelled. Notes can’t be edited or removed, and sending the same note twice adds it twice, so check the list before you retry. Attaching a document shows it to the customer straight away, on their view of the quote. Removing one only unlinks it: the file stays in your library. Uploads through the API are limited to 5 MB and to PDF, images, Word, Excel, PowerPoint, plain text and CSV, and download links expire after 15 minutes.
• Customers (read and write) — your customers, their contacts and their addresses. With write access a tool can add and update them, for example to import a customer list from another system and keep it in sync. Give each customer your own system’s id in external_id: it’s unique within the account, so a re-run finds the customer instead of creating a second one. Contacts and addresses are made inactive rather than deleted, and a contact who has unsubscribed from emails can’t be resubscribed through the API.
• Items and categories (read and write) — your menu items, with pricing, categories, dietary/allergen codes, photos and the supplier each item is bought in from (external_supplier_id; send null to remove it). A bundle can’t have a supplier.
• Packages (read and write) — your packages, what they contain, their description and their photos. The description is plain text: what you send is shown as written, never as formatting, and sending back the text you read keeps the formatting made in Puree.
• Staff (read and write) — your staff roles and their charge rates, and the people who work your events, with their phone numbers, emails and the roles they work as. Looking up covers both; changing adds and edits people (roles and rates are changed in Puree). It contains no pay information. Tokens made with the old separate Staff members permission keep working.
• Who works each shift (read and write) — the shifts on each quote (the role, how many are needed and the times) and who is named on them. With write access a tool can put one of your staff on a shift or take them off. Only active people can be added, a full shift is refused, and someone already working another role at the same event can’t be added twice. A clash with another event is reported but doesn’t stop it. Accounts that roster through Deputy can’t change shifts here, because Deputy decides who works. Names only: phone numbers and emails come under Staff.
• Delivery run sheet (read and write) — each day’s deliveries, supplier collections and equipment returns, in run sheet order, with the address, customer, contact and instructions for each stop. With write access a tool can set the departure time, run, order within the run and driver for a stop, and add or rename drivers. Stops come from your quotes, so they can’t be added or removed here, and their delivery date and time are the quote’s. “A day” is in your account’s time zone, and a departure time can be sent as a full timestamp or as HH:MM on the stop’s own day. Two stops can share a run and position, as on the run sheet page.
• Supplier deliveries and collections (read and write) — for each quote, how goods from each outside supplier arrive and go back: delivery or collection, date, time, address and instructions. Setting it adds or removes the matching collection or return on your run sheet, but never emails the supplier: sending the order is still done in Puree. A supplier with nothing on the quote can’t be arranged.
• Dockets (read) — the chef, driver, equipment and beverage dockets, event brief and consolidated docket for a quote, its standard quote PDF, and a day’s delivery run sheet, as the same PDFs Puree prints. See Docket and Quote PDFs below.
• Commentary and email templates (read and write) — the reusable wording for each quote section and email, by location. Write in plain text, which is kept as paragraphs. Placeholders such as {customer_name} are kept exactly as written and filled in when the email is sent. Attached files can be read but not uploaded, and your terms and conditions aren’t part of this area: they’re managed in Puree, where every change is versioned.
• Tasks (read and write) — your to-do list: tasks for customers, quotes and enquiries, with due dates and reminders. Tasks are completed rather than deleted.
• Enquiries and opportunities (read and write) — your leads, including their tags and notes. Your own tools can log and update leads, tag them and add notes.
• Tags (read and write) — the tags you use on quotes and enquiries, so a tool can create the tag it needs.
• Menu headings, presentation styles, suppliers and venue types — the small lists the rest of your data refers to, so a tool can add the one it needs instead of asking someone to create it in Puree first. Menu headings, presentation styles and suppliers come under Items and categories; venue types, the venue bookings a quote can carry, come under Packages.
• Newsletter groups — your email lists, and who is in them. They come under Customers. Putting someone in a group never subscribes them: anyone who has unsubscribed stays unsubscribed.
• Recipes and ingredients (read and write) — for accounts using recipes: your recipes, ingredients and their costs.

Nothing is ever deleted outright. The only removals are taking a contact out of a newsletter group, taking a person off a shift, and unlinking a document from a quote, and each leaves the contact, the person or the document itself in place (a document stays in your library). Everything else is made inactive, completed or retired instead, so nothing your quotes depend on disappears.

Photos. Item and package writes can carry a photo you supply, sent as base64 in the JSON body. It replaces the current photo, and Puree never fetches one from a web address.

• Formats: JPEG, PNG and WebP, plus iPhone HEIC/HEIF, which is converted to JPEG where the server supports it (otherwise it’s refused by name).
• Size: up to 5 MiB once decoded. A photo over 4,000 px on its long side is scaled down to 4,000. Images too large to process safely, such as huge or interlaced PNGs, are refused before they’re decoded, with a message saying what to send instead.
• Cleaned on the way in: colours are converted to sRGB (so iPhone and CMYK photos look right), the photo is turned upright, and EXIF data, including GPS location, is stripped.
• Base64 may carry a data: prefix, line breaks or URL-safe characters.
• Errors name the problem (“photo is 5.03 MiB decoded…”, “photo is GIF; send JPEG, PNG or WebP”). If the server is busy processing another photo, you’ll get 503 with a Retry-After header: wait that long and send it again.
• Checksum: send sha256, the SHA-256 of the file in hex, with a photo or an uploaded document, and Puree checks it arrived intact. If it doesn’t match, nothing changes and the error says so.

Upload links. For a larger file, or one an AI assistant would otherwise have to copy out as base64, ask for an upload link with POST /uploads and purpose document or photo.

• Two ways to send the file. The link opens a Puree page, with no sign-in, that shows your business’s name and what the file is for, where someone drops in one file. Your code can instead PUT the file’s bytes straight to the link.
• The link is limited. It works once, for 15 minutes, only for your account and for the person and app that asked for it. It stops working if that app’s access is removed.
• Checked as usual. The file is checked by the same rules as any other upload.
• Using the upload. Once GET /uploads/{upload_id} says it’s ready, use its upload_id once:
  • to attach the document to a quote;
  • to add it to your document library without attaching it to anything (POST /documents), so no customer sees it;
  • or as an item’s or package’s photo.
• Unused uploads are deleted after a day.

Docket and Quote PDFs

GET /orders/{order_id}/dockets/{type} returns one PDF, where type is chef, driver, equipment, beverage, event_brief, consolidated or quote.

• It needs the Dockets permission. The quote PDF also needs Orders, because it shows prices.
• The quote is Puree’s standard quote PDF for the current version, not a custom quote template.
• A docket that doesn’t apply to that quote (a driver docket with no delivery, a beverage docket with no drinks) is refused with 422 and the code not_applicable, so you can tell “doesn’t apply” from an error.
• Downloading counts as printing it, so the Dockets page shows it as printed.
• Download links. Add ?mode=link to get a link to the PDF instead of the file, for a tool that can’t pass a file on, such as an AI assistant. Anyone with the link can open it, without signing in, for 15 minutes.
  • Each time it’s opened, Puree makes the PDF fresh, so it’s always current.
  • Opening it is what counts as printing, by the person whose access asked for it.
• A day’s delivery run sheet is GET /run_sheets/{date}, with the same Dockets permission, and ?mode=link works there too.
• PDFs take longer to make than other requests, so they have their own limits, as well as the general one: 10 dockets a minute and 3 event briefs a minute, and, separately, 10 run sheets a minute.

Allergens and Dietary Tags

Allergens are food safety, so the API says where each one comes from, and it never says a dish is allergen-free.

• Items list allergens, each marked manual (set by a person) or ai (found by Puree’s AI detection, which you should describe as detected rather than confirmed). recipe_allergens lists allergens in the recipe’s ingredients that aren’t on the item yet, with the ingredients they come from.
• Order lines list every allergen the line may contain: the dish’s own and those of any options chosen for it, together. An option never hides the dish’s allergens. Each says where it came from: option, snapshot (recorded on the line when it was added) or item_live (the dish’s current allergens). dietary_tags are as the quote prints them. A bundle shows its allergens on its content lines, and says so with allergens_on: "contents". These are the same allergens Puree’s quotes, dockets and labels print.
• A dietary tag such as “Contains nuts” is marked looks_like_allergen, so treat it as an allergen warning even though it’s filed as a dietary tag.
• An empty list means nothing is recorded, not that the food is free of allergens. Ask the caterer to confirm.

Who Decides What Is Allowed

Only the account owner decides who can use API and AI access, and what each person may do.

1. The owner accepts the terms. Before anything is enabled, the owner reads and accepts a short risk acknowledgement, including that Puree isn’t responsible for external AI systems you connect. It needs 2FA and a fresh code. A copy is emailed to the owner and to Puree. If the wording ever changes, owners have 30 days to accept the new version; after that, API access, including tokens and connected AI apps, pauses until they do, and resumes as soon as they accept.
2. The owner grants access. On Settings → API and AI access, the owner sees one row per person, with a summary of what they can use. Edit opens that person’s access: start from a preset (No access, Look up only, Menu manager, Sales, Everything) or choose area by area, from None to Look up to Look up and change. Admins don’t get access automatically; they need a grant like anyone else.
3. People create tokens, or connect AI apps, within their grant. They can only tick what they’ve been given. If the owner later narrows someone’s access, that person’s existing tokens are narrowed or revoked straight away, and any AI app they connected that relied on what was taken away is disconnected.

Two-factor authentication (2FA) is required to grant access, to accept the terms, to create a token and to connect an AI app. If someone turns 2FA off, their tokens and connected apps are paused, not deleted, and work again as soon as they turn it back on. See Two-Factor Authentication.

The Base URL

All endpoints live under a single versioned base URL:

https://puree.app/api/public/v1

Getting an Access Token

Every request must carry a personal access token. Once API access is enabled for your account and the owner has given you access, you can create one from Settings → API and AI access. Choose a name, tick the permissions you need (only what the owner granted is available) and, if you like, an expiry date. The token is shown once, so copy it straight away. Tokens look like puree_at_ followed by 40 hex characters. Treat a token like a password — anyone with it can use the access it carries, so store it securely and revoke it from the same page if it’s ever exposed.

Authenticating a Request

Pass the token in an Authorization header using the Bearer scheme. Here’s a complete example that lists your customers:

curl https://puree.app/api/public/v1/customers \
  -H "Authorization: Bearer puree_at_your_token_here"

A request with a missing or invalid token comes back as 401 Unauthorized. A token that tries something it wasn’t given permission for is refused with 403. A paused token (because its holder has turned 2FA off) also gets 403, with the code two_factor_required.

To check a token, or to find out which account it works in, call GET /account. It needs no particular permission and returns the account’s name, time zone, currency and country, and the person the token acts for.

Searching and Paging

The list endpoints are paginated and support a search parameter for fuzzy matching (for example, on a customer’s name or a contact’s email). Combine query parameters as normal:

curl "https://puree.app/api/public/v1/customers?search=acme&page=2" \
  -H "Authorization: Bearer puree_at_your_token_here"

A filter that takes a list of names, such as an item’s master list, takes them comma-separated and in any case: items?item_category_group=beverages,equipment. A name that doesn’t exist is refused with 400, never answered with an unfiltered list.

The delivery run sheet lists need a day: deliveries?date=2027-03-10, or from and to for up to 31 days. They’re always in run sheet order.

Orders carry expires_at and expired, and can be filtered by expiry and by number. expired is true only for a quote whose offer has lapsed (a draft, an expired quote, or a pending quote that was never accepted, past its expiry day): an order that has become a booking (accepted, confirmed, live, or an online order being processed) is never expired, whatever its date. The expiry filters go by date alone, whatever the state, so add state=pending for quotes about to lapse: orders?state=pending&expires_after=2027-03-01&expires_before=2027-03-14 lists the open quotes that expire in those two weeks (whole days in your time zone, both ends included, so a quote expiring late on the 14th counts). orders?reference=1042 finds the quote the app shows as #1042 (#1042 works too); a number no quote has returns an empty list.

Rate Limits

Each access token you create is limited to 60 requests per minute. An AI app connected with Sign in to Puree gets more, because answering a question takes many small lookups: 300 reads and 120 changes a minute. All the tokens and apps on one account share a ceiling of 600 requests a minute between them.

If you go over, requests return 429 Too Many Requests with a Retry-After header saying how many seconds are left before you can try again. Wait that long and retry. Docket and run sheet PDFs have tighter limits of their own (see Docket and Quote PDFs). If you’re building something that needs a higher limit, get in touch.

To change many items or packages at once, send up to 50 in one request with PATCH /items/bulk or PATCH /packages/bulk. Each is saved on its own, so one that fails doesn’t stop the rest, and the response says which were updated and why any weren’t: retry only the failed ones. Photos can’t be changed in bulk.

When Something Goes Wrong

Write requests must send JSON, with Content-Type: application/json. Anything else is refused with 415 Unsupported Media Type before it’s read.

Errors come back as JSON with an errors array. Each entry has a machine-readable code, a short title, and sometimes a longer detail:

{
  "errors": [
    { "code": "unauthorized", "title": "Missing or invalid access token" }
  ]
}

The ones you’re most likely to meet:

Status	Code	Means
400	invalid_request	A value was malformed: an unknown key, a wrong type, a bad filter, or a change to something that can only be read. Nothing was written.
401	unauthorized	The token is missing or invalid.
403	insufficient_scope, two_factor_required	The token doesn’t have this permission, or is paused.
404	not_found	It isn’t on this account.
409	conflict	It would duplicate something that must be unique, such as a name or a customer’s external_id. Nothing was written.
415	unsupported_media_type	The body wasn’t sent as JSON.
422	validation_failed, not_applicable	The values didn’t pass validation (each error names its field), or the docket you asked for doesn’t apply to that quote.
429	rate_limited	Too many requests; wait and retry.

The Activity Log

Everything done through a token or a connected AI app is recorded on the Activity log tab of the API and AI access page, in plain English, for example “Changed the item Crispy pork belly: moved from position 24 to 16”. Each row shows who, which connection, what changed and whether it worked. You can search, filter by person, connection, type and dates, and click a row for the full details. The owner sees everyone’s activity; everyone else sees their own. Entries are kept for 13 months, and tokens and other secrets are never shown. See API and AI Access: Decide Who Can Connect AI to Your Puree Account for the full picture, and Connecting with an AI Agent if you’re connecting an AI assistant.

The Full Reference

Every endpoint, parameter and response field is documented in the interactive API reference. It’s a reference rather than a console: try calls from your own tools, with a token you’ve created.

Open the API reference →

Questions, or want access enabled for your account? Email us at email@puree.app.