API

A product catalogue on your shop’s site, a booking form that saves straight into Bookings, an app where customers see their own orders, your till sending in the day’s sales. Each of those is an endpoint: an address that does one thing with one model’s records — list them, read one, create, update or delete — for whoever you allow. Nothing is public until you make an endpoint for it.

Each project has one project key, made with the project. Find it on API → Keys (also on the API Overview and in Project settings), with a copy button. Add it to every address — or send it as the X-Api-Key header:

GET https://mint-c5e1255519fc.herokuapp.com/public/api/products?apiKey=mint_pk_…

curl 'https://mint-c5e1255519fc.herokuapp.com/public/api/products' -H 'X-Api-Key: mint_pk_…'

The project key is meant for your website’s code, where anyone can read it: it only says which project a call is for. What a call may do is still each endpoint’s choice — anyone, signed-in customers, or a server key. Endpoints for server keys need a secret server key as well; never put one of those in a page.

Regenerate (API → Keys) makes a new key; the old one stops at once, so every site, widget and app that calls the API needs the new one. Sites MINT hosts for the project switch by themselves. The widget and analytics snippets carry it as data-key.

Customers (who signed up on your site) and Webhooks (your server told when records change) sit in the same sidebar section.

An endpoint is a method and an address under your project’s API — GET /products/featured — plus its rules: who can call it, which records it reaches, which fields go in and out, and for a list, how it’s filtered and paged.

Switch an endpoint off and it answers 404 until it’s on again; its settings are kept. Changes on its page are a draft until you press Save changes.

1. Pick the model.
2. Tick its endpoints — List and Read one start ticked; add Create, Update, Delete if your site or app changes records.
3. Pick who can call them. For Signed-in customers, leave Only their own records ticked so each customer reaches just theirs — see Customer sign-in. Press Generate.

They answer at once. Endpoints the model already has are left as they are (one that was off is turned back on). Then open each to set its rules and fields. A website project’s Pages, SEO and Contents have their list and read-one endpoints from the start — that’s how your site reads them.

Every project’s API can sign customers up and in from the start. These endpoints are always on and can’t be switched off; they’re listed on Endpoints as Built in, and in the API reference with an example of each.

Set up sign-in (on that section) opens Widgets → Login & account: where customers are kept (MINT’s Customers, or a model of yours), their customer roles, and the ready-made sign-in box for your site. Your own sign-in form calling these endpoints works just as well.

Their own data, with their token

1. Sign in (or up). The answer has a token — keep it on their device.
2. Send it on calls: Authorization: Bearer <token>.
3. Call endpoints for Signed-in customers with Only their own records — on Endpoints, Generate endpoints for customers makes them. Each customer then gets just theirs: the bookings or orders they created, and their own record in the model they sign up to.

// 1. Sign in
const res = await fetch('https://mint-c5e1255519fc.herokuapp.com/public/api/auth/login?apiKey=mint_pk_…', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email, password }),
});
const { token } = await res.json();
localStorage.setItem('customerToken', token);

// 2. Their bookings — only theirs
const mine = await fetch('https://mint-c5e1255519fc.herokuapp.com/public/api/bookings?apiKey=mint_pk_…', {
  headers: { Authorization: 'Bearer ' + localStorage.getItem('customerToken') },
}).then(r => r.json());

1. Model — whose records it works on.
2. What it does — List, Read one, Create, Update, Delete, or Upload files.
3. Address — lowercase words and dashes, up to four parts: /products/featured. Read one, Update and Delete end with /:id, where the record’s id goes: /my/orders/:id. A few first words are kept for MINT’s own addresses (auth, site, pages, shop, cart, checkout…), and two endpoints can’t share a method and address.
4. Who can call it, and a name for you and your team.

When a custom address and a model’s /:id could both match — /products/featured and /products/:id — the one with more fixed words wins, so featured is never taken for an id.

An Upload files endpoint takes the files and answers their links; your site then sends those links in the record’s file field through its Create (or Update) endpoint. Make one with Generate (tick Upload files — it answers at /<model>/files) or New endpoint. Only models with a file or image field can have one.

Who can call it is its Access tab, as for any endpoint — and a valid server key may always upload, whoever the endpoint is for. With Anyone, one address can upload 20 times in 15 minutes.

Status is Published, Stock is more than 0, Email is their email. The tests fit the field: is, is not, is one of, contains, more / less than (before / after for dates), is empty, is not empty. Records must meet all the rules — or switch to any one of these.

On an endpoint for signed-in customers a rule can compare with the customer: Owner is the signed-in customer (what “only their own records” is), or a text field with their email, their name or their phone — orders placed with a customer’s email before they had an account, say — or an options field with their customer role. A customer without one (no customer role, no phone) matches nothing. A value is checked against the field when you save (“Price” takes a number), so a rule can’t fail later for being mistyped. Archived records and, on models with record access, private ones never reach the API whatever the rules say.

Calculated (formula) fields are always worked out by the server. Requests aren’t refused for sending a field that isn’t written, so a site can send back a record it read.

A link — a post’s author, a hero’s button page — comes back as the linked record’s id (a top-level link with its name). A caller can ask for the whole record instead with populate=. This panel decides which links it may ask for:

A linked record comes out as its own model’s API shows it: who may call that model’s Read one endpoint, its rules and its fields — never more. A model without a public API comes out by its name only (marked name only), and nothing past it can be filled.

Name the key after what will use it — “The shop’s till”, “Nightly import” — so you can revoke one without stopping the others. The key (mint_sk_…) is shown once: copy it into your server’s environment variables. After that only its last four characters show, with who made it and when it was last used.

curl 'https://mint-c5e1255519fc.herokuapp.com/public/api/till/orders?apiKey=mint_pk_…' \
  -H "Authorization: Bearer $MINT_SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"quantity": 3, "note": "From the till"}'

X-Api-Key: mint_sk_… works too. Any key in use opens every endpoint that needs a key. A wrong or revoked key, or none, answers 401 with code: "key_required". Revoke stops a key at once.

Pick a period — the last hour, 24 hours or 7 days — to see how many calls came in, how many failed, how long they typically took and how slow the slowest 5% were, with a chart of calls that worked (green) and failed (red) over time. Commonest errors lists what callers were told most often. Click one to see just those calls.

Below are the calls themselves, newest first. Narrow them by answer (worked, failed, refused 4xx, server errors 5xx), endpoint, who called, or text in the address, query, error or a customer’s email. Turn on Live to check for new calls every 5 seconds while you test your site.

The Overview shows the last 24 hours as a chart, with See what failed when something did. Your own AI can read the logs too, through Connect AI — ask it why a call fails.

Every project has its own, made from its public name (see Projects → Its public address). Below, <project> stands for it and <model> for the model’s address:

https://mint-c5e1255519fc.herokuapp.com/public/api/<model>?apiKey=mint_pk_…

A custom endpoint has its own address under the same root — https://mint-c5e1255519fc.herokuapp.com/public/api/products/featured; every call adds the project key. GET https://mint-c5e1255519fc.herokuapp.com/public/api/?apiKey=… describes the project: its name and kind, every endpoint (method, address, who may call it, how many rules, its fields in and out), and every public model with its actions, who may call it, and its fields (key, label, kind, required, allowed values, and readOnly on those a request can’t write) — handy for checking what’s on.

Bodies are JSON. Calls work from any website (CORS is open) and from servers alike.

const res = await fetch('https://mint-c5e1255519fc.herokuapp.com/public/api/products?apiKey=mint_pk_…&limit=12&sort=-createdAt');
const { doc, total, totalPages } = await res.json();

Every list answers { doc, total, page, limit, totalPages }: doc is this page’s records, total how many records match your filters across every page, and totalPages how many pages that makes at this limit. There’s another page while page < totalPages.

GET https://mint-c5e1255519fc.herokuapp.com/public/api/products?apiKey=mint_pk_…&page=2&limit=12

{ "doc": [ …12 records… ], "total": 37, "page": 2, "limit": 12, "totalPages": 4 }

Pages are stable: records that sort the same are always put in the same order, so paging never shows a record twice or skips one — unless records are added or removed while you page.

async function all(model, query = {}) {
  const records = [];
  for (let page = 1; ; page++) {
    const params = new URLSearchParams({ ...query, page, limit: 100 });
    const res = await fetch(`https://mint-c5e1255519fc.herokuapp.com/public/api/${model}?apiKey=mint_pk_…&${params}`);
    if (!res.ok) throw new Error((await res.json()).message);
    const { doc, totalPages } = await res.json();
    records.push(...doc);
    if (page >= totalPages) return records;
  }
}

You can sort by any of the model’s own fields and by createdAt, updatedAt, code and _id. A field the list can’t sort by is skipped; if none is left, the default applies. The reference on the Public API page lists each model’s sortable fields.

<field>=<value> keeps the records whose field equals the value. For anything else, add an operator to the field’s key with an underscore: <field>_<operator>=<value>.

GET https://mint-c5e1255519fc.herokuapp.com/public/api/products?apiKey=mint_pk_…&status=live&price_gte=10&price_lte=50&sort=price

How filters combine

• Every filter must match: status=live&featured=true is live and featured.
• Two operators on one field make a range: price_gte=10&price_lt=20.
• For “this or that” on one field use _in. Filters on different fields can’t be OR-ed — make two requests, or use search.
• Filters, search, sort, page, limit and fields all work together, in any order.total and totalPages count what matches.

What the API does with a name it doesn’t know

It ignores it, so cache busters like ?v=2 are harmless — but so is a typo: ?staus=live filters nothing. If a filter seems to be ignored, check the key in Models (it’s the key, not the label, and it’s case-sensitive). A value the API can’t read is an error instead, with the reason: price=cheap answers 400 “price must be a number”, and so does an operator the field doesn’t take, like status_gte.

Writing the address

Values with spaces, &, +, # or accents must be encoded. Let the browser do it:

const params = new URLSearchParams({
  status: 'live',
  price_btwn: '10_50',
  name_contains: 'trail & road',   // encoded for you
  sort: '-createdAt',
  page: '1',
  limit: '12',
});
const res = await fetch(`https://mint-c5e1255519fc.herokuapp.com/public/api/products?apiKey=mint_pk_…&${params}`);

GET https://mint-c5e1255519fc.herokuapp.com/public/api/?apiKey=… lists, for each model with List on, its filters (each field’s key, kind and operators), the fields search looks through, and the fields it can sort by.

With a plain day, the operators work in whole days, the way people say it:

It looks through the model’s text, email, long text, options and tags fields, and matches the words as one piece of text: search=trail shoe finds “Trail Shoe 2”, not “shoe for the trail”. It works alongside filters and sorting, and isn’t a ranked search — sort the results as you like. At most 100 characters are used.

const params = new URLSearchParams({ search: input.value, status: 'live', limit: '10' });
const { doc } = await fetch(`https://mint-c5e1255519fc.herokuapp.com/public/api/products?apiKey=mint_pk_…&${params}`).then(r => r.json());

GET https://mint-c5e1255519fc.herokuapp.com/public/api/products?apiKey=mint_pk_…&fields=name,price&limit=100

{ "doc": [ { "_id": "66f0…", "name": "Trail shoe", "price": 89 }, … ], "total": 37, … }

_id always comes back. Keys the model doesn’t have are skipped; if none of them is known, every field comes back. Linked records named in fields still come with their name. fields only changes what comes back — you can filter and sort by fields you didn’t ask for.

GET https://mint-c5e1255519fc.herokuapp.com/public/api/posts/66f0…?apiKey=mint_pk_…&populate=author,hero.button_page

{
  "_id": "66f0…",
  "title": "Spring menu",
  "author": { "_id": "66a1…", "name": "Ana", "bio": "…" },
  "hero": { "heading": "Fresh bread", "button_page": { "_id": "66b2…", "title": "Order online", "slug": "order" } },
  "publishedAt": "2026-10-16T09:30:00.000Z"
}

Several are comma-separated. A link the endpoint doesn’t offer answers 400 with the ones it does (see Linked records). A linked record the caller isn’t allowed to see is null, or left out of a list of links. A linked record’s own links stay ids unless you fill them too.

Each record of such a model carries publishedAt, when it last went live. A record that’s never been published, or was taken off, isn’t in the answers at all; filters, search and sort run on the published values.

A server — a preview build, an import — can read the drafts as they are, never-published ones too, with status=draft and a server key. If the model has a field of its own called status, write _status=draft instead (it always works).

curl "https://mint-c5e1255519fc.herokuapp.com/public/api/posts?apiKey=mint_pk_…&status=draft" \
  -H "x-api-key: $MINT_SERVER_KEY"

The last one reads total from the answer. Every list endpoint on the Public API page comes with examples made from that model’s own fields — press Try on one to send it.

let page = 0, totalPages = 1;
async function loadMore() {
  if (page >= totalPages) return;            // nothing left
  page += 1;
  const res = await fetch(`https://mint-c5e1255519fc.herokuapp.com/public/api/products?apiKey=mint_pk_…&status=live&sort=-createdAt&limit=12&page=${page}`);
  const data = await res.json();
  totalPages = data.totalPages;
  render(data.doc);                          // append to what's shown
}

A list is { doc, total, page, limit, totalPages }; one record is the record itself. A record has _id, code (when the model numbers records), createdAt, updatedAt and the model’s own fields — nothing else. Linked records come with their name: "category": { "_id": "…", "name": "Shoes" }. Records you archive in the panel never come out — not in lists, and not by their _id.

{
  "doc": [
    { "_id": "66f0…", "name": "Trail shoe", "price": 89, "category": { "_id": "66e1…", "name": "Shoes" },
      "createdAt": "2026-09-30T10:12:00.000Z", "updatedAt": "2026-09-30T10:12:00.000Z" }
  ],
  "total": 37, "page": 1, "limit": 12, "totalPages": 4
}

• Send the model’s fields as JSON. Anything else is ignored; calculated (formula) fields are worked out on the server, and read-only fields are left to your team, whatever you send.
• Create answers 201 with the new record. Update changes only the fields you send and answers with the record.
• The same checks as the panel apply: required fields, allowed values, min/max, unique fields.

await fetch('https://mint-c5e1255519fc.herokuapp.com/public/api/bookings?apiKey=mint_pk_…', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ guestName: 'Ana Lima', date: '2026-10-14', guests: 2 }),
});

For models that need a signed-in customer, send their token: Authorization: Bearer <token> — from customer sign-in. With the Login widget on the page, Mint.auth.fetch('orders') does that for you. Records a signed-in customer creates are theirs, which is what own records only goes by. See Customers & sign-in.

const res = await fetch('https://mint-c5e1255519fc.herokuapp.com/public/api/orders?apiKey=mint_pk_…', {
  headers: { Authorization: 'Bearer ' + token },
});

Limits

300 requests a minute per visitor’s IP address, and 40 sign-in or sign-up attempts per 15 minutes. If your own server calls the API for every page view (server-side rendering), all those calls come from one address — cache the answers, or call from the browser.

It’s made from what the live API says it offers, so it always matches the Endpoints page — make or switch on an endpoint and it appears, grouped by model; Open goes to its page. Above the models, Lists: paging, sorting and filters sums up the query parameters and operators every list takes. Click an endpoint for the rest: a list shows its sortable and searchable fields, every filter its fields take (with their operators and allowed values) and example requests made from its own fields, each with Try; a create or update shows the body fields; every endpoint shows an example response. Endpoints marked Customer need a signed-in customer’s token. The customer sign-in endpoints are listed too, and for a website, the site and page endpoints.

Each endpoint’s own page has a Reference tab with the same for that endpoint alone, as JSON you can copy: the Request — its address, headers, and for a create or update the body with every field it writes (required ones named) — the Response it answers with (a list’s page, one record, or { "message": "Deleted" }), and the Errors it can answer instead, each with its message and code. It follows the endpoint as you edit it: untick a field under Fields and it leaves the sample response straight away, before you save.

Open an endpoint and its Example request is at the top — switch between curl for a terminal and fetch for your site or app, and copy it. The address is your project’s, the body has the model’s fields filled in by example, the project key is on the address, and an endpoint for signed-in customers carries the Authorization: Bearer <customer token> header to fill in. For instance, creating a booking:

curl -X POST 'https://…/public/api/bookings?apiKey=mint_pk_…' \
  -H 'Content-Type: application/json' \
  -d '{"guest":"Ada Lovelace","nights":2}'

const res = await fetch('https://…/public/api/bookings?apiKey=mint_pk_…', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ guest: 'Ada Lovelace', nights: 2 }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.message);

1. Press Try on an endpoint in the reference — or pick a method and type a path, like /products?limit=5.
2. For a create or update, edit the example body. It starts with the model’s fields filled in by example.
3. Press Send. You see the status, how long it took and the JSON that came back. Copy as fetch gives you the same call for your code.

To try a customer-only endpoint, send POST /auth/register or /auth/login first: the tester keeps the token and sends it with the next requests. After a list or a create, the record’s _id fills in the next :id.

Where the public API lets your site ask for records, a webhook sends them as they change: a new booking to your front-desk system, a paid order to the warehouse, anything to Zapier. Whether the change was made in the panel, through the public API or by an AI assistant, the project POSTs the record to an address of yours.

1. On Webhooks, press Add a webhook.
2. Pick the model and when it’s sent: a record created, changed, deleted — any of them. A model with drafts can also send when a record is published (the record as it went live) or taken off (its draft), with event: "publish" or "unpublish". Publishing also refreshes your site’s pages. A scheduled publish sends them too, with source: "schedule".
3. Give the address your server listens on, starting with https://, and a note on what it does with it. Without an address the webhook stays off.
4. Copy the secret that’s shown — it isn’t shown again. Your server uses it to check each request (next section). Lost it? The key button makes a new one; the old one stops matching at once.
5. Press Send test. Your server gets an event: "test" request with the model’s newest record (or an example), and the answer shows straight away.

Each request has a JSON body like this:

{
  "delivery": "6f1c…",          // the same on every retry — skip ones you've seen
  "event": "create",            // create | update | delete | publish | unpublish | test
  "route": "orders",
  "project": { "id": "…", "slug": "acme-shop", "name": "Shop" },
  "source": "api",              // api | panel | test
  "at": "2026-10-04T09:30:00.000Z",
  "record": { "_id": "…", "createdAt": "…", "updatedAt": "…", "total": 42 }
}

Every request carries x-mint-event, x-mint-delivery, x-mint-timestamp (seconds) and x-mint-signature. The signature is sha256= followed by the HMAC-SHA256, in hex, of the timestamp, a dot and the body exactly as it arrived — keyed with the webhook’s secret. Work it out yourself and compare; turn away a request that doesn’t match or whose timestamp is more than a few minutes old. In Node:

import crypto from 'crypto';

// In your handler, with the body exactly as it arrived (not re-serialised):
function fromMint(rawBody, headers, secret) {
  const timestamp = headers['x-mint-timestamp'];
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');
  const given = String(headers['x-mint-signature'] || '');
  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300; // 5 minutes
  return fresh && given.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}