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/{workspace}/schema/introspect/{source} to read the data source's live schema, reconcile the workspace's model to match, and get back the set of changes that were detected.

{source} is the ID of the data source to introspect. A request without a body applies every detected change except those covered by the source's stored exclusions.

Preview changes with POST /api/{workspace}/schema/introspect/{source}/diff. It returns detected operations without applying them and ignores stored exclusions, so the preview includes previously excluded collections.

To choose what gets applied, send the operations returned by the diff together with the exclusions to store. Monospace drops the operations that would import an excluded namespace or collection. Send the body with a Content-Type: application/json header — a request without a Content-Type header is treated as having no body.

{
  "migration": { "operations": [] },
  "introspection": {
    "excludedNamespaces": [{ "dbName": "analytics" }],
    "excludedCollections": [{ "namespaceDbName": "blog", "dbName": "comments" }]
  }
}

Omit namespaceDbName for a collection outside any namespace. The lists you send replace the source's stored exclusions.

Changes to existing collections are always applied; you can choose only among collections being added. If your selection leaves the model inconsistent with the source, the request fails with 422 and commits nothing. The response lists the remaining operations in meta.residual.operations.

To apply a re-scan using the stored exclusions, send a request without a 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 applied changes in a data envelope. Operations skipped because of exclusions are not included. 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 workspace 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 workspace's stored model inside a transaction before returning it, so the workspace 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 workspace. 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