Millbase API

Your first request#

You’ll need a Millbase account and administrator access to the organization you want to connect.

1. Create an API key

   In Millbase, open Settings → API and integrations → API keys. Name your integration, select Warehouse and projects, choose an expiry, then generate a key.

   Open API settings

2. Save your key

   Copy it when it’s created; the full key is shown only once. Replace the placeholder below in your terminal. Store production keys in your server’s secret manager.

   TerminalCopy

   export MILLBASE_API_KEY='YOUR_MILLBASE_API_KEY'

3. Read your projects

   Run this on your server or in a terminal. Node.js 22+ and Python 3 examples use built-in libraries.

   cURLNode.jsPython

   Copy

   curl --fail-with-body --get 'https://app.millbase.ca/api/v1/data/projects' \
     -H "Authorization: Bearer $MILLBASE_API_KEY" \
     --data-urlencode 'fields=id,name,status' \
     --data-urlencode 'limit=10'

What comes back

A JSON object with your rows and pagination details. This is a fictional example; your response contains your organization’s records. An empty data array means no records matched.

{
  "data": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "Example kitchen",
      "status": "active"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "nextOffset": null
  }
}

Authentication#

Send your key in the Authorization header with every request: Authorization: Bearer YOUR_MILLBASE_API_KEY.

Use one key per integration, with only the permissions it needs. Keys can expire after 30, 90, or 365 days. Revoke a key in API settings to stop access, then create a replacement when rotating credentials.

Keep keys in server-side environment variables or a secret manager. Never put them in browser code, public repositories, URLs, or chat messages.

Endpoint reference#

Start with the catalog to see exactly which datasets and fields your key can access.

curl --fail-with-body 'https://app.millbase.ca/api/v1/resources' \
  -H "Authorization: Bearer $MILLBASE_API_KEY"

All paths below are relative to the base URL. This reference lists every public dataset; your key’s permissions determine which ones you can read. Expand a row’s fields to see its allowed columns.

Generated from Millbase’s public OpenAPI schema. View live OpenAPI · Download this reference

Filters & queries#

For a simple GET, use fields, limit, and offset. Add filter=id and value=YOUR_RECORD_UUID to find one record. URL-encode parameter values.

Use POST /query for several filters or date ranges. For example, read task logs for a project. Replace PROJECT_UUID with an ID from your projects response.

curl --fail-with-body 'https://app.millbase.ca/api/v1/query' \
  -H "Authorization: Bearer $MILLBASE_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "resource": "task-logs",
  "fields": [
    "id",
    "project_id",
    "worker_id",
    "seconds",
    "status"
  ],
  "filters": [
    {
      "field": "project_id",
      "op": "eq",
      "value": "PROJECT_UUID"
    }
  ],
  "limit": 50,
  "offset": 0
}'

{
  "resource": "task-logs",
  "fields": [
    "id",
    "project_id",
    "worker_id",
    "seconds",
    "status"
  ],
  "filters": [
    {
      "field": "project_id",
      "op": "eq",
      "value": "PROJECT_UUID"
    }
  ],
  "limit": 50,
  "offset": 0
}

Queries accept only the catalog’s named fields. Wildcards, joins, SQL, arbitrary tables, and organization overrides are not supported.

Pagination#

Read pagination.nextOffset and pass it as offset in the next request. Stop when it is null. Keep the same resource, fields, and filters across pages.

import { setTimeout } from 'node:timers/promises';

let offset = 0;
do {
  const response = await fetch('https://app.millbase.ca/api/v1/query', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.MILLBASE_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ resource: 'materials', limit: 100, offset }),
    signal: AbortSignal.timeout(30_000),
  });
  if (!response.ok) throw new Error(await response.text());
  const { data, pagination } = await response.json();
  console.log(data);
  offset = pagination.nextOffset;
  if (offset !== null) await setTimeout(1100);
} while (offset !== null);

Each page reads current stored data without response caching. Records may change while you paginate; this is not a frozen export. For ongoing work, elapsed seconds reflect the last saved value, so use start and end timestamps when calculating running durations.

Permissions & privacy#

API and MCP access is available on Free, Pro, and Enterprise. An organization administrator chooses the permissions for each integration.

Worker compensation requires both people:read and financials:read. The endpoint reference lists every required permission; all listed permissions must be granted.

Limits & errors#

API and MCP share these organization limits. Creating more keys does not increase them. Authenticated discovery, initialization, and invalid queries also count. Requests are limited to 16 KB and responses to 1 MB.

Errors return error.code and error.message. For 429 responses, respect the Retry-After header; use backoff with jitter for temporary failures. The X-Monthly-Remaining header reports remaining organization requests.

Connecting an agent instead of building an app? Follow the MCP guide.