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

# Update Entities

> Set the same field values on up to 100 selected database records in one table, for example changing their name field. Only supplied fields change. Each record is authorized and validated independently: data contains saved records, pending_changes contains changes held for before-save workflows, and failures contains records that were not updated. A successful response can include failures; inspect all three lists before reporting success or retrying. Retry only failed records, not saved or pending records.

## Authentication and permissions

> **Token requirements:** **User-based token (OAuth)** or **Organization-scoped API key** or **Workspace-scoped API key**.
>
> Send a bearer access token for one of these identities. The permissions and resource restrictions below also apply.

| Credential | Access requirements |
| - | - |
| Organization-scoped API key | `entities:write` |
| Workspace-scoped API key | `entities:write` |
| User-based token (OAuth) | Supported, subject to permissions |

Permissions joined by **+** are all required; **or** separates alternatives. Full-access keys still cannot call endpoints marked unsupported. Workspace keys must allow every workspace checked by the request. OAuth access depends on the user’s roles and resource access.

* **Change a record in a workspace's database, or in a database shared with one of your workspaces:** The permission is checked on the record's owning workspace, or on a workspace the record's database is shared with; Read alone admits no changes. A record in a database not shared with one of your workspaces is refused. Update requires Update access; archive and unarchive require Delete access. Database, table, field and record conditions still apply.


## OpenAPI

````yaml /sections/api-reference/openapi-spec-v2.yaml put /v2/entities
openapi: 3.1.0
info:
  title: Serval Public API
  description: Serval Public API
  contact:
    name: Serval
    url: https://serval.com
    email: support@serval.com
  license:
    name: Serval License
    url: https://serval.com/license
  version: 2.0.0
servers:
  - url: https://public.api.serval.com
security:
  - BearerAuth: []
tags:
  - name: Access Membership API
  - name: Access Policy API
  - name: Access Policy Approval Procedure API
  - name: Access Profile API
  - name: Access Relationship API
  - name: Access Request API
  - name: Agent API
  - name: Alerts API
  - name: Analytics API
  - name: App Instance API
  - name: App Resource API
  - name: App Resource Role API
  - name: Approval Delegation API
  - name: Approval Procedure API
  - name: Approval Request API
  - name: Assignment Rules API
  - name: Audit Log API
  - name: Billing API
  - name: Browser API
  - name: Campaign API
  - name: Change Blackout API
  - name: Change Model API
  - name: Connected Channels API
  - name: Custom Field API
  - name: Custom Role API
  - name: Custom Service API
  - name: Dashboards API
  - name: Email Intake API
  - name: Entity API
  - name: Entity Field Mapping API
  - name: Entity Ingestion Config API
  - name: Entity Type API
  - name: Folder API
  - name: Forms API
  - name: Group API
  - name: Guidance API
  - name: Help Agent API
  - name: Improvement Request API
  - name: Journey API
  - name: Knowledge API
  - name: Knowledge Base API
  - name: One-Time Window API
  - name: Package API
  - name: Platform Migration API
  - name: Project API
  - name: Report API
  - name: Review API
  - name: Role Sync API
  - name: Roles API
  - name: SLA API
  - name: Schedule API
  - name: Skills API
  - name: Tag API
  - name: Ticket API
  - name: Ticket Import API
  - name: Ticket Type API
  - name: Topic API
  - name: User API
  - name: User Relationship API
  - name: Widgets API
  - name: Worker API
  - name: Workflow API
  - name: Workflow Approval Procedure API
  - name: Workflow Run API
  - name: Workspace API
  - name: Workspace Group API
  - name: Workspace SDLC Settings API
  - name: Workspace User API
paths:
  /v2/entities:
    put:
      tags:
        - Entity API
      summary: Update Entities
      description: >-
        Set the same field values on up to 100 selected database records in one
        table, for example changing their name field. Only supplied fields
        change. Each record is authorized and validated independently: data
        contains saved records, pending_changes contains changes held for
        before-save workflows, and failures contains records that were not
        updated. A successful response can include failures; inspect all three
        lists before reporting success or retrying. Retry only failed records,
        not saved or pending records.
      operationId: svrelay.publicv2.PublicAPIServiceV2.UpdateEntities
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/svstore.publicapi.UpdateEntitiesRequest'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/svstore.publicapi.UpdateEntitiesResponse'
      security:
        - BearerAuth: []
components:
  schemas:
    svstore.publicapi.UpdateEntitiesRequest:
      type: object
      properties:
        entityIds:
          type: array
          items:
            type: string
          title: entity_ids
          description: Up to 100 record IDs from one table. Duplicate IDs are updated once.
          x-stainless-terraform-configurability: required
        fieldValues:
          type: array
          items:
            $ref: '#/components/schemas/svstore.EntityFieldValueInput'
          title: field_values
          description: >-
            Set these values on every selected record; omitted fields are
            unchanged.
          x-stainless-terraform-configurability: required
      title: UpdateEntitiesRequest
      required:
        - entityIds
        - fieldValues
      additionalProperties: false
    svstore.publicapi.UpdateEntitiesResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/svstore.Entity'
          title: data
          x-stainless-terraform-configurability: optional
        pendingChanges:
          type: array
          items:
            $ref: '#/components/schemas/svstore.EntityPendingChange'
          title: pending_changes
          x-stainless-terraform-configurability: optional
        failures:
          type: array
          items:
            $ref: '#/components/schemas/svstore.publicapi.UpdateEntitiesFailure'
          title: failures
          x-stainless-terraform-configurability: optional
      title: UpdateEntitiesResponse
      additionalProperties: false
    svstore.EntityFieldValueInput:
      type: object
      properties:
        fieldId:
          type: string
          title: field_id
          description: Identify the field by ID or key. At least one is required.
          x-stainless-terraform-configurability: optional
        fieldKey:
          type: string
          title: field_key
          x-stainless-terraform-configurability: optional
        value:
          $ref: '#/components/schemas/google.protobuf.Value'
          title: value
          description: |-
            The field value. Null or absent clears the field.
             Type is determined by the field's data_type in the schema:
               TEXT, UNIQUE, ENUM, ENTITY_REF, USER_REF → string
               TICKET_REF → string (ticket ID)
               GROUP_REF → string (a group ID or unambiguous group name usable by the
                 owning workspace; unmatched ingestion values are left unset)
               FILE → string (file ID)
               NUMBER → number
               BOOL → bool
               TIMESTAMP → string (ISO 8601, e.g. "2024-03-15T10:30:00Z")
               TIMESTAMP_RANGE → struct {"start", "end"}, with an ISO 8601 start and
                 a later ISO 8601 end or explicit null; also accepts "<start>/<end>"
                 and "<start>/..". Omitting an endpoint is invalid. A null or ".."
                 end needs the field's timestamp_range.allows_open_end; otherwise
                 the write fails with InvalidArgument.
               MULTI_SELECT → list of strings (enum option IDs)
          x-stainless-terraform-configurability: optional
        pinned:
          type:
            - boolean
            - 'null'
          title: pinned
          description: |-
            Pin this value to prevent ingestion from overwriting it.
             Omitted keeps the field's current pin; false unpins; true = sticky.
          x-stainless-terraform-configurability: optional
      title: EntityFieldValueInput
      additionalProperties: false
      description: |-
        Input for setting a field value on an entity (create/update requests).
         At least one of field_id or field_key is required to identify the target field.
         The field's data type is resolved from the schema — callers don't need to specify it.
    svstore.Entity:
      type: object
      properties:
        id:
          type: string
          title: id
          description: Identity
          x-stainless-terraform-configurability: optional
        key:
          type: string
          title: key
          x-stainless-terraform-configurability: optional
        name:
          type: string
          title: name
          x-stainless-terraform-configurability: optional
        teamId:
          type: string
          title: team_id
          x-stainless-terraform-configurability: optional
        entityTypeId:
          type: string
          title: entity_type_id
          x-stainless-terraform-configurability: optional
        entityTypeKey:
          type: string
          title: entity_type_key
          x-stainless-terraform-configurability: optional
        createdByUserId:
          type: string
          title: created_by_user_id
          description: Audit
          x-stainless-terraform-configurability: optional
        updatedByUserId:
          type: string
          title: updated_by_user_id
          x-stainless-terraform-configurability: optional
        createdAt:
          $ref: '#/components/schemas/google.protobuf.Timestamp'
          title: created_at
          x-stainless-terraform-configurability: optional
        updatedAt:
          $ref: '#/components/schemas/google.protobuf.Timestamp'
          title: updated_at
          x-stainless-terraform-configurability: optional
        deletedAt:
          oneOf:
            - $ref: '#/components/schemas/google.protobuf.Timestamp'
            - type: 'null'
          title: deleted_at
          x-stainless-terraform-configurability: optional
        archivedAt:
          oneOf:
            - $ref: '#/components/schemas/google.protobuf.Timestamp'
            - type: 'null'
          title: archived_at
          description: >-
            Set when the entity is archived (reversible, key-reserving). The
            item still
             exists and keeps its key; it's just hidden from active browse.
          x-stainless-terraform-configurability: optional
        fieldValues:
          type: array
          items:
            $ref: '#/components/schemas/svstore.EntityFieldValue'
          title: field_values
          description: Data
          x-stainless-terraform-configurability: optional
        sourceAppInstanceIds:
          type: array
          items:
            type: string
          title: source_app_instance_ids
          x-stainless-terraform-configurability: optional
        sharedMetadata:
          oneOf:
            - $ref: '#/components/schemas/svstore.SharedEntityMetadata'
            - type: 'null'
          title: shared_metadata
          description: |-
            Populated when the record belongs to another team's database shared
             with the requesting team (a team-level or org-wide share at "Can read"
             or "Can write").
          x-stainless-terraform-configurability: optional
        sourceApps:
          type: array
          items:
            $ref: '#/components/schemas/svstore.EntitySourceApp'
          title: source_apps
          description: >-
            Branding for each id in source_app_instance_ids, resolved by the
            read
             handlers across the organization so a record of a shared database still
             names its source in the grantee team. Ids svflow no longer knows are
             absent. Filled on every user-API response that carries an entity.
          x-stainless-terraform-configurability: optional
      title: Entity
      additionalProperties: false
    svstore.EntityPendingChange:
      type: object
      properties:
        id:
          type: string
          title: id
          x-stainless-terraform-configurability: optional
        entityId:
          type: string
          title: entity_id
          x-stainless-terraform-configurability: optional
        entityTypeId:
          type: string
          title: entity_type_id
          x-stainless-terraform-configurability: optional
        operation:
          $ref: '#/components/schemas/svstore.EntityChangeOperation'
          title: operation
          x-stainless-terraform-configurability: optional
        state:
          $ref: '#/components/schemas/svstore.EntityPendingChangeState'
          title: state
          x-stainless-terraform-configurability: optional
        entityWorkflowRuleIds:
          type: array
          items:
            type: string
          title: entity_workflow_rule_ids
          x-stainless-terraform-configurability: optional
        submittedByUserId:
          type: string
          title: submitted_by_user_id
          x-stainless-terraform-configurability: optional
        createdAt:
          $ref: '#/components/schemas/google.protobuf.Timestamp'
          title: created_at
          x-stainless-terraform-configurability: optional
        fieldChanges:
          type: array
          items:
            $ref: '#/components/schemas/svstore.EntityPendingFieldChange'
          title: field_changes
          x-stainless-terraform-configurability: optional
        runs:
          type: array
          items:
            $ref: '#/components/schemas/svstore.EntityPendingChangeRun'
          title: runs
          x-stainless-terraform-configurability: optional
        reason:
          type: string
          title: reason
          description: The workflow's rejection messages or why the change was not applied.
          x-stainless-terraform-configurability: optional
      title: EntityPendingChange
      additionalProperties: false
    svstore.publicapi.UpdateEntitiesFailure:
      type: object
      properties:
        entityId:
          type: string
          title: entity_id
          x-stainless-terraform-configurability: optional
        message:
          type: string
          title: message
          x-stainless-terraform-configurability: optional
      title: UpdateEntitiesFailure
      additionalProperties: false
    google.protobuf.Value:
      oneOf:
        - type: 'null'
        - type: number
        - type: string
        - type: boolean
        - type: array
        - type: object
          additionalProperties: true
      description: |-
        `Value` represents a dynamically typed value which can be either
         null, a number, a string, a boolean, a recursive struct value, or a
         list of values. A producer of value is expected to set one of these
         variants. Absence of any variant indicates an error.

         The JSON representation for `Value` is JSON value.
    google.protobuf.Timestamp:
      type: string
      examples:
        - '2025-01-15T01:30:15.000Z'
        - '2025-06-01T00:00:00.000Z'
      format: date-time
      description: A timestamp in RFC 3339 format (e.g., "2025-01-15T01:30:15Z").
    svstore.EntityFieldValue:
      type: object
      properties:
        id:
          type: string
          title: id
          description: >-
            The EAV row id. NOT populated on entity read paths
            (Entity.field_values:
             search / list / get / create / update) since the v4 slim document_json
             dropped it — it has no consumer there. It IS populated on the
             listEntityFieldValueHistory RPC, which reads EAV rows directly.
          x-stainless-terraform-configurability: optional
        entityId:
          type: string
          title: entity_id
          x-stainless-terraform-configurability: optional
        fieldId:
          type: string
          title: field_id
          x-stainless-terraform-configurability: optional
        fieldKey:
          type: string
          title: field_key
          x-stainless-terraform-configurability: optional
        fieldName:
          type: string
          title: field_name
          x-stainless-terraform-configurability: optional
        dataType:
          $ref: '#/components/schemas/svstore.EntityTypeField.DataType'
          title: data_type
          x-stainless-terraform-configurability: optional
        value:
          $ref: '#/components/schemas/google.protobuf.Value'
          title: value
          description: |-
            The field value as a JSON-compatible value. Type interpretation is
             determined by data_type:
               TEXT, UNIQUE, ENUM, ENTITY_REF, USER_REF → string
               TICKET_REF → string (ticket ID)
               GROUP_REF → string (svauth group ID)
               FILE → string (file ID)
               NUMBER → number
               BOOL → bool
               TIMESTAMP → string (ISO 8601, e.g. "2024-03-15T10:30:00Z")
               TIMESTAMP_RANGE → struct {"start", "end"}; start is an ISO 8601 string,
                 end is a later ISO 8601 string or null for an ongoing window
               MULTI_SELECT → list of strings (enum option IDs)
          x-stainless-terraform-configurability: optional
        setByUserId:
          type:
            - string
            - 'null'
          title: set_by_user_id
          description: |-
            Attribution: who/what set this field value. Stored in the slim
             document_json and populated on ALL entity read paths (search / list / get
             / create / update) as well as field-value history.
          x-stainless-terraform-configurability: optional
        setByAppInstanceId:
          type:
            - string
            - 'null'
          title: set_by_app_instance_id
          x-stainless-terraform-configurability: optional
        createdAt:
          $ref: '#/components/schemas/google.protobuf.Timestamp'
          title: created_at
          description: >-
            Temporal context. NOT populated on entity read paths
            (Entity.field_values)
             since the v4 slim document_json dropped created_at — it has no consumer
             there. It IS populated on the listEntityFieldValueHistory RPC. The current
             value for a field has deleted_at unset.
          x-stainless-terraform-configurability: optional
        deletedAt:
          oneOf:
            - $ref: '#/components/schemas/google.protobuf.Timestamp'
            - type: 'null'
          title: deleted_at
          x-stainless-terraform-configurability: optional
        pinned:
          type: boolean
          title: pinned
          description: >-
            When true, ingestion cannot overwrite this user-set value. Stored in
            the
             slim document_json and populated on ALL entity read paths.
          x-stainless-terraform-configurability: computed_optional
        redacted:
          type: boolean
          title: redacted
          description: >-
            Set when an access rule hides this field's value from the caller:
            the
             placement exists on the entity's type, but value and attribution are
             withheld (unset) — whether or not a value is stored.
          x-stainless-terraform-configurability: computed_optional
        sensitive:
          type: boolean
          title: sensitive
          description: >-
            Set when the field is marked sensitive and the caller may read it:
            the
             value is withheld (unset) — whether or not one is stored — until the
             caller reveals it with RevealEntityFieldValue, an audited call.
             Attribution and pinned state are still populated. Never set together
             with redacted (a hidden field is hidden, not sensitive).
          x-stainless-terraform-configurability: computed_optional
        setByFormula:
          type: boolean
          title: set_by_formula
          description: Set on field-value history when a formula wrote this value.
          x-stainless-terraform-configurability: computed_optional
      title: EntityFieldValue
      additionalProperties: false
      description: |-
        EntityFieldValue represents a concrete field value on a specific entity.
         Used for both current values (on Entity.field_values) and historical values
         (in field value history responses).
    svstore.SharedEntityMetadata:
      type: object
      properties:
        sourceTeamId:
          type: string
          title: source_team_id
          x-stainless-terraform-configurability: optional
        sourceTeamName:
          type: string
          title: source_team_name
          x-stainless-terraform-configurability: optional
      title: SharedEntityMetadata
      additionalProperties: false
      description: |-
        The owning team of a record read through another team's share. The
         share's level, not this marker, decides whether the record is writable.
    svstore.EntitySourceApp:
      type: object
      properties:
        appInstanceId:
          type: string
          title: app_instance_id
          x-stainless-terraform-configurability: optional
        displayName:
          type: string
          title: display_name
          x-stainless-terraform-configurability: optional
        serviceName:
          type: string
          title: service_name
          x-stainless-terraform-configurability: optional
        serviceDisplayName:
          type: string
          title: service_display_name
          x-stainless-terraform-configurability: optional
        logoUrl:
          type: string
          title: logo_url
          x-stainless-terraform-configurability: optional
        domain:
          type: string
          title: domain
          x-stainless-terraform-configurability: optional
        useIntegratedServiceRegistry:
          type: boolean
          title: use_integrated_service_registry
          x-stainless-terraform-configurability: computed_optional
        isCustom:
          type: boolean
          title: is_custom
          x-stainless-terraform-configurability: computed_optional
      title: EntitySourceApp
      additionalProperties: false
      description: >-
        Who ingested a record: the connection's name and enough of its service
        to
         draw a logo. Never configuration.
    svstore.EntityChangeOperation:
      type: string
      title: EntityChangeOperation
      enum:
        - ENTITY_CHANGE_OPERATION_UNSPECIFIED
        - ENTITY_CHANGE_OPERATION_CREATE
        - ENTITY_CHANGE_OPERATION_UPDATE
        - ENTITY_CHANGE_OPERATION_ARCHIVE
        - ENTITY_CHANGE_OPERATION_UNARCHIVE
        - ENTITY_CHANGE_OPERATION_DELETE
    svstore.EntityPendingChangeState:
      type: string
      title: EntityPendingChangeState
      enum:
        - ENTITY_PENDING_CHANGE_STATE_UNSPECIFIED
        - ENTITY_PENDING_CHANGE_STATE_PENDING
        - ENTITY_PENDING_CHANGE_STATE_APPLIED
        - ENTITY_PENDING_CHANGE_STATE_REJECTED
        - ENTITY_PENDING_CHANGE_STATE_CONFLICTED
        - ENTITY_PENDING_CHANGE_STATE_ERRORED
    svstore.EntityPendingFieldChange:
      type: object
      properties:
        fieldId:
          type: string
          title: field_id
          x-stainless-terraform-configurability: optional
        beforeJson:
          type: string
          title: before_json
          description: JSON values; empty when the field had or gets no value.
          x-stainless-terraform-configurability: optional
        afterJson:
          type: string
          title: after_json
          x-stainless-terraform-configurability: optional
        redacted:
          type: boolean
          title: redacted
          description: The caller cannot read this field, so both values are withheld.
          x-stainless-terraform-configurability: computed_optional
        pinned:
          type:
            - boolean
            - 'null'
          title: pinned
          description: The pin state the change sets; unset when it keeps the current pin.
          x-stainless-terraform-configurability: optional
      title: EntityPendingFieldChange
      additionalProperties: false
    svstore.EntityPendingChangeRun:
      type: object
      properties:
        entityWorkflowRuleId:
          type: string
          title: entity_workflow_rule_id
          x-stainless-terraform-configurability: optional
        workflowId:
          type: string
          title: workflow_id
          x-stainless-terraform-configurability: optional
        workflowRunId:
          type:
            - string
            - 'null'
          title: workflow_run_id
          x-stainless-terraform-configurability: optional
        state:
          $ref: '#/components/schemas/svstore.EntityPendingChangeRunState'
          title: state
          x-stainless-terraform-configurability: optional
      title: EntityPendingChangeRun
      additionalProperties: false
    svstore.EntityTypeField.DataType:
      type: string
      title: DataType
      enum:
        - DATA_TYPE_UNSPECIFIED
        - TEXT
        - NUMBER
        - BOOL
        - TIMESTAMP
        - ENUM
        - ENTITY_REF
        - USER_REF
        - UNIQUE
        - MULTI_SELECT
        - FILE
        - TICKET_REF
        - TIMESTAMP_RANGE
        - GROUP_REF
    svstore.EntityPendingChangeRunState:
      type: string
      title: EntityPendingChangeRunState
      enum:
        - ENTITY_PENDING_CHANGE_RUN_STATE_UNSPECIFIED
        - ENTITY_PENDING_CHANGE_RUN_STATE_QUEUED
        - ENTITY_PENDING_CHANGE_RUN_STATE_RUNNING
        - ENTITY_PENDING_CHANGE_RUN_STATE_ALLOWED
        - ENTITY_PENDING_CHANGE_RUN_STATE_REJECTED
        - ENTITY_PENDING_CHANGE_RUN_STATE_ERRORED
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.