GoodMem REST API Reference

This documentation is automatically generated from the GoodMem OpenAPI specification.

Authentication

All REST API requests require authentication via HTTP header:

• Header name: x-api-key
• Value: Your API key

Example:

curl -H "x-api-key: your_api_key_here" \
  http://localhost:8080/v1/spaces

Error Handling

The REST API uses standard HTTP status codes:

• 400 Bad Request: Invalid request parameters
• 401 Unauthorized: Invalid or missing API key
• 403 Forbidden: Insufficient permissions for the operation
• 404 Not Found: Requested resource does not exist
• 429 Too Many Requests: Rate limits exceeded
• 500 Internal Server Error: Server-side error
• 503 Service Unavailable: Service temporarily unavailable

Endpoints

The following endpoint categories are available:

Core Operations

• API Keys - Create and manage API keys for authentication
• Spaces - Create and manage memory spaces
• Users - User management and permissions

AI/ML Services

• Embedders - Text and document embedding generation
• LLMs - Large language model integrations
• Rerankers - Result reranking for improved relevance

Data Operations

• Memories - Create, retrieve, and delete memories

System

• General - System utilities and operations
• System - System information and initialization

Request Format

All requests use JSON for both request and response bodies:

// Request
POST /v1/spaces HTTP/1.1
Content-Type: application/json
x-api-key: your_api_key_here

{
  "name": "My Space",
  "description": "A new memory space",
  "embedder_id": "embedder_123"
}

// Response
HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "space_123",
  "name": "My Space",
  "description": "A new memory space",
  "created_at": "2024-01-15T10:30:00Z"
}

Getting Started

1. Create an API key using Create API Key
2. Set up authentication with the x-api-key header
3. Create a space using Create Space
4. Start adding memories using Create Memory

Base URL

All API endpoints are relative to:

http://localhost:8080/v1

Rate Limiting

API requests are rate-limited per API key. Rate limit information is provided in the response headers:

• X-RateLimit-Limit: Maximum requests per window
• X-RateLimit-Remaining: Requests remaining in current window
• X-RateLimit-Reset: Unix timestamp when the limit resets

Response Format

All responses return JSON with consistent structure:

Success Response:

{
  "id": "resource_id",
  "name": "Resource Name",
  "created_at": "2024-01-15T10:30:00Z"
}

Error Response:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request parameters",
    "details": "Field 'name' is required"
  }
}

Need gRPC Instead?

If you prefer high-performance binary protocols with streaming support, check out the gRPC API Reference which provides the same functionality using Protocol Buffers.