---
title: "patchEntity"
method: PATCH
path: "/v1/entity/{slug}/{id}"
tags: ["Entities"]
---

# patchEntity

`PATCH /v1/entity/{slug}/{id}`

Partially updates an entity with the passed in entity data.

- If an _updated_at is passed and the server contains a newer version of the entity a `409` Error is returned

## Activity

If no `activity_id` query parameter is provided, implicitly creates Activity of type `EntityUpdated`

## Relations

To create a relation, store a property that defines a `$relation` array.

Example:

```json
{
  "contacts": {
    "$relation": [
      { "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }
    ]
  }
}
```

The items in `$relation` support two properties:
- `entity_id` - The ID of the entity to link
- `_tags` - Tags or labels for the relation (optional)

## Path parameters

- `slug` string, required — URL-friendly identifier for the entity schema
- `id` string, uuid, required

## Query parameters

- `activity_id` union
  - string, ulid — See https://github.com/ulid/spec
  - '' | 'null', nullable
- `fill_activity` boolean
- `dry_run` boolean
- `async` boolean
- `validate` boolean
- `direct` boolean

## Request body

- Entity
  - `_id` string, uuid
  - `_org` string — Organization Id the entity belongs to
  - `_owners` EntityOwner[]
    - `org_id` string, required
    - `user_id` string
  - `_schema` string — URL-friendly identifier for the entity schema
  - `_title` string, nullable — Title of entity
  - `_tags` string[], nullable
  - `_created_at` string, date-time, nullable
  - `_updated_at` string, date-time, nullable
  - `_deleted_at` string, date-time, nullable
  - `_acl` object — Access control list (ACL) for an entity. Defines sharing access to external orgs or users.
    - `view` string[]
    - `edit` string[]
    - `delete` string[]
  - `_purpose` string[], nullable
  - `_purpose_name` string[], nullable — Automatically computed purpose names from _purpose attribute
  - `_manifest` string[], nullable — Manifest ID used to create/update the entity
  - `_changesets` object, nullable — Pending attribute changesets for attributes configured with external or approval edit mode. The value shape is `Changeset` (`proposed_value`, `created_at`, `edit_mode`, ...) and is what `:apply` / `:dismiss` operate on. Read-only via normal entity PATCH/PUT operations — those handlers strip `_changesets` from request bodies. Use the changeset management endpoints to mutate this field.

## Response `200`

Entity was updated

- EntityItem
  - `_id` string, uuid, required
  - `_org` string, required — Organization Id the entity belongs to
  - `_owners` EntityOwner[]
    - `org_id` string, required
    - `user_id` string
  - `_schema` string, required — URL-friendly identifier for the entity schema
  - `_title` string, nullable, required — Title of entity
  - `_tags` string[], nullable
  - `_created_at` string, date-time, nullable, required
  - `_updated_at` string, date-time, nullable, required
  - `_deleted_at` string, date-time, nullable
  - `_acl` object — Access control list (ACL) for an entity. Defines sharing access to external orgs or users.
    - `view` string[]
    - `edit` string[]
    - `delete` string[]
  - `_purpose` string[], nullable
  - `_purpose_name` string[], nullable — Automatically computed purpose names from _purpose attribute
  - `_manifest` string[], nullable — Manifest ID used to create/update the entity
  - `_changesets` object, nullable — Pending attribute changesets for attributes configured with external or approval edit mode. The value shape is `Changeset` (`proposed_value`, `created_at`, `edit_mode`, ...) and is what `:apply` / `:dismiss` operate on. Read-only via normal entity PATCH/PUT operations — those handlers strip `_changesets` from request bodies. Use the changeset management endpoints to mutate this field.

## Other responses

- `409` — Conflict: newer version exists
- `422` — Entity validation error when `?validate=true`

---

[API](https://skmtc.net/epilot/apis/entity-api.md) · [All operations](https://skmtc.net/epilot/apis/entity-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/epilot/entity-api/versions/8dd3d44e1c4f/schema)