# Archilogic Developer Documentation > APIs and SDKs for building on Archilogic's spatial data platform. Archilogic provides tools to render, > query, and programmatically interact with floor plan data — including a 2D/3D rendering SDK, a REST API, > a GraphQL API, and a remote MCP server for AI agent access. > > **Raw Markdown** versions of every page are served alongside the HTML. To fetch the source of any page, > append `.md` to the URL path (e.g. `https://developers.archilogic.com/space-graph/geometries.md`). --- ## Floor Plan SDK Install via `npm install @archilogic/floor-plan-sdk`. In v5 the constructor takes a single object: `new FloorPlanEngine({ container, options })` — not two positional arguments as in v3. Also import the stylesheet: `import '@archilogic/floor-plan-sdk/dist/style.css'`. Load a floor with `floorPlan.loadFloorById(floorId, { publishableAccessToken })` (renamed from `loadScene` in v3; the token key is `publishableAccessToken`, **not** `publishableToken`). Options can be updated at runtime with `floorPlan.set(options)`. Query methods (`getSpaces`, `getElements`, `getElementById`, `getSpaceById`) are synchronous (unlike the async Extension SDK equivalents). Each accepts a `{ where, select }` object; the default `select` returns `{ id, type }` only — explicitly list other fields like `area`, `contour`, or `elements` to receive them. Theming is set under `options.theme` with sub-keys `byType`, `byId`, and `byFilter` (an array; the **last** matching filter wins). Markers use `position` (not `pos` as in v3); the same rename applies to `click` and `mousemove` event callbacks: `floorPlan.on('click', ({ position, sourceEvent, nodeId }) => {})`. - [Guide](https://developers.archilogic.com/floor-plan-engine/guide): Integration guide for the WebGL-based 2D floor plan rendering SDK - [API Reference](https://developers.archilogic.com/floor-plan-engine/api): Full JavaScript/TypeScript API reference - [Changelog](https://developers.archilogic.com/floor-plan-engine/changelog): Version history and migration notes --- ## 3D Embed API Install via `npm install @archilogic/embed-api` or load from `https://unpkg.com/@archilogic/embed-api`. Construct with `new ArchilogicEmbed(container, options)` then `await viewer.viewerReadyPromise` before calling any methods. Load a 3D scene with `viewer.loadScene(sceneId, { publishableAccessToken })` — the publishable token **must** allow the `viewer.archilogic.com` domain. All navigation and mutation methods return promises; `set(options)` deep-merges an update into the current options. Key startup options: `transparentBackground`, `minimap`, `showTitle`, `showLogo`, `presentationMode` (use the `PresentationMode` enum: `jumpToCameraDefault`, `tourLoop`, `tourOnce`, etc.), and the `uiButtons` map to hide/show individual toolbar controls. Call `viewer.zoomExtents({ spaceId })` to fly to a specific space. Cleanup with `viewer.destroy()` which stops messaging and removes event listeners. - [Guide](https://developers.archilogic.com/3d-embed-api/guide): Embed interactive 3D floor plans in any webpage via iframe - [Examples](https://developers.archilogic.com/3d-embed-api/examples): Code examples for the 3D Embed API - [Changelog](https://developers.archilogic.com/3d-embed-api/changelog): Version history --- ## Extension SDK Extensions export a `run({ hostApi, container?, parameters? })` function executed inside a sandbox. **Editor** extensions can render UI inside `container` (an iframe) and subscribe to events (`layout-change`, `selection-change`, `canvas-click`). **Cloud Worker** extensions must `return` a value from `run`; they are invoked via `POST /v2/floor/:floorId/extensions/:extensionId` and are automatically exposed as MCP tools for the organization. The `hostApi` query methods (`getSpaces`, `getElements`, `getElementById`, `getSpaceById`, `getProducts`) are **async** (unlike the synchronous Floor Plan SDK equivalents) and share the same `{ where, select }` shape. Mutation is done through the operations endpoint using typed operation objects (e.g. `operation:spaceUpdate`). Gotcha: worker extensions must return something — an extension that completes without returning will yield an empty response to the caller. PDF export is available via `hostApi.exportPdf({ orientation, format, skipDownload? })`; `orientation` is `'landscape' | 'portrait'`, `format` is `'A4' | 'A3' | 'letter'`. SVG export is available via `hostApi.exportSvg({ skipDownload? })`. Both methods trigger a browser download by default in editor extensions, and only return a value when `skipDownload: true` (`ArrayBuffer` for PDF, `string` for SVG). Other export formats (DXF, GeoJSON, IMDF, IFC, GLTF) are not yet available. - [Guide](https://developers.archilogic.com/extension-sdk/guide): Build extensions for the Archilogic platform, including headless cloud worker execution - [Setup](https://developers.archilogic.com/extension-sdk/setup): Setup and configuration guide - [API Reference](https://developers.archilogic.com/extension-sdk/api): Extension SDK API reference - [Changelog](https://developers.archilogic.com/extension-sdk/changelog): Version history --- ## Space API — Authentication Three token types serve different roles. **Publishable tokens** are safe to ship in frontend code; they are restricted to the `floor:readPublic`, `floor:queryPublic`, `customAttributes:read`, and `customAttributeValues:readPublic` scopes and are validated against an allowed-domain list — pass them as the `pubtoken` query parameter. **Secret tokens** carry all scopes and must only be used server-side; pass as `Authorization: Bearer `. **Temporary tokens** are minted server-side via `POST /v2/temporary-access-token/create` (authenticated with the secret token) and returned as `{ authorization, expiresAt }`; the frontend then uses `authorization` directly as a Bearer value. Gotcha: publishable tokens for the **3D Embed API** must explicitly allow `viewer.archilogic.com` as an origin — without it the viewer will be blocked even with a valid token. Scopes for temporary tokens must be a subset of the minting secret token's scopes; `durationSeconds` defaults to 3600 (min 900, max 86400). OAuth 2.0 is supported for third-party apps acting on behalf of users. - [Authentication](https://developers.archilogic.com/space-api/authentication): Access token types and authentication guide - [OAuth 2.0](https://developers.archilogic.com/space-api/oauth): OAuth 2.0 authorization flow --- ## Space API — REST Base URL: `https://api.archilogic.com/v2/{resource}`. The API exposes floors, layouts, spaces, assets, and custom-attribute definitions. Rate limits: 30,000 requests/5 min per IP for single-resource reads; 3,000 requests/5 min per IP for list queries and export operations. Floors can be exported as GeoJSON, PNG/SVG, DXF, IFC, GLTF, IMDF, or PDF. Layout endpoints (CRUD + revisions + `operations`) are only available to customers on Space Graph. The `POST /layout/{layoutId}/operations` endpoint is the primary write path for spatial data — it accepts an array of typed operation objects such as `operation:spaceUpdate` or `operation:assetMove`. Gotcha: `GET /floor` and `GET /space` return paginated lists; always check for a `next` cursor. Webhook payloads must be validated using the shared secret; event types include `floor.updated`, `layout.updated`, and `layout.published`. - [Introduction](https://developers.archilogic.com/space-api/v2/introduction): REST API overview, base URL, rate limits, and authentication - [Webhooks](https://developers.archilogic.com/space-api/v2/webhooks): Webhook setup, event types, and payload validation - [Examples](https://developers.archilogic.com/space-api/v2/examples): REST API code examples --- ## Space API — GraphQL Endpoint: `https://api.archilogic.com/graphql`. Uses the same token/scope system as the REST API. Main entry-point queries: `getBuildings`, `getBuildingById`, `getFloors(where: FloorFilter, archived: Boolean)`, `getFloorById(id)`, and `getLayoutById(id)`. Floors expose `area`, `spaceCount`, `elementCount`, and `elementSurfaceArea` as aggregation fields that each accept an inline `where` filter, e.g. `meetArea: area(where: { category: { eq: "meet" } })`. Filters use comparator objects: `NumberComparator` (`eq`, `gt`, `gte`, `lt`, `lte`), `StringComparator`, `DateComparator`; and can be composed with `or`/`and` arrays. Custom attributes are filtered via `customAttribute: { key: { eq: "dept" }, value: { eq: "Product" } }` — the `key` field matches the definition's `apiFieldName`. Gotcha: `getFloors` returns a wrapper object `{ floors: [...] }`, not a bare array — destructure accordingly. The GraphQL API requires a Space Graph subscription. **Archived floors**: `getFloors` excludes archived floors by default — pass `archived: true` to query only archived floors. `getFloorById` and `getLayoutById` resolve any floor regardless of its archived state. The `isArchived` field is available on the Floor object. For archived floors, SpaceGraph-derived fields return degraded values: `spaces`, `elements`, `adjacentSpaces`, and `customAttributes` return `[]`; `spaceCount`, `elementCount`, `seatCapacity`, and `elementSurfaceArea` return `null` (not `0`). Floor-level DB properties (id, name, area, level, labels, location, categories, isPrivate, isArchived, createdAt, updatedAt) are always available. - [Introduction](https://developers.archilogic.com/space-api/graphql/introduction): GraphQL API endpoint and available queries - [Resources](https://developers.archilogic.com/space-api/graphql/resources): Building, Floor, Space, and Asset object schemas with field definitions - [Filtering](https://developers.archilogic.com/space-api/graphql/filtering): Filter parameters for buildings, floors, and spaces - [Pagination](https://developers.archilogic.com/space-api/graphql/pagination): Cursor-based pagination guide - [Examples](https://developers.archilogic.com/space-api/graphql/examples): GraphQL code examples --- ## Space API — MCP Server The Archilogic MCP Server is a **remote** server at `https://mcp.archilogic.com/mcp` using Streamable HTTP transport (Beta — breaking changes possible). Connect from Claude Desktop by adding an `archilogic` entry with `command: "npx", args: ["mcp-remote", "https://mcp.archilogic.com/mcp"]`; other clients that support remote Streamable HTTP can connect directly. Authentication is via OAuth 2.0 — the client is prompted on first connect. Available operations: `list_buildings`, `list_floors` (supports filtering by name, area, seat capacity, space count, and space properties), `list_spaces_by_floor` (returns area, category, subCategory, and assets), `get_floor_space_metrics` (area broken down by category: work/meet/care/socialize/circulate/support, plus seat capacity and space counts), `get_floor_element_metrics` (workstation, lighting, seating, table, storage counts plus windows/doors/walls), `get_floor_filter_options` (discovers filterable attribute values on a floor), and `export_floor_pdf` (styled PDF with optional `byFilter` color-coding). Custom worker extensions are automatically exposed as additional MCP operations for the organization. - [Introduction](https://developers.archilogic.com/space-api/mcp-server/introduction): Remote MCP server setup, operations, and extension --- ## Space Graph Data Model The Space Graph is Archilogic's graph-based spatial data format. A floor has one or more **layouts**; the default layout is what REST/GraphQL queries target unless `getLayoutById` is specified. **Coordinate system**: right-handed, X+ east, Y+ up, Z+ south; `position` is `[x, y, z]`; `rotation` is in **degrees** (positive = counter-clockwise); default `rotationAxis` is `[0, 1, 0]` (up). All units are in meters. **Spaces** have `category` and `subCategory` fields (e.g. `category: "work"`, `subCategory: "privateOffice"`) — these are the correct query keys; do not use `type` or `usage` for space taxonomy. **Elements** are typed with a `type` string such as `element:wall`, `element:window`, `element:door`, `element:asset` (furniture). Transform elements (`element:asset`, etc.) use `position`/`rotation` for placement; edge elements (`element:wall`) reference an `edge` ID from the spatial graph and have `parameters.height`, `parameters.width`, `parameters.offset`. **Custom attributes** are defined per resource type with an `apiFieldName` (the query/mutation key), a `title`, and a JSON Schema `valueType`; values are set via layout operations and queried with `customAttributes: { key, value }`. - [Introduction](https://developers.archilogic.com/space-graph/): Overview of the graph-based spatial data format - [Spatial Graph](https://developers.archilogic.com/space-graph/spatial-graph): Core spatial graph concept and structure - [Spaces](https://developers.archilogic.com/space-graph/spaces): Space objects — rooms and programmatic areas; `category`/`subCategory` taxonomy - [Elements](https://developers.archilogic.com/space-graph/elements): Architectural elements — walls, doors, windows, assets; edge vs transform vs boundary types - [Products](https://developers.archilogic.com/space-graph/products): Furniture and product objects - [Components](https://developers.archilogic.com/space-graph/components): Component model - [Custom Attributes](https://developers.archilogic.com/space-graph/custom-attributes): Definition (`apiFieldName`, `schema`) and value management - [Geometries](https://developers.archilogic.com/space-graph/geometries): Geometry formats and coordinate system (right-handed, X+ east, Y+ up, Z+ south, rotation in degrees CCW) ## Space REST API Operations - [List floors](https://developers.archilogic.com/space-api/v2/reference/operations/floor-get): `GET /floor` - [Create floor](https://developers.archilogic.com/space-api/v2/reference/operations/floor-post): `POST /floor` - [Update floor](https://developers.archilogic.com/space-api/v2/reference/operations/floor-patch): `PATCH /floor` - [Get floor](https://developers.archilogic.com/space-api/v2/reference/operations/floor-floorid-get): `GET /floor/{floorId}` - [Export floor as GeoJSON](https://developers.archilogic.com/space-api/v2/reference/operations/floor-floorid-geojson-get): `GET /floor/{floorId}/geo-json` - [Export floor as PNG / SVG](https://developers.archilogic.com/space-api/v2/reference/operations/floor-floorid-2d-image-post): `POST /floor/{floorId}/2d-image` - [Export floor as DXF](https://developers.archilogic.com/space-api/v2/reference/operations/floor-floorid-dxf-post): `POST /floor/{floorId}/dxf` - [Export floor as IFC](https://developers.archilogic.com/space-api/v2/reference/operations/floor-floorid-ifc-post): `POST /floor/{floorId}/ifc` - [Export floor as GLTF](https://developers.archilogic.com/space-api/v2/reference/operations/floor-floorid-gltf-post): `POST /floor/{floorId}/gltf` - [Export floor as IMDF](https://developers.archilogic.com/space-api/v2/reference/operations/floor-floorid-imdf-post): `POST /floor/{floorId}/imdf` - [Archive a floor](https://developers.archilogic.com/space-api/v2/reference/operations/floor-floorid-archive-post): `POST /floor/{floorId}/archive` - [Unarchive a floor](https://developers.archilogic.com/space-api/v2/reference/operations/floor-floorid-unarchive-post): `POST /floor/{floorId}/unarchive` - [Duplicate a floor](https://developers.archilogic.com/space-api/v2/reference/operations/floor-floorid-duplicate-post): `POST /floor/{floorId}/duplicate` - [Assign label to floor](https://developers.archilogic.com/space-api/v2/reference/operations/floor-floorid-label-labeltitle-put): `PUT /floor/{floorId}/label/{labelTitle}` - [Remove a label](https://developers.archilogic.com/space-api/v2/reference/operations/floor-floorid-label-labeltitle): `DELETE /floor/{floorId}/label/{labelTitle}` - [List layouts](https://developers.archilogic.com/space-api/v2/reference/operations/layout-get): `GET /layout` - [Create a layout](https://developers.archilogic.com/space-api/v2/reference/operations/layout-post): `POST /layout` - [Get layout](https://developers.archilogic.com/space-api/v2/reference/operations/layout-layoutid-get): `GET /layout/{layoutId}` - [Update layout](https://developers.archilogic.com/space-api/v2/reference/operations/layout-layoutid-patch): `PATCH /layout/{layoutId}` - [Delete layout](https://developers.archilogic.com/space-api/v2/reference/operations/layout-layoutid-delete): `DELETE /layout/{layoutId}` - [Duplicate a layout](https://developers.archilogic.com/space-api/v2/reference/operations/layout-layoutid-duplicate-post): `POST /layout/{layoutId}/duplicate` - [List layout revisions](https://developers.archilogic.com/space-api/v2/reference/operations/layout-layoutid-revisions-get): `GET /layout/{layoutId}/revisions` - [Create a layout revision](https://developers.archilogic.com/space-api/v2/reference/operations/layout-layoutid-revisions-post): `POST /layout/{layoutId}/revisions` - [Get layout revision](https://developers.archilogic.com/space-api/v2/reference/operations/layout-layoutid-revisions-revisionid-get): `GET /layout/{layoutId}/revisions/{revisionId}` - [Run layout operations](https://developers.archilogic.com/space-api/v2/reference/operations/layout-layoutid-operations-post): `POST /layout/{layoutId}/operations` - [List spaces](https://developers.archilogic.com/space-api/v2/reference/operations/space-get): `GET /space` - [Get space](https://developers.archilogic.com/space-api/v2/reference/operations/space-spaceid-get): `GET /space/{spaceId}` - [Get space GeoJSON](https://developers.archilogic.com/space-api/v2/reference/operations/space-spaceid-geojson-get): `GET /space/{spaceId}/geo-json` - [List assets](https://developers.archilogic.com/space-api/v2/reference/operations/asset-get): `GET /asset` - [Get asset](https://developers.archilogic.com/space-api/v2/reference/operations/asset-assetid-get): `GET /asset/{assetId}` - [Get asset GeoJSON](https://developers.archilogic.com/space-api/v2/reference/operations/asset-assetid-geojson-get): `GET /asset/{assetId}/geo-json` - [List definitions](https://developers.archilogic.com/space-api/v2/reference/operations/custom-attributes-get): `GET /custom-attributes` - [List definitions for resource type](https://developers.archilogic.com/space-api/v2/reference/operations/resourcetype-custom-attributes-get): `GET /{resourceType}/custom-attributes` - [Create definition](https://developers.archilogic.com/space-api/v2/reference/operations/resourcetype-custom-attributes-post): `POST /{resourceType}/custom-attributes` - [Update definition](https://developers.archilogic.com/space-api/v2/reference/operations/resourcetype-custom-attributes-patch): `PATCH /{resourceType}/custom-attributes` - [Delete definition](https://developers.archilogic.com/space-api/v2/reference/operations/resourcetype-custom-attributes-delete): `DELETE /{resourceType}/custom-attributes` - [Get definitions for resource type and key](https://developers.archilogic.com/space-api/v2/reference/operations/resourcetype-custom-attributes-apifieldname-get): `GET /{resourceType}/custom-attributes/{apiFieldName}` - [Create temporary access token](https://developers.archilogic.com/space-api/v2/reference/operations/temporary-access-token-create-post): `POST /temporary-access-token/create` - [List labels](https://developers.archilogic.com/space-api/v2/reference/operations/label-get): `GET /label` - [Get label](https://developers.archilogic.com/space-api/v2/reference/operations/label-title-get): `GET /label/{title}` - [Create or update label](https://developers.archilogic.com/space-api/v2/reference/operations/label-title-put): `PUT /label/{title}` - [Delete label](https://developers.archilogic.com/space-api/v2/reference/operations/label-title-delete): `DELETE /label/{title}` - [List webhooks](https://developers.archilogic.com/space-api/v2/reference/operations/webhook-get): `GET /webhook` - [Create webhook](https://developers.archilogic.com/space-api/v2/reference/operations/webhook-post): `POST /webhook` - [Get webhook](https://developers.archilogic.com/space-api/v2/reference/operations/webhook-webhookid-get): `GET /webhook/{webhookId}` - [Update webhook](https://developers.archilogic.com/space-api/v2/reference/operations/webhook-webhookid-patch): `PATCH /webhook/{webhookId}` - [Delete webhook](https://developers.archilogic.com/space-api/v2/reference/operations/webhook-webhookid-delete): `DELETE /webhook/{webhookId}` - [List extensions](https://developers.archilogic.com/space-api/v2/reference/operations/extensions-get): `GET /extensions` - [Create extension](https://developers.archilogic.com/space-api/v2/reference/operations/extensions-post): `POST /extensions` - [Add a new version](https://developers.archilogic.com/space-api/v2/reference/operations/extensions-patch): `PATCH /extensions/{extensionId}` - [Delete extension](https://developers.archilogic.com/space-api/v2/reference/operations/extensions-delete): `DELETE /extensions/{extensionId}` - [List buildings](https://developers.archilogic.com/space-api/v2/reference/operations/buildings-get): `GET /buildings` - [Create building](https://developers.archilogic.com/space-api/v2/reference/operations/buildings-post): `POST /buildings` - [Get building](https://developers.archilogic.com/space-api/v2/reference/operations/buildings-buildingid-get): `GET /buildings/{buildingId}` - [Update building](https://developers.archilogic.com/space-api/v2/reference/operations/buildings-buildingid-patch): `PATCH /buildings/{buildingId}` - [Delete building](https://developers.archilogic.com/space-api/v2/reference/operations/buildings-buildingid-delete): `DELETE /buildings/{buildingId}` ## Optional - [Space API Changelog](https://developers.archilogic.com/space-api/changelog): REST and GraphQL API version history - [Floor Plan SDK Changelog](https://developers.archilogic.com/floor-plan-engine/changelog): Floor Plan SDK version history - [Extension SDK Changelog](https://developers.archilogic.com/extension-sdk/changelog): Extension SDK version history - [3D Embed API Changelog](https://developers.archilogic.com/3d-embed-api/changelog): 3D Embed API version history - [Floor Plan SDK v3 Guide](https://developers.archilogic.com/floor-plan-engine/v3/guide): Legacy v3 documentation