GoodMemGoodMem
ReferenceAPIREST APISpaces

List memories in a space

GET /v1/spaces/{spaceId}/memories: Lists all memories within a given space.

GET
/v1/spaces/{spaceId}/memories

Lists all memories within a given space. Pagination is supported via maxResults and nextToken (opaque). nextToken is a URL-safe Base64 string without padding; do not parse or construct it. This is a read-only operation with no side effects and is safe to retry.

AUTHORIZATION: Requires LIST_MEMORY on the exact containing space. Each returned memory must also satisfy READ_MEMORY, either directly or through DIRECT_MEMBERS_OF that space. Both predicates are evaluated in PostgreSQL. Returns NOT_FOUND if the specified space does not exist.

Authorization

ApiKeyAuth
headerx-api-key<token>

Path Parameters

spaceId*string

The UUID of the space containing the memories

Query Parameters

includeContent?boolean

Whether to include the original content in the response (defaults to false). The snake_case alias include_content is also accepted.

Defaultfalse
includeProcessingHistory?boolean

Whether to include background job processing history in the response (defaults to false). The snake_case alias include_processing_history is also accepted.

Defaultfalse
statusFilter?string

Filter memories by processing status (PENDING, PROCESSING, COMPLETED, FAILED). The snake_case alias status_filter is also accepted.

Value in"PENDING""PROCESSING""COMPLETED""FAILED"
filter?string

Optional metadata filter expression for list results See Filter Expressions reference for syntax and examples.

maxResults?integer

Maximum number of results per page (defaults to 50, clamped to [1, 500]). The snake_case alias max_results is also accepted.

Formatint32
Default50
nextToken?string

Opaque pagination token for the next page. URL-safe Base64 without padding; do not parse or construct it. The snake_case alias next_token is also accepted.

sortBy?string

Field to sort by (e.g., 'created_at'). The snake_case alias sort_by is also accepted.

Value in"created_at""updated_at""content_type""processing_status"
sortOrder?string

Sort direction (ASCENDING or DESCENDING). The snake_case alias sort_order is also accepted.

Value in"ASCENDING""DESCENDING""SORT_ORDER_UNSPECIFIED"

Header Parameters

GoodMem-Timeout-Ms?integer

Optional waiting budget in milliseconds, measured from REST servlet ingress and shared across all internal gRPC calls. Supply one decimal integer from 1 to 86400000. Omission adds no deadline. Existing shorter deadlines still apply. Expiry returns HTTP 504 before streaming starts; after streaming starts, no successful completion event is sent. Use SSE or opt into GoodMem-Stream-Terminal for an explicit terminal outcome. Retrieval work is cooperatively cancelled. An accepted mutation may still commit after timeout or disconnect; a failed response does not imply rollback.

Formatint64
Range1 <= value <= 86400000

Response Body

Successfully retrieved memories

application/json
  1. response

Response containing a list of memories within a space

memories*array<>

Array of memories in the space

Example
[  {    "memoryId": "550e8400-e29b-41d4-a716-446655440000",    "spaceId": "550e8400-e29b-41d4-a716-446655440001",    "contentType": "text/plain",    "processingStatus": "COMPLETED"  }]
nextToken?|

Token for retrieving the next page of results

Example"eyJvZmZzZXQiOjEwLCJsaW1pdCI6MTB9"
Example Request
curl -X GET 'https://your-goodmem-server.example.com/v1/spaces/550e8400-e29b-41d4-a716-446655440000/memories?includeContent=false&includeProcessingHistory=false&statusFilter=COMPLETED&filter=val%28%27%24.source%27%29+%3D+%27email%27&maxResults=100&nextToken=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...&sortBy=created_at&sortOrder=DESCENDING' \  -H 'GoodMem-Timeout-Ms: 30000'
Example Response
{  "memories": [    {      "memoryId": "550e8400-e29b-41d4-a716-446655440000",      "spaceId": "550e8400-e29b-41d4-a716-446655440001",      "contentType": "text/plain",      "processingStatus": "COMPLETED"    }  ],  "nextToken": "eyJvZmZzZXQiOjEwLCJsaW1pdCI6MTB9"}