Skip to main content
Points are the core data structure in Qdrant. Each point consists of an ID, a vector (or multiple vectors), and an optional payload.

​
API Endpoint

PUT /collections/{collection_name}/points
This endpoint performs an upsert operation: if a point with the given ID already exists, it will be overwritten. Otherwise, a new point will be created.

​
Point Structure

Each point has the following structure:
​
id
integer | string
required
Unique identifier for the point. Can be an integer or UUID string.
​
vector
array | object
required
Vector data. Can be a simple array for single vectors or an object with named vectors.
​
payload
object
Optional JSON object with additional data associated with the point.

​
Insert a Single Point

curl -X PUT http://localhost:6333/collections/my_collection/points \
  -H 'Content-Type: application/json' \
  -d '{
    "points": [
      {
        "id": 1,
        "vector": [0.05, 0.61, 0.76, 0.74],
        "payload": {
          "city": "Berlin",
          "country": "Germany",
          "population": 3645000,
          "year": 2023
        }
      }
    ]
  }'

​
Insert Multiple Points (Batch)

Batch insertion is more efficient for inserting multiple points at once. 
curl -X PUT http://localhost:6333/collections/my_collection/points \
  -H 'Content-Type: application/json' \
  -d '{
    "points": [
      {
        "id": 1,
        "vector": [0.05, 0.61, 0.76, 0.74],
        "payload": {"city": "Berlin", "country": "Germany"}
      },
      {
        "id": 2,
        "vector": [0.19, 0.81, 0.75, 0.11],
        "payload": {"city": "London", "country": "UK"}
      },
      {
        "id": 3,
        "vector": [0.36, 0.55, 0.47, 0.94],
        "payload": {"city": "Paris", "country": "France"}
      }
    ]
  }'

​
Insert Points with Named Vectors

For collections with multiple named vectors, specify each vector separately. 
curl -X PUT http://localhost:6333/collections/multi_vector_collection/points \
  -H 'Content-Type: application/json' \
  -d '{
    "points": [
      {
        "id": 1,
        "vector": {
          "text": [0.1, 0.2, 0.3, 0.4],
          "image": [0.5, 0.6, 0.7, 0.8]
        },
        "payload": {
          "title": "Product A",
          "description": "High quality item"
        }
      }
    ]
  }'

​
Insert Points Using Batch Format

The batch format is more efficient for inserting many points with the same structure. 
curl -X PUT http://localhost:6333/collections/my_collection/points \
  -H 'Content-Type: application/json' \
  -d '{
    "batch": {
      "ids": [1, 2, 3],
      "vectors": [
        [0.05, 0.61, 0.76, 0.74],
        [0.19, 0.81, 0.75, 0.11],
        [0.36, 0.55, 0.47, 0.94]
      ],
      "payloads": [
        {"city": "Berlin"},
        {"city": "London"},
        {"city": "Paris"}
      ]
    }
  }'

​
Query Parameters

​
wait
boolean
default:"true"
If true, wait for changes to actually happen. If false, return immediately after the request is accepted.
​
ordering
string
Define ordering guarantees for the operation:
  • weak - No ordering guarantees
  • medium - Operations are ordered within a single node
  • strong - Operations are ordered across all nodes
​
timeout
integer
Timeout for the operation in seconds.

​
Using the Wait Parameter

curl -X PUT "http://localhost:6333/collections/my_collection/points?wait=true" \
  -H 'Content-Type: application/json' \
  -d '{...}'
The request will return only after the points are fully indexed and available for search.
Setting wait=false provides lower latency but points may not be immediately available for search.

​
Response Format

​
result
object
Result of the upsert operation.
​
result.operation_id
integer
Sequential number of the operation.
​
result.status
string
Operation status: completed or acknowledged.
​
status
string
Overall response status, typically “ok”.
​
time
number
Time taken to execute the operation in seconds.
Response Example
{
  "result": {
    "operation_id": 0,
    "status": "completed"
  },
  "status": "ok",
  "time": 0.002375
}

​
Update Modes

Control how points are inserted or updated: 
curl -X PUT http://localhost:6333/collections/my_collection/points \
  -H 'Content-Type: application/json' \
  -d '{
    "points": [...],
    "update_mode": "insert_only"
  }'
​
update_mode
string
default:"upsert"
  • upsert - Insert new points and update existing ones (default)
  • insert_only - Only insert new points, skip existing ones
  • update_only - Only update existing points, skip new ones
Vector dimensions must match the collection configuration. Mismatched dimensions will result in an error.

​
Best Practices

  1. Batch Size: Insert points in batches of 100-1000 for optimal performance
  2. Wait Parameter: Use wait=false for bulk uploads to improve throughput
  3. Payload Size: Keep payloads reasonably sized (< 1MB per point) for best performance
  4. IDs: Use sequential integers or UUIDs; avoid very long string IDs