Upsert entities

The API uses type for Database and app for Space. See Terminology.

Creates Entity (or Entities) if no existing duplicate is found (based on the Conflict Field); otherwise, it either skips creating or updates the existing duplicate, depending on the Conflict Action.
Setting the fibery/id Field for Entities is mandatory to apply the Conflict Action when a duplicate is found.
The Conflict Field can be of type: fibery/text, fibery/int, or fibery/date


Conflict Action	Description
`skip-create`	do not create Entity if a Duplicate was found
`update-latest`	updates the Duplicate found with all fields from the Entity to be created, excluding platform fields (`fibery/id`, `fibery/public-id`, `fibery/rank`, `fibery/creation-date`). If more than one Duplicate is found, the Duplicate with the latest `fibery/creation-date` is selected for updating.

If a batch of Entities is passed to the command and it contains Duplicates, the following action is taken:

skip-create: Uses the first found Duplicate in the batch.
update-latest: Uses the last found Duplicate in the batch.

Duplicate matching rules:

NULL values are not considered equal. An entity with a NULL Conflict Field value is not considered a Duplicate of another entity with a NULL value.
Text Field comparisons are case-sensitive.

The result is an array of created Entities or resolved Conflicts, in the order of the Entities. The array contents are determined as follows:

Created: If an Entity was created, the array contains the new Entity’s information with create action.
Skipped: If an Entity was not created because skip-create was applied to a found Duplicate, the array contains a resolved Conflict with skip-create action.
Updated: If an Entity was used to update a found Duplicate due to update-latest, the array contains a resolved Conflict with update-latest action.
Batch Duplicate handling: If an Entity was ignored due to a Duplicate found within the same batch of Entities, the array contains a resolved Conflict with prefer-duplicate-found-in-the-batch action. This action uses the Duplicate entity (D) and resolves it by applying the specified Conflict Action later:
If no Conflict is found for D, the array contains the created Entity D info with create action.
If a Conflict is found for D and resolved with skip-create, the array contains a resolved Conflict with skip-create action.
If a Conflict is found for D and resolved with update-latest, the array contains a resolved Conflict with update-latest action.

Case 1

Batch of Entities contain duplicates
There are no existing duplicates in the DB
Conflict Action is skip-create

const response = await fetch('https://YOUR_ACCOUNT.fibery.io/api/commands', {
  method: 'POST',
  headers: {
    'Authorization': 'Token YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    command: 'fibery.entity.batch/create-or-update',
    args: {
      type: 'Cricket/Player',
      entities: [
        // Entity 1 (does not exist in the DB)
        {
          'fibery/id': 'd17390c4-98c8-11e9-a2a3-2a2ae2dbcce4',
          'Cricket/Name': 'Curtly Ambrose',
          'Cricket/Shirt Number': 1,
          'Cricket/Height': '2.01',
          'Cricket/Retired': false
        },
        // Entity 2 (does not exist in the DB)
        {
          'fibery/id': '20f9b920-9752-11e9-81b9-4363f716f666',
          'Cricket/Name': 'Brian Lara',
          'Cricket/Shirt Number': 18,
          'Cricket/Height': '1.75',
          'Cricket/Retired': false
        },
        // Entity 3 (duplicate of Entity 1)
        {
          'fibery/id': '79580f9d-fd30-439e-8040-6922d9f0455d',
          'Cricket/Name': 'Curtly Ambrose',
          'Cricket/Shirt Number': 1,
          'Cricket/Height': '2.10',
          'Cricket/Retired': true
        }
      ],
      'conflict-field': 'Cricket/Name',
      'conflict-action': 'skip-create'
    }
  })
});
const data = await response.json();

Result:

{
  "success": true,
  "result": [
    {
      "action": "create",
      "created": {
        "Cricket/Height": "2.01",
        "fibery/modification-date": "2025-09-02T14:32:25.905Z",
        "fibery/id": "d17390c4-98c8-11e9-a2a3-2a2ae2dbcce4",
        "fibery/created-by": {"fibery/id": "4044090b-7165-4791-ac15-20fb12ae0b64"},
        "fibery/creation-date": "2025-09-02T14:32:25.905Z",
        "Cricket/Name": "Curtly Ambrose",
        "fibery/public-id": "3",
        "Cricket/Retired": false,
        "Cricket/Shirt Number": 1,
        "Cricket/Bio": {"fibery/id": "01990ad7-e855-701f-ae77-6c146f6b9ee7"},
        "fibery/rank": 5674304923033269
      }
    },
    {
      "action": "create",
      "created": {
        "Cricket/Height": "1.75",
        "fibery/modification-date": "2025-09-02T14:32:25.905Z",
        "fibery/id": "20f9b920-9752-11e9-81b9-4363f716f666",
        "fibery/created-by": {"fibery/id": "4044090b-7165-4791-ac15-20fb12ae0b64"},
        "fibery/creation-date": "2025-09-02T14:32:25.905Z",
        "Cricket/Name": "Brian Lara",
        "fibery/public-id": "2",
        "Cricket/Retired": false,
        "Cricket/Shirt Number": 18,
        "Cricket/Bio": {"fibery/id": "01990ad7-e855-701d-a776-0d933166aa86"},
        "fibery/rank": 5674304922933269
      }
    },
    {
      "action": "prefer-duplicate-found-in-the-batch",
      "entity": {
        "fibery/id": "79580f9d-fd30-439e-8040-6922d9f0455d",
        "Cricket/Name": "Curtly Ambrose",
        "Cricket/Shirt Number": 1,
        "Cricket/Height": "2.10",
        "Cricket/Retired": true
      },
      "duplicate": {
        "fibery/id": "d17390c4-98c8-11e9-a2a3-2a2ae2dbcce4",
        "Cricket/Name": "Curtly Ambrose",
        "Cricket/Shirt Number": 1,
        "Cricket/Height": "2.01",
        "Cricket/Retired": false
      }
    }
  ]
}

Case 2

Batch of Entities contains duplicates
There are existing duplicates in the DB
Conflict Action is skip-create

const response = await fetch('https://YOUR_ACCOUNT.fibery.io/api/commands', {
  method: 'POST',
  headers: {
    'Authorization': 'Token YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    command: 'fibery.entity.batch/create-or-update',
    args: {
      type: 'Cricket/Player',
      entities: [
        // Entity 1 (already exists in the DB)
        {
          'fibery/id': 'a1185326-afc5-4467-a8f7-825b090a97e1',
          'Cricket/Name': 'Curtly Ambrose',
          'Cricket/Shirt Number': 1,
          'Cricket/Height': '2.01',
          'Cricket/Retired': false
        },
        // Entity 2 (already exists in the DB)
        {
          'fibery/id': 'abe35d9b-4286-49f9-9ecb-0a777dcf98da',
          'Cricket/Name': 'Brian Lara',
          'Cricket/Shirt Number': 18,
          'Cricket/Height': '1.75',
          'Cricket/Retired': false
        },
        // Entity 3 (duplicate of Entity 1)
        {
          'fibery/id': '79580f9d-fd30-439e-8040-6922d9f0455d',
          'Cricket/Name': 'Curtly Ambrose',
          'Cricket/Shirt Number': 1,
          'Cricket/Height': '2.10',
          'Cricket/Retired': true
        }
      ],
      'conflict-field': 'Cricket/Name',
      'conflict-action': 'skip-create'
    }
  })
});
const data = await response.json();

Result:

{
  "success": true,
  "result": [
    {
      "action": "skip-create",
      "entity": {
        "fibery/id": "a1185326-afc5-4467-a8f7-825b090a97e1",
        "Cricket/Name": "Curtly Ambrose",
        "Cricket/Shirt Number": 1,
        "Cricket/Height": "2.01",
        "Cricket/Retired": false
      },
      "duplicate": {
        "Cricket/Height": "2.01",
        "fibery/modification-date": "2025-09-02T14:32:25.905Z",
        "fibery/id": "d17390c4-98c8-11e9-a2a3-2a2ae2dbcce4",
        "fibery/created-by": {"fibery/id": "4044090b-7165-4791-ac15-20fb12ae0b64"},
        "fibery/creation-date": "2025-09-02T14:32:25.905Z",
        "Cricket/Name": "Curtly Ambrose",
        "fibery/public-id": "3",
        "Cricket/Retired": false,
        "Cricket/Shirt Number": 1,
        "Cricket/Bio": {"fibery/id": "01990ad7-e855-701f-ae77-6c146f6b9ee7"},
        "fibery/rank": 5674304923033269
      }
    },
    {
      "action": "skip-create",
      "entity": {
        "fibery/id": "abe35d9b-4286-49f9-9ecb-0a777dcf98da",
        "Cricket/Name": "Brian Lara",
        "Cricket/Shirt Number": 18,
        "Cricket/Height": "1.75",
        "Cricket/Retired": false
      },
      "duplicate": {
        "Cricket/Height": "1.75",
        "fibery/modification-date": "2025-09-02T14:32:25.905Z",
        "fibery/id": "20f9b920-9752-11e9-81b9-4363f716f666",
        "fibery/created-by": {"fibery/id": "4044090b-7165-4791-ac15-20fb12ae0b64"},
        "fibery/creation-date": "2025-09-02T14:32:25.905Z",
        "Cricket/Name": "Brian Lara",
        "fibery/public-id": "2",
        "Cricket/Retired": false,
        "Cricket/Shirt Number": 18,
        "Cricket/Bio": {"fibery/id": "01990ad7-e855-701d-a776-0d933166aa86"},
        "fibery/rank": 5674304922933269
      }
    },
    {
      "action": "prefer-duplicate-found-in-the-batch",
      "entity": {
        "fibery/id": "79580f9d-fd30-439e-8040-6922d9f0455d",
        "Cricket/Name": "Curtly Ambrose",
        "Cricket/Shirt Number": 1,
        "Cricket/Height": "2.10",
        "Cricket/Retired": true
      },
      "duplicate": {
        "fibery/id": "d17390c4-98c8-11e9-a2a3-2a2ae2dbcce4",
        "Cricket/Name": "Curtly Ambrose",
        "Cricket/Shirt Number": 1,
        "Cricket/Height": "2.01",
        "Cricket/Retired": false
      }
    }
  ]
}

Case 3

Batch of Entities contains duplicates
There are no existing duplicates in the DB
Conflict Action is update-latest

const response = await fetch('https://YOUR_ACCOUNT.fibery.io/api/commands', {
  method: 'POST',
  headers: {
    'Authorization': 'Token YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    command: 'fibery.entity.batch/create-or-update',
    args: {
      type: 'Cricket/Player',
      entities: [
        // Entity 1 (duplicate of Entity 3)
        {
          'fibery/id': 'd17390c4-98c8-11e9-a2a3-2a2ae2dbcce4',
          'Cricket/Name': 'Curtly Ambrose',
          'Cricket/Shirt Number': 1,
          'Cricket/Height': '2.01',
          'Cricket/Retired': false
        },
        // Entity 2 (does not exist in the DB)
        {
          'fibery/id': '20f9b920-9752-11e9-81b9-4363f716f666',
          'Cricket/Name': 'Brian Lara',
          'Cricket/Shirt Number': 18,
          'Cricket/Height': '1.75',
          'Cricket/Retired': false
        },
        // Entity 3 (does not exist in the DB)
        {
          'fibery/id': '79580f9d-fd30-439e-8040-6922d9f0455d',
          'Cricket/Name': 'Curtly Ambrose',
          'Cricket/Shirt Number': 1,
          'Cricket/Height': '2.10',
          'Cricket/Retired': true
        }
      ],
      'conflict-field': 'Cricket/Name',
      'conflict-action': 'update-latest'
    }
  })
});
const data = await response.json();

Result:

{
  "success": true,
  "result": [
    {
      "action": "prefer-duplicate-found-in-the-batch",
      "entity": {
        "fibery/id": "d17390c4-98c8-11e9-a2a3-2a2ae2dbcce4",
        "Cricket/Name": "Curtly Ambrose",
        "Cricket/Shirt Number": 1,
        "Cricket/Height": "2.01",
        "Cricket/Retired": false
      },
      "duplicate": {
        "fibery/id": "79580f9d-fd30-439e-8040-6922d9f0455d",
        "Cricket/Name": "Curtly Ambrose",
        "Cricket/Shirt Number": 1,
        "Cricket/Height": "2.10",
        "Cricket/Retired": true
      }
    },
    {
      "action": "create",
      "created": {
        "Cricket/Height": "1.75",
        "fibery/modification-date": "2025-09-02T14:39:58.586Z",
        "fibery/id": "20f9b920-9752-11e9-81b9-4363f716f666",
        "fibery/created-by": {"fibery/id": "4044090b-7165-4791-ac15-20fb12ae0b64"},
        "fibery/creation-date": "2025-09-02T14:39:58.586Z",
        "Cricket/Name": "Brian Lara",
        "fibery/public-id": "4",
        "Cricket/Retired": false,
        "Cricket/Shirt Number": 18,
        "Cricket/Bio": {"fibery/id": "01990ade-d091-7022-b1c4-7efe12ccd84b"},
        "fibery/rank": 7072311628808326
      }
    },
    {
      "action": "create",
      "created": {
        "Cricket/Height": "2.10",
        "fibery/modification-date": "2025-09-02T14:39:58.586Z",
        "fibery/id": "79580f9d-fd30-439e-8040-6922d9f0455d",
        "fibery/created-by": {"fibery/id": "4044090b-7165-4791-ac15-20fb12ae0b64"},
        "fibery/creation-date": "2025-09-02T14:39:58.586Z",
        "Cricket/Name": "Curtly Ambrose",
        "fibery/public-id": "5",
        "Cricket/Retired": true,
        "Cricket/Shirt Number": 1,
        "Cricket/Bio": {"fibery/id": "01990ade-d091-7024-9fd1-e03f62f5860e"},
        "fibery/rank": 7072311628908326
      }
    }
  ]
}

Case 4

Batch of Entities contains duplicates
There are existing duplicates in the DB
Conflict Action is update-latest

const response = await fetch('https://YOUR_ACCOUNT.fibery.io/api/commands', {
  method: 'POST',
  headers: {
    'Authorization': 'Token YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    command: 'fibery.entity.batch/create-or-update',
    args: {
      type: 'Cricket/Player',
      entities: [
        // Entity 1 (duplicate of Entity 3)
        {
          'fibery/id': 'a1185326-afc5-4467-a8f7-825b090a97e1',
          'Cricket/Name': 'Curtly Ambrose',
          'Cricket/Shirt Number': 1,
          'Cricket/Height': '2.01',
          'Cricket/Retired': false
        },
        // Entity 2 (already exists in the DB)
        {
          'fibery/id': 'abe35d9b-4286-49f9-9ecb-0a777dcf98da',
          'Cricket/Name': 'Brian Lara',
          'Cricket/Shirt Number': 18,
          'Cricket/Height': '1.75',
          'Cricket/Retired': false
        },
        // Entity 3 (already exists in the DB)
        {
          'fibery/id': 'c79d09ba-1c2d-40f4-aa3b-cf7bc79ff7a8',
          'Cricket/Name': 'Curtly Ambrose',
          'Cricket/Shirt Number': 1,
          'Cricket/Height': '2.10',
          'Cricket/Retired': true
        }
      ],
      'conflict-field': 'Cricket/Name',
      'conflict-action': 'update-latest'
    }
  })
});
const data = await response.json();

Result:

{
  "success": true,
  "result": [
    {
      "action": "prefer-duplicate-found-in-the-batch",
      "entity": {
        "fibery/id": "a1185326-afc5-4467-a8f7-825b090a97e1",
        "Cricket/Name": "Curtly Ambrose",
        "Cricket/Shirt Number": 1,
        "Cricket/Height": "2.01",
        "Cricket/Retired": false
      },
      "duplicate": {
        "fibery/id": "79580f9d-fd30-439e-8040-6922d9f0455d",
        "Cricket/Name": "Curtly Ambrose",
        "Cricket/Shirt Number": 1,
        "Cricket/Height": "2.15",
        "Cricket/Retired": true
      }
    },
    {
      "action": "update-latest",
      "entity": {
        "fibery/id": "abe35d9b-4286-49f9-9ecb-0a777dcf98da",
        "Cricket/Name": "Brian Lara",
        "Cricket/Shirt Number": 18,
        "Cricket/Height": "1.75",
        "Cricket/Retired": false
      },
      "duplicate": {
        "Cricket/Height": "1.75",
        "fibery/modification-date": "2025-09-02T14:39:58.586Z",
        "fibery/id": "20f9b920-9752-11e9-81b9-4363f716f666",
        "fibery/created-by": {"fibery/id": "4044090b-7165-4791-ac15-20fb12ae0b64"},
        "fibery/creation-date": "2025-09-02T14:39:58.586Z",
        "Cricket/Name": "Brian Lara",
        "fibery/public-id": "4",
        "Cricket/Retired": false,
        "Cricket/Shirt Number": 18,
        "Cricket/Bio": {"fibery/id": "01990ade-d091-7022-b1c4-7efe12ccd84b"},
        "fibery/rank": 7072311628808326
      },
      "updated": {
        "Cricket/Height": "1.75",
        "fibery/id": "20f9b920-9752-11e9-81b9-4363f716f666",
        "Cricket/Name": "Brian Lara",
        "Cricket/Retired": false,
        "Cricket/Shirt Number": 18
      }
    },
    {
      "action": "update-latest",
      "entity": {
        "fibery/id": "c79d09ba-1c2d-40f4-aa3b-cf7bc79ff7a8",
        "Cricket/Name": "Curtly Ambrose",
        "Cricket/Shirt Number": 1,
        "Cricket/Height": "2.15",
        "Cricket/Retired": true
      },
      "duplicate": {
        "Cricket/Height": "2.10",
        "fibery/modification-date": "2025-09-02T14:39:58.586Z",
        "fibery/id": "79580f9d-fd30-439e-8040-6922d9f0455d",
        "fibery/created-by": {"fibery/id": "4044090b-7165-4791-ac15-20fb12ae0b64"},
        "fibery/creation-date": "2025-09-02T14:39:58.586Z",
        "Cricket/Name": "Curtly Ambrose",
        "fibery/public-id": "5",
        "Cricket/Retired": true,
        "Cricket/Shirt Number": 1,
        "Cricket/Bio": {"fibery/id": "01990ade-d091-7024-9fd1-e03f62f5860e"},
        "fibery/rank": 7072311628908326
      },
      "updated": {
        "Cricket/Height": "2.15",
        "fibery/id": "79580f9d-fd30-439e-8040-6922d9f0455d",
        "Cricket/Name": "Curtly Ambrose",
        "Cricket/Retired": true,
        "Cricket/Shirt Number": 1
      }
    }
  ]
}

Getting started

General

HTTP API

AI & agents

Integrations

GraphQL API

Case 1

Case 2

Case 3

Case 4

Getting started

General

HTTP API

AI & agents

Integrations

GraphQL API

​Case 1

​Case 2

​Case 3

​Case 4

Case 1

Case 2

Case 3

Case 4