Create Entities

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.).

  {
    "type": "object",
    "properties": {
      "id": {
        "type": "number",
        "description": "Unique internal ID for the product"
      },
      "sku": {
        "type": "string",
        "description": "Unique SKU"
      },
      "name": {
        "type": "string",
        "description": "Product name"
      },
      "description": {
        "type": "string",
        "description": "Detailed product description"
      },
      "color": {
        "type": "string",
        "description": "Primary color"
      },
      "cost": {
        "type": "number",
        "description": "Product cost or price"
      },
      "specifications": {
        "type": "object",
        "description": "Any key-value specs for the product"
      }
    },
    "required": ["id", "sku", "name"]
  }

Example Request

curl -X POST "https://api.getomni.ai/v1/entity" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 12345,
    "sku": "283JAD03",
    "name": "Nike Air Max",
    "description": "Men’s running shoe with Air cushioning.",
    "color": "Black",
    "cost": 99.99,
    "specifications": {
      "material": "synthetic",
      "weight": "12oz"
    }
  }'

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.

{
  "id": 12345,
  "sku": "283JAD03",
  "name": "Nike Air Max",
  "duplicates": [
    {
      "id": 38291,
      "sku": "XYE-83",
      "similarity": 0.87,
      "duplicate": true
    }
  ]
}

Error

{
  "error": "Invalid request"
}

Potential error codes:

• 400 Bad Request: Missing required fields or invalid JSON.

• 401 Unauthorized: Missing or invalid API key.

POST /v1/entities/batch

Upsert (create or update) multiple entities in a single batch request.

• URL

  bashCopy codePOST /v1/entities/batch
• Headers

  • Authorization: Bearer <YOUR_API_KEY>

  • Content-Type: application/json

• Request Body

  {
    "entities": [
      {
        "id": 12345,
        "sku": "283JAD03",
        "name": "Nike Air Max",
        "description": "Men’s running shoe with Air cushioning.",
        "color": "Black",
        "cost": 99.99,
        "specifications": { "material": "synthetic", "weight": "12oz" }
      },
      {
        "id": 12346,
        "sku": "283JAD04",
        "name": "Nike Air Zoom",
        "description": "Men’s running shoe with Zoom cushioning.",
        "color": "White",
        "cost": 109.99
      }
      // ... up to thousands or millions of items in multiple calls
    ]
  }
• Asynchronous Processing

  • For very large batches (tens of thousands to millions of entities), the request will return quickly with a jobId and initial status. You will then use the provided jobId to poll for the status of the indexing job.

  • Smaller batches may be processed synchronously, returning results directly in the response.

• Example Request

  bashCopy codecurl -X POST "https://api.getomni.ai/v1/entities/batch" \
    -H "Authorization: Bearer <YOUR_API_KEY>" \
    -H "Content-Type: application/json" \
    -d '{
      "entities": [
        {
          "id": 12345,
          "sku": "283JAD03",
          "name": "Nike Air Max",
          "description": "Men’s running shoe with Air cushioning.",
          "color": "Black",
          "cost": 99.99
        },
        {
          "id": 12346,
          "sku": "283JAD04",
          "name": "Nike Air Zoom",
          "description": "Men’s running shoe with Zoom cushioning.",
          "color": "White",
          "cost": 109.99
        }
      ]
    }'
• Example Response (Asynchronous)

  jsonCopy code{
    "jobId": "a9b5c4f0-8202-4375-8e2c-4383a5b0d450",
    "status": "PENDING",
    "message": "Batch submitted successfully"
  }

  • Use GET /v1/entities/batch/status?jobId=<jobId> to check status and retrieve results.

• Example Response (Synchronous)

  jsonCopy code{
    "jobId": null,
    "entities": [
      {
        "id": 12345,
        "sku": "283JAD03",
        "duplicates": [
          {
            "id": 38291,
            "sku": "XYE-83",
            "similarity": 0.87,
            "duplicate": true
          }
        ]
      },
      {
        "id": 12346,
        "sku": "283JAD04",
        "duplicates": []
      }
    ]
  }

GET /v1/entities/batch/status

Check the status of a batch job submitted by POST /v1/entities/batch.

• URL

  bashCopy codeGET /v1/entities/batch/status?jobId=<jobId>
• Headers

  • Authorization: Bearer <YOUR_API_KEY>

• Parameters

  • jobId (required): The job identifier returned from the batch request.

• Response

  Success (200 OK)

  jsonCopy code{
    "jobId": "a9b5c4f0-8202-4375-8e2c-4383a5b0d450",
    "status": "COMPLETED",
    "indexedCount": 40000000,
    "duplicatesFound": 500000,
    "message": "Batch indexing complete",
    "results": [
      {
        "id": 12345,
        "duplicates": [
          { "id": 38291, "similarity": 0.87, "duplicate": true }
        ]
      }
      // ... truncated
    ]
  }

  • status can be PENDING, PROCESSING, COMPLETED, or FAILED.

  • results is optional and may include a summary or partial data depending on request size.

  Error

  jsonCopy code{
    "error": "Invalid jobId"
  }