Embedding Models

Check word availability

POST/api/v1/embedding-models/{embeddingModelId}/word-availabilities

Check which words in words are present in the vocabulary of a specific embedding model. When whitelistWords is non-empty, a word is only marked available if it is both in the vocabulary AND in the allow-list.

Path Parameters

Parameter	Type	Required	Description
`embeddingModelId`	string	Yes

Request Body

wordsarray<string>YesWords to check for vocabulary presence.

whitelistWordsarray<string>NoOptional allow-list: if non-empty, only words that are both in the model's vocabulary AND in this list are marked as available.

Response

availabilitiesarray<object>One entry per word supplied in the request.

wordstringThe checked word.

isAvailablebooleanWhether the word is present in the model's vocabulary.

Example

cURL
Python
Node.js
Go

curl -X POST "https://app.neuroflash.com/api/v1/embedding-models/{embedding_model_id}/word-availabilities" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "words": [],
      "whitelistWords": []
  }'

import requests

response = requests.post(
    f"https://app.neuroflash.com/api/v1/embedding-models/{embedding_model_id}/word-availabilities",
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
    json={
        "words": [],
        "whitelistWords": []
    },
).json()

const response = await fetch(
  `https://app.neuroflash.com/api/v1/embedding-models/${embeddingModelId}/word-availabilities`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
          "words": [],
          "whitelistWords": []
    }),
  }
).then((r) => r.json());

body, _ := json.Marshal(map[string]any{
		"words": []any{},
		"whitelistWords": []any{},
	})

req, _ := http.NewRequest("POST", "https://app.neuroflash.com/api/v1/embedding-models/"+embeddingModelID+"/word-availabilities", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

Response:

{
  "availabilities": [
    {
      "word": "car",
      "isAvailable": true
    }
  ]
}

Compute a word similarity matrix

POST/api/v1/embedding-models/{embeddingModelId}/word-similarity-matrices

Return a pairwise cosine-similarity matrix for all words in the request that are present in the model's vocabulary. Words not found in the vocabulary are silently excluded from the result.

The response words list and the matrix rows/columns are aligned: matrix[i][j] is the similarity between words[i] and words[j]. Values are rounded to two decimal places.

Path Parameters

Parameter	Type	Required	Description
`embeddingModelId`	string	Yes

Request Body

wordsarray<string>YesWords to compare pairwise. Only words present in the model's vocabulary are included in the response (unavailable words are silently dropped).

Response

wordsarray<string>Words actually scored — subset of the requested list, limited to words present in the model's vocabulary.

matrixarray<array<number>>Square matrix of pairwise cosine-similarity scores. The entry at [i][j] is the similarity between words[i] and words[j]. Values are rounded to two decimal places.

Example

cURL
Python
Node.js
Go

curl -X POST "https://app.neuroflash.com/api/v1/embedding-models/{embedding_model_id}/word-similarity-matrices" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "words": []
  }'

import requests

response = requests.post(
    f"https://app.neuroflash.com/api/v1/embedding-models/{embedding_model_id}/word-similarity-matrices",
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
    json={
        "words": []
    },
).json()

const response = await fetch(
  `https://app.neuroflash.com/api/v1/embedding-models/${embeddingModelId}/word-similarity-matrices`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
          "words": []
    }),
  }
).then((r) => r.json());

body, _ := json.Marshal(map[string]any{
		"words": []any{},
	})

req, _ := http.NewRequest("POST", "https://app.neuroflash.com/api/v1/embedding-models/"+embeddingModelID+"/word-similarity-matrices", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

Response:

{
  "words": [
    "car",
    "automotive",
    "volkswagen"
  ],
  "matrix": [
    [
      0
    ]
  ]
}

List embedding models

GET/api/v1/embedding-models

Return the catalog of word-embedding models available to the caller. Optional country and language query parameters narrow the list to a single locale. Use the returned id of a model as embeddingModelId on the scoring, matching and completion endpoints. This catalog is global — it is not workspace-scoped.

Query Parameters

Parameter	Type	Default	Description
`country`	string	—	ISO 3166-1 alpha-2 country code, e.g. `de` or `us`.
`language`	string	—	ISO 639-1 language code, e.g. `de` or `en`.
`page`	integer	`1`	Page number to retrieve. The first page is 1 (not 0).
`size`	integer	`20`	Number of elements per page. Maximum 100.

Response

pageobject

sizeintegerRequested page size. Echoed back even when data contains fewer elements (e.g. on the last page).

totalElementsintegerTotal number of elements across all pages.

totalPagesintegerTotal number of pages given the requested size.

currentPageintegerPage number returned. The first page is 1 (not 0).

dataarray<object>Elements on the current page. May contain fewer than page.size on the last page.

idstringStable identifier for this embedding model. Pass this as embeddingModelId to the word-scoring / text-scoring / text-matching / word-completion endpoints.

languagestringISO 639-1 language code this model was trained on.

countrystringISO 3166-1 alpha-2 country code this model was trained on.

versionstringInternal version string of the model artifact.

sourcesarray<string>Data sources used when building this model.

featuresarray<string>Preprocessing features applied when training this model (e.g. phrase detection, deduplication).

tagstringOptional free-text discriminator distinguishing this model from siblings on the same locale/training run (e.g. a customer-specific variant). Not localized.

trainingYearstringYear of the training run, four digits.

trainingMonthstringMonth of the training run, zero-padded to two digits.

labelstringEnglish display label combining language, country and date. Suitable as the user-visible name when no localized string is available.

languageLabelstringEnglish display label for the model's language.

countryLabelstringEnglish display label for the model's country.

monthLabelstringEnglish display label for the model's training month.

tokenCountintegerNumber of tokens consumed during model training.

hasTranslationbooleanWhether an English translation companion model is available. When true results can be translated for cross-language UX.

loadingStatusstringWhether the model artifact is loaded into memory. One of loaded, not loaded, loading, error.

_embeddedobjectSub-resources embedded in an :class:EmbeddingModel response. Mirrors the HAL-style _embedded convention used elsewhere in the platform (e.g. TargetAudience._embedded).

mappersarray<object>Mapper bundles bundled with this model. For the catalog of all mappers (with country/language metadata) see GET /mappers.

keystringStable, displayable unique identifier of the mapper bundle. Not localized; use it as the key of an entry referencing this mapper on POST /word-scores / POST /text-scores.

variablesarray<string>Variables exposed by this mapper. Each one can be referenced independently by combining id = name + '_' + variable.

translationKeystringi18n key for the mapper's display name. Resolve client-side; do not show the raw key to users.

labelstringEnglish display label for this mapper. Use as a fallback when the i18n bundle for the user's locale doesn't carry translationKey.

Example

cURL
Python
Node.js
Go

curl "https://app.neuroflash.com/api/v1/embedding-models" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

import requests

response = requests.get(
    f"https://app.neuroflash.com/api/v1/embedding-models",
    headers={"Authorization": f"Bearer {token}"},
).json()

const response = await fetch(
  `https://app.neuroflash.com/api/v1/embedding-models`,
  { headers: { Authorization: `Bearer ${token}` } }
).then((r) => r.json());

req, _ := http.NewRequest("GET", "https://app.neuroflash.com/api/v1/embedding-models", nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

Response:

{
  "page": {
    "size": 20,
    "totalElements": 137,
    "totalPages": 7,
    "currentPage": 1
  },
  "data": [
    {
      "id": "001",
      "language": "en",
      "country": "us",
      "version": "0.1",
      "sources": [
        "commoncrawl"
      ],
      "features": [
        "phrases",
        "deduplication"
      ],
      "tag": "customer",
      "trainingYear": "2020",
      "trainingMonth": "01",
      "label": "English (US) 2020-01",
      "languageLabel": "English",
      "countryLabel": "US",
      "monthLabel": "January",
      "tokenCount": 50000000,
      "hasTranslation": false,
      "loadingStatus": "loaded",
      "_embedded": {
        "mappers": [
          "..."
        ]
      }
    }
  ]
}

Get an embedding model by id

GET/api/v1/embedding-models/{id}

Return a single embedding model identified by its id. The same id is used as embeddingModelId on the scoring, matching and completion endpoints.

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes