Developer Documentation

Build with the Cultural Intelligence Layer

Simple integration, comprehensive data. Get started in minutes with our developer-first API documentation.

How kultur.dev Works

Your App

kultur.dev API

Cultural Intelligence
Engine

Response

Simple REST API • 99.9% Uptime • 195 Countries Supported

Introduction

kultur.dev is the Cultural Intelligence API that helps businesses go global without cultural missteps. Our AI analyzes, adapts, and generates content that resonates with local audiences across 195 countries.

What You Can Do

Analyze content for cultural risks
Query cultural norms & practices
Rewrite content for local markets
Generate culturally-aware content
Create PDF cultural reports

Use Cases

Marketing localization
Content moderation
International expansion
Cross-cultural communication
Brand safety screening

Quick Start

Get up and running with kultur.dev in under 5 minutes.

Create Your Account

Create Free Account

Get Your API Key

After signing up, find your API key in the Dashboard. Keep it secure!

Authorization: Bearer ck_your_api_key_here

Make Your First API Call

Query our cultural intelligence knowledge base:

python

import requests

response = requests.post(
    "https://kultur.dev/api/v1/query",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "query": "What are the business gift-giving customs in Japan?",
        "target_markets": ["JP"]
    }
)

result = response.json()
print(result['response'])

Explore the Playground

Test all endpoints interactively without writing any code.

Open API Playground

Authentication

All API requests must include your API key in the Authorization header using Bearer token authentication:

Authorization: Bearer YOUR_API_KEY

Security Best Practice

Never expose your API key in client-side code. Always make API calls from your backend server.

Key Management

You can regenerate your API key anytime from the Dashboard. Old keys are immediately revoked.

How It Works

Submit Content

Send your content along with target markets and industry context to our API.

AI Analysis

Our AI cross-references your content against our knowledge base of 195 countries.

Get Insights

Receive detailed findings, risk scores, and actionable suggestions for improvement.

Cultural Intelligence

Our knowledge base covers comprehensive cultural data including:

Business Etiquette

Meeting protocols, negotiation styles, gift-giving customs

Communication

Direct vs indirect communication, formality levels, taboo topics

Values & Beliefs

Religious considerations, cultural values, social norms

Marketing & Branding

Color meanings, imagery sensitivities, messaging tone

Holidays & Observances

National holidays, religious observances, cultural events

Legal & Compliance

Advertising regulations, content restrictions, local laws

Target Markets

Specify target markets using ISO 3166-1 alpha-2 country codes. The number of markets you can analyze per request depends on your plan:

Free

Up to 3

markets per request

Pro

Up to 10

markets per request

Enterprise

Unlimited

all 195 countries

Example country codes:

US, GB, DE, FR, JP, CN, IN, BR, AU, KR, MX, SA, AE, SG, ZA

API Reference

POST/api/v1/analyze/text1 creditsAll tiers

Analyze Content

Analyze text content for cultural risks, sensitivities, and appropriateness across target markets. Returns detailed findings with severity scores and actionable suggestions. Also available at /api/v1/analyze.

Request Body

contentstringrequired

The text content to analyze (max 10,000 characters)

target_marketsstring[]

ISO 3166-1 alpha-2 country codes (e.g., ["JP", "DE", "CN"])

industrystring

Industry context (e.g., "technology", "finance", "healthcare")

min_severitynumber

Minimum severity threshold 0.0-1.0 (default: 0.0)

brand_voiceobject

Brand voice parameters (Enterprise only)

Response

request_idstring

Unique identifier for this request

content_analyzedstring

The content that was analyzed (truncated if long)

overall_risk_scorenumber

Overall risk score from 0.0 (safe) to 1.0 (high risk)

markets_clearedstring[]

Markets where content passed analysis

findingsarray

List of cultural issues found with severity, confidence, market, category, issue, and suggestion

universal_flagsstring[]

Flags that apply across all markets

processing_time_msnumber

Processing time in milliseconds

credits_usednumber

Number of credits consumed

credits_remainingnumber

Credits remaining after this request

POST/api/v1/query1 creditsAll tiers

Query Knowledge Base

Ask questions about cultural norms, business practices, and local customs. Powered by our comprehensive knowledge base covering 195 countries.

Request Body

querystringrequired

Your cultural intelligence question (max 500 characters)

target_marketsstring[]

ISO country codes to focus the response on

industrystring

Industry context for more relevant answers

Response

request_idstring

Unique identifier for this request

querystring

The original query

responsestring

Detailed cultural intelligence answer

confidence_scorenumber

Confidence in the response (0.0-1.0)

sources_usedstring[]

Knowledge sources referenced

credits_usednumber

Number of credits consumed

POST/api/v1/rewrite1 creditsAll tiers

Rewrite Content

Transform content to be culturally appropriate for specific markets while maintaining your message. Supports multiple tone options.

Request Body

contentstringrequired

Content to rewrite (max 5,000 characters)

tonestringrequired

Target tone: formal, humble, celebratory, respectful, casual

target_marketsstring[]

Markets to optimize for

industrystring

Industry context

brand_voiceobject

Brand voice parameters (Enterprise only)

Response

request_idstring

Unique identifier for this request

original_contentstring

The original content (truncated)

rewritten_contentstring

Culturally-adapted content

tone_appliedstring

The tone that was applied

markets_optimizedstring[]

Markets the content was optimized for

credits_usednumber

Number of credits consumed

POST/api/v1/generate1 creditsAll tiers

Generate Content

Generate new culturally-aware content from scratch. Perfect for creating localized marketing copy, emails, and communications. Note: This endpoint uses "prompt" as the input field (not "content" like other endpoints).

Request Body

promptstringrequired

What to generate (max 1,000 characters). Note: Use "prompt" not "content" for this endpoint.

target_marketsstring[]

Markets to generate content for

industrystring

Industry context

brand_voiceobject

Brand voice parameters (Enterprise only)

Response

request_idstring

Unique identifier for this request

promptstring

The original prompt

generated_contentstring

The generated culturally-aware content

markets_targetedstring[]

Markets the content was generated for

credits_usednumber

Number of credits consumed

POST/api/v1/analyze/image5 creditsAll tiers

Image Analysis

Analyze images for cultural risks across target markets using GPT-4 Vision. Detects gestures, symbols, colors, dress code, food/dining context, and social context. Also available at /api/v1/image.

Request Body

image_urlstring

URL of the image to analyze. Provide either image_url or image_base64.

image_base64string

Base64-encoded image data. Provide either image_url or image_base64.

target_marketsstring[]

ISO country codes (default: ["US","UK","DE","JP","CN","SA","IN","BR"])

include_knowledgeboolean

Include related knowledge base entries in response (default: true)

Response

content_typestring

"image"

overall_riskstring

Risk level: safe, low, medium, high, or critical

risk_scorenumber

Risk score from 0.0 (safe) to 1.0 (critical)

summarystring

Summary of the cultural analysis

issuesarray

Detected cultural issues with category, description, risk_level, affected_markets, recommendation, and confidence

safe_marketsstring[]

Markets where the image is culturally safe

risky_marketsstring[]

Markets where cultural issues were detected

recommendationsstring[]

Actionable recommendations

processing_time_msnumber

Processing time in milliseconds

credits_usednumber

Number of credits consumed (5)

credits_remainingnumber

Credits remaining after this request

POST/api/v1/analyze/video20 creditsAll tiers

Video Analysis

Analyze videos for cultural appropriateness. Extracts key frames and analyzes each for potential cultural issues, aggregating findings into a comprehensive report. Also available at /api/v1/video.

Request Body

video_urlstring

URL of the video to analyze. Provide either video_url or video_base64.

video_base64string

Base64-encoded video data. Provide either video_url or video_base64.

target_marketsstring[]

ISO country codes (default: ["US","UK","DE","JP","CN","SA","IN","BR"])

num_framesnumber

Number of frames to analyze, 1-10 (default: 5)

include_knowledgeboolean

Include related knowledge base entries (default: true)

Response

content_typestring

"video"

overall_riskstring

Risk level: safe, low, medium, high, or critical

risk_scorenumber

Risk score from 0.0 (safe) to 1.0 (critical)

summarystring

Summary of the cultural analysis

issuesarray

Detected cultural issues across all frames

safe_marketsstring[]

Markets where the video is culturally safe

risky_marketsstring[]

Markets where cultural issues were detected

recommendationsstring[]

Actionable recommendations

frame_countnumber

Number of frames analyzed

processing_time_msnumber

Processing time in milliseconds

credits_usednumber

Number of credits consumed (20)

credits_remainingnumber

Credits remaining after this request

POST/api/v1/reports/generate50 creditsPro & Enterprise

PDF Reports

Generate comprehensive PDF reports for cultural analysis. Single Market Deep Dive (Pro+) or Cross-Market Comparison (Enterprise).

Request Body

report_typestringrequired

single_market or cross_market (Enterprise only)

contentstringrequired

Content to analyze (max 10,000 characters)

country_codesstring[]required

ISO country codes (1 for single, 2-10 for cross-market)

industrystring

Industry context

customer_namestring

Customer name for report header

company_logo_urlstring

Logo URL for white-label (Enterprise only)

Response

PDF Filebinary

The generated PDF report as binary data

X-Report-IDheader

Unique report identifier in response header

X-Credits-Usedheader

Credits consumed in response header

WebSocket/api/v1/streaming/analyze5 creditsPro & Enterprise

Real-time Streaming

Analyze video frames in real-time via WebSocket connection. Ideal for live video feeds, video conferencing content moderation, or real-time broadcast analysis. Supports up to 2 frames per second.

Connection Parameters

api_keyqueryrequired

Your API key for authentication

target_marketsqueryrequired

Comma-separated market codes (e.g., "US,JP,DE")

sensitivityquery

Analysis sensitivity: low, standard (default), high

Client → Server Messages

type: "frame"

Send a video frame for analysis. Include "data" field with base64-encoded image

type: "ping"

Keepalive ping (server responds with "pong")

type: "stop"

Gracefully end the streaming session

Server Messages

type: "connected"

Connection established with session_id and config

type: "analysis_result"

Analysis results for a processed frame

type: "status"

Periodic status updates (every 10 frames)

type: "error"

Error message with code and details

POST/api/v1/audio/analyze5 creditsAll tiers

Audio Analysis

Transcribe audio files and analyze spoken content for cultural sensitivities. Uses OpenAI Whisper for transcription, then runs cultural analysis on the transcript. Supports MP3, WAV, M4A, OGG, FLAC, and WEBM formats up to 25MB.

Request Body

filefile (multipart)required

Audio file to analyze. Supported: MP3, WAV, M4A, OGG, FLAC, WEBM. Max 25MB.

target_marketsstring

Comma-separated ISO country codes (e.g., "US,JP,DE"). Default: US

Response

analysis_idstring

Unique identifier for this analysis

transcriptstring

Full text transcription of the audio

language_detectedstring

Detected language of the audio (ISO code)

duration_secondsnumber

Duration of the audio file in seconds

cultural_analysisobject

Cultural analysis results: overall_risk_score, risk_level, summary, issues, recommendations, market_specific_notes

target_marketsstring[]

Markets analyzed

credits_usednumber

Number of credits consumed (5)

analyzed_atstring

ISO timestamp of analysis

POST/api/v1/feedback/submit0 creditsAll tiers

Submit Feedback

Submit feedback on an API response to improve the cultural intelligence engine. Low-rated corrections (1-2) with detailed text are automatically incorporated into the knowledge base, making future responses more accurate.

Request Body

endpointstringrequired

Which endpoint: analyze, query, rewrite, generate, image, video, audio

ratinginteger (1-5)required

1=wrong, 2=poor, 3=acceptable, 4=good, 5=excellent

request_idstring

The request_id from the original API response

correctionstring

The correct information if the response was wrong (50+ chars for auto-enrichment)

contextstring

The original query/content that was analyzed

target_marketsstring[]

Markets the feedback applies to

categorystring

Category: color, gesture, number, language, religion, etiquette, legal, other

commentstring

Additional context or explanation

Response

feedback_idstring

Unique feedback identifier

statusstring

pending_review or accepted_and_enriched

messagestring

Confirmation message

GET/api/v1/feedback/stats0 creditsAll tiers

Feedback Stats

Get your feedback submission statistics including total count, status breakdown, and average rating.

Request Body

Response

total_feedbacknumber

Total feedback submissions

by_statusobject

Count by status (pending_review, accepted_and_enriched)

average_ratingnumber

Average rating across all submissions

Best Practices

Be Specific with Markets

Always specify target markets for more accurate and relevant analysis. Generic global analysis is less actionable.

Include Industry Context

Different industries have different cultural sensitivities. A joke that works in gaming might fail in finance.

Use Streaming for Long Queries

For complex questions, use /query/stream to get faster perceived response times.

Cache Responses

For frequently analyzed content, cache our responses to save credits and improve performance.

Handle Errors Gracefully

Implement retry logic with exponential backoff for rate limits (429) and server errors (5xx).

Review Before Publishing

Use our API for screening, but always have human review for high-stakes content.

Error Handling

All errors return a JSON body with an error code and message:

Status	Error	Description
`400`	`bad_request`	Invalid request body or parameters
`401`	`unauthorized`	Missing or invalid API key
`402`	`insufficient_credits`	Not enough credits for this operation
`403`	`feature_not_available`	Feature requires a higher tier plan
`429`	`rate_limited`	Too many requests, slow down
`500`	`internal_error`	Server error, please retry

Rate Limits

Free

requests/minute

Pro

100

requests/minute

Enterprise

1,000

requests/minute

Tip: Rate limit headers are included in every response: X-RateLimit-Remaining and X-RateLimit-Reset

API Keys

Managing Your Keys

Access your API keys in the Dashboard. You can view your key prefix, regenerate keys, and monitor usage.

Key Format

API keys start with ck_ followed by a random string:

ck_FZHWsSf9vAGGlm-u3pOstAsXE-Tic8hYWfN0V_URwYw

Regenerating Keys

If you believe your key has been compromised, regenerate it immediately from the Dashboard. The old key will be revoked instantly.

Frequently Asked Questions

kultur.dev is a Cultural Intelligence API that helps businesses analyze, adapt, and generate content for global markets. Our AI-powered platform understands cultural nuances across 195 countries, helping you avoid costly mistakes and create content that resonates locally.

Still have questions?

Our team is here to help you succeed with cultural intelligence.

Contact Support Try the Playground