POST /ai_enrich • Credits: 2 credits per call

AI Enrich runs one prompt through OpenAI, Anthropic, Gemini or Perplexity from a single endpoint. Send a POST request with a provider and a prompt. The response holds the generated content, the model name, the finish reason and the token counts. Each call costs 2 credits.

What does AI Enrich do?

AI Enrich is one endpoint in front of four AI providers. You pick the provider and the model. RichAPI holds the provider API keys, so you need no OpenAI, Anthropic, Google or Perplexity account. The endpoint fills {{variable}} placeholders in your prompt from a context object. It can force structured JSON output, and it can turn on web search. Sales and marketing teams use AI Enrich to classify leads, to extract fields from raw text and to summarize company descriptions.

Which endpoint does AI Enrich use?

Method: POST
URL: https://api.richapi.ai/api/v1/ai_enrich
Authentication: x-api-key header
Response: Synchronous JSON
Credits: 2 credits per call

Which providers and models does AI Enrich accept?

AI Enrich accepts four values for the provider parameter. Each provider has a default model. If you omit the model parameter, AI Enrich uses that default.

Provider	`provider` value	Default model	Accepted model names
OpenAI	`openai`	`gpt-4o-mini`	Any model name that the OpenAI Chat Completions API accepts.
Anthropic	`anthropic`	`claude-haiku-4-5-20251001`	Any model name that the Anthropic Messages API accepts.
Gemini	`gemini`	`gemini-2.0-flash`	Any model name that the Gemini `generateContent` API accepts.
Perplexity	`perplexity`	`sonar`	Any model name that the Perplexity Responses API accepts.

AI Enrich does not check the model value against a list. It passes the value straight to the provider. If the provider rejects the model name, AI Enrich returns the provider's error status, usually 404, with a short error message and the provider field.

CAUTION: A wrong provider value returns 400 and costs no credit. The four accepted values are openai, anthropic, gemini and perplexity.

How to send an AI Enrich request

Copy your API key from the RichAPI dashboard.
Pick a provider: openai, anthropic, gemini or perplexity.
Write the prompt. Put a {{variable}} placeholder where a value changes per record.
Put the value for each placeholder in the context object.
Set the model parameter, or omit it to use the provider default.
Send a POST request to https://api.richapi.ai/api/v1/ai_enrich.
Send the API key in the x-api-key header.
Read the generated text from the content field of the response.

cURL

curl -X POST https://api.richapi.ai/api/v1/ai_enrich   
  -H "x-api-key: YOUR_API_KEY"   
  -H "Content-Type: application/json"   
  -d '{
    "provider": "openai",
    "model": "gpt-4o-mini",
    "system_prompt": "You are a concise assistant.",
    "prompt": "Summarize this: {{text}}",
    "context": { "text": "RichAPI is a B2B data enrichment API." },
    "temperature": 0.3,
    "max_tokens": 4096
  }'

Python

import requests

response = requests.post(
    "https://api.richapi.ai/api/v1/ai_enrich",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "provider": "openai",
        "model": "gpt-4o-mini",
        "system_prompt": "You are a concise assistant.",
        "prompt": "Summarize this: {{text}}",
        "context": {"text": "RichAPI is a B2B data enrichment API."},
        "temperature": 0.3,
        "max_tokens": 4096,
    },
    timeout=60,
)
response.raise_for_status()
print(response.json())

Node.js

const response = await fetch("https://api.richapi.ai/api/v1/ai_enrich", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    provider: "openai",
    model: "gpt-4o-mini",
    system_prompt: "You are a concise assistant.",
    prompt: "Summarize this: {{text}}",
    context: { text: "RichAPI is a B2B data enrichment API." },
    temperature: 0.3,
    max_tokens: 4096,
  }),
});

const data = await response.json();
console.log(data);

What parameters does AI Enrich accept?

Parameter	Type	Required	Default	Description
`provider`	string	Yes	—	The AI provider: `openai`, `anthropic`, `gemini` or `perplexity`.
`prompt`	string	Yes	—	The prompt text. It accepts `{{variable}}` placeholders that `context` fills.
`model`	string	No	The provider default	The model name. AI Enrich passes it to the provider without a check.
`temperature`	number	No	`0.3`	The sampling temperature. The value must be between 0 and 2. Perplexity ignores it.
`context`	object	No	`{}`	Key and value pairs that fill the `{{variable}}` placeholders in `prompt`.
`system_prompt`	string	No	`""`	System instructions for the model.
`output_type`	string	No	`text`	The output format: `text` or `json`.
`output_schema`	object	No	`{}`	A JSON schema for structured output. Perplexity is the one provider that receives it.
`max_tokens`	integer	No	`4096`	The maximum number of output tokens. The value must be a positive integer.
`use_web_search`	boolean	No	`false`	Turns on web search for the provider.
`search_domain_filter`	array	No	`[]`	Perplexity only. It limits the search to the domain names in the array.
`search_recency_filter`	string	No	`""`	Perplexity only. One of `day`, `week`, `month` or `year`.

How do {{variable}} placeholders and context work?

The prompt parameter accepts {{variable}} placeholders. The context parameter holds the values. Before AI Enrich calls the provider, it replaces every {{key}} in the prompt with the matching value from context. This turns one prompt into a template that you send once per record.

Send this request body:

{
  "provider": "anthropic",
  "prompt": "Write a one-line opener for {{name}}, {{title}} at {{company}}.",
  "context": {
    "name": "Jane Smith",
    "title": "VP Sales",
    "company": "Northwind Analytics"
  }
}

The provider receives this prompt:

Write a one-line opener for Jane Smith, VP Sales at Northwind Analytics.

Four rules control the replacement:

Rule	Behavior
Name match	A `{{key}}` placeholder matches the `context` key with the same name. The match is case sensitive.
Value type	A number, a boolean or an object in `context` becomes text before the replacement.
Missing key	If `context` holds no key for a placeholder, the raw `{{key}}` text stays in the prompt.
Extra key	A `context` key with no placeholder in the prompt changes nothing.

CAUTION: A misspelled placeholder sends the raw {{key}} text to the model. The call still costs credits. Check the placeholder names against the context keys before you send a batch.

How do you force structured JSON output?

Set output_type to json. Each provider handles the JSON mode in a different way, and only Perplexity receives the output_schema object.

Provider	What `output_type: "json"` does	Receives `output_schema`?
`openai`	Turns on the OpenAI JSON object mode.	No
`anthropic`	Nothing. Anthropic ignores `output_type`.	No
`gemini`	Sets the JSON response type on the Gemini request.	No
`perplexity`	Sets a JSON schema response format built from `output_schema`.	Yes

Three points follow from the table:

For OpenAI, Anthropic and Gemini, name the fields you want inside the prompt text.
For OpenAI, write the word JSON in the prompt. The OpenAI JSON object mode requires it.
For Perplexity, pass the shape in output_schema. If output_type is json and output_schema is empty, Perplexity receives a schema that accepts any object.

The content field of the response is always a string. If you set output_type to json, parse content as JSON in your own code.

Which providers support web search?

Set use_web_search to true to turn on web search. All four providers support web search, and each one uses a different mechanism.

Provider	Web search support	Mechanism
`openai`	Yes, for a model name that holds `gpt-4o`, `gpt-4.1` or `gpt-5`	The OpenAI Responses API with the `web_search_preview` tool.
`anthropic`	Yes	The Anthropic Messages API with the `web_search` tool.
`gemini`	Yes	The Gemini `generateContent` API with Google Search grounding.
`perplexity`	Yes	Native Perplexity web search. It returns a `citations` array.

The two search filters are not general. search_domain_filter and search_recency_filter reach the provider for Perplexity only, and only when use_web_search is true. OpenAI, Anthropic and Gemini ignore both parameters.

CAUTION: For OpenAI, use a model name that holds gpt-4o, gpt-4.1 or gpt-5. Any other OpenAI model name runs the prompt without web search. The call still costs 2 credits.

What does AI Enrich return?

AI Enrich returns one JSON object. It holds the generated content, the provider, the model and the token counts.

{
  "model": "gpt-4o-mini",
  "content": "RichAPI is a B2B data enrichment API.",
  "provider": "openai",
  "tokens_used": 30,
  "input_tokens": 18,
  "finish_reason": "stop",
  "output_tokens": 12
}

What does each AI Enrich response field mean?

Field	Type	Description
`model`	string	The model that produced the content. A provider can return a dated model name, for example `gpt-4o-mini-2024-07-18`. For `gemini` the value is an empty string.
`content`	string	The generated text. If `output_type` is `json`, this string holds the JSON document.
`provider`	string	The provider that ran the prompt: `openai`, `anthropic`, `gemini` or `perplexity`.
`tokens_used`	integer	The total token count for the call. It is the sum of `input_tokens` and `output_tokens`.
`input_tokens`	integer	The token count of the prompt and the system prompt.
`finish_reason`	string	Why the model stopped. The value comes from the provider, for example `stop`, `end_turn` or `completed`.
`output_tokens`	integer	The token count of the generated content.
`citations`	array	Perplexity only. Source URLs for a web search answer. The field is absent for the other three providers.

Example: how do you classify a lead?

Set temperature to 0 and a low max_tokens value. Name the labels in the prompt so the model returns one label.

Request body:

{
  "provider": "openai",
  "model": "gpt-4o-mini",
  "system_prompt": "You are a B2B lead qualification assistant. Answer with one label and nothing else.",
  "prompt": "Classify this lead as ICP, ADJACENT or OUT_OF_ICP. Our ICP is a software company with 50 to 500 employees that sells to sales teams. Lead: {{name}}, {{title}} at {{company}}, industry {{industry}}, {{employee_count}} employees.",
  "context": {
    "name": "Jane Smith",
    "title": "VP Sales",
    "company": "Northwind Analytics",
    "industry": "Computer Software",
    "employee_count": 180
  },
  "temperature": 0,
  "max_tokens": 16
}

Response:

{
  "model": "gpt-4o-mini-2024-07-18",
  "content": "ICP",
  "provider": "openai",
  "tokens_used": 97,
  "input_tokens": 95,
  "finish_reason": "stop",
  "output_tokens": 2
}

Cost: 2 credits, or $0.04.

Example: how do you extract structured fields from raw text?

Use Perplexity for this task. Perplexity is the one provider that receives output_schema, so the response shape follows the schema that you send.

Request body:

{
  "provider": "perplexity",
  "model": "sonar",
  "system_prompt": "Extract fields from text. Return JSON that matches the schema. Add no commentary.",
  "prompt": "Extract the company name, the industry and the employee count from this text: {{text}}",
  "context": {
    "text": "Northwind Analytics is a 180-person computer software company in Austin, Texas."
  },
  "output_type": "json",
  "output_schema": {
    "type": "object",
    "properties": {
      "company_name": { "type": "string" },
      "industry": { "type": "string" },
      "employee_count": { "type": "integer" }
    }
  },
  "temperature": 0
}

Response:

{
  "model": "sonar",
  "content": "{\"company_name\":\"Northwind Analytics\",\"industry\":\"Computer Software\",\"employee_count\":180}",
  "provider": "perplexity",
  "tokens_used": 112,
  "input_tokens": 78,
  "finish_reason": "completed",
  "output_tokens": 34
}

The content field holds a JSON string. Parse it in your own code to read company_name, industry and employee_count.

Cost: 2 credits, or $0.04.

Example: how do you summarize a company description?

Cap the length in the system_prompt and set a low max_tokens value. This keeps the summary short and the cost of tokens down.

Request body:

{
  "provider": "anthropic",
  "model": "claude-haiku-4-5-20251001",
  "system_prompt": "You are a concise assistant. Write two sentences and no more.",
  "prompt": "Summarize this company description for a sales representative: {{description}}",
  "context": {
    "description": "Northwind Analytics builds a revenue analytics platform for B2B sales teams. The platform reads CRM data and scores open pipeline. Northwind Analytics serves 400 mid-market software accounts and works from Austin, Texas."
  },
  "temperature": 0.3,
  "max_tokens": 200
}

Response:

{
  "model": "claude-haiku-4-5-20251001",
  "content": "Northwind Analytics sells a revenue analytics platform that scores open pipeline from CRM data. The company serves 400 mid-market software accounts from Austin, Texas.",
  "provider": "anthropic",
  "tokens_used": 168,
  "input_tokens": 129,
  "finish_reason": "end_turn",
  "output_tokens": 39
}

Cost: 2 credits, or $0.04.

How much does AI Enrich cost?

One AI Enrich call costs 2 credits, whatever the provider. At $0.02 a credit, the rate on the 1,000 and 5,000 credit packs, one call costs $0.04. Larger packs cost less per credit. The price is flat per call. The tokens_used, input_tokens and output_tokens fields report the token count of the call, and no token count changes the credit cost. A long prompt and a short prompt cost the same 2 credits.

Calls	Credits	Cost
1	2	$0.04
100	200	$4.00
1,000	2,000	$40.00
10,000	20,000	$400.00

Provider	Credits per call	Cost per call
`openai`	2	$0.04
`anthropic`	2	$0.04
`gemini`	2	$0.04
`perplexity`	2	$0.04

RichAPI charges credits for a successful call only. A call that returns an error status costs no credit.

What errors does AI Enrich return?

Status	Meaning	What to do
`400`	The request body failed validation. The `error` field names the parameter.	Correct the parameter that the message names. A missing `provider`, a missing `prompt`, a `temperature` outside 0 to 2 and a `max_tokens` value below 1 each return `400`.
`401`	The API key is missing, wrong or revoked.	Send a valid key in the `x-api-key` header.
`404`	The provider does not know the model name.	Check the `model` value, or omit it to use the provider default.
`405`	The request used a method other than `POST`.	Send the request again with the `POST` method.
`429`	The request rate is over the limit. A rate limit at the provider also returns `429`.	Wait for the seconds in the `Retry-After` header, then send the request again.
`502`	The provider returned an empty or unreadable answer.	Send the request again. If the failure repeats, contact support.

A 400 response looks like this:

{
  "error": "'provider' is required (openai, anthropic, gemini, perplexity)"
}

A provider error holds the provider name. This is a 429 response for a provider rate limit:

{
  "error": "Rate limit exceeded. Please slow down and retry shortly.",
  "provider": "openai"
}

Frequently asked questions

Does the AI Enrich API need my own OpenAI or Anthropic key?

No. The AI Enrich API uses the RichAPI provider keys. Send only your RichAPI key in the x-api-key header.

Do more tokens make an AI Enrich call cost more credits?

No. An AI Enrich call costs 2 credits for every provider. The token fields in the response report usage only, and they never change the credit cost.

Which AI Enrich providers support web search?

All four providers support web search through the use_web_search parameter. Perplexity is the one provider that reads search_domain_filter and search_recency_filter, and it is the one provider that returns a citations array.

Why does the AI Enrich API ignore my output_schema?

Perplexity is the one provider that receives the output_schema object. For OpenAI, Anthropic and Gemini, set output_type to json and name the fields you want inside the prompt text.

What happens to a {{variable}} placeholder with no matching context key?

The raw {{key}} text stays in the prompt and reaches the model. The call still costs credits, so check the placeholder names against the context keys before you send a batch.

Is the AI Enrich API synchronous?

Yes. The AI Enrich API returns the generated content in the same response. No polling call and no webhook are needed.

Which model does the AI Enrich API use by default?

The AI Enrich API uses the provider default: gpt-4o-mini for OpenAI, claude-haiku-4-5-20251001 for Anthropic, gemini-2.0-flash for Gemini and sonar for Perplexity.

What does AI Enrich do?

Which endpoint does AI Enrich use?

Which providers and models does AI Enrich accept?

How to send an AI Enrich request

cURL

Python

Node.js

What parameters does AI Enrich accept?

How do {{variable}} placeholders and context work?

How do you force structured JSON output?

Which providers support web search?

What does AI Enrich return?

What does each AI Enrich response field mean?

Example: how do you classify a lead?

Example: how do you extract structured fields from raw text?

Example: how do you summarize a company description?

How much does AI Enrich cost?

What errors does AI Enrich return?

Frequently asked questions

Does the AI Enrich API need my own OpenAI or Anthropic key?

Do more tokens make an AI Enrich call cost more credits?

Which AI Enrich providers support web search?

Why does the AI Enrich API ignore my output_schema?

What happens to a {{variable}} placeholder with no matching context key?

Is the AI Enrich API synchronous?

Which model does the AI Enrich API use by default?

Related articles