Skip to main content

Unstructured API key

Time to complete: ~2 minutes

The unstructured API key gives you access to Read (text analysis) and Vision (image analysis). It is separate from per-model keys used by ML, Forecast, and Loop.

Before you start
  • Heimdall account
  • You need Read/Vision only: skip this page if you are doing tabular ML via Lake

How to get your key​

  1. Sign in at heimdallapp.org
  2. Either:
    • Sidebar footer → Looking for unstructured? (opens Settings), or
    • Sidebar → Account → API keys (/settings?section=api-keys)
  3. Click Generate under the unstructured key section
Important: Store Your API Key Securely

Unstructured API key is issued one time and cannot be retrieved. If you lose your API key, you'll need to generate a new one and update your applications.

What You Can Do with Your Unstructured API Key​

Your single unstructured API key gives you access to:

  • Text Analysis - Extract sentiment, topics, and insights from text data
  • Image Analysis - Analyze images and extract features

Using Your Unstructured API Key​

Include your unstructured API key in the headers of all API requests for both text and image analysis:

headers = {
    'X-api-key': 'YOUR-UNSTRUCTURED-API-KEY',
    'X-username': 'YOUR-USERNAME'
}

Expected Response​

When you analyze text, you get a JSON payload like this:

{
  "length": 108,
  "word_count": 17,
  "oov_ratio": 0.17647058823529413,
  "oov_ratio_2": 0.29411764705882354,
  "sentence_count": 1,
  "avg_word_length": 5.470588235294118,
  "avg_sentence_length": 17,
  "noun_count": 7,
  "verb_count": 3,
  "adjective_count": 2,
  "adverb_count": 0,
  "pronoun_count": 0,
  "stopword_count": 5,
  "tfidf_top1": "accessible",
  "tfidf_top2": "amazing",
  "tfidf_top3": "data",
  "sentiment": "positive",
  "compound_sentiment_score": 0.5859,
  "line_punct_ratio": 1.0,
  "short_line_ratio": 0.0,
  "dup_line_char_frac": 0.0,
  "top_2gram_char_frac": 0.08,
  "alpha_ratio": 0.84,
  "frac_all_caps_words": 0.0,
  "unigram_entropy": 3.91,
  "compression_ratio": 0.71,
  "emb_00": 0.0123,
  "emb_01": -0.0456,
  "emb_63": 0.0089
}

The live payload also includes emb_02 through emb_62 (64 dimensions total). They are omitted here.

Security Best Practices​

  • Never commit API keys to version control
  • Use environment variables to store API keys
  • Rotate keys regularly for security

Lake vs unstructured key​

NeedUse
One text/image per API callThis key → Read/Vision
Thousands of files for ML trainingLake → Add data → Unstructured zip: no unstructured key required for ingest

Next steps​

  1. First API call
  2. Unstructured suite overview
  3. Tabular ML? → User journeys (Lake path, not this key)