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

Core Operations

• Access Policy - Grant and revoke permissions, assign roles, and check what a caller is authorized to do.
• API Keys - Manage API authentication keys for accessing the GoodMem REST API.
• Service Identities - Create and manage non-human identities for production workloads and services.
• Spaces - Manage memory storage spaces as isolated domains.
• Users - Manage user accounts and authentication.

AI/ML Services

• Embedders - Configure and manage embedding models for memory vectorization.
• LLMs - Manage language models for text generation and processing.
• OCR - Run layout-aware OCR on documents and images.
• Rerankers - Configure and manage reranking models for search result optimization.

Data Operations

• Memories - Create, retrieve, search, and manage memories in the system.

System and Utilities

• Admin - Instance administration: license reload, graceful drain, background-job purge, retrieval log policies, and ownership transfer.
• Ping - Run single and streaming probe operations.
• System - System information, initialization, and management operations.

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"
}

Query Parameter Naming

Query parameters in GET endpoints support both CamelCase and snake_case naming conventions for flexibility:

• CamelCase (OpenAPI spec format): ?ownerId=123&maxResults=50
• snake_case (alternative format): ?owner_id=123&max_results=50

Both formats are accepted and can be used interchangeably. If both formats are provided with different values, the CamelCase format takes precedence.

Example - List spaces with filtering:

# Both of these requests are equivalent
curl -H "x-api-key: your_api_key_here" \
  "http://localhost:8080/v1/spaces?ownerId=user_123&maxResults=10"

curl -H "x-api-key: your_api_key_here" \
  "http://localhost:8080/v1/spaces?owner_id=user_123&max_results=10"

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.