Macro Tables

Macro tables aggregate rows from multiple obra_tablas across different obras into a single view. Each macro table has a set of columns (source, custom, or computed) and an optional set of source obra_tablas. Sources can be selected in two modes:

Explicit — specific obra_tablas are linked to the macro table.
Template (sourceMode: "template") — sources are resolved dynamically based on a defaultTablaId pattern, matching tables across all obras in the tenant.

List macro tables

GET /api/macro-tables

string

Returns all macro tables for the authenticated user’s active tenant, including their columns and resolved sources.

Response

macroTables

MacroTable[]

required

Array of macro table objects.

Show MacroTable properties

string

UUID.

tenantId

string

Tenant UUID.

name

string

Display name (unique per tenant).

description

string | null

Optional description.

settings

object

Source selection settings (includes sourceMode).

sourceCount

number

Number of resolved source tablas.

sources

Source[]

Explicit source links.

Show Source properties

string

Source UUID.

macroTableId

string

Parent macro table UUID.

obraTablaId

string

Linked obra_tabla UUID.

position

number

Display order.

columns

Column[]

Column definitions.

Show Column properties

string

UUID.

macroTableId

string

Parent macro table UUID.

columnType

string

source, custom, or computed.

sourceFieldKey

string | null

Field key from source rows (for source columns). Prefix obra. to reference obra fields.

label

string

Display label.

dataType

string

Data type (text, number, date, etc.).

position

number

Display order.

config

object

Column configuration (aggregation settings, computed type, etc.).

createdAt

string

ISO 8601 creation timestamp.

updatedAt

string

ISO 8601 update timestamp.

Request
Response

curl 'https://<domain>/api/macro-tables' \
  --cookie 'sb-access-token=<session>'

{
  "macroTables": [
    {
      "id": "mt-uuid-...",
      "tenantId": "tenant-uuid-...",
      "name": "Resumen de materiales",
      "description": null,
      "settings": { "sourceMode": "explicit" },
      "sourceCount": 3,
      "sources": [
        { "id": "src-uuid-...", "macroTableId": "mt-uuid-...", "obraTablaId": "ot-uuid-...", "position": 0 }
      ],
      "columns": [
        { "id": "col-uuid-...", "macroTableId": "mt-uuid-...", "columnType": "source", "sourceFieldKey": "material", "label": "Material", "dataType": "text", "position": 0, "config": {} }
      ],
      "createdAt": "2024-05-01T00:00:00Z",
      "updatedAt": "2024-06-01T00:00:00Z"
    }
  ]
}

Create a macro table

POST /api/macro-tables

string

Creates a new macro table with sources and columns. At least one source and one column are required.

Request body

name

string

required

Display name. Must be unique within the tenant.

description

string

Optional description.

settings

object

Source selection settings.

sources

SourceInput[]

required

Source obra_tablas. Must contain at least one item.

Show SourceInput fields

obraTablaId

string

required

UUID of the obra_tabla to include as a source. Must belong to an obra in the tenant.

columns

ColumnInput[]

required

Column definitions. Must contain at least one item.

Show ColumnInput fields

label

string

required

Display label.

columnType

string

default:"source"

source, custom, or computed.

sourceFieldKey

string | null

Required for source columns. Field key from source rows or obra.<fieldName> to reference obra fields.

dataType

string

default:"text"

Data type of the column.

config

object

Column configuration.

Response

macroTable

MacroTable

required

The newly created macro table with its sources and columns.

Request
Response

curl -X POST 'https://<domain>/api/macro-tables' \
  --cookie 'sb-access-token=<session>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Resumen de materiales",
    "sources": [{ "obraTablaId": "ot-uuid-..." }],
    "columns": [
      { "label": "Material", "columnType": "source", "sourceFieldKey": "material", "dataType": "text" },
      { "label": "Cantidad", "columnType": "source", "sourceFieldKey": "cantidad", "dataType": "number" }
    ]
  }'

{
  "macroTable": {
    "id": "mt-uuid-...",
    "name": "Resumen de materiales",
    "sources": [{ "id": "src-uuid-...", "obraTablaId": "ot-uuid-...", "position": 0 }],
    "columns": [
      { "id": "col-1-uuid", "label": "Material", "columnType": "source", "dataType": "text", "position": 0, "config": {} },
      { "id": "col-2-uuid", "label": "Cantidad", "columnType": "source", "dataType": "number", "position": 1, "config": {} }
    ]
  }
}

Get a macro table

GET /api/macro-tables/{id}

string

Returns a single macro table by UUID, including fully resolved sources (with obra and tabla metadata) and columns.

Path parameters

string

required

UUID of the macro table.

Response

macroTable

MacroTable

required

The macro table object. In template source mode, sources include dynamically resolved obra_tablas.

Update a macro table

PATCH /api/macro-tables/{id}

string

Partially updates a macro table. Supplying sources or columns replaces those lists entirely (existing entries are deleted and new ones inserted). Fields not supplied are left unchanged.

When columns is supplied, existing custom values for deleted columns are also removed via cascade.

Path parameters

string

required

UUID of the macro table.

Request body

name

string

New display name.

description

string

New description (empty string sets it to null).

settings

object

Updated source selection settings.

sources

SourceInput[]

Replacement source list. Replaces all existing sources.

columns

ColumnInput[]

Replacement column list. Replaces all existing columns.

Response

macroTable

MacroTable

required

The updated macro table with resolved sources and columns.

Delete a macro table

DELETE /api/macro-tables/{id}

string

Permanently deletes a macro table and all related data (sources, columns, and custom values) via cascade.

Path parameters

string

required

UUID of the macro table.

Response

boolean

required

Always true on success.

List rows

GET /api/macro-tables/{id}/rows

string

Returns aggregated rows from all resolved source tablas, with source and custom column values mapped. Supports pagination, search, and structured filters.

Path parameters

string

required

UUID of the macro table.

Query parameters

page

number

default:"1"

Page number.

limit

number

default:"50"

Results per page. Clamped between 1 and 200.

string

Full-text search across all display columns.

obraId

string

Filter rows to only those from the obra with this UUID.

filters

string

URL-encoded JSON object of structured filters keyed by column ID.

Response

rows

MacroTableRow[]

required

Paginated array of row objects. Each row contains:

id — UUID of the source row from obra_tabla_rows
_sourceTablaId — UUID of the source tabla
_sourceTablaName — Name of the source tabla
_obraId — UUID of the parent obra
_obraName — Name of the parent obra
One key per column ID with the resolved value

columns

Column[]

required

Column definitions for the macro table.

pagination

object

required

Show Pagination properties

Request
Response

curl 'https://<domain>/api/macro-tables/mt-uuid-.../rows?page=1&limit=25' \
  --cookie 'sb-access-token=<session>'

{
  "rows": [
    {
      "id": "row-uuid-...",
      "_sourceTablaId": "ot-uuid-...",
      "_sourceTablaName": "Materiales",
      "_obraId": "obra-uuid-...",
      "_obraName": "Escuela N° 42",
      "col-1-uuid": "Cemento Portland",
      "col-2-uuid": 50
    }
  ],
  "columns": [
    { "id": "col-1-uuid", "label": "Material", "columnType": "source", "dataType": "text", "position": 0 },
    { "id": "col-2-uuid", "label": "Cantidad", "columnType": "source", "dataType": "number", "position": 1 }
  ],
  "pagination": { "page": 1, "limit": 25, "total": 1, "totalPages": 1, "hasNextPage": false, "hasPreviousPage": false }
}

Save custom values

POST /api/macro-tables/{id}/rows

string

Upserts custom column values for one or more rows. Only columns with columnType: "custom" are accepted; values for other column types are silently ignored.

Path parameters

string

required

UUID of the macro table.

Request body

customValues

CustomValueInput[]

required

Array of custom values to upsert.

Show CustomValueInput fields

sourceRowId

string

required

UUID of the obra_tabla_rows row this value belongs to.

columnId

string

required

UUID of the custom macro table column.

value

any

required

The value to store (any JSON-serializable type).

Response

boolean

required

Always true on success.

updated

number

required

Number of custom values upserted.

Request
Response

curl -X POST 'https://<domain>/api/macro-tables/mt-uuid-.../rows' \
  --cookie 'sb-access-token=<session>' \
  --header 'Content-Type: application/json' \
  --data '{
    "customValues": [
      {
        "sourceRowId": "row-uuid-...",
        "columnId": "col-custom-uuid",
        "value": "Aprobado"
      }
    ]
  }'

{ "ok": true, "updated": 1 }

GET /api/macro-tables/{id}/sidebar

string

Returns the role-based sidebar visibility assignments for a macro table, along with all available roles for the tenant. Requires admin or owner role (or superadmin).

Path parameters

string

required

UUID of the macro table.

Response

assignments

object[]

required

Current sidebar assignments.

Show Assignment properties

string

Assignment UUID.

role_id

string

UUID of the assigned role.

position

number

Display position in the sidebar.

roles

object[]

required

All roles available for the tenant.

Show Role properties

string

UUID.

key

string

Machine-readable role key.

name

string

Display name.

tenantName

string | null

required

Display name of the tenant that owns this macro table.

POST /api/macro-tables/{id}/sidebar

string

Replaces the sidebar role assignments for a macro table. Roles present in roleIds are added; roles previously assigned but not in the list are removed.

Path parameters

string

required

UUID of the macro table.

Request body

roleIds

string[]

required

Array of role UUIDs that should have this macro table visible in their sidebar.

Response

boolean

required

Always true on success.

Request
Response

curl -X POST 'https://<domain>/api/macro-tables/mt-uuid-.../sidebar' \
  --cookie 'sb-access-token=<session>' \
  --header 'Content-Type: application/json' \
  --data '{ "roleIds": ["role-uuid-1", "role-uuid-2"] }'

{ "ok": true }

List table templates

GET /api/macro-tables/templates

string

Returns the default tabla templates defined for the tenant. Templates represent reusable tabla structures that can be used as the basis for macro table source selection in template mode.

Response

templates

DefaultTabla[]

required

Show DefaultTabla properties

string

UUID of the default tabla.

name

string

Display name.

description

string | null

Optional description.

sourceType

string

Source type identifier.

columnCount

number

Number of columns defined in this template.

Request
Response

curl 'https://<domain>/api/macro-tables/templates' \
  --cookie 'sb-access-token=<session>'

{
  "templates": [
    {
      "id": "tmpl-uuid-...",
      "name": "Planilla de materiales",
      "description": "Estructura estándar para registro de materiales",
      "sourceType": "materials",
      "columnCount": 5
    }
  ]
}

API Endpoints

List macro tables

Response

Create a macro table

Request body

Response

Get a macro table

Path parameters

Response

Update a macro table

Path parameters

Request body

Response

Delete a macro table

Path parameters

Response

List rows

Path parameters

Query parameters

Response

Save custom values

Path parameters

Request body

Response

Get sidebar assignments

Path parameters

Response

Set sidebar assignments

Path parameters

Request body

Response

List table templates

Response

Build docs developers (and LLMs) love

API Endpoints

​List macro tables

​Response

​Create a macro table

​Request body

​Response

​Get a macro table

​Path parameters

​Response

​Update a macro table

​Path parameters

​Request body

​Response

​Delete a macro table

​Path parameters

​Response

​List rows

​Path parameters

​Query parameters

​Response

​Save custom values

​Path parameters

​Request body

​Response

​Get sidebar assignments

​Path parameters

​Response

​Set sidebar assignments

​Path parameters

​Request body

​Response

​List table templates

​Response

Build docs developers (and LLMs) love

List macro tables

Response

Create a macro table

Request body

Response

Get a macro table

Path parameters

Response

Update a macro table

Path parameters

Request body

Response

Delete a macro table

Path parameters

Response

List rows

Path parameters

Query parameters

Response

Save custom values

Path parameters

Request body

Response

Get sidebar assignments

Path parameters

Response

Set sidebar assignments

Path parameters

Request body

Response

List table templates

Response