Skip to content

Create a entity

POST
/{resource}/data/entities
curl --request POST \
--url https://example.com/v1/example/data/entities \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "id": "example", "hidden": true, "pose": { "position": [ 1.5, 0, -3.2 ], "quaternion": [ 0, 0, 0, 1 ] }, "aqrs": [ { "url": "example", "category": 1 } ], "imdf": { "category": "example", "imported": true }, "type": "door", "roles": { "additionalProperty": true } }'

An id is generated if the body doesn’t include one.

With Content-Type: application/geo+json, takes IMDF features. Amenities, occupants with their anchors, and kiosks become landmarks; openings become doors; and fixtures become obstacles. Units are referred to by the ids a GeoJSON read gives them. Only what IMDF describes is written - a landmark’s location, name and category, a door’s location, an obstacle’s shape - so a PUT and a PATCH both leave everything else as it is. IMDF positions are worked out from the space’s georeference, so these need one.

resource
required
string
/^\d+$/

The project ID of the space

One of: discriminator: type

A way through a wall that would otherwise divide the walkable area, such as a doorway. Routes can pass through it in either direction, between points 1m in front of and 1m behind its pose, which is placed on the wall facing out of it. Applied when routes are worked out, so it doesn’t need the navigation mesh to be regenerated.

object
id
required

Identifies the entity. Equal to its key in the space’s entities. Treat it as opaque - new ones are usually UUIDs.

string
>= 1 characters
hidden

Leaves a landmark out of what visitors are shown. It doesn’t stop any entity from affecting routes.

boolean
pose

Where the entity is, and which way it faces. Entities placed by their points don’t use it.

object
position
required

A point [x, y, z] in metres, in the space’s coordinate frame. The frame is shared by every floor and map, with +y up.

array
>= 3 items <= 3 items
quaternion
required

A rotation as a unit quaternion [x, y, z, w]. [0, 0, 0, 1] is no rotation.

array
>= 4 items <= 4 items
aqrs

Accessible QR codes linked to the entity. Currently only used for landmarks.

Array<object>

A physical Accessible QR code (AQR) placed in the space and linked to an entity. Visitors can scan it for more information when settings.scanForAQRs is on.

object
url
required

The URL encoded in the code, which identifies that individual code and the information it links to.

string
category

The code’s numeric category. It can be read from further away than the URL, so it’s used to match a code before its URL has been read.

number
imdf

How the entity relates to IMDF.

object
category

The IMDF category to export the entity with, in place of the one worked out from its type and category - e.g. atm.

string
imported

Whether the entity was created by an IMDF import.

boolean
type
required
string
Allowed value: door
roles

Reserved for limiting the door to certain roles. Not used yet.

object
key
additional properties
boolean

The created entity

One of: discriminator: type

A way through a wall that would otherwise divide the walkable area, such as a doorway. Routes can pass through it in either direction, between points 1m in front of and 1m behind its pose, which is placed on the wall facing out of it. Applied when routes are worked out, so it doesn’t need the navigation mesh to be regenerated.

object
id
required

Identifies the entity. Equal to its key in the space’s entities. Treat it as opaque - new ones are usually UUIDs.

string
>= 1 characters
hidden

Leaves a landmark out of what visitors are shown. It doesn’t stop any entity from affecting routes.

boolean
pose

Where the entity is, and which way it faces. Entities placed by their points don’t use it.

object
position
required

A point [x, y, z] in metres, in the space’s coordinate frame. The frame is shared by every floor and map, with +y up.

array
>= 3 items <= 3 items
quaternion
required

A rotation as a unit quaternion [x, y, z, w]. [0, 0, 0, 1] is no rotation.

array
>= 4 items <= 4 items
aqrs

Accessible QR codes linked to the entity. Currently only used for landmarks.

Array<object>

A physical Accessible QR code (AQR) placed in the space and linked to an entity. Visitors can scan it for more information when settings.scanForAQRs is on.

object
url
required

The URL encoded in the code, which identifies that individual code and the information it links to.

string
category

The code’s numeric category. It can be read from further away than the URL, so it’s used to match a code before its URL has been read.

number
imdf

How the entity relates to IMDF.

object
category

The IMDF category to export the entity with, in place of the one worked out from its type and category - e.g. atm.

string
imported

Whether the entity was created by an IMDF import.

boolean
type
required
string
Allowed value: door
roles

Reserved for limiting the door to certain roles. Not used yet.

object
key
additional properties
boolean

Example

{
"pose": {
"position": [
1.5,
0,
-3.2
],
"quaternion": [
0,
0,
0,
1
]
},
"type": "door"
}

The body is invalid. issues describes what was wrong.

Media typeapplication/json
object
error
required

A description of the error

string
code
required

A stable identifier for the kind of error

string
issues

For invalidBody: what failed validation, and where

Array<object>
object

Example generated

{
"error": "example",
"code": "example",
"issues": [
{}
]
}

The token is missing or invalid.

Media typeapplication/json
object
error
required

A description of the error

string
code
required

A stable identifier for the kind of error

string
issues

For invalidBody: what failed validation, and where

Array<object>
object

Example generated

{
"error": "example",
"code": "example",
"issues": [
{}
]
}

The token has no access to this space.

Media typeapplication/json
object
error
required

A description of the error

string
code
required

A stable identifier for the kind of error

string
issues

For invalidBody: what failed validation, and where

Array<object>
object

Example generated

{
"error": "example",
"code": "example",
"issues": [
{}
]
}

An item with this id already exists or the space is being duplicated - or, for IMDF, the space has no georeference or floors (noGeoreference, noFloors) or is missing information IMDF requires (imdfIncomplete).

Media typeapplication/json
object
error
required

A description of the error

string
code
required

A stable identifier for the kind of error

string
issues

For invalidBody: what failed validation, and where

Array<object>
object

Example generated

{
"error": "example",
"code": "example",
"issues": [
{}
]
}

The body isn’t in a format this operation accepts.

Media typeapplication/json
object
error
required

A description of the error

string
code
required

A stable identifier for the kind of error

string
issues

For invalidBody: what failed validation, and where

Array<object>
object

Example generated

{
"error": "example",
"code": "example",
"issues": [
{}
]
}

Too many requests. Retry after Retry-After seconds.

Media typeapplication/json
object
error
required

A description of the error

string
code
required

A stable identifier for the kind of error

string
issues

For invalidBody: what failed validation, and where

Array<object>
object

Example generated

{
"error": "example",
"code": "example",
"issues": [
{}
]
}
Retry-After
integer

Seconds to wait before retrying

Something upstream failed.

Media typeapplication/json
object
error
required

A description of the error

string
code
required

A stable identifier for the kind of error

string
issues

For invalidBody: what failed validation, and where

Array<object>
object

Example generated

{
"error": "example",
"code": "example",
"issues": [
{}
]
}

The space is moving between servers. Retry after Retry-After seconds.

Media typeapplication/json
object
error
required

A description of the error

string
code
required

A stable identifier for the kind of error

string
issues

For invalidBody: what failed validation, and where

Array<object>
object

Example generated

{
"error": "example",
"code": "example",
"issues": [
{}
]
}
Retry-After
integer

Seconds to wait before retrying

Something upstream timed out.

Media typeapplication/json
object
error
required

A description of the error

string
code
required

A stable identifier for the kind of error

string
issues

For invalidBody: what failed validation, and where

Array<object>
object

Example generated

{
"error": "example",
"code": "example",
"issues": [
{}
]
}