Core Concepts
Five concepts cover everything you need to build with WhizAI. Start here.
App
An App is your tenant boundary inside WhizAI. Every resource — API keys, runs, artifacts — is scoped to an app and isolated from all other apps.
- Owned by an organization; one org can have many apps
- Each app has its own API keys with configurable scopes
- Usage, billing, and data are tracked and isolated per app
When you need to care:
When creating API keys or reviewing usage. Your API key already carries app context — you do not need to pass an app ID on every request.
Capability
A Capability is the stable, versioned operation you call to get a result. Capabilities are the public contract — their slug and input/output shape are guaranteed across platform releases.
- Called via
POST /v1/capabilities/:id/executeorclient.capabilities.run(slug, input) - Each capability declares the input schema it expects and the artifact type it produces
- Regular API keys are capabilities-only — they cannot call internal workflow endpoints directly
Under the hood:
Capabilities run on an internal workflow engine — you never call workflows directly, and regular API keys are capabilities-only. The engine handles orchestration, retries, and provider routing invisibly.
Examples:
video.generate, image.upscale, content.enrich, search.semantic
Run
A Run is one execution of a capability. Calling a capability returns a run ID immediately; the run completes asynchronously and produces one or more artifacts.
- Track status with
client.runs.get(runId)orGET /v1/workflow-runs/:id - States:
pending→running→completed|failed - Full input, context, and result are stored for inspection and replay
- Poll for status or receive completion via webhook
Typical flow:
Execute a capability → receive runId → poll or subscribe → fetch artifact when complete.
Artifact
An Artifact is the produced asset from a run — an image, video, structured data file, or any other output. Artifacts are persistent, reusable, and traceable back to the run that created them.
- Fetch with
client.artifacts.get(artifactId)orGET /v1/artifacts/:id - Every artifact carries provenance: which run, which step, which input produced it
- Artifacts can serve as input to future capability calls — compound your results over time
- Scoped to your app; never visible across tenant boundaries
Reuse pattern:
Pass an existing artifactId as input to a new capability call to refine, transform, or publish that asset without re-generating it from scratch.
Trigger
A Trigger automates capability execution in response to an event, schedule, or webhook — no polling code required on your side.
- Manage triggers with
client.triggers - Types: scheduled (cron), event-driven (webhook), and data-arrival
- Each trigger maps an event to a capability call with a fixed input template
- Runs created by triggers appear alongside manual runs — same status, same artifacts
Example:
A trigger fires content.enrich every time new content is ingested, automatically producing enriched artifacts without a human in the loop.
Ready to Build?
Now that you understand the five core concepts, explore the available capabilities and make your first API call.