Get or create version by facts

Answers the live version of the product whose facts are the ones you send, and creates it when no version holds them. Send the agent state you are about to test, and callers that run at the same time on that state all receive one version instead of each creating its own. The key order you send does not change the match. The answer is 200 whether the version already existed or was created now, because the caller asks for the version for a state and not for a new row.

POST /versions/get-or-create

Get or create version by facts

cURL

curl --request POST \
  --url https://api.galtea.ai/versions/get-or-create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "productId": "prod_123",
  "facts": {
    "model": "gpt-4o",
    "temperature": "0.7",
    "promptVersion": "12"
  },
  "name": "nightly build"
}
'

200

{
  "id": "ver_123",
  "productId": "prod_123",
  "userId": "user_123",
  "number": 7,
  "name": "support release",
  "description": "Version description",
  "modelId": "model_123",
  "systemPrompt": "You are a helpful assistant",
  "datasetUri": "https://example.com/dataset.csv",
  "datasetDescription": "Training dataset",
  "guardrails": "Safety guidelines",
  "facts": {
    "model": "gpt-4o",
    "temperature": "0.7",
    "promptVersion": "12"
  },
  "otelInputSourceRule": {
    "spanName": "ExecuteActivity:add_user_message",
    "attribute": "app.arguments",
    "path": "$[0].message.content",
    "predicate": {
      "path": "$[0].message.role",
      "equals": "user"
    }
  },
  "otelOutputSourceRule": {
    "spanName": "ExecuteActivity:save_reply",
    "attribute": "app.arguments",
    "path": "$[0].message.content",
    "predicate": {
      "path": "$[0].message.role",
      "equals": "assistant"
    }
  },
  "initializationEndpointConnectionId": "ec_123",
  "conversationEndpointConnectionId": "ec_123",
  "finalizationEndpointConnectionId": "ec_123",
  "phoneConnectionId": "phoneConnection_123",
  "webRtcConnectionId": "webRtcConnection_123",
  "parentVersionId": "ver_122",
  "createdAt": "2023-11-07T05:31:56Z",
  "deletedAt": "2023-11-07T05:31:56Z"
}

Authorizations

Authorization · string · header · required

API key authorization. Pass your API key in the Authorization header as a Bearer token. Both new (gsk_*) and legacy (gsk-) API keys are accepted, e.g. Authorization: Bearer gsk_... or Authorization: Bearer gsk-....

Body

application/json

productId · string · required

Product the version belongs to.

Minimum string length: 1

Example:

"prod_123"

facts · object · required

The agent state this version represents, as a flat map of text to text. Every key and every value is trimmed, an entry whose key or value is then empty is dropped, and the rest is kept exactly, so "0.7" and "0.70" are two different facts. At most 32 keys, and at most 2000 bytes once the map is encoded as JSON, which counts its punctuation too. No key and no value may hold the NUL character or half of a surrogate pair. Two keys that become equal after the spaces around them are removed are refused, unless both become empty, which drops them instead because a blank key names no fact; a key repeated with the exact same spelling never reaches that rule, because JSON parsing keeps only its last value. Two live versions of one product may not hold the same facts; the key order you send does not change that comparison. A map that leaves no entry is stored as null. A fact whose key is "model" or "model_name" (case, "_" and "-" are ignored, so "modelName" counts too) is a model fact. It can link the version to the model whose name equals its value, provider prefix included (for example "azure/gpt-4o") and ignoring case. The model must be one the product organization can use: one of its own models or a global one. Its own model wins over a global model of the same name. Model facts that find two different models link none. At least one key and value must survive the trimming, or the call is refused. A version this call creates is linked to the model a model fact names; a version it finds keeps its model.

Show child attributes

Example:

{
  "model": "gpt-4o",
  "temperature": "0.7",
  "promptVersion": "12"
}

name · string

Name for the version, used only when this call creates one. A version the call finds keeps the name it already has. A name another version of the product holds is refused.

Example:

"nightly build"

Response

200

application/json

Version resolved successfully

id · string

Example:

"ver_123"

productId · string

Example:

"prod_123"

userId · string | null

Example:

"user_123"

number · integer · read-only

The version's sequence number inside its product. It starts at 1, is assigned when the version is created, never changes, and is never reused after a version is deleted. The canonical label is "v" followed by this number.

Required range: x >= 1

Example:

7

name · string

Optional human label. Omit it and the version is stored under its canonical label. A name of "v" followed by digits is rejected, because it reads as the number of another version. The one exception is the number this version is given, which produces the same result as omitting the name. "v1.0" is accepted.

Example:

"support release"

description · string | null

Example:

"Version description"

modelId · string | null

The model the version runs on; token cost reads its prices. It must be one of the product organization's models or a global model. On a create, a modelId you send is the model; when you omit it or send null or an empty string, a model fact links the model (see facts). On an update, a model fact links the model only when you omit modelId and the version has no model; null clears the model.

Example:

"model_123"

systemPrompt · string | null

Example:

"You are a helpful assistant"

datasetUri · string | null

Example:

"https://example.com/dataset.csv"

datasetDescription · string | null

Example:

"Training dataset"

guardrails · string | null

Example:

"Safety guidelines"

facts · object | null

The agent state this version represents, as a flat map of text to text. Every key and every value is trimmed, an entry whose key or value is then empty is dropped, and the rest is kept exactly, so "0.7" and "0.70" are two different facts. At most 32 keys, and at most 2000 bytes once the map is encoded as JSON, which counts its punctuation too. No key and no value may hold the NUL character or half of a surrogate pair. Two keys that become equal after the spaces around them are removed are refused, unless both become empty, which drops them instead because a blank key names no fact; a key repeated with the exact same spelling never reaches that rule, because JSON parsing keeps only its last value. Two live versions of one product may not hold the same facts; the key order you send does not change that comparison. A map that leaves no entry is stored as null. A fact whose key is "model" or "model_name" (case, "_" and "-" are ignored, so "modelName" counts too) is a model fact. It can link the version to the model whose name equals its value, provider prefix included (for example "azure/gpt-4o") and ignoring case. The model must be one the product organization can use: one of its own models or a global one. Its own model wins over a global model of the same name. Model facts that find two different models link none.

Show child attributes

Example:

{
  "model": "gpt-4o",
  "temperature": "0.7",
  "promptVersion": "12"
}

otelInputSourceRule · object | null

Recover a turn's user-visible input for products whose user message lives on a non-LLM span. Set per organization, product or version. The version rule wins, then the product rule. Per span it applies only when no LLM input is present. Per turn the value it extracts IS the turn input, ahead of every fallback, and the turn input is EMPTY when the rule extracts nothing from any span of the turn. The two directions resolve independently.

Show child attributes

Example:

{
  "spanName": "ExecuteActivity:add_user_message",
  "attribute": "app.arguments",
  "path": "$[0].message.content",
  "predicate": {
    "path": "$[0].message.role",
    "equals": "user"
  }
}

otelOutputSourceRule · object | null

Recover a turn's user-visible output for templated or non-LLM replies whose final answer lives on a non-LLM span. Set per organization, product or version. The version rule wins, then the product rule. Per span it applies only when no LLM output is present. Per turn the value it extracts IS the turn output, ahead of every fallback, and the turn output is EMPTY when the rule extracts nothing from any span of the turn. The two directions resolve independently.

Show child attributes

Example:

{
  "spanName": "ExecuteActivity:save_reply",
  "attribute": "app.arguments",
  "path": "$[0].message.content",
  "predicate": {
    "path": "$[0].message.role",
    "equals": "assistant"
  }
}

initializationEndpointConnectionId · string | null

Example:

"ec_123"

conversationEndpointConnectionId · string | null

Example:

"ec_123"

finalizationEndpointConnectionId · string | null

Example:

"ec_123"

phoneConnectionId · string | null

The version's phone connection (telephony conversation target). At most one conversation target may be set across conversationEndpointConnectionId, phoneConnectionId, and webRtcConnectionId.

Example:

"phoneConnection_123"

webRtcConnectionId · string | null

The version's WebRTC connection (live two-way audio conversation target). At most one conversation target may be set across conversationEndpointConnectionId, phoneConnectionId, and webRtcConnectionId.

Example:

"webRtcConnection_123"

parentVersionId · string | null

Id of the version this one was revised from (its direct parent in the revision lineage). On create, providing this value records the parent edge; the parent must belong to the same product. Omit or null to create a root version with no parent. On responses, this is the recorded parent edge (null for roots).

Example:

"ver_122"

createdAt · string<date-time>

deletedAt · string<date-time> | null