---
title: "Insert new points into the collection"
method: POST
path: "/collections/{collectionId}/points"
tags: ["Point"]
---

# Insert new points into the collection

`POST /collections/{collectionId}/points`

This endpoint assumes all points to be inserted are new points and does not check for duplication. It is important to ensure consistency of the database you do not insert duplicate points. If you are unsure if a point exists, you can leave the id field blank and the database will assign a new id. *For cosine distance, you must normalise the vectors prior to inserting them.*

## Request body

- InsertPointsRequest
  - `points` PointAsObject[], required
    - `_id` string, uuid

## Response `200`

The operation was successful but you must check the failedRanges to ensure all the points were inserted. If some points were not inserted, you can retry the operation by using the failedRanges depending on the error. For example, if the failedRanges is [[0, 2]], you can retry the operation by sending the first two points again.

- InsertPointsResponse
  - `message` string — A message indicating the result of the operation
  - `failedRanges` object[] — A list of ranges of points that failed to insert. Each range has a start and an end index. The end index is exclusive. For example, if the range is [0, 2], the first two points failed to insert.
    - `shardId` string, uuid
    - `start` integer
    - `end` integer
    - `error` string

## Other responses

- `403` — Something unexpected happened
- `503` — Something unexpected happened

## Changes

- **2024-04-11** (v2) `e6fd80307fb5` — 3 warning, 1 info
  - removed the request property `points/items/id`
  - removed the request property `points/items/metadata`
  - removed the request property `points/items/vector`
  - added the new optional request property `points/items/_id`
- **2024-03-05** (v2) `dd1cf2f988c1` — 2 breaking, 1 warning, 2 info
  - added the new required request property `points/items/vector`
  - the `points` request property's minItems was increased to `1`
  - removed the request property `points/items/_id`
  - added the new optional request property `points/items/id`
  - …1 more

[Change history](https://skmtc.dev/semafind/apis/semadb-api/changes/collections/:collectionId/points/post.md)

---

[API](https://skmtc.dev/semafind/apis/semadb-api.md) · [All operations](https://skmtc.dev/semafind/apis/semadb-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/semafind/semadb-api/revisions/e756ed7c3cd3/schema)