Public API & SDK
Relevant source files
The following files were used as context for generating this wiki page:
The Tuturuuu Public API and SDK ecosystem provides developers with a type-safe, promise-based interface to interact with workspace resources including storage, documents, and analytics. The system is designed with a security-first architecture that prioritizes server-side execution to protect sensitive API keys while enabling robust client-side experiences through proxy patterns.
Sources: apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/api-keys/sdk-guide.tsx:132-137, apps/external/README.md:5-13
Architecture and Security
The Tuturuuu platform utilizes a security-first design for its external integrations. Developers are instructed to never expose the TUTURUUU_API_KEY to the client browser. Instead, a proxy pattern is implemented where the client makes requests to local server-side API routes, which then utilize the Tuturuuu SDK to communicate with the platform.
Data Flow Pattern
The following diagram illustrates the secure communication flow between a user's browser and the Tuturuuu platform using the SDK.
The client communicates only with the local server, keeping the API key hidden within server-side environment variables.
Sources: apps/external/README.md:7-13, apps/external/README.md:88-100
The Tuturuuu SDK
The official TypeScript SDK (available as the tuturuuu package) handles authentication, error handling, and API communication automatically. It provides high-performance file operations by utilizing signed URLs to upload directly to Supabase Storage.
Key Features
| Feature | Description |
|---|---|
| Type-safe | Full TypeScript support with comprehensive type definitions. |
| Promise-based | Modern async/await API for all operations. |
| Direct Uploads | Direct-to-storage uploads using signed URLs for optimal performance. |
| Error Handling | Specific error classes for Authentication, Authorization, and Rate Limits. |
| Zero Config | Works out of the box with just a workspace API key. |
Sources: apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/api-keys/sdk-guide.tsx:139-158, README.md:148-150
Initialization and Usage
The SDK is initialized by providing a workspace-specific API key. Best practices dictate using environment variables to store these keys.
import { TuturuuuClient } from 'tuturuuu';
// Initialize with server-side environment variable
const client = new TuturuuuClient(process.env.TUTURUUU_API_KEY);
Sources: apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/api-keys/sdk-guide.tsx:21-23, apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/api-keys/sdk-guide.tsx:182-187
Core Operations
Storage Management
The SDK provides comprehensive methods for managing workspace assets. This includes listing files, uploading with upsert options, and generating temporary share links.
The SDK abstracts the complexity of signed URL generation and storage pathing.
Sources: apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/api-keys/sdk-guide.tsx:25-72, apps/external/src/app/sdk/README.md:37-45
Document Operations
The SDK allows for programmatic creation and searching of workspace documents. These operations typically require specific permissions.
| Operation | SDK Method | Required Permission |
|---|---|---|
| Create Document | client.documents.create() | manage_documents |
| Search Documents | client.documents.search() | manage_documents |
| Storage Ops | client.storage.* | manage_drive |
Sources: apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/api-keys/sdk-guide.tsx:74-88, apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/api-keys/sdk-guide.tsx:288-301
API Limits and Policies
The Tuturuuu platform enforces usage standards to ensure service reliability across all workspaces.
Rate Limits and Resource Quotas
- Default Rate Limit: 100 requests per minute.
- Default Storage Limit: 100MB per workspace (configurable via
STORAGE_LIMIT_BYTES). - File Size Limit: 100MB per individual file.
- AI Usage: Subject to subscription-based quotas and budget caps.
Sources: apps/web/src/data/legal/acceptable-use-sections.tsx:107-109, apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/api-keys/sdk-guide.tsx:307-313, packages/ai/src/chat/google/route.ts:316-321
Acceptable Use for API Consumers
API consumers must strictly adhere to the following:
- Identification: Automated bots and integrations must identify themselves accurately.
- Data Handling: Consumers must handle user data in accordance with the platform's Privacy Policy and not store more data than necessary.
- Security: API keys must never be published in public repositories. Compromised keys must be revoked immediately.
Sources: apps/web/src/data/legal/acceptable-use-sections.tsx:115-127
SDK Package Structure and Distribution
The SDK is distributed as a compiled package containing JavaScript files and TypeScript declaration files.
The build process ensures that type safety is maintained for consumers while providing optimized runtime code.
Sources: packages/sdk/PUBLISHING.md:162-176, packages/sdk/PUBLISHING.md:43-52
Summary
The Public API & SDK layer of the Tuturuuu platform enables secure, extensible integration for external applications. By utilizing the SDK in server-side environments and adhering to the platform's proxy pattern, developers can build powerful tools for storage, document management, and AI-assisted productivity without compromising workspace security or performance.