Embedder

Services

EmbedderService Service

Service for managing Embedder configurations in the GoodMem system.

Authentication: gRPC metadata x-api-key: <api-key>

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

Authorization model:

• Every RPC evaluates a typed authorization operation against the GoodMem instance or a particular embedder.
• Ownership, code-defined role assignments, and direct grants can supply authority; an API-key ceiling may further restrict the authenticated principal's effective authority.
• Listing requires LIST_EMBEDDER on the instance and returns only embedders on which the caller has READ_EMBEDDER.

CreateEmbedder

Creates a new embedder configuration.

Auth: gRPC metadata x-api-key: <api-key>

Authorization Required: CREATE_EMBEDDER on the proposed embedder, evaluated using its proposed owner.

Summary:

• Owner defaults to the authenticated principal unless owner_id is provided; authorization is evaluated against that proposed owner
• ALREADY_EXISTS: another embedder for the same owner has the same effective provider connection and model configuration after endpoint canonicalization and provider-default resolution; equivalent credentials participate in this comparison
• The response omits stored credentials; use GetEmbedder with include_credentials=true for separately authorized disclosure

Side Effects:

• Persists the embedder and its credentials; sets audit fields

Error Codes:

• UNAUTHENTICATED: missing/invalid auth
• PERMISSION_DENIED: lacks CREATE_EMBEDDER on the proposed 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 'x-api-key: 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 x-api-key: <api-key>

Authorization Required: READ_EMBEDDER on the requested embedder. When include_credentials is true, the caller must also hold READ_EMBEDDER_CREDENTIALS; only the current owner or an instance administrator can supply that authority.

Side Effects: None

Error Codes:

• UNAUTHENTICATED: missing/invalid auth
• PERMISSION_DENIED: lacks READ_EMBEDDER, or requests credentials without READ_EMBEDDER_CREDENTIALS
• 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 'x-api-key: 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 principal.

Auth: gRPC metadata x-api-key: <api-key>

Authorization Required: LIST_EMBEDDER on the GoodMem instance and READ_EMBEDDER on each returned embedder. The standard user role may enumerate the catalog and read owned embedders; direct grants can expose additional embedders.

Request Parameters:

• owner_id (optional, bytes UUID): filter the already-authorized result set by owner
• provider_type (optional): UNSPECIFIED ignored
• label_selectors (optional): AND of exact key=value matches (case-sensitive)
• Stored credentials are always omitted from list responses

Note: bytes fields in JSON must be base64.

Side Effects: None

Error Codes:

• UNAUTHENTICATED: missing/invalid auth
• PERMISSION_DENIED: lacks instance-level 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 'x-api-key: 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 x-api-key: <api-key>

Authorization Required: UPDATE_EMBEDDER on the requested embedder.

Credential handling: Omitting credentials preserves the stored value. A present empty payload is invalid and never clears it. The response always omits credentials.

Side Effects:

• Persists changes; updates updated_at and updated_by_id

Error Codes:

• UNAUTHENTICATED: missing/invalid auth
• PERMISSION_DENIED: lacks UPDATE_EMBEDDER on the requested 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
• ALREADY_EXISTS: the resulting effective provider connection and model configuration would duplicate another embedder for the same owner
• INTERNAL: unexpected server error

Idempotency: Idempotent with identical input; safe to retry.

Examples:

grpcurl -plaintext \
-H 'x-api-key: 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 x-api-key: <api-key>

Authorization Required: DELETE_EMBEDDER on the requested embedder.

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 on the requested 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 'x-api-key: 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 are returned only by GetEmbedder when explicitly requested and separately authorized. Create, update, and list responses omit them.

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)