Namespaces

Namespaces in RAGaaS are isolated environments that contain your infrastructure configuration and documents.

Getting Started

Before creating a namespace, ensure you have:

Created an account and obtained your API key
Reviewed our infrastructure guide for setting up required services
Gathered necessary credentials for your infrastructure components

Overview

A namespace is a logical container that:

Holds your infrastructure configuration (file storage, vector storage, embedding models, etc.)
Isolates documents and their embeddings
Enables multi-tenant or multi-project setups
Simplifies configuration management

Create separate namespaces for different projects, environments (dev/prod), or tenants to maintain clean separation of data and configurations.

Required Components

A namespace requires configuration for three essential components:

File Storage: Where your documents are stored
- Learn more in our File Storage guide
- Supports S3-compatible storage providers
Vector Storage: Where document embeddings are stored
- Learn more in our Vector Storage guide
- Currently supports Pinecone
Embedding Model: The model used to create document embeddings
- Learn more in our Embedding Models guide
- Supports OpenAI, Cohere, and Jina models

Optionally, you can also configure:

Web Scraper: For ingesting web-based content
- Learn more in our Web Scraping guide
- Currently supports Firecrawl

Creating Your First Namespace

Here's how to create a namespace:

First, gather your credentials from the infrastructure setup:
- S3 credentials from your storage provider
- Pinecone API key and index host
- OpenAI, Cohere, or Jina API key
- (Optional) Firecrawl API key
Create the namespace using our API:

curl -X POST https://api.ragaas.dev/v1/namespaces \
  -H "Authorization: Bearer $RAGAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production",
    "fileStorageConfig": {
      "provider": "S3_COMPATIBLE",
      "bucket": "your-bucket",
      "region": "us-east-1",
      "endpoint": "your-endpoint-url",
      "credentials": {
        "accessKeyId": "your-access-key-id",
        "secretAccessKey": "your-secret-access-key"
      }
    },
    "vectorStorageConfig": {
      "provider": "PINECONE",
      "apiKey": "your-pinecone-api-key",
      "indexHost": "your-index-host"
    },
    "embeddingModelConfig": {
      "provider": "OPENAI",
      "model": "text-embedding-3-small",
      "apiKey": "your-openai-api-key"
    },
    "webScraperConfig": {
      "provider": "FIRECRAWL",
      "apiKey": "your-firecrawl-api-key"
    }
  }'

The web scraper configuration is optional. Add it only if you need to ingest web-based content.

Connector configurations (Notion, Google Drive, Dropbox, OneDrive) can be added later by updating the namespace. See Updating a Namespace for details on how to add these configurations.

Updating a Namespace

You can update any configuration in your namespace using the PATCH endpoint. Each configuration can be updated independently or together in a single request.

File Storage Configuration

Update your file storage configuration when you need to:

Switch to a different S3-compatible provider
Change storage regions for better performance
Update access credentials
Move data to a new bucket

curl -X PATCH https://api.ragaas.dev/v1/namespaces/ns_123 \
  -H "Authorization: Bearer $RAGAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileStorageConfig": {
      "provider": "S3_COMPATIBLE",
      "bucket": "new-bucket",
      "region": "us-west-2",
      "endpoint": "new-endpoint-url",
      "credentials": {
        "accessKeyId": "new-access-key-id",
        "secretAccessKey": "new-secret-access-key"
      }
    }
  }'

Vector Storage Configuration

Update your vector storage settings when you need to:

Rotate API keys
Switch to a different Pinecone index
Update to a new Pinecone project

curl -X PATCH https://api.ragaas.dev/v1/namespaces/ns_123 \
  -H "Authorization: Bearer $RAGAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vectorStorageConfig": {
      "provider": "PINECONE",
      "apiKey": "new-pinecone-api-key",
      "indexHost": "new-index-host"
    }
  }'

Embedding Model Configuration

Update your embedding model configuration when you want to:

Switch between OpenAI, Cohere, and Jina models
Upgrade to newer model versions
Change API keys
Switch to different model variants (e.g., multilingual)

curl -X PATCH https://api.ragaas.dev/v1/namespaces/ns_123 \
  -H "Authorization: Bearer $RAGAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "embeddingModelConfig": {
      "provider": "COHERE",
      "model": "embed-multilingual-v3.0",
      "apiKey": "new-cohere-api-key"
    }
  }'

Web Scraper Configuration

Update your web scraper settings when you need to:

Update API keys
Change scraping providers

curl -X PATCH https://api.ragaas.dev/v1/namespaces/ns_123 \
  -H "Authorization: Bearer $RAGAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webScraperConfig": {
      "provider": "FIRECRAWL",
      "apiKey": "new-firecrawl-api-key"
    }
  }'

After configuring the web scraper, you can start ingesting web-based content. See our Web Scraping guide for details.

Notion Configuration

Update your Notion configuration when you need to:

Change Notion integration settings
Update OAuth credentials
Switch to a different Notion workspace

curl -X PATCH https://api.ragaas.dev/v1/namespaces/ns_123 \
  -H "Authorization: Bearer $RAGAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notionConfig": {
      "clientId": "your-notion-client-id",
      "clientSecret": "your-notion-client-secret"
    }
  }'

After configuring Notion, you can create connections to access your Notion files. See our Notion Connector guide for details.

Google Drive Configuration

Update your Google Drive configuration when you need to:

Change Google Cloud project settings
Update OAuth credentials
Rotate API keys
Modify Drive access permissions

curl -X PATCH https://api.ragaas.dev/v1/namespaces/ns_123 \
  -H "Authorization: Bearer $RAGAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "googleDriveConfig": {
      "clientId": "your-google-client-id",
      "clientSecret": "your-google-client-secret",
      "apiKey": "your-google-api-key"
    }
  }'

After configuring Google Drive, you can create connections to access your Google Drive files. See our Google Drive Connector guide for details.

Dropbox Configuration

Add or update your Dropbox configuration when you need to:

Connect your Dropbox account to RAGaaS
Update OAuth credentials
Change Dropbox app settings

curl -X PATCH https://api.ragaas.dev/v1/namespaces/ns_123 \
  -H "Authorization: Bearer $RAGAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dropboxConfig": {
      "clientId": "your-dropbox-app-key",
      "clientSecret": "your-dropbox-app-secret"
    }
  }'

After configuring Dropbox, you can create connections to access your Dropbox files. See our Dropbox Connector guide for details.

OneDrive Configuration

Add OneDrive integration to your namespace when you need to:

Connect with Microsoft OneDrive
Search across OneDrive files
Ingest content from OneDrive

curl -X PATCH https://api.ragaas.dev/v1/namespaces/ns_123 \
  -H "Authorization: Bearer $RAGAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "onedriveConfig": {
      "clientId": "your-azure-client-id",
      "clientSecret": "your-azure-client-secret"
    }
  }'

After adding OneDrive configuration, you'll need to create a connection and authorize access. See our OneDrive Connector guide for details.

You can update multiple configurations in a single request. Only include the configurations you want to update. Existing configurations that aren't included in the request will remain unchanged.

Best Practices

Namespace Organization

Environment Separation
- Create separate namespaces for development and production
- Use different infrastructure credentials for each environment
- Test configuration changes in development first
Project Isolation
- Use different namespaces for distinct projects or use cases
- Maintain separate vector indexes for better performance
- Avoid mixing documents from different domains
Multi-tenant Setup
- Create a namespace per tenant for complete isolation
- Use tenant-specific storage buckets and vector indexes
- Implement proper access controls per namespace

Next Steps

After creating your namespace:

Start ingesting documents into your namespace
Learn about search capabilities to query your documents
View the complete API reference for all namespace operations

Next: Data Ingestion View API Reference