canonical: https://jentic.com/apis/clarifai.com/clarifai-clarifai # 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 that runs pre-trained and custom AI models for image recognition, object detection, face detection, text classification, and embedding generation. This spec covers the v2 prediction surface - model inference, input management, semantic search, workflow execution, and concept management - scoped under a user_id and app_id pair so each request is namespaced to the right application. Authentication uses a Personal Access Token in the Authorization header. ## For AI agents Run AI predictions against Clarifai's pre-trained or custom vision and language models, manage the inputs and concepts in an app, and execute multi-step workflows. Useful for any agent that needs vision tagging, embedding generation, or content moderation. ## Scope Does not handle pixel-level image editing, video transcoding, or model training pipelines - use for prediction, input management, semantic search, and workflow execution against Clarifai-hosted models only. ## Capabilities - Run a prediction against a Clarifai model and receive concept tags, bounding boxes, or embeddings - Pin a prediction to a specific model version for reproducible outputs - Add, list, and remove inputs (images, video, text) within a Clarifai app - Run semantic search over indexed inputs to find visually or conceptually similar items - Execute a multi-model workflow against a single input in one call - Manage the concept taxonomy of an app - list and add concepts used as labels ## Use cases ### Image moderation pipeline for user-generated content A marketplace runs every uploaded photo through a Clarifai moderation model by calling POST /users/{user_id}/apps/{app_id}/models/{model_id}/outputs with the image URL. Predictions returning unsafe concepts are routed to a human review queue, while clean inputs are added to the app's index via POST /users/{user_id}/apps/{app_id}/inputs for later semantic search. Example prompt: POST a moderation prediction for a new upload, and if any unsafe concept exceeds 0.8, queue the asset for review ### Visual search for product catalogues An ecommerce team indexes the product catalogue as Clarifai inputs, then exposes a 'shop the look' feature backed by POST /users/{user_id}/apps/{app_id}/searches. The search request takes a sample image and returns visually similar items from the indexed corpus. Pinning predictions to a specific model version keeps embeddings consistent across reindexes. Example prompt: Index 1,000 product images as Clarifai inputs, then search the index with a customer-uploaded photo and return top 10 matches ### Custom workflow for multi-step tagging Teams that need more than a single model output build a Clarifai workflow that chains general tagging, brand detection, and demographic estimation, then run it with POST /users/{user_id}/apps/{app_id}/workflows/{workflow_id}/results. One API call returns the combined output, which simplifies the calling agent's parsing and reduces network round-trips. Example prompt: Run a workflow that tags an image, detects brand logos, and estimates demographics, then return the merged output ### Agent integration via Jentic Through Jentic, an agent can resolve intents like 'tag this image with general concepts' to the right Clarifai prediction endpoint, including the user_id, app_id, and model_id path parameters that scope the request. The PAT is stored in the Jentic credential vault and only injected at execution time. Example prompt: Search Jentic for 'predict concepts in an image', load the schema for the prediction endpoint, and execute it with the supplied image URL ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | /users/{user_id}/apps/{app_id}/models/{model_id}/outputs | Run a prediction against a model | | POST | /users/{user_id}/apps/{app_id}/inputs | Add inputs to the app | | GET | /users/{user_id}/apps/{app_id}/inputs | List inputs | | POST | /users/{user_id}/apps/{app_id}/searches | Search inputs | | GET | /users/{user_id}/apps/{app_id}/models | List models | | POST | /users/{user_id}/apps/{app_id}/workflows/{workflow_id}/results | Run a workflow | | GET | /users/{user_id}/apps/{app_id}/concepts | List concepts | | POST | /users/{user_id}/apps/{app_id}/concepts | Add concepts | ## Key resources - **Predict** — Run model and model-version inference and receive predicted outputs - **Inputs** — Add, list, get, and delete inputs (images, video, text) within an app - **Models** — List, get, and delete models available to the app - **Search** — Semantic search across indexed inputs - **Workflows** — List and run multi-model workflows - **Concepts** — List and add the concept taxonomy used for labelling ## 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/{user_id}/apps/{app_id}/...), so a rule can pin your agent to one app for prediction and search. You choose the operations it may call, so adding concepts or running workflows 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 'predict concepts for an image' or 'search inputs in an app', 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-api variant)** — The sibling Clarifai spec covering the same REST surface with a slightly different base URL and parameter naming. - **Claid.ai Image Editing API** — Claid edits and reformats the images that Clarifai then classifies or indexes. - **Civic Auth API** — Civic Auth verifies the user identity that owns the assets being submitted to Clarifai. ## FAQ ### Why is there no official OpenAPI spec for this Clarifai API variant? 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 sent in the Authorization header with the format 'Key YOUR_PAT_HERE'. PATs are issued from https://clarifai.com/settings/security. Through Jentic, the PAT is stored encrypted in the credential vault and injected at execution time. ### Can I run predictions against my own custom Clarifai models? Yes. The prediction endpoint at /users/{user_id}/apps/{app_id}/models/{model_id}/outputs takes whichever model_id you target, including custom models trained in your app. To pin output stability, point to a specific version with /models/{model_id}/versions/{model_version_id}/outputs. ### How do I run a Clarifai prediction through Jentic? Search Jentic for 'predict concepts in an image'. Jentic returns POST /users/{user_id}/apps/{app_id}/models/{model_id}/outputs with its input schema. Load the schema, supply user_id, app_id, model_id, and the image data, and execute - the SDK handles the PAT header for you. ### What is the difference between this spec and the clarifai-api spec under the same vendor? Both specs cover the Clarifai REST surface; this 'clarifai' spec uses a base URL with the /v2 prefix already applied and slightly different path parameter casing (user_id vs userId). Pick whichever matches the codebase you are integrating from - both are kept in the catalogue for compatibility with existing integrations. ### Does the search endpoint do semantic similarity? Yes. POST /users/{user_id}/apps/{app_id}/searches performs semantic search over inputs that have been indexed in the app, returning items ranked by similarity to the query input. It is the standard primitive for visual search, deduplication, and 'similar items' features. ### Can I limit what my agent is allowed to do with the Clarifai API? Yes. Because you run Jentic One yourself, your own rules decide which Clarifai operations and credentials the agent can use. Clarifai puts the user and app id in the URL path (/users/{user_id}/apps/{app_id}/...), so you can pin the agent to a single app and allow only read-style calls like running predictions and searching indexed inputs. Write operations such as adding concepts or running workflows stay off limits unless you explicitly grant them, and your stored API key is injected only at execution time.