API referenceBeta
Docs menu

Macrows API

Read and write Macrows Cloud project tables, append rows, update records, and call MCP tools with organization API keys.

Create a key on the API keys page and send it as a bearer token on every request.

Authentication

Add your API key as a bearer token.

Required header

Authorization: Bearer <api-key>

Request body

Content-Type: application/json

Keys created from Macrows Cloud are prefixed with mcr_. Public project write calls require readwrite keys.

  • Only projects listed on a key are accessible for that key.
  • Project IDs and table IDs are required UUIDs.

REST response envelope

dataobject

Endpoint payload. The response field tables below describe the contents of this object.

metaobject

Response metadata returned by REST endpoints.

apiVersionstring

Current REST API version. Today this is v1.

requestIdstring

Request identifier. Matches the X-Request-ID response header.

List projects

GET/api/v1/public/projects

List all projects that this API key can read.

data fields

projectsobject[]

Projects the API key can read.

idstring

Cloud project UUID.

namestring

Display name of the project.

Example request
curl -H "Authorization: Bearer $MACROWS_API_KEY" \
  https://www.macrows.app/api/v1/public/projects

List tables

GET/api/v1/public/projects/{projectId}/tables

List all tables for one project.

data fields

projectIdstring

Cloud project UUID used in the request.

latestVersioninteger

Project version number. Reuse in write calls.

tablesobject[]

Available tables in the project.

idstring

Table UUID.

namestring

Display name.

fieldCountinteger

Number of fields.

recordCountinteger

Number of rows currently saved.

Example request
curl -H "Authorization: Bearer $MACROWS_API_KEY" \
  https://www.macrows.app/api/v1/public/projects/$PROJECT_ID/tables

Get table

GET/api/v1/public/projects/{projectId}/tables/{tableId}

Read table rows and table definition with optional pagination.

Query params

limitinteger

Rows per page. Defaults to 100, maximum 500.

offsetinteger

Offset inside the result set. Defaults to 0.

data fields

projectIdstring

Cloud project UUID used in request.

latestVersioninteger

Project version number.

tableobject

Table structure and metadata.

idstring

Table UUID.

namestring

Display name.

recordCountinteger

Rows in the table.

fieldCountinteger

Number of fields.

fieldsobject[]

Field definitions for the table.

pageobject

Pagination block for rows.

offsetinteger

Current offset.

limitinteger

Page size.

nextOffsetinteger|null

Next offset if more rows exist.

totalinteger

Total row count in table.

recordsobject[]

Returned rows in this page.

Example request
curl -H "Authorization: Bearer $MACROWS_API_KEY" \
  "https://www.macrows.app/api/v1/public/projects/$PROJECT_ID/tables/$TABLE_ID?limit=10&offset=0"

Append rows

POST/api/v1/public/projects/{projectId}/tables/{tableId}/rows

Append one or more rows. Always send latestVersion from read response inexpectedVersion.

Request body

expectedVersionintegerrequired

Latest project version from data.latestVersion in a read response. Required for all writes.

rowsobject[]required

Rows to append. Send 1 to 500 rows per request. Keys are table field IDs.

cellsobject

Map of fieldId to string, number, boolean, null, or string[] value.

Writable values

Writable field types

text, number, boolean, singleSelect, multiSelect, date, email, and url can be written.

Read-only field types

linkedRecord, lookup, button, formula, createdAt, and updatedAt cannot be written through the public API.

Cell valuestring|number|boolean|null|string[]

Use null or an empty string to clear a cell. string[] is accepted for select values.

Formula-looking strings

Values starting with = are rejected by public write endpoints.

Select fields

Single-select and multi-select values must match existing option labels.

data fields

latestVersioninteger

New project version after write.

projectobject

Updated project metadata including id, name, rowCount, tableCount, latestVersion, role, and edit capability flags.

Example request
curl -X POST 'https://www.macrows.app/api/v1/public/projects/$PROJECT_ID/tables/$TABLE_ID/rows' \
  -H "Authorization: Bearer $MACROWS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedVersion": 1,
    "rows": [
      {
        "cells": {
          "FIELD_ID": "value"
        }
      }
    ]
  }'

Update rows

PATCH/api/v1/public/projects/{projectId}/tables/{tableId}/rows

Update existing records. IDs in the project are required in the body.

Request body

expectedVersionintegerrequired

Latest project version from data.latestVersion in a read response. Required for all writes.

updatesobject[]required

Existing cells to update. Send 1 to 1000 updates per request.

fieldIdstring

UUID of target field.

recordIdstring

UUID of row to edit.

valuestring|number|boolean|null|string[]

New value to write.

Writable values

Writable field types

text, number, boolean, singleSelect, multiSelect, date, email, and url can be written.

Read-only field types

linkedRecord, lookup, button, formula, createdAt, and updatedAt cannot be written through the public API.

Cell valuestring|number|boolean|null|string[]

Use null or an empty string to clear a cell. string[] is accepted for select values.

Formula-looking strings

Values starting with = are rejected by public write endpoints.

Select fields

Single-select and multi-select values must match existing option labels.

data fields

latestVersioninteger

New project version after write.

projectobject

Updated project metadata including id, name, rowCount, tableCount, latestVersion, role, and edit capability flags.

Example request
curl -X PATCH 'https://www.macrows.app/api/v1/public/projects/$PROJECT_ID/tables/$TABLE_ID/rows' \
  -H "Authorization: Bearer $MACROWS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedVersion": 1,
    "updates": [{
      "fieldId": "FIELD_ID",
      "recordId": "RECORD_ID",
      "value": "updated text"
    }]
  }'

MCP endpoint

POST/api/v1/mcp

JSON-RPC endpoint for MCP-compatible tooling. Browser calls must use the same origin as the request URL.

Available tools

list_tables

Read table summaries for a project.

get_table

Read one table's fields and paginated records. Supports limit up to 500 and offset.

append_rows

Append 1 to 500 rows. Requires a readwrite key and expectedVersion.

update_cells

Update 1 to 1000 existing cells. Requires a readwrite key and expectedVersion.

tools/list response fields

jsonrpcstring

Protocol version.

idstring|number|null

Request id.

resultobject

Returned tools and table-access capabilities.

Example request
curl -X POST 'https://www.macrows.app/api/v1/mcp' \
  -H "Authorization: Bearer $MACROWS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Try it now

Paste one of your API keys to send real requests. Use a read key first with list projects and list tables. Use write keys for append/update.

Request path

GET/api/v1/public/projects

Example command

curl -X GET 'https://www.macrows.app/api/v1/public/projects'

Rate limits

Current limits

All public REST and MCP requests

120 requests per minute per API key in one shared bucket.

Counter scope

Reads, writes, and MCP calls all increment the same per-key counter.

Errors

Common responses

400

Invalid request, invalid UUID, invalid JSON, invalid cell value, read-only field, duplicate cell update, or missing record.

401

Missing or invalid API key (`missing_api_key`, `invalid_api_key`).

403

Wrong key scope, missing project scope, inactive key owner, or invalid MCP browser origin.

404

Table or project resource not found.

409

Project version changed; refresh latestVersion before retrying writes.

413

Generated change payload is too large.

429

Rate-limited by key bucket; retry after delay.