GoodMem API Overview

GoodMem provides two equivalent API protocols for vector-based memory storage and retrieval: gRPC and REST. Both APIs offer the same functionality and are automatically kept in sync.

Protocol Comparison

Choosing a Protocol

Use gRPC when:

• Building backend services or microservices
• Performance is critical
• You need streaming capabilities
• Your team is comfortable with Protocol Buffers
• Type safety is important

Use REST when:

• Building web applications or frontend integrations
• Working with standard HTTP tooling
• You need browser compatibility
• Your team prefers JSON APIs
• You're prototyping or testing

Authentication

Both protocols use the same authentication method:

gRPC: Include API key in metadata

authorization: Bearer your_api_key_here

REST: Include API key in HTTP header

Authorization: Bearer your_api_key_here

Error Handling

Both protocols return the same error information:

gRPC: Uses standard gRPC status codes

• UNAUTHENTICATED - Invalid or missing API key
• PERMISSION_DENIED - Insufficient permissions
• NOT_FOUND - Resource does not exist
• INVALID_ARGUMENT - Invalid request parameters
• INTERNAL - Server-side error

REST: Maps to standard HTTP status codes

• 401 Unauthorized - Invalid or missing API key
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource does not exist
• 400 Bad Request - Invalid request parameters
• 500 Internal Server Error - Server-side error

Rate Limiting & Quotas

Both protocols share the same rate limits and quota enforcement. Rate limit information is provided in response headers (REST) or metadata (gRPC).

Data Formats

gRPC: Uses Protocol Buffer binary format

• UUIDs are sent as 16-byte binary values
• Timestamps use google.protobuf.Timestamp
• Efficient binary encoding

REST: Uses JSON format

• UUIDs are sent as standard string format (8-4-4-4-12)
• Timestamps are ISO 8601 strings
• Human-readable JSON structure

Getting Started

1. Get an API Key: Create an API key using the CreateApiKey method
2. Choose Your Protocol: Select gRPC or REST based on your use case
3. Explore the APIs: Browse the service documentation for your chosen protocol
4. Try It Out: Use the provided examples to make your first API calls

Next Steps

• gRPC Reference - Complete gRPC API documentation
• REST Reference - Complete REST API documentation (coming soon)