Skip to content

AI Enrichment

Request

AI Enrichment API

Overview

The AI Enrichment API allows you to enrich data or generate insights using advanced language models. Send a query or prompt and receive AI-generated responses that can include analysis, summaries, recommendations, or structured data extraction.

Request Body

{
  "query": "string (required)",
  "options": {
    "format_json": "boolean (optional)"
  },
  "effort": "string (optional, default: low)"
  "max_credits": "integer (optional)"
}

Field Descriptions

  • query: The main prompt or question to send to the AI model (required)
  • options (optional): Additional configuration options
    • format_json: Whether to return response in structured JSON format (defaults to false)
  • effort (optional): Specifies the level of enrichment effort to apply, by default is low
  • max_credits must be a positive integer if provided

Request Constraints

  • query is required and must be non-empty
  • options.format_json when provided must be a boolean value
  • effort when provided accepted values are: low, medium, high
  • Query length should not exceed 8000 characters

Response Fields

  • success: Boolean indicating request success
  • query: Echo of the input query
  • response: AI-generated response (string or structured object based on format_json setting)
  • confidence: AI confidence score in the response (0.0-1.0)
  • credits_consumed: Number of credits used for this request
  • credits_remaining (int | null): Approximate remaining credit balance. Use GET /v1/credits/remaining for precise value.
  • token_usage: Token consumption details
    • prompt_tokens: Tokens used in the input
    • completion_tokens: Tokens used in the response
    • total_tokens: Total tokens consumed
  • processing_time_ms: Time taken to process the request in milliseconds

Confidence Levels

  • 0.9-1.0: Very high confidence - factual, well-supported responses
  • 0.7-0.9: High confidence - good quality responses with minor uncertainty
  • 0.5-0.7: Medium confidence - reasonable responses but may need verification
  • 0.0-0.5: Low confidence - speculative or uncertain responses

Common Use Cases

  1. Data Analysis & Insights: Analyze trends, patterns, and generate business insights
  2. Content Generation: Create marketing copy, emails, summaries, and reports
  3. Data Extraction: Parse unstructured text and extract structured information
  4. Research & Summarization: Synthesize information and provide comprehensive overviews
  5. Decision Support: Generate recommendations and evaluate options
  6. Text Enhancement: Improve, rewrite, or optimize existing content

Credit Usage

AI enrichment consumes credits based on the complexity and length of the response:

  • Simple Queries: 1-3 credits (short responses, basic analysis)
  • Standard Queries: 3-6 credits (medium-length responses, data extraction)
  • Complex Analysis: 6-12 credits (detailed analysis, research, long-form content)
  • JSON Structured Output: +1-2 credits additional (for formatting and validation)
Security
BearerAuth
Bodyapplication/jsonrequired
querystring, <= 8000 characters(Query)required

The main prompt or question to send to the AI model

optionsAIEnrichmentOptions (object) or null
Any of:

Options for AI enrichment request.

effortstring(EnrichmentEffortType)

Enrichment effort type

Default:"low"
Enum:"low""medium""high"
agent_typestring or null(Agent Type)
Any of:

Type of specialized agent to use for processing

string
curl -i -X POST \
  https://api-gateway.agenthq.withlantern.com/v1/enrich/ai \
  -H 'Authorization: Bearer <YOUR_ApiToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "string",
    "options": {
      "format_json": false
    },
    "effort": "low",
    "agent_type": "funding"
  }'

Responses

Success Response

Bodyapplication/json
successboolean(Success)required

Boolean indicating request success

querystring(Query)required

Echo of the input query

responsestring or object(Response)required
Any of:

AI-generated response

string
confidencenumber or null(Confidence)
Any of:

AI confidence score (0.0-1.0) or null if disabled

[ 0 .. 1 ]
number
credits_consumedinteger(Credits Consumed)required

Number of credits used for this request

credits_remaininginteger or null(Credits Remaining)
Any of:

Approximate remaining credit balance. Use GET /v1/credits/remaining for precise balance.

integer
token_usageobject(TokenUsage)required

Token consumption details

processing_time_msinteger(Processing Time Ms)required

Time taken to process the request in milliseconds

agent_usedstring(Agent Used)required

Type of agent that was used for processing

Response
{
  "success": true,
  "query": "Analyze the market trends for electric vehicles in 2024",
  "response": "Based on current market data, electric vehicle adoption is accelerating rapidly in 2024. Key trends include: 1) Increased affordability with new models under $30k, 2) Improved charging infrastructure with 40% more stations, 3) Enhanced battery technology offering 300+ mile ranges...",
  "confidence": 0.85,
  "credits_consumed": 5,
  "credits_remaining": 950,
  "token_usage": {
    "prompt_tokens": 45,
    "completion_tokens": 234,
    "total_tokens": 279
  },
  "processing_time_ms": 1200
}