Bluon Embeddings API

Use the Bluon Embeddings API to fetch relevant diagnostic and repair data, as well as manual context for specific equipment, to feed your RAG app. No external embedding tool needed. Send a plain text query and receive the most semantically similar records, ranked by score, ready to drop into your agent or chatbot prompt.

Two Knowledge Bases

MasterMechanic troubleshooting problem/solution sets, and chunked text from equipment manuals.

Semantic Search

Natural language queries match on meaning, not keywords. Ask the way a technician would.

Text In, Context Out

Embedding is handled server-side with one model for queries and stored content. You never send a vector.

Base URL

{{base_url}}/embedding/{{namespace}}/search

Embeddings endpoints live under /embedding/ and do not take a partner slug in the path. Authentication uses the same Bearer token as the rest of the Bluon API, described in the API Overview. All requests are POST with a JSON body.

Namespaces

The namespace in the path selects which knowledge base is searched. The request body shape is the same for both.

NamespaceContentRecordsFilter
trainingMasterMechanic troubleshooting data: real problem/solution sets from tech support calls, tagged with brand, model, and equipment type where known47,000+Optional
manualsChunked text from equipment manuals (IOM, parts lists, product data, wiring, service facts), each chunk tied to a manual ID, page number, and source PDF1,500,000+manual_id required

Request Body

FieldTypeRequiredDescription
query.inputs.textstringrequiredThe plain text query. Phrase it as a question or symptom description.
query.top_kintegerrequiredNumber of hits to return. Start with 3 to 5 for prompt context.
query.filterobjectoptional*Metadata filter. For manuals this must containmanual_id: { "$in": [...] } with one or more manual UUIDs.

* Required for the manuals namespace. Requests to manuals without a manual_id filter are rejected.

1. Troubleshooting Search (training)

Returns the problem/solution sets most similar to your query. Each hit's text is a complete, self-contained troubleshooting record that can be passed straight into an LLM prompt.

Endpoint

POST {{base_url}}/embedding/training/search

Example Curl

curl -X 'POST' \
  'https://test.hub.bluontoolbox.com/uat/embedding/training/search' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer [YOUR_TOKEN]' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "inputs": {
        "text": "Compressor will not start, what should I do?"
      },
      "top_k": 3
    }
  }'

Example Response

{
  "usage": {
    "embed_total_tokens": 14,
    "read_units": 1
  },
  "result": {
    "hits": [
      {
        "_id": "training_1005",
        "_score": 0.5785589814186096,
        "fields": {
          "QC Date": "6/11/24",
          "brand": "Airtemp",
          "calling_group": "Residential Condenser",
          "model_details": "5 Tons 208-230V 1Ph R-410A",
          "model_number": "VSH3BE4M1SP60K",
          "text": "Problem: Compressor not starting, just humming, fan comes on, no attempt from compressor to start. Static refrigerant pressure on both lines is 250. Meter readings at compressor terminals are not as expected.\nSolution: Based on the symptoms and meter readings, it appears the compressor may be mechanically locked up internally. To troubleshoot further, reconnect all components, and with power off, measure the amp draw on the black wire between the contactor and compressor. A high amp draw may indicate a locked compressor. Consult with your boss about trying a hard start kit, understanding the potential risks of causing a burnout. Consider replacing the contactor, compressor, and capacitor. Monitor the situation closely to avoid damaging the system further.\nBrand: Airtemp\nModel: VSH3BE4M1SP60K\nModel Details: 5 Tons 208-230V 1Ph R-410A\nEquipment Type: Residential Condenser",
          "unit_type": "Residential Condenser"
        }
      },
      {
        "_id": "training_3080",
        "_score": 0.5634335875511169,
        "fields": {
          "QC Date": "6/24/24",
          "calling_group": "Refrigeration",
          "text": "Problem: The Embraco compressor is not starting properly, pulling high amps, and feels seized up. The system may have blockages causing the issue.\nSolution: 1. Recover some refrigerant to ensure it's not overcharged. 2. Disconnect the compressor from the system and run it briefly to check if it can start. 3. Check the filter dryer and cap tube for blockages by using nitrogen to blow through them. 4. Consider replacing the compressor with a new one, along with the filter dryer and possibly the cap tube. 5. Avoid shaking or damaging the compressor to prevent a short circuit. 6. Check and confirm correct wiring to capacitor terminals. 7. Utilize a better quality meter like a Fluke for accurate readings and troubleshooting. 8. Remove the compressor carefully to avoid any damage to the system.\nEquipment Type: Refrigeration",
          "unit_type": "Refrigeration"
        }
      },
      {
        "_id": "training_2117",
        "_score": 0.5577990412712097,
        "fields": {
          "QC Date": "6/17/24",
          "calling_group": "Commercial Package Unit",
          "text": "Problem: Compressor contactor not engaging\nSolution: Check for 24 volts at the coil of the compressor contactor. Verify operation of pressure switches and low-pressure switch. Ensure proper control voltage is reaching the contactor. Review manufacturer's wiring diagrams for proper connections and troubleshoot any discrepancies. Consider checking for refrigerant levels in the system as low pressure could prevent the compressor from starting.\nEquipment Type: Commercial Package Unit",
          "unit_type": "Commercial Package Unit"
        }
      }
    ]
  }
}

Response Fields

  • fields.text - The full problem and solution, plus any brand, model, and equipment type lines. This is the field to feed your model.
  • fields.brand, model_number, model_details - Present only when the original call was tied to a specific unit.
  • fields.calling_group / unit_type - Equipment category (Residential Condenser, Refrigeration, Commercial Package Unit, etc.).
  • fields.QC Date - Date the record was quality-checked by Bluon's technician team.

The set of keys under fields varies by record in this namespace. Treat every key except text as optional.

2. Manuals Search (manuals)

Returns the manual passages most relevant to your query, scoped to the manuals you specify. This lets you replicate MasterMechanic's "ask the manuals" experience for a specific piece of equipment.

Endpoint

POST {{base_url}}/embedding/manuals/search

Getting Manual IDs

Manual IDs are the UUIDs returned by the Manuals endpoint for a given model. A typical flow is: identify the model with Model Search or the Nameplate Reader, fetch its manuals, then pass those IDs here.

Example Curl

curl -X 'POST' \
  'https://test.hub.bluontoolbox.com/uat/embedding/manuals/search' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer [YOUR_TOKEN]' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "inputs": {
        "text": "What is the part number for the indoor control board?"
      },
      "top_k": 3,
      "filter": {
        "manual_id": {
          "$in": [
            "0A0B0755-AB17-41BC-B90D-30EA43DF23F3",
            "0A0D7D75-318E-467C-8B81-8C90B74FCE11",
            "0A5F8898-71AA-4D01-A918-466CEF71828B"
          ]
        }
      }
    }
  }'

Example Response

The text values below are shortened. Real chunks run several thousand characters and often contain Markdown tables.

{
  "usage": {
    "embed_total_tokens": 14,
    "read_units": 13
  },
  "result": {
    "hits": [
      {
        "_id": "manuals_1467222",
        "_score": 0.39580535888671875,
        "fields": {
          "chunk": "03",
          "manual_id": "0A5F8898-71AA-4D01-A918-466CEF71828B",
          "manual_type": "parts_information",
          "page_number": 3.0,
          "text": "### PANEL AND HEAT EXCHANGER PARTS\n\n1. The part quantity below indicates the required number of pieces per unit.\n2. The circled No. indicates that the part is not shown in the figure.\n\n| No. | Part No. | Part Name | PKFY-P04NLMU-E.TH | PKFY-P06NLMU-E.TH | ...",
          "url": "https://assets-bluon-prod.sfo3.cdn.digitaloceanspaces.com/oems/Parts%20List/M_PKFY-P_20NLMU_PARTS_OCB715_03-20.pdf"
        }
      },
      {
        "_id": "manuals_1467224",
        "_score": 0.39192816615104675,
        "fields": {
          "chunk": "05",
          "manual_id": "0A5F8898-71AA-4D01-A918-466CEF71828B",
          "manual_type": "parts_information",
          "page_number": 5.0,
          "text": "### ELECTRICAL PARTS\n\n1. The part quantity below indicates the required number of pieces per unit.\n2. The circled No. indicates that the part is not shown in the figure.\n\n| No. | Part No. | Part Name | PKFY-P04NLMU-E.TH | PKFY-P06NLMU-E.TH | ...",
          "url": "https://assets-bluon-prod.sfo3.cdn.digitaloceanspaces.com/oems/Parts%20List/M_PKFY-P_20NLMU_PARTS_OCB715_03-20.pdf"
        }
      },
      {
        "_id": "manuals_1467204",
        "_score": 0.3565675914287567,
        "fields": {
          "chunk": "06",
          "manual_id": "0A0B0755-AB17-41BC-B90D-30EA43DF23F3",
          "manual_type": "product_data",
          "page_number": 4.0,
          "text": "## OUTDOOR UNIT ACCESSORIES: MXZ-SM42NAMHZ\n\n| Air Deflector | Vertical Air Deflector | ADV-1 | ...",
          "url": "https://assets-bluon-prod.sfo3.cdn.digitaloceanspaces.com/oems/Product%20Data/M_SUBMITTAL_MXZ-SM42NAMHZ_en.pdf"
        }
      }
    ]
  }
}

Response Fields

  • fields.text - The manual passage as Markdown. Tables are preserved, so part numbers and specs stay structured.
  • fields.manual_id - Which of your requested manuals the chunk came from.
  • fields.manual_type - Manual category, e.g. parts_information, product_data, installation_operation_maintenance.
  • fields.page_number / chunk - Location within the manual, useful for citations.
  • fields.url - Direct link to the source PDF.

Response Shape

Both namespaces return the same envelope. Hits are nested under result.hits[], not at the top level, ordered by descending _score. Scores are cosine similarity in the 0 to 1 range and are only comparable within one namespace: troubleshooting hits typically score in the 0.5 to 0.6 range for a good match, while manual chunks score lower because each chunk covers a broader span of text. The sibling usage object reports the embedding tokens and read units consumed by the request.

Notes

  • Always filter manuals queries by manual_id. Unfiltered queries would search 1.5M chunks across every manual and return irrelevant results, so the API rejects them.
  • Pass several manual IDs at once when a model has multiple manuals. The response tells you which manual each hit came from.
  • Keep top_k small. Three to five well-scored hits give an LLM better context than twenty mixed ones.
  • Send the user's question as-is. Rewriting it into keywords usually lowers match quality for semantic search.
  • Do not pre-embed. The API embeds your text with the same model used to index the content, which is what makes the scores meaningful.