Weaviate Connector Guide

The Weaviate connector provides object CRUD, query, and connectivity-test operations against a Weaviate REST endpoint. It maps directly to /v1/objects, /v1/query, and /v1/meta.

Configuration and prerequisites

• endpoint_url (required): Weaviate endpoint, for example https://your-instance.weaviate.io.
• api_key (optional): Bearer API key used for protected deployments.
• timeout_seconds (optional): HTTP timeout in seconds (default 30).

Before sending object payloads, ensure the target class schema already exists in Weaviate.

Operation reference

• create: create an object using class (or className) and properties (or object).
• get: fetch an object by class/className and id.
• search: query objects by class/className, with optional query, vector, and limit.
• update: patch object properties by class/className, id, and properties/object.
• delete: delete an object by class/className and id.
• test: call /v1/meta to verify connectivity and endpoint readiness.

Create object (create)

curl -X POST "https://api.example.com/api/v1/integrations/<INTEGRATION_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "create",
    "class": "KnowledgeChunk",
    "properties": {
      "title": "Return policy overview",
      "content": "Customers can return eligible products within 30 days.",
      "source": "help-center"
    }
  }'

{
  "success": true,
  "data": {
    "object_count": 1,
    "id": "<OBJECT_ID>",
    "data": {
      "id": "<OBJECT_ID>"
    }
  }
}

Search objects (search)

curl -X POST "https://api.example.com/api/v1/integrations/<INTEGRATION_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "search",
    "className": "KnowledgeChunk",
    "query": "What is your return window?",
    "limit": 5
  }'

{
  "success": true,
  "data": {
    "object_count": 2,
    "objects": [
      {
        "title": "Return policy overview"
      }
    ],
    "data": {
      "data": {
        "Get": {
          "KnowledgeChunk": [
            {
              "title": "Return policy overview"
            }
          ]
        }
      }
    }
  }
}

Test connectivity (test)

curl -X POST "https://api.example.com/api/v1/integrations/<INTEGRATION_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{ "operation": "test" }'

{
  "success": true,
  "data": {
    "message": "Weaviate connection test successful",
    "details": {
      "endpoint": "https://your-instance.weaviate.io",
      "version": "1.26.7"
    }
  }
}

If endpoint_url is not configured, test returns:

{
  "success": false,
  "error": {
    "code": "VALIDATION",
    "message": "Configuration validation failed",
    "retriable": false
  },
  "metadata": {
    "processing_time_ms": 1
  }
}

Reliability guidance

• Validate class names and property schema before create/update requests.
• Use retries with backoff for transient network errors and RATE_LIMIT responses.
• Increase timeout_seconds for high-latency environments or large payload paths.

Additional resources

• Weaviate documentation
• Weaviate API reference