Entities
Interact with entities in HASH webs
What entities areCopy link to this section
An entity is a typed record in HASH's knowledge graph. It represents something such as a person, an organization, a document, or an event. Entities belong to a web, and each entity has an ID, one or more entity types, and properties describing it. Links are entities that connect two other entities.
The API returns each entity with these fields:
| Field | Type | Description |
|---|---|---|
metadata | EntityMetadata | What identifies and classifies the entity, and where its data comes from. |
properties | PropertyObject | The entity's properties, keyed by the base URL of their property type. |
propertyMetadata | PropertyObjectMetadata | The data types of the values in properties, and where they come from. |
link | Link, optional | The entities it connects, if the entity is a link. |
AuthorizationCopy link to this section
Every Entities operation needs a bearer token in the Authorization header. The request examples send it as Bearer $HASH_API_KEY.
API token starting with hsh_pat_. The token acts as the user it belongs to.
These responses mean that a request had no valid token, lacked a permission, or named something the caller can't see. Each operation's page lists all of its responses.
| Status | Meaning | Operations |
|---|---|---|
401 | The request carries no credentials, or they do not identify a permitted caller. | Every operation |
403 | The caller may not create an entity or instantiate an entity type or a type it inherits from. | Create entities |
404 | The entity does not exist, is archived, or the caller may not view it. | Get an entity |
See API authentication for creating, replacing, and revoking tokens.
EndpointsCopy link to this section
| Operation | Endpoint |
|---|---|
| Create entities | post /entities/v1 |
Creates the entities in one transaction: either all of them are created or none. Returns them in the order of the request. | |
| Get an entity | get /entities/v1/{entityId} |
Returns the entity's ID, the entity types, the provenance, and the properties with the data types and provenance of their values, of its current edition. propertyMetadata leaves out a value without a stored data type, and a list that contains one. | |
| Query entities | post /entities/v1/query |
Returns the current edition of each entity the caller may view that is not archived and meets filter, if given, a page at a time, in a stable order. The Link header names the next page. | |