@epilot/sdk 2.19.3 → 2.19.4

package/definitions/deduplication.json

@@ -0,0 +1,782 @@
+{
+  "openapi": "3.0.2",
+  "info": {
+    "version": "3.0.0",
+    "title": "Deduplication API",
+    "description": "Backend for Epilot Deduplication feature"
+  },
+  "security": [
+    {
+      "EpilotAuth": []
+    }
+  ],
+  "paths": {
+    "/v1/deduplicate": {
+      "post": {
+        "operationId": "deduplicate",
+        "summary": "deduplicate",
+        "description": "Deduplicates Entities",
+        "tags": [],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DeduplicateRequestBody"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successful response with Deduplication content",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DeduplicateRequestResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/deduplicate/job": {
+      "post": {
+        "operationId": "deduplicateAsync",
+        "summary": "deduplicateAsync",
+        "description": "Submits an async deduplication job. Returns a job ID immediately. Poll GET /v1/deduplicate/jobs/{jobId} for status.",
+        "tags": [],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DeduplicateRequestBody"
+              }
+            }
+          }
+        },
+        "responses": {
+          "202": {
+            "description": "Job accepted. Use the returned jobId to poll for status.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DeduplicateAsyncResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/deduplicate/jobs/{jobId}": {
+      "get": {
+        "operationId": "getDeduplicationJob",
+        "summary": "getDeduplicationJob",
+        "description": "Returns the current status of an async deduplication job",
+        "tags": [],
+        "parameters": [
+          {
+            "name": "jobId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "The job ID returned by POST /v1/deduplicate/job"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Current job status",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DeduplicationJob"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Job not found"
+          }
+        }
+      }
+    },
+    "/v1/detect-duplicates": {
+      "post": {
+        "operationId": "detectDuplicates",
+        "summary": "detectDuplicates",
+        "description": "Detects potential duplicate entities for the given entity using the schema's prioritized uniqueness rules. Returns matches with a confidence score.",
+        "tags": [],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DetectDuplicatesRequestBody"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Potential duplicates ranked by rule priority",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DetectDuplicatesResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/duplicates/dismiss": {
+      "post": {
+        "operationId": "dismissDuplicates",
+        "summary": "dismissDuplicates",
+        "description": "Confirms entities as NOT duplicates: clears the internal duplicate-detection flags (_matching_entities) on each given entity, so they stop appearing as open duplicate sets. The records themselves are not modified otherwise.",
+        "tags": [],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DismissDuplicatesRequestBody"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Flags cleared",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DismissDuplicatesResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/uniqueness-criteria": {
+      "get": {
+        "operationId": "listUniquenessCriteria",
+        "summary": "listUniquenessCriteria",
+        "description": "Lists UniquenessCriteria for the requesting organization. Optionally filtered by schema.",
+        "tags": [],
+        "parameters": [
+          {
+            "name": "schema",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Filter results to a specific entity schema."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Array of UniquenessCriteria records",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UniquenessCriteriaListResponse"
+                }
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "operationId": "createUniquenessCriteria",
+        "summary": "createUniquenessCriteria",
+        "description": "Creates a new UniquenessCriteria record.",
+        "tags": [],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UniquenessCriteriaCreateBody"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Created record",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UniquenessCriteria"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/uniqueness-criteria/{schema}": {
+      "get": {
+        "operationId": "getUniquenessCriteria",
+        "summary": "getUniquenessCriteria",
+        "description": "Fetch a single UniquenessCriteria record.",
+        "tags": [],
+        "parameters": [
+          {
+            "name": "schema",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Entity schema slug."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The criteria record",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UniquenessCriteria"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Record not found"
+          }
+        }
+      },
+      "put": {
+        "operationId": "updateUniquenessCriteria",
+        "summary": "updateUniquenessCriteria",
+        "description": "Replace the matchRules on an existing UniquenessCriteria record.",
+        "tags": [],
+        "parameters": [
+          {
+            "name": "schema",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Entity schema slug."
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UniquenessCriteriaUpdateBody"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Updated record",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UniquenessCriteria"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Record not found"
+          }
+        }
+      },
+      "delete": {
+        "operationId": "deleteUniquenessCriteria",
+        "summary": "deleteUniquenessCriteria",
+        "description": "Delete a UniquenessCriteria record.",
+        "tags": [],
+        "parameters": [
+          {
+            "name": "schema",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Entity schema slug."
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Record deleted"
+          },
+          "404": {
+            "description": "Record not found"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "EpilotAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "description": "Authorization header with epilot OAuth2 bearer token",
+        "bearerFormat": "JWT"
+      }
+    },
+    "schemas": {
+      "DeduplicateRequestBody": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "toKeep": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Entity id to keep and merge the duplicates into"
+            },
+            "toDelete": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              },
+              "minItems": 1,
+              "description": "Non-empty list of duplicate entity ids to merge into toKeep and delete"
+            }
+          },
+          "required": [
+            "toKeep",
+            "toDelete"
+          ]
+        },
+        "minItems": 1
+      },
+      "DeduplicateRequestResponse": {
+        "type": "object",
+        "properties": {
+          "deduplicatedEntities": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Entity"
+            },
+            "description": "The merged survivor entity of each processed set"
+          }
+        },
+        "required": [
+          "deduplicatedEntities"
+        ]
+      },
+      "Entity": {
+        "type": "object",
+        "properties": {
+          "_id": {
+            "type": "string",
+            "description": "Entity ID of the Deduplication entry"
+          },
+          "_org": {
+            "type": "string",
+            "description": "ID of the Organization that owns this Deduplication"
+          },
+          "_schema": {
+            "type": "string",
+            "description": "The Entity schema of this Deduplication"
+          },
+          "_created_at": {
+            "type": "string",
+            "description": "The timestamp of when this Deduplication was created",
+            "format": "date-time"
+          },
+          "_updated_at": {
+            "type": "string",
+            "description": "The timestamp of when this Deduplication was last updated",
+            "format": "date-time"
+          },
+          "_created_by": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "number"
+              }
+            ],
+            "description": "The Entity ID of the User that created this Deduplication"
+          },
+          "created_by": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "number"
+              }
+            ],
+            "description": "The Entity ID of the User that created this Deduplication"
+          },
+          "_tags": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Tags associated with this Deduplication"
+          },
+          "_acl": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "description": "Access Control List for this Deduplication entry"
+          },
+          "_owners": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "org_id": {
+                  "type": "string"
+                },
+                "user_id": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "org_id",
+                "user_id"
+              ]
+            }
+          },
+          "type": {
+            "type": "string",
+            "description": "Entity ID of the Deduplication entry"
+          }
+        },
+        "required": [
+          "_id"
+        ],
+        "description": "Base Entity schema"
+      },
+      "DeduplicateAsyncResponse": {
+        "type": "object",
+        "properties": {
+          "jobId": {
+            "type": "string",
+            "description": "Job ID to poll for status via GET /v1/deduplicate/jobs/{jobId}"
+          },
+          "status": {
+            "$ref": "#/components/schemas/JobStatus"
+          },
+          "message": {
+            "type": "string",
+            "description": "Initial status message"
+          }
+        },
+        "required": [
+          "jobId",
+          "status",
+          "message"
+        ],
+        "description": "Response returned immediately when a deduplication job is submitted"
+      },
+      "JobStatus": {
+        "type": "string",
+        "enum": [
+          "pending",
+          "processing",
+          "completed",
+          "failed"
+        ]
+      },
+      "DeduplicationJob": {
+        "type": "object",
+        "properties": {
+          "jobId": {
+            "type": "string",
+            "description": "Unique identifier for the deduplication job"
+          },
+          "status": {
+            "$ref": "#/components/schemas/JobStatus"
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable status message (e.g. progress info or error details)"
+          },
+          "result": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Entity"
+            },
+            "description": "Array of deduplicated entities, present when status is completed"
+          },
+          "createdAt": {
+            "type": "string",
+            "description": "ISO 8601 timestamp of job creation",
+            "format": "date-time"
+          },
+          "updatedAt": {
+            "type": "string",
+            "description": "ISO 8601 timestamp of last update",
+            "format": "date-time"
+          }
+        },
+        "required": [
+          "jobId",
+          "status",
+          "createdAt",
+          "updatedAt"
+        ],
+        "description": "Represents an async deduplication job"
+      },
+      "DetectDuplicatesRequestBody": {
+        "type": "object",
+        "properties": {
+          "schema": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Entity schema to search (e.g. 'contact'). Must have UniquenessCriteria configured for the calling org."
+          },
+          "entity": {
+            "type": "object",
+            "additionalProperties": {},
+            "description": "The entity to look up potential duplicates for. Attribute values are extracted from this entity per the schema's match rules; system fields such as '_id' are supported. A rule is evaluated when at least one of its attributes resolves to a non-empty value on this entity; attributes without a value require candidates to also lack a value for them."
+          }
+        },
+        "required": [
+          "schema",
+          "entity"
+        ]
+      },
+      "DetectDuplicatesResponse": {
+        "type": "object",
+        "properties": {
+          "matches": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/DetectedDuplicateMatch"
+            }
+          }
+        },
+        "required": [
+          "matches"
+        ]
+      },
+      "DetectedDuplicateMatch": {
+        "type": "object",
+        "properties": {
+          "entity": {
+            "$ref": "#/components/schemas/Entity"
+          },
+          "confidence": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1,
+            "description": "Confidence score for the match, between 0 and 1."
+          },
+          "matched_attributes": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "minItems": 1,
+            "description": "Names of the attributes that matched on the rule that produced this hit."
+          }
+        },
+        "required": [
+          "entity",
+          "confidence",
+          "matched_attributes"
+        ]
+      },
+      "DismissDuplicatesRequestBody": {
+        "type": "object",
+        "properties": {
+          "schema": {
+            "type": "string",
+            "minLength": 1
+          },
+          "entityIds": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            },
+            "minItems": 1,
+            "maxItems": 100,
+            "description": "Entities whose duplicate flags (_matching_entities) are cleared — the records are confirmed as NOT duplicates and stay separate"
+          }
+        },
+        "required": [
+          "schema",
+          "entityIds"
+        ]
+      },
+      "DismissDuplicatesResponse": {
+        "type": "object",
+        "properties": {
+          "dismissed": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Entity ids whose duplicate flags were cleared"
+          }
+        },
+        "required": [
+          "dismissed"
+        ]
+      },
+      "UniquenessCriteriaListResponse": {
+        "type": "object",
+        "properties": {
+          "items": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/UniquenessCriteria"
+            }
+          }
+        },
+        "required": [
+          "items"
+        ]
+      },
+      "UniquenessCriteria": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Unique identifier of the criteria record."
+          },
+          "orgId": {
+            "type": "string",
+            "description": "Organization the criteria belong to."
+          },
+          "schema": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Entity schema these criteria apply to (e.g. 'contact')."
+          },
+          "matchRules": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/MatchRule"
+            },
+            "minItems": 1,
+            "description": "Ordered list of match rules. Order is the evaluation priority."
+          },
+          "createdAt": {
+            "type": "string",
+            "description": "ISO 8601 timestamp of record creation.",
+            "format": "date-time"
+          },
+          "updatedAt": {
+            "type": "string",
+            "description": "ISO 8601 timestamp of last update.",
+            "format": "date-time"
+          }
+        },
+        "required": [
+          "id",
+          "orgId",
+          "schema",
+          "matchRules",
+          "createdAt",
+          "updatedAt"
+        ],
+        "description": "Defines what makes an entity of a given schema unique within an organization."
+      },
+      "MatchRule": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "maxLength": 100,
+            "description": "Optional human-readable label for the rule. Purely descriptive; not used during matching."
+          },
+          "attributes": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/MatchAttribute"
+            },
+            "minItems": 1,
+            "description": "Attributes that must all match for this rule to fire. Attributes without a value on the source entity must also have no value on a matching candidate."
+          },
+          "confidence": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1,
+            "description": "Confidence assigned to matches produced by this rule, between 0 and 1."
+          }
+        },
+        "required": [
+          "attributes",
+          "confidence"
+        ],
+        "description": "One way to identify the same entity. Evaluated in order; first rule whose attributes are all available and that returns hits wins."
+      },
+      "MatchAttribute": {
+        "type": "object",
+        "properties": {
+          "attribute": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Name of the entity attribute to match on. Its query path is resolved from the entity schema at query time."
+          }
+        },
+        "required": [
+          "attribute"
+        ],
+        "description": "One attribute participating in a match rule. Wrapped as an object so per-attribute options can be added later."
+      },
+      "UniquenessCriteriaCreateBody": {
+        "type": "object",
+        "properties": {
+          "schema": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Entity schema these criteria apply to."
+          },
+          "matchRules": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/MatchRule"
+            },
+            "minItems": 1
+          }
+        },
+        "required": [
+          "schema",
+          "matchRules"
+        ]
+      },
+      "UniquenessCriteriaUpdateBody": {
+        "type": "object",
+        "properties": {
+          "matchRules": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/MatchRule"
+            },
+            "minItems": 1
+          }
+        },
+        "required": [
+          "matchRules"
+        ]
+      }
+    }
+  },
+  "servers": [
+    {
+      "url": "https://deduplication.sls.epilot.io"
+    }
+  ]
+}