{ "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" } ] }