HTTP API

HTTP API Reference

VortexDB’s HTTP API provides a RESTful interface for vector operations using JSON over HTTP/1.1.

Base URL

http://localhost:3000

The port can be configured via the HTTP_PORT environment variable. The server binds to 127.0.0.1 by default.

Endpoints

Health Check

Check if the server is running.

Responsestring

Returns “OK” if the server is healthy.

curl http://localhost:3000/health

OK

Root

Verify the server is running.

curl http://localhost:3000/

Vector Database server is running!

Insert Point

vectorarrayrequired

Array of floating-point numbers representing the vector. Must match the configured DIMENSION.

payloadobjectrequired

Metadata object associated with the vector.

payload properties

content_typestringrequired

Type of content: "Text" or "Image"

contentstringrequired

The content string

point_idstring

UUID of the created point.

curl -X POST http://localhost:3000/points \
  -H "Content-Type: application/json" \
  -d '{
    "vector": [0.1, 0.2, 0.3, 0.4],
    "payload": {
      "content_type": "Text",
      "content": "Hello, VortexDB!"
    }
  }'

{
  "point_id": "550e8400-e29b-41d4-a716-446655440000"
}

Error Responses:

Status	Description
`400 Bad Request`	Invalid JSON or missing fields
`500 Internal Server Error`	Server error during insertion

Batch Insert

Insert multiple vectors in a single request.

vectorsarrayrequired

Array of insert objects, each with vector and payload fields (same shape as single insert).

point_idsarray

Array of UUIDs for each created point, in the same order as the input.

curl -X POST http://localhost:3000/points/batch \
  -H "Content-Type: application/json" \
  -d '{
    "vectors": [
      {
        "vector": [0.1, 0.2, 0.3, 0.4],
        "payload": {"content_type": "Text", "content": "Document one"}
      },
      {
        "vector": [0.5, 0.6, 0.7, 0.8],
        "payload": {"content_type": "Text", "content": "Document two"}
      }
    ]
  }'

{
  "point_ids": [
    "550e8400-e29b-41d4-a716-446655440000",
    "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
  ]
}

Error Responses:

Status	Description
`400 Bad Request`	Invalid JSON or missing fields
`500 Internal Server Error`	Server error during insertion

Get Point

Retrieve a point by its ID.

idstringrequired

UUID of the point to retrieve.

idstring

The point’s UUID.

vectorarray

The stored vector values.

payloadobject

The associated payload metadata.

curl http://localhost:3000/points/550e8400-e29b-41d4-a716-446655440000

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "vector": [0.1, 0.2, 0.3, 0.4],
  "payload": {
    "content_type": "Text",
    "content": "Hello, VortexDB!"
  }
}

Error Responses:

Status	Description
`404 Not Found`	Point does not exist
`500 Internal Server Error`	Server error during retrieval

Delete Point

Delete a point by its ID.

idstringrequired

UUID of the point to delete.

curl -X DELETE http://localhost:3000/points/550e8400-e29b-41d4-a716-446655440000

(empty body)

Error Responses:

Status	Description
`500 Internal Server Error`	Server error during deletion

Search Points

Search for the k nearest neighbors to a query vector.

vectorarrayrequired

Query vector. Must match the configured DIMENSION.

similaritystringrequired

Distance metric: "Euclidean", "Manhattan", "Hamming", or "Cosine"

limitintegerrequired

Maximum number of results to return.

resultsarray

Array of point IDs ordered by similarity (closest first).

curl -X POST http://localhost:3000/points/search \
  -H "Content-Type: application/json" \
  -d '{
    "vector": [0.1, 0.2, 0.3, 0.4],
    "similarity": "Cosine",
    "limit": 5
  }'

{
  "results": [
    "550e8400-e29b-41d4-a716-446655440000",
    "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  ]
}

Error Responses:

Status	Description
`400 Bad Request`	Invalid JSON or missing fields
`500 Internal Server Error`	Server error during search

Batch Search

Search against multiple query vectors in a single request.

queriesarrayrequired

Array of search query objects, each with vector, similarity, and limit.

resultsarray

Array of result arrays, one per input query, each ordered by similarity.

curl -X POST http://localhost:3000/points/search/batch \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      {"vector": [0.1, 0.2, 0.3, 0.4], "similarity": "Cosine", "limit": 2},
      {"vector": [0.5, 0.6, 0.7, 0.8], "similarity": "Euclidean", "limit": 2}
    ]
  }'

{
  "results": [
    ["550e8400-...", "6ba7b810-..."],
    ["f47ac10b-...", "9a1b2c3d-..."]
  ]
}

Error Responses:

Status	Description
`400 Bad Request`	Invalid JSON or missing fields
`500 Internal Server Error`	Server error during search

Error Format

Errors are returned as plain text with an appropriate HTTP status code:

curl -v http://localhost:3000/points/nonexistent-id

< HTTP/1.1 404 Not Found
< content-type: text/plain; charset=utf-8
<
Point not found

Examples

Complete Workflow

# 1. Check health
curl http://localhost:3000/health
# OK

# 2. Insert a vector
POINT_ID=$(curl -s -X POST http://localhost:3000/points \
  -H "Content-Type: application/json" \
  -d '{
    "vector": [0.1, 0.2, 0.3, 0.4],
    "payload": {"content_type": "Text", "content": "First document"}
  }' | jq -r '.point_id')

echo "Created point: $POINT_ID"

# 3. Get the point
curl http://localhost:3000/points/$POINT_ID

# 4. Search for similar vectors
curl -X POST http://localhost:3000/points/search \
  -H "Content-Type: application/json" \
  -d '{
    "vector": [0.15, 0.25, 0.35, 0.45],
    "similarity": "Cosine",
    "limit": 10
  }'

# 5. Delete the point
curl -X DELETE http://localhost:3000/points/$POINT_ID

OpenAPI Specification

The complete OpenAPI specification is available at:

/docs/openapi.yaml

You can import this into tools like Postman or Swagger UI for interactive API exploration.

Next Steps

gRPC API

High-performance gRPC API reference

Python SDK

Python client documentation