> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a new entity in the knowledge graph.

> Entities are the fundamental building blocks of the knowledge graph…

Entities are the fundamental building blocks of the knowledge graph. They
represent concepts, instances, classes, properties, events, actions, or
custom types within your domain.
**Request Body**

* `name`: The entity's display name (required, max 256 chars)
* `entity_type`: Type of entity (concept, instance, class, property, event, action, state, or custom)
* `properties`: Optional key-value pairs for additional metadata
  **Response**
  Returns the created entity with its assigned unique identifier and
  automatically generated embedding vector for semantic similarity search.
  **Errors**
* `400 Bad Request`: Invalid input (empty name, exceeds limits, invalid characters)
* `500 Internal Server Error`: Entity creation or embedding generation failed
  **Example (curl)**

```bash theme={null}
curl -X POST 'https://api.nsr.stateset.com/api/v1/entities' \
-H 'X-API-Key: your-api-key' \
-H 'Content-Type: application/json' \
-d '{'name': 'Customer', 'entity_type': 'class', 'properties': {'description': 'A person who purchases goods'}}'
```

Create a new knowledge graph entity.

**Required scope:** `write`

### Request body

`CreateEntityRequest`

<ParamField body="entity_type" type="string" required>
  Type of entity (concept, instance, class, relation, predicate)
</ParamField>

<ParamField body="name" type="string" required>
  Name of the entity
</ParamField>

<ParamField body="properties" type="object">
  Optional properties as key-value pairs
</ParamField>

### Response

`EntityResponse`

<ResponseField name="confidence" type="number (float)" required>
  Confidence score
</ResponseField>

<ResponseField name="created_at" type="string">
  Creation timestamp (RFC3339)
</ResponseField>

<ResponseField name="entity_type" type="string" required>
  Entity type
</ResponseField>

<ResponseField name="has_embedding" type="boolean" required>
  Whether entity has an embedding vector
</ResponseField>

<ResponseField name="id" type="string" required>
  Unique entity ID
</ResponseField>

<ResponseField name="name" type="string" required>
  Entity name
</ResponseField>

<ResponseField name="properties" type="object" required>
  Entity properties
</ResponseField>

<ResponseField name="updated_at" type="string">
  Last update timestamp (RFC3339)
</ResponseField>

### Status codes

| Code  | Meaning                                            |
| ----- | -------------------------------------------------- |
| `201` | Entity created successfully                        |
| `400` | Invalid request - validation failed                |
| `401` | Unauthorized — missing or invalid credentials      |
| `403` | Forbidden — the key/token lacks the required scope |
| `429` | Rate limited — see Retry-After / X-RateLimit-Reset |

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://api.nsr.stateset.com/api/v1/entities' \
    --header 'X-API-Key: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
    "entity_type": "string",
    "name": "string",
    "properties": {}
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "confidence": 1,
    "created_at": "string",
    "entity_type": "string",
    "has_embedding": true,
    "id": "string",
    "name": "string",
    "properties": {},
    "updated_at": "string"
  }
  ```
</ResponseExample>