Create

Create makes a new entity with POST /entities and answers 201. It never overwrites. An id that is already taken is refused with 409 AlreadyExists.

http

POST /ngsi-ld/v1/entities
Content-Type: application/json

{
    "id": "urn:ngsi-ld:Vehicle:A4567",
    "type": "Vehicle",
    "speed": {
        "type": "Property",
        "value": 52
    }
}

curl

curl -i http://localhost:1056/ngsi-ld/v1/entities \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "urn:ngsi-ld:Vehicle:A4567",
    "type": "Vehicle",
    "speed": {
        "type": "Property",
        "value": 52
    }
}'

rust

let vehicle = Entity::builder()
    .id(iri!("urn:ngsi-ld:Vehicle:A4567"))
    .entity_type("Vehicle")
    .property("speed", 52)
    .build()?;

let outcome = client.entities().create(&vehicle).send().await?;

python

response = requests.post(
    f"{BASE}/entities",
    json={
        "id": "urn:ngsi-ld:Vehicle:A4567",
        "type": "Vehicle",
        "speed": {
            "type": "Property",
            "value": 52,
        },
    },
)
assert response.status_code == 201

HTTP/1.1 201 Created
Location: /ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:A4567

The id in Location is percent-encoded as a single path segment. An entity created with the id urn:ngsi-ld:Building:x/y comes back as /ngsi-ld/v1/entities/urn:ngsi-ld:Building:x%2Fy. Andromeda encodes every character a path segment can't carry, % included, and leaves : and @ as they are. Subscriptions, registrations, temporal entities and every other resource you create with an id get the same Location, and an id in a request path is encoded the same way.

To create many entities in one request, use a batch. To create the entity or replace it if it exists, use upsert there.

What gets refused

• 409 AlreadyExists when an entity with this id exists. Use replace or merge to change it.
• 400 BadRequestData when the body breaks a data model rule. The overview lists the common ones.