Weaviate Getting Started: Account, Keys, First Request (2026)

Getting started overview

This guide outlines the initial steps to begin using Weaviate, focusing on account creation, obtaining necessary credentials, and executing a foundational request. Weaviate offers two primary deployment models: Weaviate Cloud, a managed service, and Weaviate Open Source, which allows for self-hosting. This guide will primarily focus on the Weaviate Cloud experience for initial setup, as it offers a streamlined path to a working environment. For self-hosted deployments, additional steps related to infrastructure provisioning and container orchestration are required, as detailed in the Weaviate installation instructions.

The general workflow for getting started includes:

1. Selecting a deployment option (Cloud or self-hosted).
2. Creating an account and an instance (for Weaviate Cloud).
3. Obtaining API keys or authentication tokens.
4. Initializing a client in your preferred programming language.
5. Making your first API call to create a schema or ingest data.

This process aims to establish a functional Weaviate instance that can store and retrieve vector embeddings and their associated data objects. Weaviate supports various client libraries, including Python, TypeScript, and Go, for interacting with the database.

Create an account and get keys

To begin with Weaviate Cloud, navigate to the Weaviate website and sign up for an account. Weaviate offers a free Sandbox tier, which provides one project and capacity for up to 100,000 objects, suitable for initial development and testing.

Account Creation Steps:

1. Go to the Weaviate Cloud signup page.
2. Provide your email address and create a password, or use a supported single sign-on (SSO) provider.
3. Verify your email address if prompted.
4. Once logged in, you will be directed to the Weaviate Console.

Instance and API Key Generation:

Within the Weaviate Console, you need to create a new Weaviate instance (also referred to as a cluster or service). This instance will be your dedicated vector database.

1. From the Weaviate Console dashboard, select the option to create a new cluster/instance.
2. Choose a deployment region that is geographically close to your application or users to minimize latency.
3. Select your desired tier (e.g., the free Sandbox tier for initial exploration).
4. Provide a descriptive name for your instance.
5. Weaviate instances are typically secured using API keys. After your instance is provisioned (which may take a few minutes), locate the API keys or authentication tokens associated with your new instance. These keys are crucial for authenticating your requests to the Weaviate API.
6. Note down the cluster URL (endpoint) and the API key(s) provided. These will be used in your application code. Weaviate uses a combination of the cluster URL and an API key for authentication, often referred to as a WEAVIATE_CLUSTER_URL and WEAVIATE_API_KEY, or similar environment variables.

For more advanced authentication methods, such as OpenID Connect (OIDC), consult the official Weaviate authentication documentation. OAuth 2.0 is a common framework for delegated authorization, often used with OIDC to secure APIs. The OAuth 2.0 specification outlines the general principles of token-based authorization.

Your first request

After setting up your Weaviate instance and obtaining the necessary API keys and cluster URL, you can make your first request. This example uses the Python client library, which is a common choice for Weaviate users. Ensure you have Python installed and then install the Weaviate client:

pip install weaviate-client

The following Python code initializes the client, creates a simple schema, and ingests a data object. This demonstrates the fundamental operations of defining a data structure and adding data.

Python Example:

import weaviate
import os

# Replace with your Weaviate cluster URL and API key
WEAVIATE_CLUSTER_URL = os.getenv("WEAVIATE_CLUSTER_URL", "YOUR_WEAVIATE_CLUSTER_URL")
WEAVIATE_API_KEY = os.getenv("WEAVIATE_API_KEY", "YOUR_WEAVIATE_API_KEY")

# Initialize the Weaviate client
client = weaviate.Client(
    url=WEAVIATE_CLUSTER_URL,
    auth_client_secret=weaviate.AuthClientSecret.api_key(api_key=WEAVIATE_API_KEY)
)

# Verify connection (optional but recommended)
if client.is_ready():
    print("Weaviate client is ready!")
else:
    print("Weaviate client is NOT ready. Check your URL and API key.")
    exit()

# Define a schema for a 'Question' class
# This schema tells Weaviate what properties your data objects will have.
question_schema = {
    "class": "Question",
    "vectorizer": "text2vec-openai", # Or 'none' if you provide your own vectors
    "properties": [
        {
            "name": "title",
            "dataType": ["text"]
        },
        {
            "name": "answer",
            "dataType": ["text"]
        }
    ]
}

# Ensure the schema doesn't already exist, then create it
# In a production environment, you would manage schema migrations more carefully.
try:
    client.schema.delete_class("Question") # Clean up previous runs if any
except weaviate.exceptions.UnexpectedStatusCodeException as e:
    print(f"Could not delete class (might not exist): {e}")

client.schema.create_class(question_schema)
print("Schema 'Question' created.")

# Add a data object
data_object = {
    "title": "What is the capital of France?",
    "answer": "Paris"
}

# Note: If using a vectorizer like 'text2vec-openai', ensure you have an OpenAI API key configured
# Weaviate will automatically vectorize the 'title' and 'answer' properties.

object_uuid = client.data_object.create(
    data_object=data_object,
    class_name="Question"
)
print(f"Data object created with UUID: {object_uuid}")

# Perform a GraphQL-based semantic search (e.g., 'nearText')
# This query finds questions semantically similar to "European cities".
query_result = client.query.get(
    "Question",
    ["title", "answer"]
).with_near_text({"concepts": ["European cities"]}).with_limit(1).do()

print("\nSemantic Search Result:")
print(query_result)

Before running the Python example, remember to replace "YOUR_WEAVIATE_CLUSTER_URL" and "YOUR_WEAVIATE_API_KEY" with the actual values obtained from your Weaviate Console. If you are using a vectorizer like text2vec-openai, you will also need to configure your OpenAI API key, typically by setting an environment variable like OPENAI_APIKEY, which Weaviate will use for generating embeddings.

Common next steps

Once you have successfully made your first request, several common next steps can further enhance your Weaviate application:

• Data Ingestion: Explore more sophisticated data ingestion strategies, including bulk import methods for large datasets. Weaviate supports various data types and allows for custom vectorization. Review the Weaviate data import documentation for details.
• Advanced Querying: Experiment with different query types beyond basic semantic search, such as filtering, aggregation, and hybrid search (combining keyword and vector search). The Weaviate search documentation provides comprehensive examples.
• Schema Design: Optimize your schema for specific use cases, considering properties, data types, and vectorizer configurations. Proper schema design is crucial for performance and search relevance.
• Integration with ML Models: Integrate Weaviate with machine learning models for real-time vector generation or re-ranking search results. Weaviate supports various vectorizer modules and can be used with custom models.
• Monitoring and Scaling: For production deployments, learn about monitoring your Weaviate instance's performance and scaling strategies to handle increased data volume and query load.
• Security: Implement robust security practices, including proper API key management and access control, as outlined in the Weaviate authentication guide.

Troubleshooting the first call

Encountering issues during your first Weaviate API call is common. Here are some troubleshooting tips:

• Incorrect Cluster URL or API Key: Double-check that the WEAVIATE_CLUSTER_URL and WEAVIATE_API_KEY in your code exactly match the values provided in your Weaviate Console. Typos or leading/trailing spaces are common causes of authentication failures.
• Network Connectivity: Ensure your development environment has outbound network access to the Weaviate Cloud endpoint. Firewall rules or proxy settings can block connections.
• Client Library Version: Make sure you are using a compatible and up-to-date version of the Weaviate client library. Check the Weaviate client library documentation for the latest versions and any breaking changes.
• Schema Conflicts: If you are repeatedly running the example, you might encounter errors if the 'Question' class already exists from a previous run. The example includes a delete_class call to mitigate this, but ensure it executes successfully or manually delete the class from the Weaviate Console if needed.
• Vectorizer Configuration: If you use a module like text2vec-openai, ensure your OpenAI API key is correctly configured (e.g., as an environment variable or passed directly to the client initialization). Errors related to embedding generation often point to missing or invalid external API keys.
• Error Messages: Carefully read the error messages returned by the Weaviate client. They often provide specific clues about what went wrong, such as authentication failures, schema validation errors, or network issues.
• Weaviate Console Logs: Check the logs and status within your Weaviate Console for your instance. These logs can provide server-side insights into connection attempts and query processing, which may help diagnose issues not apparent client-side.
• Documentation and Community: Consult the official Weaviate documentation and community forums. Many common issues have already been addressed and documented.