Skip to main content

Text Scoring & Analysis

Score a set of texts​

POST/api/v1/workspaces/{workspaceId}/text-scores

Score one or more full texts against an embedding model along the requested dimensions and mappers. When goalConfig is provided, a combined goalScore is returned per text plus a breakdown of the contributing goalScoreFactors.

Path Parameters​

ParameterTypeRequiredDescription
workspaceIdstringYesThe workspace the request operates on. Must match the workspace claim in the gateway token.

Request Body​

FieldTypeRequiredDescription
textsarray<string>YesTexts to score. Each text is returned with its own scores in data.
embeddingModelIdstringYesId of the embedding model to score against (see GET /embedding-models).
goalConfigobjectNoDefinition of the goal a scoring run is optimizing towards. A goal combines an optional modelRankScore preference, optional per-dimension weights and optional per-mapper weights, and a normalization strategy.
modelRankScorenumberNoWord-frequency preference from -1 (only infrequent words count positively) to 1 (only very frequent ones).
dimensionsarray<object>NoPer-dimension weights making up the goal.
idintegerYesDimension id, matching the id of an entry in dimensions.
weightintegerYesDirection in which a factor pulls the goal score.
mappersarray<object>NoPer-mapper weights making up the goal.
idstringYesMapper id, matching the id of an entry in mappers.
weightintegerYesDirection in which a factor pulls the goal score.
normalizationstringNoNormalization applied to per-factor scores before combining them.
dimensionsarray<object>NoSemantic dimensions to score each text against.
idintegerYesInternal dimension id. Repeat this id in goalConfig.dimensions[].id to give the dimension a weight.
wordsarray<string>NoSeed words defining this dimension. Used directly when type is manual; merged with the dimension's stored seeds when type is dimension.
typestringYesWhether the dimension is derived from a known dimension or from manual seed words.
namestringNoOptional display name for analytics/UI.
mapperKeysarray<string>NoCompound mapper-variable ids to score each text against. Each id matches the id returned by GET /mappers (e.g. en_emotions_standard_valence).

Response​

FieldTypeDescription
dataarray<object>Scored texts in the order they were submitted.
modelRankScorenumberScore reflecting how frequent the words used in this text are in the embedding model's vocabulary.
goalScoreFactorsarray<object>Breakdown of factors that contributed to goalScore. Empty when no goalConfig was provided.
fieldstringName of the factor (dimension/mapper/intrinsic) that contributed.
valuenumberNumeric contribution of this factor to the combined goal score.
typestringCategory of the factor (e.g. dimension, mapper, intrinsic).
dimensionScoresobjectPer-dimension scores keyed by str(dimension.id).
mapperScoresobjectPer-mapper-variable scores keyed by mapper id.
goalScorenumberCombined goal score (only set when goalConfig is provided).

Example​

curl -X POST "https://app.neuroflash.com/api/v1/workspaces/{workspace_id}/text-scores" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "texts": [],
      "embeddingModelId": "string",
      "goalConfig": {},
      "dimensions": [],
      "mapperKeys": []
  }'

Response:

{
  "data": [
    {
      "modelRankScore": 0.32,
      "goalScoreFactors": [
        {
          "field": "...",
          "value": "...",
          "type": "..."
        }
      ],
      "dimensionScores": {
        "29": 0.71
      },
      "mapperScores": {
        "en_emotions_standard_valence": 0.65
      },
      "goalScore": 0.58
    }
  ]
}

Score words against a seed concept​

POST/api/v1/workspaces/{workspaceId}/word-scores

Take a set of seed concepts (seedWords) and return scored candidate words against an embedding model. For each candidate word the response carries:

  • seedScore — semantic similarity to the centroid of the seed words (cosine similarity, range roughly -1..1)
  • modelRank — the word's frequency rank in the embedding model's vocabulary (lower means more frequent)
  • dimensionScores — per-axis scores for each entry in dimensions (e.g. how "fresh" or "luxurious" the word reads)
  • mapperScores — per-variable scores for each id in mapperKeys (e.g. valence, arousal)
  • goalScore — only populated when seedScore weight is set on the request; equals seedScore_weight * seed_similarity

Two modes, controlled by whitelistWords:

  • Score a fixed list. Send a non-empty whitelistWords and only those words are scored.
  • Find and score. Leave whitelistWords empty and the service picks the limit words from the embedding vocabulary closest to seedWords (further narrowed by wordrankLimit if provided), then scores those.

Typical use case: marketing keyword optimization — give the endpoint your campaign concepts in seedWords and a list of candidate keywords in whitelistWords to score them, or skip the whitelist and let the service surface fresh suggestions.

Path Parameters​

ParameterTypeRequiredDescription
workspaceIdstringYesThe workspace the request operates on. Must match the workspace claim in the gateway token.

Request Body​

FieldTypeRequiredDescription
seedWordsarray<string>YesAnchor words for the run. Their centroid defines what seedScore and the per-word seedScore field measure similarity against. In find-and-score mode (empty whitelistWords) the candidate set is also drawn from the region of vocabulary closest to this centroid.
whitelistWordsarray<string>NoRestrict scoring to exactly these words. When empty, the service runs in find-and-score mode and picks candidates from the embedding model's vocabulary.
embeddingModelIdstringYesId of the embedding model whose vocabulary and vector space the scoring runs against. See GET /embedding-models.
limitintegerNoFind-and-score mode only: maximum number of candidate words to pull from the vocabulary before scoring them. Ignored when whitelistWords is non-empty.
wordrankLimitintegerNoFrequency cutoff applied to candidate selection: only words within the top-N most frequent of the vocabulary are eligible. -1 disables the cutoff. Has no effect when whitelistWords is supplied.
seedScorenumberNoWeight applied to the per-word seed-similarity factor when computing the combined goalScore. Range -1 (penalise words close to the seed) to 1 (reward words close to the seed). null disables the goal-score computation entirely, in which case the response's goalScore fields are also null.
dimensionsarray<object>NoSemantic dimensions to score each word against. Each entry contributes a per-word dimensionScores value in the response.
idintegerYesInternal dimension id. Repeat this id in goalConfig.dimensions[].id to give the dimension a weight.
wordsarray<string>NoSeed words defining this dimension. Used directly when type is manual; merged with the dimension's stored seeds when type is dimension.
typestringYesWhether the dimension is derived from a known dimension or from manual seed words.
namestringNoOptional display name for analytics/UI.
mapperKeysarray<string>NoCompound mapper-variable ids to score each word against. Each id matches the id returned by GET /mappers (e.g. en_emotions_standard_valence). Each id contributes a per-word mapperScores value in the response.

Response​

FieldTypeDescription
dataarray<object>Scored words returned by the request.
wordstringThe scored word, lowercased.
seedScorenumberSemantic similarity with the request's seed words. null when no seed was provided (whitelist mode).
modelRankintegerFrequency rank in the embedding model's vocabulary (lower = more frequent).
seedScoreQuartileintegerQuartile assignment within the scored set; -1 means unassigned.
modelRankQuartileintegerQuartile assignment within the scored set; -1 means unassigned.
dimensionScoresobjectPer-dimension scores keyed by str(dimension.id). Missing values are omitted (use 0 as a fallback in clients).
mapperScoresobjectPer-mapper-variable scores keyed by mapper id. Missing values are omitted.
goalScorenumberCombined goal score (only set when goalConfig is provided).
averagesobjectAverages across all scored words for the same request.
modelRankScorenumberAverage model-rank score across the scored set.
seedScorenumberAverage seed-similarity score across the scored set.
dimensionScoresobjectPer-dimension averages keyed by str(dimension.id).
mapperScoresobjectPer-mapper averages keyed by mapper id.
goalScorenumberAverage goal score (only set when goalConfig is provided).

Example​

curl -X POST "https://app.neuroflash.com/api/v1/workspaces/{workspace_id}/word-scores" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "seedWords": [],
      "whitelistWords": [],
      "embeddingModelId": "string",
      "limit": 100,
      "wordrankLimit": -1,
      "seedScore": 0,
      "dimensions": [],
      "mapperKeys": []
  }'

Response:

{
  "data": [
    {
      "word": "innovative",
      "seedScore": 0.42,
      "modelRank": 1234,
      "seedScoreQuartile": 0,
      "modelRankQuartile": 0,
      "dimensionScores": {
        "29": 0.71
      },
      "mapperScores": {
        "en_emotions_standard_valence": 0.65
      },
      "goalScore": 0.58
    }
  ],
  "averages": {
    "modelRankScore": 0.32,
    "seedScore": 0.45,
    "dimensionScores": {
      "29": 0.62
    },
    "mapperScores": {
      "en_emotions_standard_valence": 0.58
    },
    "goalScore": 0.55
  }
}

Check a text for plagiarism​

POST/api/v1/workspaces/{workspaceId}/plagiarism-checks

Scan a piece of text for verbatim matches on the public web via the upstream plagiarism service. The input must contain at least 15 words. Returns the total word count of the input plus a list of sources where matching passages were found, including a matchPercentage per source.

Quota is enforced through the usage-service against the workspace's plagiarismChecks budget — callers who have exhausted their monthly allowance get 403 with ERROR_NO_REMAINING_PLAGIARISM_CHECKS. Each successful call increments the counter by one.

Path Parameters​

ParameterTypeRequiredDescription
workspaceIdstringYesThe workspace the request operates on. Must match the workspace claim in the gateway token.

Request Body​

FieldTypeRequiredDescription
textstringYesThe text to scan for plagiarism. Must contain at least 15 words after stripping punctuation, otherwise the request is rejected with translation key plagiarismTextTooShort.

Response​

FieldTypeDescription
wordCountintegerTotal number of words in the input text (after punctuation stripping).
matchesarray<object>Sources on the public web that contain passages matching the input text. Empty when no plagiarism was detected.
urlstringURL of the external page where the match was found.
titlestringHTML &lt;title&gt; of the page where the match was found.
matchSnippetstringExcerpt of the matching passage, usually with surrounding context. Suitable for highlighting in the UI.
wordsMatchedintegerNumber of words in the input text that matched this source.
matchPercentagenumberFraction of the input text matched by this source, expressed as a percentage in the range 0 - 100.

Example​

curl -X POST "https://app.neuroflash.com/api/v1/workspaces/{workspace_id}/plagiarism-checks" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "text": "string"
  }'

Response:

{
  "wordCount": 28,
  "matches": [
    {
      "url": "https://en.wikipedia.org/wiki/Example_Person",
      "title": "Example Person - Wikipedia",
      "matchSnippet": "She was born in Sydney and studied English Literature and Law at the University of New South Wales...",
      "wordsMatched": 24,
      "matchPercentage": 84.5
    }
  ]
}

Tokenize a text​

POST/api/v1/workspaces/{workspaceId}/tokenizations

Split a piece of text into tokens using the tokenizer for the given language. Each token carries its surface form, normalized form, character offsets in the original text, a stop-word flag, and (when available) a list of synonyms. The response also includes tokenCount for convenience.

Path Parameters​

ParameterTypeRequiredDescription
workspaceIdstringYesThe workspace the request operates on. Must match the workspace claim in the gateway token.

Request Body​

FieldTypeRequiredDescription
languagestringYesISO 639-1 language code that selects which tokenizer/model to use, e.g. en, de, fr, ja.
textstringYesThe text to tokenize.

Response​

FieldTypeDescription
tokenCountintegerTotal number of tokens returned. Equal to len(tokens).
tokensarray<object>The tokens produced from the input text, in their original order.
stringstringThe original substring of the input that this token covers.
tokenstringThe normalized/lemmatized form of the token used for downstream processing. For Japanese inputs this is identical to string.
indexStartintegerZero-based character offset where this token starts in the input text.
indexEndintegerZero-based character offset where this token ends in the input text (exclusive).
isStopbooleanWhether the token is considered a stop word in the chosen language (e.g. the, and, of in English).
synonymsarray<string>Synonyms of the token, when available for this language. Empty list when no synonyms were found.

Example​

curl -X POST "https://app.neuroflash.com/api/v1/workspaces/{workspace_id}/tokenizations" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "language": "string",
      "text": "string"
  }'

Response:

{
  "tokenCount": 5,
  "tokens": [
    {
      "string": "Angela",
      "token": "angela",
      "indexStart": 0,
      "indexEnd": 6,
      "isStop": false,
      "synonyms": []
    }
  ]
}

Suggest completions for a partial word​

POST/api/v1/workspaces/{workspaceId}/autocomplete-suggestions

Return up to ten suggestions for a partially typed word, drawn from the supplied embedding model's vocabulary. Use the whitelistWords field to restrict the candidate set (e.g. to a campaign-specific glossary).

Typical use case: powering the inline-autocomplete dropdown in a copy-editing UI.

Path Parameters​

ParameterTypeRequiredDescription
workspaceIdstringYesThe workspace the request operates on. Must match the workspace claim in the gateway token.

Request Body​

FieldTypeRequiredDescription
wordstringYesPartial word the caller wants completions for. Treated as a prefix and matched against the embedding model's vocabulary.
embeddingModelIdstringYesId of the embedding model whose vocabulary completions are drawn from (see GET /embedding-models).
whitelistWordsarray<string>NoIf non-empty, only completions present in this whitelist are returned. Useful to restrict autocomplete to a campaign-specific glossary.

Response​

FieldTypeDescription
suggestionsarray<string>Up to ten suggested completions, ordered from best to worst.

Example​

curl -X POST "https://app.neuroflash.com/api/v1/workspaces/{workspace_id}/autocomplete-suggestions" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "word": "string",
      "embeddingModelId": "string",
      "whitelistWords": []
  }'

Response:

{
  "suggestions": [
    "multicolored",
    "multihued"
  ]
}