Upsert Vectors

Inserts or updates vector values to the index.

  • Path: /upsert
    • Method: [GET | POST]
    • Body: JSON: UpsertVector(...) OR Array<UpsertVector>
  • Auth: Authorization: Bearer TOKEN
    • Role: READWRITE
  • Response: JSON: Result<String>

Example Request

curl https://better-dodo-20522-us1-vector.upstash.io/upsert \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"id": "id10",
  "vector": [0.44,0.8,0.05,0.72,0.83,0.49,0.6,0.48],
  "metadata": { "key": "value" } }'

Example Response

{
  "result": "Success"
}

Query Vectors

Queries vectors similar to given query vector.

  • Path: /query
    • Method: [GET | POST]
    • Body: JSON: QueryVector(...)
  • Auth: Authorization: Bearer TOKEN
    • Role: READONLY
  • Response: JSON: Result<List<VectorScore>>

Example Request

curl https://better-dodo-20522-us1-vector.upstash.io/query \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{ "vector": [0.42,0.63,0.05,0.72,0.83,0.49,0.6,0.48],
"topK": 2,
  "includeVectors": true,
  "includeMetadata": true
 }'

Example Response

{
  "result": [
    {
      "id": "id12",
      "score": 1.0,
      "vector": [0.42, 0.63, 0.05, 0.72, 0.83, 0.49, 0.6, 0.48],
      "metadata": { "key": "value" }
    },
    {
      "id": "id11",
      "score": 0.99996454,
      "vector": [0.44, 0.63, 0.05, 0.72, 0.83, 0.49, 0.6, 0.48],
      "metadata": { "key": "value" }
    }
  ]
}

Fetch Random Vector

Fetches a random vector. Returns null if the index is empty.

  • Path: /random
    • Method: [GET]
  • Auth: Authorization: Bearer TOKEN
    • Role: READONLY
  • Response: JSON: Result<Vector?>

Example Request

curl https://better-dodo-20522-us1-vector.upstash.io/random \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response

{
  "result": [
    {
      "id": "id12",
      "score": 1.0,
      "vector": [0.42, 0.63, 0.05, 0.72, 0.83, 0.49, 0.6, 0.48],
      "metadata": { "key": "value" }
    },
    {
      "id": "id11",
      "score": 0.99996454,
      "vector": [0.44, 0.63, 0.05, 0.72, 0.83, 0.49, 0.6, 0.48],
      "metadata": { "key": "value" }
    }
  ]
}

Fetch Vectors

Fetches an array of vectors which their ids are given.

The returned length of an array is same as the queried vector ids.

If a vector is not found, null is returned for corresponding id.

  • Path: /fetch
    • Method: [GET | POST]
    • Body: JSON: FetchRequest(...)
  • Auth: Authorization: Bearer TOKEN
    • Role: READONLY
  • Response: JSON: Result<List<Vector?>>

Example Request

curl https://better-dodo-20522-us1-vector.upstash.io/fetch \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{ "ids": ["id11", "id12", "abcde"],
  "includeVectors": true,
  "includeMetadata": true }'

Example Response

{
  "result": [
    {
      "id": "id11",
      "vector": [0.44, 0.63, 0.05, 0.72, 0.83, 0.49, 0.6, 0.48],
      "metadata": { "key": "value" }
    },
    {
      "id": "id12",
      "vector": [0.42, 0.63, 0.05, 0.72, 0.83, 0.49, 0.6, 0.48],
      "metadata": { "key": "value" }
    },
    null
  ]
}

Range Vectors

Returns a range of vectors starting with(including) startNodeId until end of the index store or given limit.

  • Path: /range
    • Method: [GET | POST]
    • Body: JSON: RangeRequest(...)
  • Auth: Authorization: Bearer TOKEN
    • Role: READONLY
  • Response: JSON: Result<RangeResponse>

Delete Vectors

Deletes vector(s) with the given ID(s).

  • Path: /delete
    • Method: [DELETE | POST]
    • Body: String: ID or Array<String>: IDs
  • Auth: Authorization: Bearer TOKEN
    • Role: READWRITE
  • Response: JSON: Result<DeletedCount>

Example Request

curl https://better-dodo-20522-us1-vector.upstash.io/delete \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '["id11", "id12", "abcde"]'

Example Response

{
  "result": {
    "deleted": 2
  }
}

Reset Index

Deletes all vectors and all state belonging to the index.

Index will be completely empty after /reset is called.

  • Path: /reset
    • Method: [DELETE | POST]
  • Auth: Authorization: Bearer TOKEN
    • Role: READWRITE
  • Response: JSON: Result<String>

Example Request

curl https://better-dodo-20522-us1-vector.upstash.io/reset \
-d ''  -H "Authorization: Bearer YOUR_TOKEN"

Example Response

{
  "result": "Success"
}

Index Info

Returns some information for the index, such as

  • vectorCount: Number of vectors in the index
  • pendingVectorCount: Number of vectors waiting to be indexed
  • indexSize: Size of the index on the disk

Stats will be updated eventually, so it might take some time to see the effect of changes in this endpoint.

  • Path: /info
    • Method: [GET | POST]
  • Auth: Authorization: Bearer TOKEN
    • Role: READONLY
  • Response: JSON: Result<Info>

Example Request

curl https://better-dodo-20522-us1-vector.upstash.io/info \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response

{
  "result": {
    "vectorCount": 7,
    "pendingVectorCount": 0,
    "indexSize": 43501
  }
}

Was this page helpful?