GoodMem REST API ReferenceCopy Anchor Link

This documentation is automatically generated from the GoodMem OpenAPI specification.

AuthenticationCopy Anchor Link

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 HandlingCopy Anchor Link

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

EndpointsCopy Anchor Link

Core OperationsCopy Anchor Link

• Access Policy - Browse REST endpoints for authorization checks, direct grants, and scoped role assignments, including inspection, listing, and revocation.
• API Keys - Browse REST endpoints for creating, reading, listing, updating, and deleting GoodMem API keys.
• Service Identities - Browse REST endpoints for workload identity creation, lookup, listing, updates, deletion, and ownership transfer.
• Spaces - Browse REST endpoints for memory-space creation, lookup, updates, deletion, ownership transfer, and listing spaces or their memories.
• Users - Browse REST endpoints for human-user management, profile lookup, and enrollment creation, inspection, completion, and revocation.

AI/ML ServicesCopy Anchor Link

• Decision Models - Register Jev, Laya, and Clef decision models and evaluate structured questions.
• Embedders - Browse REST endpoints for creating, reading, listing, updating, and deleting embedder configurations used for memory vectorization.
• LLMs - Browse REST endpoints for creating, reading, listing, updating, and deleting GoodMem language-model configurations.
• OCR - Find the REST endpoint for layout-aware OCR on documents and images, with a link to the document extraction request and response reference.
• Rerankers - Browse REST endpoints for creating, reading, listing, updating, and deleting reranker configurations used to rank retrieval results.

Data OperationsCopy Anchor Link

• Memories - Browse REST endpoints for memory creation, semantic retrieval, content and page-image downloads, deletion, and batch operations.

System and UtilitiesCopy Anchor Link

• Admin - Browse REST endpoints for server draining, license reloads, job purging, retrieval log policies, and GoodMem instance ownership transfer.
• Ping - Browse REST endpoints for single and streaming probes of embedder, reranker, and LLM endpoints.
• System - Browse REST endpoints for GoodMem instance identity, server build metadata, and system initialization.

Request FormatCopy Anchor Link

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 NamingCopy Anchor Link

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 StartedCopy Anchor Link

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 URLCopy Anchor Link

All API endpoints are relative to:

http://localhost:8080/v1

Rate LimitingCopy Anchor Link

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 FormatCopy Anchor Link

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?Copy Anchor Link

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