Public Projects Guide#

This guide explains how to make projects publicly accessible, allowing anyone to read embeddings and search for similar documents without authentication.

Overview#

Projects can be configured to allow unauthenticated (public) read access by setting the public_read field to true. This is useful for:

Open datasets and research data
Public APIs and services
Shared knowledge bases
Educational resources

Important: Public access only applies to read operations. Write operations (creating, updating, or deleting embeddings) always require authentication.

Creating a Public Project#

Set public_read to true when creating a project:

curl -X PUT "https://api.example.com/v1/projects/alice/public-knowledge" \
  -H "Authorization: Bearer alice_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "project_handle": "public-knowledge",
    "description": "Publicly accessible knowledge base",
    "instance_id": 123,
    "public_read": true
  }'

Response:

{
  "project_handle": "public-knowledge",
  "owner": "alice",
  "description": "Publicly accessible knowledge base",
  "instance_id": 123,
  "public_read": true
}

Making an Existing Project Public#

Update an existing project using PATCH:

curl -X PATCH "https://api.example.com/v1/projects/alice/my-project" \
  -H "Authorization: Bearer alice_api_key" \
  -H "Content-Type: application/json" \
  -d '{"public_read": true}'

Making a Public Project Private#

To disable public access:

curl -X PATCH "https://api.example.com/v1/projects/alice/public-knowledge" \
  -H "Authorization: Bearer alice_api_key" \
  -H "Content-Type: application/json" \
  -d '{"public_read": false}'

Accessing Public Projects Without Authentication#

Once a project has public_read enabled, anyone can access it without providing an API key.

Get Project Metadata#

curl -X GET "https://api.example.com/v1/projects/alice/public-knowledge"

Response:

{
  "project_handle": "public-knowledge",
  "owner": "alice",
  "description": "Publicly accessible knowledge base",
  "instance_id": 123,
  "public_read": true
}

Retrieve All Embeddings#

curl -X GET "https://api.example.com/v1/embeddings/alice/public-knowledge?limit=100"

Response:

{
  "embeddings": [
    {
      "text_id": "doc001",
      "text": "Public document content",
      "metadata": {"category": "science"},
      "vector_dim": 3072
    },
    {
      "text_id": "doc002",
      "text": "Another public document",
      "metadata": {"category": "history"},
      "vector_dim": 3072
    }
  ]
}

Get a Specific Embedding#

curl -X GET "https://api.example.com/v1/embeddings/alice/public-knowledge/doc001"

Response:

{
  "text_id": "doc001",
  "text": "Public document content",
  "metadata": {"category": "science"},
  "vector_dim": 3072,
  "vector": [0.021, -0.015, 0.043, ...]
}

Search for Similar Documents#

# Search by existing document ID
curl -X GET "https://api.example.com/v1/similars/alice/public-knowledge/doc001?count=5&threshold=0.7"

Response:

{
  "user_handle": "alice",
  "project_handle": "public-knowledge",
  "results": [
    {"id": "doc002", "similarity": 0.92},
    {"id": "doc003", "similarity": 0.85},
    {"id": "doc004", "similarity": 0.78}
  ]
}

Search with Raw Embeddings#

curl -X POST "https://api.example.com/v1/similars/alice/public-knowledge?count=5" \
  -H "Content-Type: application/json" \
  -d '{
    "vector": [0.032, -0.018, 0.056, ...]
  }'

Operations Still Requiring Authentication#

Even for public projects, these operations require authentication:

Creating Embeddings (Requires Auth)#

# This will fail with 401 Unauthorized
curl -X POST "https://api.example.com/v1/embeddings/alice/public-knowledge" \
  -H "Content-Type: application/json" \
  -d '{"embeddings": [...]}'

# This succeeds with valid API key
curl -X POST "https://api.example.com/v1/embeddings/alice/public-knowledge" \
  -H "Authorization: Bearer alice_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "embeddings": [{
      "text_id": "doc123",
      "instance_handle": "openai-large",
      "vector": [0.1, 0.2, 0.3, ...],
      "vector_dim": 3072
    }]
  }'

Deleting Embeddings (Requires Auth)#

# Delete specific embedding (requires auth)
curl -X DELETE "https://api.example.com/v1/embeddings/alice/public-knowledge/doc001" \
  -H "Authorization: Bearer alice_api_key"

# Delete all embeddings (requires auth)
curl -X DELETE "https://api.example.com/v1/embeddings/alice/public-knowledge" \
  -H "Authorization: Bearer alice_api_key"

Modifying Project Settings (Requires Auth)#

# Update project description (requires auth)
curl -X PATCH "https://api.example.com/v1/projects/alice/public-knowledge" \
  -H "Authorization: Bearer alice_api_key" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated description"}'

Deleting Project (Requires Auth)#

curl -X DELETE "https://api.example.com/v1/projects/alice/public-knowledge" \
  -H "Authorization: Bearer alice_api_key"

You can combine public read access with user-specific editor permissions:

curl -X PUT "https://api.example.com/v1/projects/alice/collaborative-public" \
  -H "Authorization: Bearer alice_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "project_handle": "collaborative-public",
    "description": "Public read, restricted write",
    "instance_id": 123,
    "public_read": true,
    "shared_with": [
      {
        "user_handle": "bob",
        "role": "editor"
      },
      {
        "user_handle": "charlie",
        "role": "editor"
      }
    ]
  }'

In this configuration:

Anyone can read embeddings and search (no auth required)
bob and charlie can add/modify/delete embeddings (with auth)
alice (owner) has full control (with auth)

Use Cases#

Open Research Dataset#

Share research data publicly while maintaining write control:

curl -X PUT "https://api.example.com/v1/projects/university/research-corpus" \
  -H "Authorization: Bearer university_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "project_handle": "research-corpus",
    "description": "Open research corpus for academic use",
    "instance_id": 456,
    "public_read": true,
    "metadataScheme": "{\"type\":\"object\",\"properties\":{\"doi\":{\"type\":\"string\"},\"year\":{\"type\":\"integer\"}},\"required\":[\"doi\"]}"
  }'

Researchers worldwide can access the data without credentials, but only authorized users can add new data.

Public API Backend#

Build a public search API on top of embapi:

import requests

def public_search_api(query_vector, count=10):
    """Public search function requiring no authentication"""
    response = requests.post(
        "https://api.example.com/v1/similars/company/product-docs",
        json={"vector": query_vector},
        params={"count": count, "threshold": 0.6}
    )
    return response.json()

# No API key needed for public projects!
results = public_search_api(query_embedding)

Educational Resources#

Share educational content publicly:

curl -X PUT "https://api.example.com/v1/projects/edu/learning-materials" \
  -H "Authorization: Bearer edu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "project_handle": "learning-materials",
    "description": "Free educational content embeddings",
    "instance_id": 789,
    "public_read": true
  }'

Students and educators can access the materials without creating accounts.

Community-Driven Knowledge Base#

Open knowledge base with restricted editors:

curl -X PUT "https://api.example.com/v1/projects/community/wiki-embeddings" \
  -H "Authorization: Bearer community_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "project_handle": "wiki-embeddings",
    "description": "Community wiki embeddings",
    "instance_id": 321,
    "public_read": true,
    "shared_with": [
      {"user_handle": "moderator1", "role": "editor"},
      {"user_handle": "moderator2", "role": "editor"}
    ]
  }'

Security Considerations#

What is Publicly Visible#

When public_read is enabled:

✅ Project metadata (name, description, owner)
✅ All embedding vectors and text content
✅ All embedding metadata
✅ Vector dimensions and instance references
❌ API keys (never exposed)
❌ User passwords or credentials

Best Practices#

Review Content First: Ensure no sensitive information is in embeddings or metadata before enabling public access
Use Metadata Schemas: Enforce consistent metadata structure with validation
Monitor Usage: Track access patterns to your public projects
Set Clear Descriptions: Provide clear project descriptions explaining the data’s purpose and licensing
Consider Rate Limiting: For high-traffic public APIs, implement rate limiting at the application level

What to Avoid#

❌ Don’t make projects public that contain:

Personal identifiable information (PII)
Proprietary or confidential data
Sensitive research data not yet published
Internal company information

✅ Do make projects public that contain:

Already-published research data
Open educational resources
Public domain content
Creative Commons licensed materials

Disabling Public Access#

If you need to make a public project private again:

curl -X PATCH "https://api.example.com/v1/projects/alice/public-knowledge" \
  -H "Authorization: Bearer alice_api_key" \
  -H "Content-Type: application/json" \
  -d '{"public_read": false}'

After this change:

All read operations require authentication
Existing anonymous access is immediately revoked
No data is deleted, just access is restricted

Checking if a Project is Public#

View project metadata to check the public_read flag:

curl -X GET "https://api.example.com/v1/projects/alice/public-knowledge"

Look for "public_read": true in the response.

Project Sharing Guide - Share with specific users
RAG Workflow Guide - Complete RAG implementation
Metadata Validation Guide - Enforce data quality

Troubleshooting#

Public Access Not Working#

Symptom: Still getting 401 Unauthorized for public project

Solutions:

Verify public_read: true is set:

curl -X GET "https://api.example.com/v1/projects/alice/my-project"

Check you’re using GET/POST for similars (not other methods)
Ensure the project exists and handle is correct

Accidentally Made Project Public#

Solution: Immediately disable public access:

curl -X PATCH "https://api.example.com/v1/projects/alice/my-project" \
  -H "Authorization: Bearer alice_api_key" \
  -H "Content-Type: application/json" \
  -d '{"public_read": false}'

Want to Track Public Usage#

Solution: Anonymous requests are logged with user set to “public”. Review server logs to monitor public access patterns.

Public Projects Guide#

Overview#

Creating a Public Project#

Making an Existing Project Public#

Making a Public Project Private#

Accessing Public Projects Without Authentication#

Get Project Metadata#

Retrieve All Embeddings#

Get a Specific Embedding#

Search for Similar Documents#

Search with Raw Embeddings#

Operations Still Requiring Authentication#

Creating Embeddings (Requires Auth)#

Deleting Embeddings (Requires Auth)#

Modifying Project Settings (Requires Auth)#

Deleting Project (Requires Auth)#

Combining Public Access with User Sharing#

Use Cases#

Open Research Dataset#

Public API Backend#

Educational Resources#

Community-Driven Knowledge Base#

Security Considerations#

What is Publicly Visible#

Best Practices#

What to Avoid#

Disabling Public Access#

Checking if a Project is Public#

Related Documentation#

Troubleshooting#

Public Access Not Working#

Accidentally Made Project Public#

Want to Track Public Usage#