GoodMem REST API Reference

The GoodMem REST API provides the same functionality as the gRPC API using standard HTTP requests and JSON payloads.

API Overview

Complete REST API documentation is now available! The REST endpoints mirror all gRPC methods with:

• Standard HTTP methods (GET, POST, PUT, DELETE)
• JSON request/response bodies
• HTTP status codes for error handling
• Standard HTTP headers for authentication

Available Endpoints

The REST API is organized into the following categories with complete documentation:

• API Keys - Manage API authentication keys (4 endpoints)
• Embedders - Configure embedding models (5 endpoints)
• General - System administration and utility operations (3 endpoints)
• LLMs - Manage language models (5 endpoints)
• Memories - Create, retrieve, and manage memories (9 endpoints)
• Rerankers - Configure reranking models (5 endpoints)
• Spaces - Manage memory storage spaces (6 endpoints)
• System - System information and initialization (2 endpoints)
• Users - User management and authentication (3 endpoints)

Total: 42 REST API endpoints fully documented

REST Endpoint Patterns

REST endpoints follow these patterns:

API Key Management

• POST /v1/apikeys - Create API key
• GET /v1/apikeys - List API keys
• PUT /v1/apikeys/{id} - Update API key
• DELETE /v1/apikeys/{id} - Delete API key

Space Management

• POST /v1/spaces - Create space
• GET /v1/spaces - List spaces
• GET /v1/spaces/{id} - Get space
• PUT /v1/spaces/{id} - Update space
• DELETE /v1/spaces/{id} - Delete space

Memory Operations

• POST /v1/spaces/{space_id}/memories - Store memory
• GET /v1/spaces/{space_id}/memories - List memories
• POST /v1/spaces/{space_id}/memories:search - Search memories

Authentication

Include your API key in the Authorization header:

Authorization: Bearer your_api_key_here

Data Formats

Request/Response Format: JSON

UUIDs: Standard string format (8-4-4-4-12)

{
  "space_id": "123e4567-e89b-12d3-a456-426614174000"
}

Timestamps: ISO 8601 format

{
  "created_at": "2025-01-15T10:30:00.000Z"
}

Error Responses

REST API errors follow standard HTTP status codes:

{
  "error": {
    "code": "INVALID_ARGUMENT", 
    "message": "The request parameters are invalid",
    "details": []
  }
}

Getting Started

1. Choose an endpoint category from the list above
2. Review the endpoint documentation for request/response details
3. Use the Authentication section below for API key setup
4. Test with your API key using any HTTP client

Interactive API Exploration

While this documentation provides detailed endpoint information, you can also explore the REST API interactively using Swagger UI:

• Local Development: Visit http://localhost:8080/openapi on your running GoodMem server
• This provides an interactive interface to test endpoints directly

Next Steps

• Review the gRPC API Reference for alternative API approach
• Check the Overview for choosing between gRPC and REST
• For interactive testing, use the Swagger UI on your GoodMem server