Import Changes

Import Changes Made Outside Monospace

When a collection or field is added, altered, or deleted directly in a data source — through SQL, another tool, or a separate migration system — Monospace does not see it until you re-introspect. Send a request to POST /api/{project}/schema/introspect/{source} to read the data source's live schema, reconcile the project's model to match, and get back the set of changes that were detected.

{source} is the ID of the data source to introspect. The request takes no body.

curl -X POST https://example.monospace.io/api/blog/schema/introspect/d7c8f0e2-9b3a-4c1e-8f2a-1a2b3c4d5e6f \
  -H "Authorization: Bearer YOUR_API_KEY"

const source = 'd7c8f0e2-9b3a-4c1e-8f2a-1a2b3c4d5e6f'

const response = await fetch(
  `https://example.monospace.io/api/blog/schema/introspect/${source}`,
  {
    method: 'POST',
    headers: { Authorization: 'Bearer YOUR_API_KEY' },
  },
)

const { data } = await response.json()

Response

The response wraps the detected changes in a data envelope. The operations array is a migration in the standard format — the same operations you would author by hand.

When a field was added to the articles collection outside Monospace, the diff reports it as an updateCollection that creates the new field:

{
  "data": {
    "operations": [
      {
        "kind": "updateCollection",
        "data": {
          "id": "f4ccfb8e-5d79-4d2f-83b0-5b749f784b00",
          "operations": [
            {
              "kind": "createPrimitiveField",
              "data": {
                "id": "a7b8c9d0-5555-4a1a-9c1a-666677778888",
                "dbName": "subtitle",
                "apiName": "subtitle",
                "type": { "name": "string", "params": { "length": "unlimited" } },
                "isNullable": true,
                "isList": false,
                "defaultValue": null,
                "readonly": false
              }
            }
          ]
        }
      }
    ]
  }
}

The detected operations use the same shapes documented in the Operation Reference. Introspected fields also carry readonly — true when the data source exposes the field through a view or computed field, false for a regular field.

No Pending Changes

When the project already matches the data source, the diff is empty.

{
  "data": {
    "operations": []
  }
}

Reconciliation Behavior

Introspection is not a dry run. Monospace applies the detected diff to the project's stored model inside a transaction before returning it, so the project reflects the data source as soon as the call succeeds. The returned operations tell you what changed.

A rename made directly in the data source is not detected as a rename. A renamed collection or field appears in the diff as a delete of the old object followed by a create of the new one; deleted objects appear as delete operations. To preserve a rename in the model, apply renameCollection or renamePrimitiveField through the migrate endpoint instead of renaming in the data source.

This endpoint reconciles in one direction only — from the data source into the project. It never writes to the data source. To push a change the other way, author it and send it to the migrate endpoint.

See Also

• Apply Migrations — push a change you designed to a data source
• Operation Reference — read the operations returned in a diff
• Introspection — how Monospace reads a data source's schema
• Schema Migration Overview — authentication, format, and error codes