Create Entities
POST
/v1/entity
POST
/v1/entity
Upsert (create or update) a single entity in the index.
Authentication
All requests require an API Key to be passed in the header. See Authentication.
Request
URL:
POST https://api.getomni.ai/v1/entity
Request Body This endpoint expects a JSON body describing the entity. The below JSON Schema is an example; you can include any fields relevant to identifying duplicates (e.g.,
name
,description
,color
,size
, etc.).
Example Request
Synchronous vs. Asynchronous For single-item upserts, the API typically responds synchronously with potential duplicates. Larger or more complex requests may run asynchronously (especially if image checks are enabled).
Response
Success (200 OK)
Returns the original entity with an array of objects representing potential duplicates, including a similarity score.
Error
Potential error codes:
400 Bad Request
: Missing required fields or invalid JSON.401 Unauthorized
: Missing or invalid API key.
POST /v1/entities/batch
POST /v1/entities/batch
Upsert (create or update) multiple entities in a single batch request.
URL
Headers
Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json
Request Body
Asynchronous Processing
For very large batches (tens of thousands to millions of entities), the request will return quickly with a
jobId
and initialstatus
. You will then use the providedjobId
to poll for the status of the indexing job.Smaller batches may be processed synchronously, returning results directly in the response.
Example Request
Example Response (Asynchronous)
Use
GET /v1/entities/batch/status?jobId=<jobId>
to check status and retrieve results.
Example Response (Synchronous)
GET /v1/entities/batch/status
GET /v1/entities/batch/status
Check the status of a batch job submitted by POST /v1/entities/batch
.
URL
Headers
Authorization: Bearer <YOUR_API_KEY>
Parameters
jobId
(required): The job identifier returned from the batch request.
Response
Success (200 OK)
status can be
PENDING
,PROCESSING
,COMPLETED
, orFAILED
.results is optional and may include a summary or partial data depending on request size.
Error
Last updated