Embeddings

Generate vector embeddings for text using ThreatWinds-hosted embedding models. This endpoint is OpenAI-compatible and returns dense float vectors suitable for semantic search, clustering, and similarity comparisons.

Endpoint: https://apis.threatwinds.com/api/ai/v1/embeddings

Method: POST

Parameters

Headers

Header	Type	Required	Description
Authorization	string	Optional*	Bearer token for session authentication
api-key	string	Optional*	API key for key-based authentication
api-secret	string	Optional*	API secret for key-based authentication
Content-Type	string	Yes	Must be application/json

Note: You must use either the Authorization header OR the api-key/api-secret combination.

Request Body

{
  "model": "nomic-embed-text-v1.5",
  "input": "Analyze this threat intelligence report",
  "encoding_format": "float"
}

Request Parameters

Parameter	Type	Required	Description
model	string	Yes	Model ID to use for embedding generation
input	string | array	Yes	Text to embed. Can be a single string or an array of strings for batch embedding
encoding_format	string	No	Format for the embedding values. float (default) or base64

Available Models

Model	Max Input Tokens	Description
nomic-embed-text-v1.5	8192	High-performance text embedding model by Nomic AI

Example

curl -X 'POST' \
  'https://apis.threatwinds.com/api/ai/v1/embeddings' \
  -H 'Authorization: Bearer <token>' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "nomic-embed-text-v1.5",
  "input": "CVE-2024-1234 is a critical remote code execution vulnerability"
}'

Batch Embedding

Embed multiple texts in a single request:

curl -X 'POST' \
  'https://apis.threatwinds.com/api/ai/v1/embeddings' \
  -H 'Authorization: Bearer <token>' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "nomic-embed-text-v1.5",
  "input": [
    "Ransomware attack targeting healthcare sector",
    "DDoS amplification using DNS reflection",
    "SQL injection in login form"
  ]
}'

Returns

A successful response returns a JSON object with an array of embedding vectors:

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [0.0123, -0.0456, 0.0789, 0.0321, 0.0654],
      "index": 0
    }
  ],
  "model": "nomic-embed-text-v1.5",
  "usage": {
    "prompt_tokens": 12,
    "total_tokens": 12
  }
}

Response Schema

Field	Type	Description
object	string	Always "list"
data	array	Array of embedding objects, one per input text
data[].object	string	Always "embedding"
data[].embedding	array	Vector of floating-point numbers representing the text
data[].index	integer	Zero-based index corresponding to the input array position
model	string	Model ID used for the request
usage.prompt_tokens	integer	Number of tokens in the input
usage.total_tokens	integer	Total tokens processed (same as prompt_tokens for embeddings)

Note: The embedding vector dimension depends on the model’s serving configuration. nomic-embed-text-v1.5 supports Matryoshka dimensions from 64 to 768. ThreatWinds serves this model at 768 dimensions by default.

Note: The example embedding array above is truncated for readability. The actual vector contains 768 values.

Error Response Headers

Header	Description
x-error	Human-readable error message
x-error-id	Unique MD5 hash identifier for error tracking

Error Codes

Status Code	Description	Possible Cause
400	Bad Request	Missing model, missing input, empty input string or array, invalid encoding_format
401	Unauthorized	Missing or invalid authentication credentials
403	Forbidden	Insufficient permissions for AI API access
500	Internal Server Error	Embedding service unavailable or server-side error