Create a new thing
Creates a thing with a default thingId and a default policyId.
The thing will be empty, i.e. no features, definition, attributes etc. by default.
The default thingId consists of your default namespace and a UUID.
The default policyId is identical with the default thingId, and allows the currently authorized subject all permissions.
In case you need to create a thing with a specific ID, use a PUT request instead, as any thingId specified in the request body will be ignored.
The field _created is filled automatically with the timestamp of the creation. The field is read-only and can
be retrieved later by explicitly selecting it or used in search filters.
Body
JSON representation of the thing to be created. Use '{}' to create an empty thing with a default policy.
_PolicyThe initial policy to create for this thing. This will create a separate policy entity managed by resource /policies/{thingId}.
Use the placeholder {{ request:subjectId }} in order to let the backend insert the authenticated subjectId of the HTTP request.
_stringThis field may contain
the policy ID of an existing policy.
The policy is copied and used for this newly created thing. The caller needs to have READ and WRITE* access to the policy.
a placeholder reference to a thing in the format {{ ref:things/[thingId]/policyId }} where you need to replace [thingId] with a valid thing ID.
The newly created thing will then obtain a copy of the policy of the referenced thing. The caller needs to have READ access to the thing and READ and WRITE* access to the policy of the thing.
* The check for WRITE permission avoids locking yourself out of the newly created policy. You can
bypass this check by setting the header allowPolicyLockout to true. Be aware that the authorized
subject cannot modify the policy if you do not assign WRITE permission on the policy resource!
If you want to specify a policy ID for the copied policy, use the policyId field.
This field must not be used together with the field _policy. If you specify both _policy and _copyPolicyFrom this will lead to an error response.
policyIdstringrequiredThe policy ID used for controlling access to this thing. Managed by
resource /policies/{policyId}.
definitionDefinitionA single fully qualified identifier of a definition in the form '::' or a valid HTTP(s) URL
attributesAttributesAn arbitrary JSON object describing the attributes of a thing.
featuresFeaturesList of features where the key represents the featureId of each feature.
The featureId key must be unique in the list.
Parameters
requested-acksstringqueryContains the "requested acknowledgements" for this modifying request as comma separated list. The HTTP call will
block until all requested acknowledgements were aggregated or will time out based on the specified timeout
parameter.
The default (if omitted) requested acks is requested-acks=twin-persisted which will block the
HTTP call until the change was persited to the twin.
timeoutstringqueryDefines how long the backend should wait for completion of the request, e.g. applied when waiting for requested
acknowledgements via the requested-acks param. Can be specified without unit (then seconds are assumed) or
together with s, ms or m unit. Example: 42s, 1m.
The default (if omitted) and maximum timeout is 60s. A value of 0 applies fire and forget semantics for
the command resulting in setting response-required=false.
response-requiredbooleanqueryDefines whether a response is required to the API call or not - if set to false the response will directly
sent back with a status code of 202 (Accepted).
The default (if ommited) response is true.
allow-policy-lockoutbooleanqueryDefines whether a subject is allowed to create a policy without having WRITE permission on the policy resource of the created policy.
The default (if ommited) is false.
namespacestringqueryDefines a custom namespace for the thing while generating a new thing ID.
Response
The thing was successfully created.
The request could not be completed. Possible reasons:
- the
thingIdmust not be set in the request body - the JSON body of the thing to be created is invalid
The request could not be completed due to missing authentication.
The request could not be completed. Possible reasons:
- the caller would not have access to the thing after creating it with the given policy.
- the caller has insufficient permissions.
The request could not be completed. Possible reasons:
- the referenced thing does not exist.
- the caller had insufficient permissions to read the referenced thing.
- the policy that should be copied does not exist.
- the caller had insufficient permissions to read the policy that should be copied.
A precondition for reading or writing the (sub-)resource failed. This will happen for write requests, if you specified an If-Match or If-None-Match header, which fails the precondition check against the current ETag of the (sub-)resource. For read requests, this error may only happen for a failing If-Match header. In case of a failing If-None-Match header for a read request, status 304 will be returned instead.
The created or modified entity is larger than the accepted limit of 100 kB.
One or more acknowledgement requests in the parameter requested-acks
were not fulfilled.
Authorization
OpenIDConnectopenIdConnectOpenID Connect Discovery URL. The placeholder is replaced by Swagger UI when configured.
NginxBasichttp (basic)Eclipse Ditto sandbox demo user (demo1 ... demo9) + password (demo)
Bearerhttp (bearer)A JSON Web Token issued by a supported OAuth 2.0 Identity Provider.