Core Concepts
Understand the mental model behind WhizAI and how everything fits together.
App
An App represents your application or service that uses WhizAI. Each app is:
- Isolated from other apps (data and usage are separate)
- Owned by an organization
- Can have multiple API keys with different scopes
- Can have multiple workflows defined
When you need to care:
When creating API keys, defining workflows, or viewing usage metrics. Each app has its own namespace.
When you don't:
For simple API calls - just use your API key. The app context is handled automatically.
Capability
A Capability is an AI-powered service you can enable and consume. WhizAI provides:
- Generation - Generate text and images from prompts
- Search - Semantic and hybrid search across your content
- Recommendations - Personalized recommendations for users
- Moderation - Content safety and policy enforcement
- Enrichment - Analyze and enhance content with AI
When you need to care:
When choosing which API endpoint to call for your use case. Each capability has its own endpoint and parameters.
When you don't:
You don't need to configure capabilities - they're always available. Just call the API.
Workflow
A Workflow is a multi-step AI orchestration that chains multiple capabilities together. Workflows are:
- Defined as JSON configurations with steps
- Versioned per app (you can have multiple versions)
- Executed asynchronously via Kafka-based workers
- Tracked with full execution history
When you need to care:
When you need to chain multiple AI operations (e.g., generate → enrich → moderate → store). Workflows handle complex orchestration automatically.
When you don't:
For simple, single-step operations, use direct API calls. Workflows are for advanced use cases.
Run
A Run is a single execution instance of a workflow. Each run:
- Has a unique ID you can track
- Maintains execution state (pending, running, completed, failed)
- Stores input, context, and results
- Can be polled for status or tracked via webhooks
When you need to care:
When executing workflows. You'll get a run ID immediately and can poll for completion or set up webhooks.
When you don't:
For synchronous API calls (like direct generation), you get results immediately - no run tracking needed.
Model
A Model is an AI model from a provider (OpenAI, Anthropic, etc.). WhizAI:
- Routes requests to the best model automatically
- Handles failover if a model is unavailable
- Optimizes for cost and latency
- Supports multiple providers and models
When you need to care:
When you want to specify a particular model or provider. Most of the time, automatic routing is best.
When you don't:
For most use cases, let WhizAI choose the best model. You can always override if needed.
Data Source / Collection
A Data Source or Collection is where your content lives for search and recommendations:
- Ingested via the
/v1/ingestor/v1/datasetsendpoints - Indexed for semantic search
- Used for recommendations and similarity search
- Isolated per project/app
When you need to care:
When you want to enable search or recommendations. You need to ingest your content first.
When you don't:
For generation and moderation, you don't need data sources - just call the API.
Usage & Cost
Usage is tracked for every API call and workflow execution:
- API calls are metered per endpoint
- Tokens are tracked for generation calls
- Workflow runs are counted
- File storage is measured
- All usage is visible in your dashboard
When you need to care:
When monitoring costs or setting budgets. Check the Usage & Cost page in your dashboard.
When you don't:
Usage tracking is automatic - you don't need to do anything. Just use the APIs.
Ready to Build?
Now that you understand the core concepts, explore the capabilities and start building.