Entity mutations

Create Entity

This mutation creates a JupiterOne entity with the given specifications. This mutation requires three parameters (with two optional parameters):

• entityKey: A string that gives the key value for the entity so that this entity can be referenced later.
• entityType: A string that gives the type of the entity being created.
• entityClass: A string that gives the class of the entity being created.
• Optional Parameters
  • timestamp:
  • properties: A JSON list that gives specific properties that the entity will have.

mutation CreateEntity (
  $entityKey: String!
  $entityType: String!
  $entityClass: [String!]!
  $timestamp: Long
  $properties: JSON
) {
  createEntity (
    entityKey: $entityKey,
    entityType: $entityType,
    entityClass: $entityClass,
    timestamp: $timestamp,
    properties: $properties
  ) {
    entity {
      _id
      ...
    }
    vertex {
      id,
      entity {
        _id
        ...
      }
      properties
    }
  }
}

Variables:

{
  "entityKey": "<an entity key>",
  "entityType": "<an entity type>",
  "entityClass": "<an entity class>",
  "timestamp": 1529329792552,
  "properties": {
    // Custom properties on the Entity
    ...
  }
}

Creating entities and a relationship between them

The following mutations utilize a J1Client.

const CREATE_ENTITY = gql`
  mutation createEntity (
    $entityKey: String!
    $entityType: String!
    $entityClass: [String!]!
    $timestamp: Long
    $properties: JSON
  ) {
    createEntity(
      entityKey: $entityKey
      entityType: $entityType
      entityClass: $entityClass
      properties: $properties
    ) {
  .
  .
  .
  }`;

const CREATE_RELATIONSHIP = gql`
  mutation CreateRelationship (
    $relationshipKey: String!
    $relationshipType: String!
    $relationshipClass: String!
    $fromEntityId: String!
    $toEntityId: String!
  ) {
    createRelationship (
      relationshipKey: $relationshipKey
      relationshipType: $relationshipType
      relationshipClass: $relationshipClass
      fromEntityId: $fromEntityId
      toEntityId: $toEntityId
    ) {
    .
    .
    .
  }`;


const entity1 = await j1Client.mutate({
  mutation: CREATE_ENTITY,
  variable: {
    entityKey: 'Example Key',
    entityType: 'ExampleType',
    entityClass: 'ExampleClass',
    properties: {
      'tag.key': 'tagvalue'
    }
  }
});

const entity2 = await j1Client.mutate({
  mutation CREATE_ENTITY,
  variable: {
    entityKey: 'Other Example Key',
    entityType: 'OtherType',
    entityClass: 'OtherClass',
    properties: {
      'tag.key': 'tag'
    }
  }
});

const relationship = await j1Client.mutate({
  mutation: CREATE_RELATIONSHIP,
  variable: {
    relationshipKey: entity1._key + ' |uses| ' + entity2._key,
    relationshipClass: 'entity_uses_entity',
    relationshipType: 'USES',
    toEntityId: entity2._id,
    toEntityKey: entity1._id,
  }
});

Updating Entity

This mutation updates an already existing entity (does not create an entity). You cannot change the entityKey, entityClass, or entityType. This mutation requires one parameter (with two optional parameters):

• entityId: A string specific to the entity that finds the entity.
• Optional Parameters:
  • timestamp:
  • properties: A JSON list of properties to be changed.

mutation UpdateEntity (
  $entityId: String!
  $timestamp: Long
  $properties: JSON
) {
  updateEntity (
    entityId: $entityId,
    timestamp: $timestamp,
    properties: $properties
  ) {
    entity {
      _id
      ...
    }
    vertex {
      id,
      entity {
        _id
        ...
      }
      properties
    }
  }
}

Variables:

{
  "entityId": "<an entity Id (entity._id)>",
  "timestamp": 1529329792552,
  "properties": {
    // Custom properties to get updated
    ...
  }
}

Property persistence

Properties set with updateEntity persist across future syncs of the source integration. If you set criticality = "tier-1" on a GitHub repository entity, the value remains on the entity after every subsequent GitHub integration sync — you do not need to re-apply it. If the integration's own data later asserts a different value for the same property, your updateEntity value continues to win until you explicitly clear it.

This makes updateEntity the right tool for one-off persistent edits on entities owned by a managed integration — for example, tagging a single repository with a criticality tier or pinning a custom unification key on two specific hosts.

When to use updateEntity vs sync modes

You want to…	Use
Set a property on one entity (or a handful, scripted one at a time) and have it survive every future integration sync.	updateEntity
Set a property on a batch of up to 10,000 entities under a stable scope, managed together, and have those values survive every future integration sync.	OVERRIDE sync mode
Refresh a property frequently on managed-integration entities, and you accept that each integration sync resets the value.	PATCH sync mode
Add or remove entities and relationships in a dataset you fully own.	DIFF sync mode

If both an OVERRIDE sync job and an updateEntity mutation set the same property on the same entity, the OVERRIDE value takes precedence. See OVERRIDE vs the entity mutation API for details.

Deleting Entity

This mutation deletes an existing entity. This mutation requires one parameter (with one optional parameter):

• entityId: A string specific to the entity that finds the entity.
• Optional Parameters:
  • timestamp
  • hardDelete - this flag completely removes all information related to the entity and is not recoverable.

mutation DeleteEntity (
  $entityId: String!
  $timestamp: Long
) {
  deleteEntity (
    entityId: $entityId,
    timestamp: $timestamp,
  ) {
    entity {
      _id
      ...
    }
    vertex {
      id,
      entity {
        _id
        ...
      }
      properties
    }
  }
}

Variables:

{
  "entityId": "<an entity Id (entity._id)>",
  "timestamp": 1529329792552
}