canonical: https://jentic.com/apis/clarifai.com/clarifai-api

# Clarifai API

Jentic publishes the only available OpenAPI specification for this Clarifai API variant, keeping it validated and agent-ready. Clarifai is a computer vision and NLP platform offering pre-trained and custom models for image classification, object detection, text analysis, and embedding generation. This spec covers the v2 REST surface with the /v2 prefix on every path and camelCase path parameters (userId, appId, modelId), making it convenient for clients generated from this OpenAPI document. Authentication uses a Personal Access Token or API Key sent as 'Key {value}' in the Authorization header.

## For AI agents

Run AI predictions against Clarifai vision and NLP models, manage inputs and concepts within an app, and execute multi-model workflows. Useful for any agent that needs image tagging, embeddings, or content moderation.

## Scope

Does not handle pixel-level image editing, video transcoding, or large-scale model training pipelines - use for prediction, input management, semantic search, workflow execution, and concept management against Clarifai-hosted models only.

## Capabilities

- Run a prediction against a Clarifai model and receive concept tags, regions, or embeddings
- Pin a prediction to a specific model version for reproducible outputs
- Create, list, get, and delete custom models within a Clarifai app
- Add and manage inputs (images, video, text) used for indexing or training
- Run semantic search over indexed inputs to find similar items
- Execute a multi-model workflow against a single input in one call
- Manage the concept taxonomy used to label inputs and predictions

## Use cases

### Custom model lifecycle for visual quality inspection

A manufacturer trains a custom Clarifai model on examples of acceptable and defective parts, then calls POST /v2/users/{userId}/apps/{appId}/models to register the model and POST /v2/users/{userId}/apps/{appId}/models/{modelId}/outputs to run inference on each part photographed on the line. Versions can be deleted via DELETE on the model id when retired.

Example prompt: Create a custom model with the 'good' and 'defective' concepts, then run prediction on a new line photo and return the top concept

### Content tagging and embedding for a media library

A media team uploads assets via POST /v2/users/{userId}/apps/{appId}/inputs and runs the general embedding model to tag each one. The embeddings power downstream semantic search through POST /v2/users/{userId}/apps/{appId}/searches. The team can list inputs and remove ones that should not be indexed via the matching DELETE endpoint.

Example prompt: Add 200 media assets as inputs, run general embeddings, and search for the top 5 nearest neighbours of a sample asset

### Concept taxonomy management

Teams maintain a concept taxonomy that drives both labelling and prediction outputs. POST /v2/users/{userId}/apps/{appId}/concepts adds new concepts, GET lists the current taxonomy. Keeping the taxonomy explicit lets the application code rely on a stable label vocabulary rather than free-text tags.

Example prompt: Add three new concepts ('outdoor-furniture', 'indoor-furniture', 'lighting') to the app and verify they appear in GET /v2/users/{userId}/apps/{appId}/concepts

### Agent integration via Jentic

Through Jentic, an agent can resolve intents like 'classify this image' or 'find similar inputs' to the right Clarifai endpoint, including the userId, appId, and modelId path parameters. The PAT or API key lives in the Jentic credential vault and is attached to the Authorization header only at execution time.

Example prompt: Search Jentic for 'run a Clarifai prediction', load the schema for POST /v2/users/{userId}/apps/{appId}/models/{modelId}/outputs, and execute it with the supplied image

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /v2/users/{userId}/apps/{appId}/models/{modelId}/outputs | Run a prediction |
| POST | /v2/users/{userId}/apps/{appId}/models | Create a model |
| GET | /v2/users/{userId}/apps/{appId}/models | List models |
| POST | /v2/users/{userId}/apps/{appId}/inputs | Add inputs |
| GET | /v2/users/{userId}/apps/{appId}/inputs | List inputs |
| POST | /v2/users/{userId}/apps/{appId}/searches | Search inputs |
| POST | /v2/users/{userId}/apps/{appId}/workflows/{workflowId}/results | Run a workflow |
| POST | /v2/users/{userId}/apps/{appId}/concepts | Create concepts |

## Key resources

- **Predictions** — Run inference against Clarifai models and specific versions
- **Models** — List, create, get, and delete models in an app
- **Inputs** — Manage the inputs (images, video, text) indexed by an app
- **Concepts** — Manage the labelling taxonomy of an app
- **Search** — Semantic search across indexed inputs
- **Workflows** — Run multi-model workflows against an input

## Why Jentic

- **Setup:** Wiring the Clarifai API by hand means managing its API key and threading predictions, input management, search, and workflow runs through user- and app-scoped endpoints yourself. Through Jentic you install once, import the Clarifai API from the API Directory, store the API key once, and your agent calls it.
- **Permission scoping:** Clarifai puts the user and app id in the URL path (/users/{userId}/apps/{appId}/...), so a rule can pin your agent to one app for prediction and search. You choose the operations it may call, so creating models or concepts is not included unless you add it.
- **Credential handling:** Your Clarifai API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'run a model prediction' or 'search inputs by concept', and Jentic returns the matching Clarifai operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Clarifai API (clarifai variant)** — The sibling Clarifai spec covering the same REST surface with a different base URL and snake_case parameters.
- **Claid.ai Image Editing API** — Claid handles pixel-level image edits that Clarifai then tags or indexes.
- **Civic Auth API** — Civic Auth verifies the identity behind a content upload pipeline.

## FAQ

### Why is there no official OpenAPI spec for the Clarifai API?

Clarifai publishes a gRPC-first reference and language SDKs rather than a maintained OpenAPI specification for the REST surface. Jentic generates and maintains this spec from the public REST documentation so AI agents and developers can call Clarifai through structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Clarifai API use?

Clarifai uses a Personal Access Token or API Key sent in the Authorization header in the format 'Key {your_pat_or_api_key}'. Through Jentic, the credential is stored encrypted in the credential vault and attached to outgoing requests only at execution time.

### Can I create custom models with this API?

Yes. POST /v2/users/{userId}/apps/{appId}/models registers a new model, and predictions against it are issued at /v2/users/{userId}/apps/{appId}/models/{modelId}/outputs. Versions of the model are addressable via the /versions/{versionId}/outputs sub-path for reproducibility.

### How do I run a workflow through Jentic?

Search Jentic for 'run a Clarifai workflow'. Jentic returns POST /v2/users/{userId}/apps/{appId}/workflows/{workflowId}/results with its input schema. Load the schema, supply userId, appId, workflowId, and the input data, and execute - the SDK handles the 'Key {pat}' Authorization header for you.

### What is the difference between this spec and the 'clarifai' spec under the same vendor?

Both specs cover the Clarifai REST surface. This 'clarifai-api' variant uses a root base URL and includes /v2 in every path, with camelCase path parameters (userId, appId). The sibling 'clarifai' spec bakes /v2 into the base URL and uses snake_case parameters. Pick whichever matches the casing your codebase already uses.

### Does this API support semantic search across my own inputs?

Yes. POST /v2/users/{userId}/apps/{appId}/searches accepts a query input and returns indexed inputs ranked by similarity. This is the standard primitive for visual search, near-duplicate detection, and 'find more like this' features once your inputs are indexed.

### Can I limit what my agent is allowed to do with the Clarifai API?

Yes. Because your Jentic One instance is self-hosted, your own rules decide which Clarifai operations and credentials the agent may use. Since Clarifai puts the user and app id in the path (/v2/users/{userId}/apps/{appId}/...), you can pin the agent to a single app and allow only read or prediction calls, such as running a model at /models/{modelId}/outputs or searching indexed inputs at /searches. Write operations like creating models or adding concepts stay off limits unless you explicitly permit them.