# AI Enrichment

# 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

json
{
  "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: Credits remaining in your account after this request
- 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)

Endpoint: POST /v1/enrich/ai
Version: 1.4.1
Security: BearerAuth

## Request fields (application/json):

  - `query` (string, required)
    The main prompt or question to send to the AI model

  - `options` (any)
    Additional configuration options

  - `effort` (string)
    Enrichment effort type
    Enum: "low", "medium", "high"

  - `agent_type` (any)
    Type of specialized agent to use for processing

## Response 200 fields (application/json):

  - `success` (boolean, required)
    Boolean indicating request success

  - `query` (string, required)
    Echo of the input query

  - `response` (any, required)
    AI-generated response

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

  - `credits_consumed` (integer, required)
    Number of credits used for this request

  - `credits_remaining` (integer, required)
    Credits remaining in your account after this request

  - `token_usage` (object, required)
    Token consumption details

  - `token_usage.prompt_tokens` (integer, required)
    Tokens used in the input

  - `token_usage.completion_tokens` (integer, required)
    Tokens used in the response

  - `token_usage.total_tokens` (integer, required)
    Total tokens consumed

  - `processing_time_ms` (integer, required)
    Time taken to process the request in milliseconds

  - `agent_used` (string, required)
    Type of agent that was used for processing

## Response 400 fields (application/json):

  - `success` (boolean)
    Always false for error responses

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `credits_required` (any)
    Credits required for insufficient credit errors

  - `credits_remaining` (any)
    Credits remaining for insufficient credit errors

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors

## Response 401 fields (application/json):

  - `success` (boolean)
    Always false for error responses

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `credits_required` (any)
    Credits required for insufficient credit errors

  - `credits_remaining` (any)
    Credits remaining for insufficient credit errors

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors

## Response 402 fields (application/json):

  - `success` (boolean)
    Always false for error responses

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `credits_required` (any)
    Credits required for insufficient credit errors

  - `credits_remaining` (any)
    Credits remaining for insufficient credit errors

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors

## Response 422 fields (application/json):

  - `detail` (array)

  - `detail.loc` (array, required)

  - `detail.msg` (string, required)

  - `detail.type` (string, required)

## Response 429 fields (application/json):

  - `success` (boolean)
    Always false for error responses

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `credits_required` (any)
    Credits required for insufficient credit errors

  - `credits_remaining` (any)
    Credits remaining for insufficient credit errors

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors

## Response 500 fields (application/json):

  - `success` (boolean)
    Always false for error responses

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `credits_required` (any)
    Credits required for insufficient credit errors

  - `credits_remaining` (any)
    Credits remaining for insufficient credit errors

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors