Clean up stale entities

When you remove a resource type from your integration mapping or decommission an integration, the associated entities in Port are not automatically deleted. This documentation explains how to properly clean up stale entities to keep your software catalog accurate and up to date.

When cleanup is needed

Cleanup is typically required when you:

• Remove a kind from your integration mapping (for example, removing pull-request to stop syncing PRs).
• Delete an integration entirely.
• Rename a blueprint identifier.
• Change your mapping in a way that orphans previously synced entities.

The 3-step cleanup process

Removing stale entities requires completing these steps in order. Skipping a step or performing them out of sequence can leave orphaned data in your catalog.

Step 1: Remove the mapping

Before deleting any entities, remove the resource mapping from your integration configuration. This prevents the integration from recreating the entities on the next resync.

1. Go to your connectors page.

2. Click on the integration you want to modify.

3. Navigate to the Mapping tab.

4. Remove the entire resource block for the kind you no longer want to sync.

5. Click Save & Resync.

For example, if you no longer want to sync pull requests, remove this entire block:

- kind: pull-request
  selector:
    query: "true"
  port:
    entity:
      mappings:
        identifier: ".id | tostring"
        title: ".title"
        blueprint: '"pullRequest"'
        properties:
          # ... properties

Order matters

Always remove the mapping before deleting entities. If you delete entities first, the next integration resync will recreate them.

Step 2: Delete the entities

Once the mapping is removed, delete the stale entities. You can do this through the UI or via the API.

Using the UI

Delete entities one by one

1. Go to the catalog page for the relevant blueprint.

2. On the entity you want to delete click on the ... button.

3. Click on Unregister button in the toolbar.

4. Confirm the deletion by clicking on Unregister again.

Delete all entities of a blueprint

If you need to delete all entities of a specific blueprint:

1. Go to the catalog page for the blueprint.

2. Click the ... menu in the top-right corner.

3. Select Delete page.

4. Click Delete to confirm the deletion.

Using the API

Delete a single entity

curl -X DELETE "https://api.getport.io/v1/blueprints/<blueprint_identifier>/entities/<entity_identifier>" \
  -H "Authorization: Bearer $PORT_ACCESS_TOKEN"

Delete multiple entities (up to 100)

curl -X POST "https://api.getport.io/v1/blueprints/<blueprint_identifier>/bulk/entities/delete" \
  -H "Authorization: Bearer $PORT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entities": ["entity_id_1", "entity_id_2", "entity_id_3"]
  }'

Delete all entities of a blueprint

To delete all entities belonging to a specific blueprint:

curl -X DELETE "https://api.getport.io/v1/blueprints/<blueprint_identifier>/all-entities" \
  -H "Authorization: Bearer $PORT_ACCESS_TOKEN"

If the entities have dependent entities (entities that reference them via required relations), add the delete_dependents query parameter:

curl -X DELETE "https://api.getport.io/v1/blueprints/<blueprint_identifier>/all-entities?delete_dependents=true" \
  -H "Authorization: Bearer $PORT_ACCESS_TOKEN"

Irreversible operation

Entity deletion is permanent and cannot be undone. Consider exporting your entities before deleting them if you might need the data later.

Step 3: Delete the blueprint (optional)

If you no longer need the blueprint itself, delete it after all its entities have been removed.

1. Go to the Data model page in Port.

2. Find the blueprint you want to delete.

3. Click the ... menu on the blueprint card.

4. Select Delete blueprint.

5. Type DELETE and click on Delete to confirm the deletion.

Blueprint deletion requirements

You can only delete a blueprint if:

• It has no remaining entities.
• No other blueprints have required relations pointing to it.

If other blueprints reference this blueprint, update or remove those relations first.

When you delete a blueprint, Port also deletes any associated catalog pages that were automatically created for that blueprint.

Export before deletion

Before deleting entities, you may want to export them for backup or audit purposes.

Using the UI

1. Go to the catalog page for the blueprint.

2. Click the Export button in the toolbar.

3. Choose your export format (CSV or JSON) to download the file.

Using the API

Use the search endpoint to retrieve all entities of a blueprint:

curl -X POST "https://api.getport.io/v1/entities/search" \
  -H "Authorization: Bearer $PORT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "combinator": "and",
    "rules": [
      {
        "property": "$blueprint",
        "operator": "=",
        "value": "<blueprint_identifier>"
      }
    ]
  }' > entities_backup.json

Handle dependent entities

When deleting entities that are referenced by other entities through relations, you have two options:

Option 1: Auto-delete dependent entities

Use the delete_dependents parameter to automatically delete entities that depend on the ones you're deleting:

curl -X DELETE "https://api.getport.io/v1/blueprints/<blueprint_identifier>/all-entities?delete_dependents=true" \
  -H "Authorization: Bearer $PORT_ACCESS_TOKEN"

Option 2: Update relations first

Manually update or remove the relations in dependent entities before deleting:

1. Identify which entities reference the entities you want to delete.
2. Update those entities to remove or change the relation values.
3. Then delete the original entities.

Mapping configuration options

Port provides configuration options to control automatic entity deletion during integration resyncs.

deleteDependentEntities

When enabled, Port automatically deletes dependent entities when their parent entity is removed during a resync. Add this to your mapping configuration:

deleteDependentEntities: true
resources:
  - kind: repository
    # ...

This option only controls deletion through required dependent relations. Setting it to false does not disable standard reconciliation cleanup and does not preserve an auto-created related entity that Port identifies as stale.

For details about entities created by createMissingRelatedEntities, including how to preserve them independently, see auto-created related entities during reconciliation.

entityDeletionThreshold

Controls whether the integration's deletion mechanism is active. Set to 0 to disable automatic deletion or 1 to enable it:

entityDeletionThreshold: 1
resources:
  - kind: repository
    # ...

enableDelete

enableDelete is an optional boolean on each item in the mapping resources list (same level as kind, selector, and port).

When cleanup is on, a resync can delete catalog entities that no longer appear in the integration data.
Set enableDelete to false on a resource if you still want that data synced into Port, but you do not want those entities deleted during cleanup.

Typical use case: the source occasionally returns an empty list (outage, filter change, partial sync) and you do not want Port to remove everything that was already in the catalog.

Value	Cleanup behavior
true / omitted	Entities of that resource’s blueprint can be deleted if they are missing from the resync (default).
false	Entities of that resource’s blueprint are not deleted during cleanup. New and updated entities are still written normally.

Cleanup uses the Port blueprint from the mapping (blueprint: '"…"'), not the integration kind name. The flag protects that blueprint.

Conflicting enableDelete values on the same blueprint

If two (or more) resources map to the same static blueprint and set conflicting enableDelete values:

Resource A	Resource B	Same blueprint?	Resync cleanup deletes for that blueprint
false	true / omitted	Yes	No
false	false	Yes	No
true / omitted	true / omitted	Yes	Yes (if entityDeletionThreshold is on)

One enableDelete: false is enough. Another resource that maps to the same blueprint with enableDelete: true does not turn deletes back on for that blueprint.

Cleanup ownership is per blueprint, not per mapping row

Cleanup ownership is per integration + blueprint: Port stores one set of entities for that blueprint from the integration. There is no separate “delete bucket” per kind / mapping row when several rows write to the same blueprint. To allow deletes again, set every resource that maps to that blueprint to enableDelete: true (or omit the flag), or split them onto different blueprints.

Interaction with entityDeletionThreshold

entityDeletionThreshold	enableDelete	Resync cleanup deletes for that blueprint
off (0)	any	No
on (1)	true / omitted	Yes (unless another resource protects the same blueprint, as described above)
on (1)	false	No

enableDelete: true does not re-enable deletes when entityDeletionThreshold is 0.

Interaction with deleteDependentEntities

When any resource has enableDelete: false with a static blueprint literal, Port also turns off cascade deletes (deleteDependentEntities) for that resync’s cleanup. That way a related parent deleted in the same cleanup run cannot remove a protected blueprint as a dependent.

YAML example

Different blueprints - each resource controls its own blueprint:

Different blueprints example (click to expand)

entityDeletionThreshold: 1
resources:
  - kind: namespace
    enableDelete: false   # namespace blueprint: no cleanup deletes
    selector:
      query: "true"
    port:
      entity:
        mappings:
          identifier: .metadata.uid
          title: .metadata.name
          blueprint: '"namespace"'
  - kind: application
    # enableDelete omitted → true → argocdApplication may be cleaned up
    selector:
      query: "true"
    port:
      entity:
        mappings:
          identifier: .metadata.uid
          title: .metadata.name
          blueprint: '"argocdApplication"'

Same blueprint - protect wins (entities of service are not deleted):

Same blueprint example (click to expand)

entityDeletionThreshold: 1
resources:
  - kind: service
    enableDelete: false
    selector:
      query: '.type == "api"'
    port:
      entity:
        mappings:
          identifier: .id
          title: .name
          blueprint: '"service"'
  - kind: service
    # true / omitted does NOT override the false above
    selector:
      query: '.type == "worker"'
    port:
      entity:
        mappings:
          identifier: .id
          title: .name
          blueprint: '"service"'

Limitations

• Configure enableDelete in the YAML mapping editor. There is no dedicated form-editor toggle in the current release.
• Applies to resync / reconciliation cleanup only. Live or webhook-driven deletes are not controlled by this flag.
• Protection matches static blueprint string literals only (for example blueprint: '"namespace"'). Dynamic JQ blueprint expressions are not protected.

For related global options, see Configure mapping - Advanced options.

Troubleshooting

Entities reappear after deletion

If entities reappear after you delete them, the integration mapping still includes the resource type. Make sure you:

1. Removed the kind from the mapping configuration.
2. Saved and resynced the integration.
3. Then deleted the entities.

Cannot delete blueprint

If you cannot delete a blueprint, check for:

• Remaining entities: Delete all entities of the blueprint first.
• Incoming relations: Other blueprints may have relations pointing to this blueprint. Update or remove those relations first.

Dependent entities blocking deletion

If you receive an error about dependent entities:

• Use the delete_dependents=true parameter in your API call.
• Or manually remove the relations from dependent entities first.