Embedder

Services

EmbedderService Service

Service for managing Embedder configurations in the GoodMem system.

Authentication: gRPC metadata authorization: Bearer <api-key>

Global errors: All RPCs may return DEADLINE_EXCEEDED, CANCELLED, UNAVAILABLE, RESOURCE_EXHAUSTED, INTERNAL.

Permissions model:

• *_OWN: operate on caller-owned embedders
• *_ANY: operate on any user's embedders (requires elevated role)

CreateEmbedder

Creates a new embedder configuration.

Auth: gRPC metadata authorization: Bearer <api-key>

Permissions Required: CREATE_EMBEDDER_OWN or CREATE_EMBEDDER_ANY

Summary:

• Owner defaults to the authenticated user unless owner_id is provided (requires *_ANY if differs)
• ALREADY_EXISTS: another embedder exists with identical {owner_id, provider_type, endpoint_url, api_path, model_identifier, credentials_fingerprint} after URL canonicalization: trailing slash stripped; default ports removed; host comparison case-insensitive; credentials_fingerprint is SHA-256 hash of normalized credentials

Side Effects:

• Persists embedder; encrypts credentials; sets audit fields

Error Codes:

• UNAUTHENTICATED: missing/invalid auth
• PERMISSION_DENIED: lacks CREATE_EMBEDDER_*
• INVALID_ARGUMENT: bad URL(s); empty/invalid fields; dimensionality <= 0; UNSPECIFIED enums; labels exceed limits/charset; unsupported modality
• ALREADY_EXISTS: matching embedder as defined above
• INTERNAL: unexpected server error

Idempotency: Non-idempotent; clients SHOULD NOT blindly retry on unknown failures.

Examples:

grpcurl -plaintext \
-H 'authorization: Bearer gm_xxx' \
-d '{
"display_name": "OpenAI TE",
"provider_type": "PROVIDER_TYPE_OPENAI",
"endpoint_url": "https://api.openai.com",
"api_path": "/embeddings",
"model_identifier": "text-embedding-3-small",
"dimensionality": 1536,
"distribution_type": "DISTRIBUTION_TYPE_DENSE",
"credentials": "sk-***",
"labels": {"env":"dev","team":"ml"}
}' \
localhost:8080 goodmem.v1.EmbedderService/CreateEmbedder

Note: bytes fields in JSON must be base64.

GetEmbedder

Retrieves details of a specific embedder.

Auth: gRPC metadata authorization: Bearer <api-key>

Permissions Required: READ_EMBEDDER_OWN or READ_EMBEDDER_ANY

Side Effects: None

Error Codes:

• UNAUTHENTICATED: missing/invalid auth
• PERMISSION_DENIED: lacks READ_EMBEDDER_*
• INVALID_ARGUMENT: invalid embedder ID format
• NOT_FOUND: embedder does not exist
• INTERNAL: unexpected server error

Idempotency: Read-only; safe to retry; results may change over time.

Examples:

grpcurl -plaintext \
-H 'authorization: Bearer gm_xxx' \
-d '{ "embedder_id": "BASE64_UUID_BYTES_HERE" }' \
localhost:8080 goodmem.v1.EmbedderService/GetEmbedder

Note: bytes fields in JSON must be base64.

ListEmbedders

Lists embedders accessible to the authenticated user.

Auth: gRPC metadata authorization: Bearer <api-key>

Permissions Required: LIST_EMBEDDER_OWN or LIST_EMBEDDER_ANY

Request Parameters:

• owner_id (optional, bytes UUID): filter by owner. If caller has LIST_EMBEDDER_ANY and owner_id is omitted, all embedders visible to the role are returned; otherwise only caller-owned embedders are returned
• provider_type (optional): UNSPECIFIED ignored
• label_selectors (optional): AND of exact key=value matches (case-sensitive)

Note: bytes fields in JSON must be base64.

Side Effects: None

Error Codes:

• UNAUTHENTICATED: missing/invalid auth
• PERMISSION_DENIED: lacks LIST_EMBEDDER_*
• INVALID_ARGUMENT: invalid filters or parameters
• INTERNAL: unexpected server error

Idempotency: Read-only; safe to retry; results may change over time.

Examples:

grpcurl -plaintext \
-H 'authorization: Bearer gm_xxx' \
-d '{ "provider_type":"PROVIDER_TYPE_OPENAI", "label_selectors":{"env":"prod"} }' \
localhost:8080 goodmem.v1.EmbedderService/ListEmbedders

UpdateEmbedder

Updates mutable properties of an embedder.

Auth: gRPC metadata authorization: Bearer <api-key>

Permissions Required: UPDATE_EMBEDDER_OWN or UPDATE_EMBEDDER_ANY

Side Effects:

• Persists changes; updates updated_at and updated_by_id

Error Codes:

• UNAUTHENTICATED: missing/invalid auth
• PERMISSION_DENIED: lacks UPDATE_EMBEDDER_*
• INVALID_ARGUMENT: invalid fields or formats
• NOT_FOUND: embedder does not exist
• FAILED_PRECONDITION: changes to dimensionality, distribution_type, or model_identifier are rejected while the embedder is referenced by active spaces/collections or ingestion jobs are running; try again after detaching or completing jobs
• INTERNAL: unexpected server error

Idempotency: Idempotent with identical input; safe to retry.

Examples:

grpcurl -plaintext \
-H 'authorization: Bearer gm_xxx' \
-d '{
"embedder_id": "BASE64_UUID_BYTES_HERE",
"replace_labels": { "items": {} }
}' \
localhost:8080 goodmem.v1.EmbedderService/UpdateEmbedder

Note: bytes fields in JSON must be base64.

DeleteEmbedder

Permanently deletes an embedder configuration.

Auth: gRPC metadata authorization: Bearer <api-key>

Permissions Required: DELETE_EMBEDDER_OWN or DELETE_EMBEDDER_ANY

Side Effects:

• Removes the embedder record; securely deletes stored credentials
• Does not invalidate or delete embeddings previously created with this embedder

Error Codes:

• UNAUTHENTICATED: missing/invalid auth
• PERMISSION_DENIED: lacks DELETE_EMBEDDER_*
• INVALID_ARGUMENT: invalid embedder ID format
• NOT_FOUND: embedder does not exist
• INTERNAL: unexpected server error

Idempotency: Safe to retry; may return NOT_FOUND if already deleted or never existed.

Examples:

grpcurl -plaintext \
-H 'authorization: Bearer gm_xxx' \
-d '{ "embedder_id": "BASE64_UUID_BYTES_HERE" }' \
localhost:8080 goodmem.v1.EmbedderService/DeleteEmbedder

Note: bytes fields in JSON must be base64.

Messages

Embedder

Represents a connection to an embedding API service for vectorization.

Embedders provide semantic vector representations of text, images, or other content by interfacing with external AI services. Each embedder configuration includes connection details, model parameters, and access credentials.

Security:

• credentials is INPUT_ONLY and is omitted from all responses.

Notes:

• All timestamps are UTC (google.protobuf.Timestamp).
• provider_type is IMMUTABLE after creation.

See also: goodmem.v1.ProviderType, goodmem.v1.Modality

Embedder.LabelsEntry

CreateEmbedderRequest

CreateEmbedderRequest.LabelsEntry

GetEmbedderRequest

ListEmbeddersRequest

ListEmbeddersRequest.LabelSelectorsEntry

ListEmbeddersResponse

UpdateEmbedderRequest

DeleteEmbedderRequest

Enums

DistributionType

Embedding distribution type for neural vectorization models.

• DISTRIBUTION_TYPE_UNSPECIFIED = 0: Invalid distribution type; never used in practice
• DISTRIBUTION_TYPE_DENSE = 1: Dense embeddings (traditional floating-point vectors)
• DISTRIBUTION_TYPE_SPARSE = 2: Sparse embeddings (high-dimensional sparse vectors)