Read API
Read is one POST for a single string. Put the counts, sentiment, and embedding in an application or a data pipeline. This key is the unstructured key under Account → API keys, not a model key.
POST https://read.heimdallapp.org/read/v1/api/process
Headers
| Header | Value |
|---|---|
X-api-key | Unstructured key |
X-username | Your Heimdall username |
Body
{ "text": "The invoice was paid yesterday." }
Send JSON. The service reads the text field. A missing username or key returns 404.
Response fields
| Group | Fields |
|---|---|
| Counts | length, word_count, sentence_count, avg_word_length, avg_sentence_length |
| Vocabulary | oov_ratio, oov_ratio_2 (a second out-of-vocabulary ratio, using WordNet) |
| Part of speech | noun_count, verb_count, adjective_count, adverb_count, pronoun_count, stopword_count |
| Top terms | tfidf_top1, tfidf_top2, tfidf_top3 |
| Sentiment | sentiment is positive, neutral, or negative. compound_sentiment_score is the VADER compound score, from -1 to 1. Above 0.05 is positive. Below -0.05 is negative. |
| Quality | line_punct_ratio, short_line_ratio, dup_line_char_frac, top_2gram_char_frac, alpha_ratio, frac_all_caps_words, unigram_entropy, compression_ratio |
| Embedding | emb_00 through emb_63 |
There is no topics field. Counts depend on the tokenizer, so compute them from a live response rather than from a pasted example.
Bulk labeled files go through Lake zip ingest, not this endpoint.