Skip to main content

Spaces

createSpace

To create a space programmatically, you can call the following query.

smplrClient.createSpace({
  organizationId: string
  name: string
  notes?: string
  tags?: string[]
  addToProjectId?: string
}): Promise<{ sid: string }>

With sid the Smplrspace ID of the space.

  • organizationId is the unique identifier of your organization in Smplrspace, something like "fbc5617e-5a27-4138-851e-839446121b2e". Personal accounts are also treated as "personal organization". To get your organization's ID, head to the Developers page from the main menu.
  • name is the name of the space to create.
  • notes - optional - are internal team notes attached to the space.
  • tags - optional - an array of tags to add to the space. If a tag doesn't exist, it will be created automatically.
  • addToProjectId - optional - the unique identifier of a project to add the space to upon creation. This only takes effect when using a project-scoped API token that includes the specified project.

setSpaceStatus

You can call the following query to programmatically publish, set as draft, or archive a space.

smplrClient.setSpaceStatus({ 
  spaceId: string; 
  status: 'published' | 'draft' | 'archived' 
}): Promise<{ status: string }>
  • spaceId - unique identifier of the space in Smplrspace, something like "spc_xxx". Refer to the page on SIDs to learn more.
  • status - one of the possible statuses, with "published" corresponding to "live" in the platform.

deleteSpace

You can call the following query to programmatically delete a space.

smplrClient.deleteSpace(spaceId: string): Promise<void>
  • spaceId - unique identifier of the space in Smplrspace, something like "spc_xxx". Refer to the page on SIDs to learn more.

listSpaces

To list all the spaces on your organization account, you can call the following query.

smplrClient.listSpaces({ 
  organizationId: string
  tagged?: string[]
  projects?: string[]
  unit?: 'sqm' | 'sqft'
  includeLevelBreakdown?: boolean
}): Promise<{
  sid: string
  deprecated_id: string
  name: string
  created_at: string
  status: string
  area: number
  projects: {
    project_sid: string
    name: string
  }[]
  levels?: {
    name: string
    area: number
  }[]
}[]>
  • organizationId is the unique identifier of your organization in Smplrspace, something like "fbc5617e-5a27-4138-851e-839446121b2e". Personal accounts are also treated as "personal organization". To get your organization's ID, head to the Developers page from the main menu.
  • tagged - optional - an array of tags to filter spaces. Only spaces that have all the specified tags will be returned (AND logic).
  • projects - optional - an array of project SIDs to filter spaces. Only spaces belonging to at least one of the specified projects will be returned (OR logic). Note that if you are using a project-scoped client token, the filtering is applied automatically and this parameter is not needed.
  • unit - optional - the unit for area values in the response. Defaults to 'sqm'.
  • includeLevelBreakdown - optional - set to true to include a levels array in the response with per-level area data. Defaults to false.

Each space in the returned array contains:

  • sid - the Smplrspace ID of the space.
  • deprecated_id - the legacy UUID identifier. See the page on SIDs for details.
  • name - the display name of the space.
  • created_at - the ISO 8601 timestamp when the space was created.
  • status - one of 'draft', 'published', or 'archived'.
  • area - the total floor area of the published space, in the unit specified by the unit parameter.
  • projects - the list of projects the space belongs to. Each entry includes project_sid and name.
  • levels - present only when includeLevelBreakdown is true - the list of levels in the published space, each with a name and area (in the specified unit). Ordered from ground level up.

getSpace

To get all details about a space, you can call the following query.

smplrClient.getSpace(spaceId: string, options?: { useCache?: boolean }): Promise<{
  sid: string // spaceId
  created_at: string
  modified_at: string
  name: string
  public_link_enabled: boolean
  status: 'draft' | 'published' | 'archived'
  definition: object | null
  embed_image: string | null
  short_code: string | null
  assetmap: object | null
}>
  • spaceId - unique identifier of the space in Smplrspace, something like "spc_xxx". Refer to the page on SIDs to learn more.
  • options - optional - as described below.
  • options.useCache - optional - set this to control whether the request should use the client's local cache. Default value: false

getSpaceFromCache

This is the synchronous equivalent of the query right above.

smplrClient.getSpaceFromCache(spaceId: string): Space

where spaceId and Space are as defined in getSpace, without the Promise.

getSpaceLevels

To get the list of levels in a space, you can call the following query.

smplrClient.getSpaceLevels(spaceId: string): Promise<{
  index: number
  name: string
  initials: string
}[]>
  • spaceId - unique identifier of the space in Smplrspace, something like "spc_xxx". Refer to the page on SIDs to learn more.

Each level in the returned array contains:

  • index - zero-based position of the level in the space.
  • name - display name of the level, e.g. "Ground floor". Defaults to "Level N" if not set.
  • initials - short label for the level, e.g. "GF". Defaults to "LN" if not set.

getSpaceLevelsFromCache

This is the synchronous equivalent of the query right above.

smplrClient.getSpaceLevelsFromCache(spaceId: string): {
  index: number
  name: string
  initials: string
}[]

where spaceId and the return value are as defined in getSpaceLevels, without the Promise.

getSpaceAssetmap (entities)

info

"Assets" are gradually being renamed to "Entities". You'll read entity/ies is the app and asset(s) here, until the change is complete. They are one and the same concept. Except this API to be deprecated soon, and a much wider API surface to be introduced as the entity manager enters general availability.

To get the full assetmap (list of entities) of a space, as saved in the entity manager (previously mapper) in the app, you can call the following query.

smplrClient.getSpaceAssetmap(spaceId: string): Promise<unknown>
  • spaceId - unique identifier of the space in Smplrspace, something like "spc_xxx".

Note that this query is currently not typed as the entity manager (previously mapper) is still in private beta. You should expect an array of "entity groups" (previously asset groups), each "entity group" being an object. The return value corresponds to the JSON export from the entity manager (previously mapper) in the app.

getSpaceAssetmapFromCache

This is the synchronous equivalent of the query right above.

smplrClient.getSpaceAssetmapFromCache(spaceId: string): unknown

where spaceId and the return value are as defined in getSpaceAssetmap.

Need any other data?

Get in touch with any use-case that would require new queries to be exposed.