monospace

Monospace

Work with a Monospace instance: query and mutate data through the REST API or the typed SDK, generate instance-specific types, bootstrap workspaces and discover schema, and use the per-workspace MCP server. Read the traps below, then load the reference that matches the task.

Verified against engine source 4f6f48c (reports 0.7.0) with @monospace/sdk 0.8.0 and @monospace/cli 0.1.0 from continuous build 31d52d0. Monospace is in early access. If an instance behaves differently, trust the instance and its error messages.

Principles

1. Don't guess the API. Monospace has a different API and SDK from Directus. The sources of truth are the types generated from the instance (monospace sdk generate), the instance's own responses and error messages, and these references. The workspace OpenAPI document describes item routes (use it for payload shapes and codegen). It is not a complete or fully correct catalog of management and schema routes, so use bootstrap-and-schema.md for those.
2. Generate types, then write against them. Examples here use illustrative collection and field names, so adapt names and types to the generated schema.
3. Inspect, write, verify. Read the schema and existing rows before writing. Send an explicit fields selection on item reads and writes. Afterwards, read back using the same key or the user's exact filter.
4. Recover, don't loop. Read the error body, including its nested source chain. After 2–3 failed attempts, re-check the schema, permissions, and license instead of retrying.

Critical traps

• Envelopes depend on the endpoint. Item and most management responses are { data } (plus meta when requested). JSON login, /api/system/info, the /schema manifest, and OpenAPI are bare. A raw item POST returns a data array even for one object. The SDK unwraps only the top level. Nested to-many relations stay relation.data, and to-one relations are direct.
• Deletes need a selection. Use deleteOne({ key, fields: ['id'] }) / deleteMany({ filter, fields: ['id'] }) / DELETE …?fields=id. Without one, the engine returns 422 and the row remains. Confirm with a read-back.
• SDK call shape: method(parameters, options?). The first argument is an object ({ key, data, fields, include, filter, sort, limit, offset, meta }), never a positional id. The optional second argument is { unwrapEnvelope: false }, needed to keep meta.totalCount. Collections are cased as named (client.Articles).
• fields selects scalars, include selects relations. Example: fields: ['id'], include: { author: { fields: ['name'] } }. Don't use dotted paths, nested objects in fields, or deep. Inside include, arguments are filter/sort/limit/offset (no underscore), and operators keep underscores (_eq).
• Filters use underscore operators (_eq, _in, _null), combined with _and/_or/_not, and _some/_every/_none on to-many relations. The full operator table is in the REST reference. _null works only on nullable fields. Field and connector capabilities decide what is filterable, sortable, and writable.
• Sort uses the object form sort: [{ field: { direction: 'desc' } }]. -field is rejected.
• No search, no page or cursor, no aggregates. Use limit (default 100) + offset + a stable sort, and meta for totalCount. Unknown parameters can be silently ignored with a 200, so a success status doesn't prove a parameter was applied.
• 64-bit integers are strings on output. Input accepts string | number, but values outside the safe integer range can round before transmission, so pass large integers as strings. Decimals are strings too. Don't convert money through floats.
• Built-in SDK transport errors: only 401 (MonospaceAuthError) and 403 (MonospacePermissionError) get subclasses. Validation failures (400/422), 402 license limits, and 404s arrive as base MonospaceError, so branch on .status. MonospaceValidationError is not currently thrown.
• One credential per request. A bearer token plus a stale session cookie returns 400. API keys act as their subject user, with no per-key scope. Creating another key for the same user doesn't change what it can do.
• Check the license before designing access control. The keyless Starter profile allows 0 custom roles, 0 custom policies, 0 service accounts, and 1 workspace (402 otherwise). Client-side filtering with administrator credentials is not tenant isolation.