Content Analysis API

The Content Analysis API allows you to analyze text and HTML content using InsightEmbed's AI capabilities. This API is the core of InsightEmbed's functionality, enabling deep understanding and insights from your content.

Text Analysis

Analyze Text

POST /analyze/text

Analyze plain text content and receive AI-powered insights.

Request Parameters

Parameter	Type	Required	Description
text	string	Yes	The text content to analyze
context	string	No	Additional context about the content to improve analysis
max_tokens	integer	No	Maximum number of tokens in the response (default: 256)
prompt_template	string	No	Custom prompt template to guide the analysis
domain	string	No	The domain this content is from (for analytics)

Example Request

{
  "text": "InsightEmbed is a SaaS platform that enables website owners to enhance their content with AI-powered insights. The platform provides a simple, embeddable widget that visitors can use to analyze and understand content on any website without requiring the website owner to implement complex AI integrations.",
  "context": "Product description",
  "max_tokens": 150,
  "prompt_template": "Summarize the key benefits of this product"
}

Example Response

{
  "success": true,
  "data": {
    "analysis": "InsightEmbed offers website owners an easy way to add AI capabilities through a simple widget, eliminating the need for complex technical integrations. Key benefits include: 1) No-code implementation, 2) Enhanced visitor experience through AI-powered content analysis, 3) Simple embedding process.",
    "tokens_used": 48,
    "analysis_id": "ana_8f7d6c5e4b3a2"
  },
  "meta": {
    "processing_time": 0.82
  }
}

Analyze HTML

POST /analyze/html

Analyze HTML content, extracting and analyzing the relevant text while maintaining context from the HTML structure.

Request Parameters

Parameter	Type	Required	Description
html	string	Yes	The HTML content to analyze
url	string	No	The URL the HTML is from (for context)
selector	string	No	CSS selector to target specific elements
max_tokens	integer	No	Maximum number of tokens in the response (default: 256)
prompt_template	string	No	Custom prompt template to guide the analysis
domain	string	No	The domain this content is from (for analytics)

Example Request

{
  "html": "<div class='product-description'><h2>InsightEmbed</h2><p>A SaaS platform that enables website owners to enhance their content with AI-powered insights.</p></div>",
  "url": "https://example.com/products",
  "selector": ".product-description",
  "max_tokens": 100,
  "prompt_template": "What is this product about?"
}

Example Response

{
  "success": true,
  "data": {
    "analysis": "This product, InsightEmbed, is a SaaS platform that helps website owners enhance their content with AI-powered insights.",
    "tokens_used": 22,
    "analysis_id": "ana_1a2b3c4d5e6f",
    "extracted_text": "InsightEmbed A SaaS platform that enables website owners to enhance their content with AI-powered insights."
  },
  "meta": {
    "processing_time": 0.65
  }
}

Batch Analysis

Analyze Multiple Texts

POST /analyze/batch

Analyze multiple text items in a single request to reduce API calls.

Request Parameters

Parameter	Type	Required	Description
items	array	Yes	Array of text items to analyze
context	string	No	Shared context for all items
max_tokens_per_item	integer	No	Maximum tokens per response (default: 128)
prompt_template	string	No	Custom prompt template

Example Request

{
  "items": [
    {
      "id": "item1",
      "text": "InsightEmbed is a SaaS platform for AI-powered content analysis."
    },
    {
      "id": "item2",
      "text": "The widget can be embedded on any website with minimal technical effort."
    }
  ],
  "context": "Product features",
  "max_tokens_per_item": 50,
  "prompt_template": "Explain the key point"
}

Example Response

{
  "success": true,
  "data": {
    "results": [
      {
        "id": "item1",
        "analysis": "InsightEmbed offers AI-powered content analysis as a SaaS solution.",
        "tokens_used": 14
      },
      {
        "id": "item2",
        "analysis": "The widget is designed for easy integration on any website without requiring technical expertise.",
        "tokens_used": 18
      }
    ],
    "batch_id": "bat_7g8h9i0j1k2l"
  },
  "meta": {
    "processing_time": 1.45,
    "total_tokens_used": 32
  }
}

Error Handling

The Content Analysis API uses standard HTTP status codes and returns detailed error information in the response body.

Common Errors

Status Code	Error Code	Description
400	invalid_request	Missing required parameters or invalid format
401	authentication_error	Invalid or missing API key
403	forbidden	The API key doesn't have permission for this operation
413	content_too_large	The submitted content exceeds size limits
429	rate_limit_exceeded	You've exceeded your rate limit
500	service_error	Internal service error

Error Response Example

{
  "success": false,
  "error": {
    "code": "content_too_large",
    "message": "The submitted text exceeds the maximum size of 10,000 characters",
    "param": "text"
  }
}

Best Practices

1. Provide Context: Always include relevant context about your content to improve analysis quality.

2. Use Custom Prompts: Tailor the analysis by providing custom prompt templates for your specific use case.

3. Optimize Token Usage: Set appropriate max_tokens values to control response length and costs.

4. Batch Processing: Use the batch API for analyzing multiple related items to reduce API calls.

5. Error Handling: Implement proper error handling in your application to manage rate limits and other potential issues.

6. Caching: Consider caching analysis results for frequently accessed content to reduce API usage.

Quotas and Limits

Plan	Daily Analysis Limit	Max Content Size	Max Batch Size
Free	100 analyses	5,000 characters	5 items
Starter	1,000 analyses	10,000 characters	10 items
Pro	5,000 analyses	20,000 characters	20 items

For more information about quotas and rate limits, see the API Reference Overview.