Roboflow

Request cancellation of a queued or running Run. Idempotent.

workflow_evals_runs_cancel

Replace a Dataset's declared input and/or ground-truth contract. A schema-only change returns the updated Dataset. A change that rewrites Cases returns 202 with an AsyncTask (poll with async_tasks_get); Case writes are rejected until it completes.

workflow_evals_datasets_update_contract

Chat with the Roboflow AI agent. Use this tool for: - **Roboflow Q&A** — the agent has the full Roboflow documentation indexed (SDKs, REST API, deployment options, training, batch processing, Universe, blocks, pricing, etc.). Ask it anything about how Roboflow works. - **Advanced workflow building** — workflows complex enough that composing the JSON yourself is impractical. The agent knows every block and connection pattern. - **Solution planning** — pass ``mode="plan"`` and the user's problem; the agent uses a stronger planning model to scope a CV solution end-to-end before any building happens. For straightforward workflows you can construct yourself, the direct ``workflow_*`` tools are fine — you don't have to route every workflow through the agent. ## Conversation flow The agent runs a multi-step conversation. It may ask clarifying questions, recommend a model, or (in plan mode) produce a plan for confirmation. Pass the returned ``conversation_id`` back on follow-up calls to keep context. Use ``agent_conversations_list`` and ``agent_conversation_get`` to find and resume past conversations. ## Long runs Complex turns (large workflow builds/edits) can take several minutes. When the agent does not finish quickly, this tool returns ``{"status": "running", "run_id": ...}`` instead of blocking. Call ``agent_chat_result`` with that ``run_id`` repeatedly until the status is no longer ``running``; the run keeps executing server-side in the meantime. Do NOT re-send the same message with agent_chat, that would start a second, duplicate run. ## What the agent changes in the workspace The agent never runs a workflow or model inference; it only validates the workflows it writes. - A **new** workflow is saved and immediately runnable by its URL slug. - An **edit** to an existing workflow is saved as a **draft**. The published version that callers using the workflow by id hit is unchanged until the user publishes it with ``agent_workflow_publish`` (pass the workflow ``url`` returned in the chat response). ``mode="plan"`` only reads and plans; it changes no workflow. ## Running an agent-built workflow Run a saved workflow with ``workflows_run(workflow_id=..., images=...)``. It always runs the published version, so publish an edit first when the user has authorized it. If execution fails, follow the specific permission or upstream error; do not assume OAuth is unsupported. If the user prefers visual testing, open the workflow's ``app_url``. ## Where to open a workflow in the Roboflow UI Each workflow in the ``workflows`` array has an ``app_url`` field with the canonical, environment-aware Roboflow UI URL. ``app_url`` is the authoritative link for a workflow; URLs embedded in the agent's ``text`` reply may not match the current environment. ## Response shape When the run finishes within the inline wait: - ``status`` — ``"completed"``. - ``text`` — the agent's reply. - ``workflows`` — workflows created or edited in this turn, each with ``id``, ``name``, ``url`` (slug), ``app_url`` (clickable Roboflow UI URL — use this), and ``specification`` (the full JSON of the saved version or draft). - ``conversation_id`` — pass back to continue the conversation. When the run is still going: ``status`` is ``"running"`` and ``run_id`` is the handle to pass to ``agent_chat_result``.

agent_chat

Compare models trained on or uploaded to one dataset version. Returns the project, version, selected frontier metric, available metrics, and one compact record per model. Each record includes evaluation metrics, median latency, exclusion reason, and server-computed frontier membership. Frontier membership indicates a speed/accuracy tradeoff, not a model recommendation or selection. This tool is read-only and starts no jobs.

model_evals_compare

Compare completed Executions: per-Check deltas and a page of Case-level deltas. Pure read; sibling Executions from one Run are always comparable.

workflow_evals_results_compare

Verify and publish an uploaded Case image. Returns the stable ``artifactId``. Checks size, type, and that the bytes decode as an image. Call only after the PUT to the signed URL succeeded.

workflow_evals_case_assets_upload_complete

Configure how a Project Deployment collects Active Learning data.

project_deployment_configure_active_learning

Connect a cloud bucket end to end in one call: reuse or create a credential, create the datasource, validate it, and start the first mirror run. A run can overwrite imported images or metadata and remove mirrored images whose source disappeared. Alternative: to only run a model/Workflow over the files and get results out, WITHOUT importing them into Roboflow, use batch processing instead (start with batch_processing_guide). Mirroring also composes with it: imported files become Asset Library images, and bulk predictions over them run as Asset Library jobs (batch_processing_asset_library_job_create). Drive the conversation in this order, and do NOT bring up credentials until the bucket is settled: 1. Pick the bucket FIRST. Ask the user which bucket to connect, confirm its region, and settle which objects to mirror (mirror_configs). Don't mention credentials yet. 2. Credential, only after the bucket is chosen. Prefer reusing one the user already has (check credentials_list and pass its credential_id). Only if none fits, create a new one dedicated to Roboflow by passing credential_name + credential_type. Secrets are never entered in chat: creating a new credential returns manual_entry_required with a url to the Roboflow app, a docs_url, and (for AWS) an aws_setup deep-link. A dedicated, least-privilege credential scoped to this bucket is recommended over reusing personal keys (IAM user with read-only or bucket-scoped access, or an IAM role that trusts Roboflow via AssumeRole). 3. Call this once with the bucket and credential to create, validate, and (when trigger is true) run it. AWS/S3 assisted setup: use the bucket and profile chosen by the user. Only query that account for details needed to configure the selected bucket. - Bucket: Ask the user which bucket to connect. Only inspect that bucket's object paths when the user asks for help choosing mirror rules; do not enumerate other profiles, buckets, or their contents. - Region: For AWS/S3, look up the chosen bucket's region with `aws s3api get-bucket-location --bucket <bucket-name> --profile <profile>` if the user wants assistance (`null`/`None` means us-east-1). Use the AWS profile the user selected. If it is unclear which profile to use, ask the user before querying their AWS account. These commands only read non-secret metadata for the selected account and bucket; never read ~/.aws/credentials or pass secret values yourself. - Credential: When a new AWS credential must be created, before handing off to the Roboflow form: resolve the AWS account for the profile in use with `aws sts get-caller-identity --profile <p>` (reads non-secret identity only), then give the user an account-scoped console deep-link so they land in the right account. Sign in at https://<accountId>.signin.aws.amazon.com/console, then for an IAM credential create an IAM user at https://console.aws.amazon.com/iam/home#/users/create, or for an AssumeRole credential create an IAM role at https://console.aws.amazon.com/iam/home#/roles/create (trusting the Roboflow principal from the prerequisites docs). Collect the resulting access keys (IAM) or role ARN (AssumeRole) and enter them in the Roboflow form. The mirror run only starts when trigger is true AND validation reports no errors; triggering consumes credits. Returns {credentialId, credentialCreated, datasourceId, validation, triggered, batchIds?}. If a new credential was created but a later step failed, a partial status is returned with the credentialId so it can be cleaned up with credentials_delete.

connect_cloud_storage

Create a new API key for the workspace. Who can create keys: a credential may create keys only if it is unscoped (full access) or holds the ``api-key:create`` scope; an OAuth token also needs the ``create_api_key`` permission. Default scope — read this carefully, it is a least-privilege footgun. Keys created in the dashboard may default to scoped (not full access), but that dashboard default does NOT apply here. When ``scopes`` is OMITTED, an API/MCP-created key INHERITS the calling credential's effective scopes — so if the caller is full access, an omitted ``scopes`` produces a FULL-ACCESS key (it comes back with ``scopes: null``). Always pass explicit least-privilege ``scopes`` whenever you can, rather than relying on the default. Scopes are stored as explicit leaf scopes — a section name or ``role:`` preset is expanded to its current leaves, so a key never auto-gains an ability added to that group later (add new scopes explicitly when needed). The secret ``key`` value is returned ONCE in the response and cannot be retrieved again. Store it immediately in a ``.gitignore``'d ``.env`` file (e.g. ``ROBOFLOW_API_KEY=rf_...``). Never echo it in logs, code comments, or tool output. Returns ``{ key_id, key, name, scopes, folder_ids, protected, publishable_key }``. ``key_id`` is the non-secret handle used in all subsequent management calls.

api_keys_create

Move selected images from one batch into a new batch.

annotation_batches_create

Create a job and move images from a batch into it.

annotation_jobs_create

Queue a durable Workflow run over an Asset Library selection. The platform owns selection authorization, entitlement and billing, workflow compatibility, staging, and job registration: it stages your selection into a Data Staging batch for you (for files you stage yourself, use ``batch_processing_run`` or ``batch_processing_staged_job_start``). The response is a 202 receipt: poll ``batch_processing_asset_library_task_get`` with its taskId until terminal, then use ``batch_processing_job_get`` with jobId.

batch_processing_asset_library_job_create

Create a datasource that mirrors a cloud bucket into your workspace. Returns the created datasource {id}. Nothing is mirrored until you call datasource_trigger (or a schedule fires). A run may overwrite imported images or metadata and remove mirrored images whose source disappears. Alternative: to only run a model/Workflow over the files and get results out, WITHOUT importing them into Roboflow, use batch processing instead (start with batch_processing_guide). Mirroring also composes with it: imported files become Asset Library images, and bulk predictions over them run as Asset Library jobs (batch_processing_asset_library_job_create). AWS/S3 assisted setup: use the bucket and profile chosen by the user. Only query that account for details needed to configure the selected bucket. - Bucket: Ask the user which bucket to connect. Only inspect that bucket's object paths when the user asks for help choosing mirror rules; do not enumerate other profiles, buckets, or their contents. - Region: For AWS/S3, look up the chosen bucket's region with `aws s3api get-bucket-location --bucket <bucket-name> --profile <profile>` if the user wants assistance (`null`/`None` means us-east-1). Use the AWS profile the user selected. If it is unclear which profile to use, ask the user before querying their AWS account. These commands only read non-secret metadata for the selected account and bucket; never read ~/.aws/credentials or pass secret values yourself. - Credential: When a new AWS credential must be created, before handing off to the Roboflow form: resolve the AWS account for the profile in use with `aws sts get-caller-identity --profile <p>` (reads non-secret identity only), then give the user an account-scoped console deep-link so they land in the right account. Sign in at https://<accountId>.signin.aws.amazon.com/console, then for an IAM credential create an IAM user at https://console.aws.amazon.com/iam/home#/users/create, or for an AssumeRole credential create an IAM role at https://console.aws.amazon.com/iam/home#/roles/create (trusting the Roboflow principal from the prerequisites docs). Collect the resulting access keys (IAM) or role ARN (AssumeRole) and enter them in the Roboflow form.

datasource_create

Provision a new v2 device. Requires the ``device:update`` scope. Returns ``{deviceId, installId, offlineProvisioningQrPayload?}``: ``installId`` is the short-lived token used by the device installer (``GET /devices/v2/:installId/install.sh``). ``offlineProvisioningQrPayload`` is only present for AI1 devices provisioned with ``offline_mode=true``.

devices_create

Create an empty Eval Dataset with declared input and ground-truth contracts. Add Cases with workflow_evals_cases_create or workflow_evals_cases_import. Adding Cases never changes the contracts; use workflow_evals_datasets_update_contract.

workflow_evals_datasets_create

Add one Case to an Eval Dataset, validated against the Dataset's contracts. A Run that selects an incomplete Case is rejected with ``EVAL_NOT_READY`` and the ``incompleteCaseIds``.

workflow_evals_cases_create

Create a new computer vision project, including Action Recognition. Action Recognition projects are video-only. Returns the created project's id, name, type, and url.

projects_create

Create a training on a dataset version. IMPORTANT: A dataset version must exist before training. Use the versions_generate tool first to create one with the desired preprocessing and augmentation settings. A modern (MMPV) version may own MANY trainings — concurrent and repeated runs are allowed. Legacy single-model-per-version (SMPV) versions already hold their one model and reject a second training with a 409; generate a fresh version to train more models. To inspect a version's trainings, use trainings_list; to monitor a specific run, use trainings_get with the returned training_id. For Action Recognition, pass model_type='cosmos3-edge'. Its video-coco export is prepared by this call. The returned trainingId identifies a background v2 run; poll trainings_get with it until the run finishes. A train_recipe is optional and is sent only when you supply one. MODEL CHOICE: for object detection and instance segmentation, prefer a NAS parent over a single named architecture: searching the architecture space against this dataset usually beats hand-tuning one. See the model_type description for ids and prerequisites. To customize hyperparameters or online augmentation, call trainings_describe_recipe FIRST, edit its ``template`` (set ``template["hyperparameters"]``; add augmentation steps as ``{name, params: {...}}`` dicts), and pass the whole dict as train_recipe. Recipe hyperparameters are sparse: keys you leave out keep their server-side defaults, which are the tuned values, so omitting a key is the right default, not a missed opportunity. Set a knob when you have a specific reason to move it, not to explore. Recipe training requires platform recipe access and an enabled runtime; trainings_describe_recipe reports their availability. COMPARING ARCHITECTURES: launch one trainings_create per candidate (MMPV versions allow many concurrent trainings) and keep each returned trainingId. Include a NAS parent as one of the candidates whenever its prerequisites are met, e.g. 'rfdetr-medium' vs 'yolo26m' vs 'rfdetr-nas-parent'. A NAS arm returns a frontier of models rather than one. Resolve it with trainings_list -> modelGroup -> models_list(group=<modelGroup>), whose docstring describes the per-child fields; use trainings_list rather than trainings_get, which inlines every child and defeats the paging. Which child represents that arm depends on the question being asked, and the obvious reading of the `recommended` flag is wrong - read the training-and-evaluation skill before comparing arms or deploying. This tool validates that the dataset version has finished generating and that the required export is ready before starting. If either is not ready the call fails with a 400 explaining what to poll and for how long: version generation can take up to about an hour on large datasets and reports 0 progress for most of it. Retry until it succeeds rather than giving up after one attempt. Training runs in the background on Roboflow servers.

trainings_create

Create a new vision-event use case. Use cases are the buckets that incoming events are grouped under. Returns ``{id, name}``; use the returned ``id`` as ``use_case_id`` when querying or ingesting events for this bucket.

vision_events_use_case_create

Create and save a new Workflow in the workspace. Do not invent the config. Start from a similar workflow (workflows_list, then workflows_get) and copy its shape; if one already fits, update it with workflows_update instead of creating a duplicate. Block types and their schemas are in the roboflow://workflows/blocks resources. Validate the config with workflow_specs_validate before saving. Validation and execution support OAuth and API-key connections with the required permissions. Once saved, execute the published workflow by URL slug with workflows_run. Saving does not test inference. Returns the created workflow including its document ID. Save this ID: it is required for workflows_update.

workflows_create

Create an Eval. Every field is optional; an empty call creates a draft. The Eval becomes ``ready`` once it has an engine-valid Spec and a compatible Eval Dataset; otherwise it stays ``draft`` with setup diagnostics. Returns the Eval detail including its ``revision`` (needed for workflow_evals_update).

workflow_evals_create

Validate, compile, and save a Spec. Invalid Specs return 422 with engine diagnostics. Draft the Spec yourself following the engine skills (start at roboflow://workflow-evals/manifest) and iterate with workflow_evals_specs_validate before saving. Confirm the Spec with the user first.

workflow_evals_specs_create

Get the recipe for uploading locally trained model weights to Roboflow. This tool never uploads anything. Weights packaging must run on the machine that has the checkpoint (it reads the weights file and needs torch), and this MCP server cannot read the user's filesystem. Calling it returns the client-side recipe: how to run the upload with the Roboflow Python SDK on the machine where the weights live. Pass whatever arguments you already know; the response names the matching upload mode and echoes them back for the SDK call. Do not infer the target project, version, or model name from the checkpoint; those come from the user.

models_custom_weights_upload_guide

Delete a batch. By default its images move to unassigned and remain accessible.

annotation_batches_delete

Delete the project's annotation data for every image assigned to a job.

annotation_jobs_delete_annotations

Delete a credential. Datasources still referencing it will fail to run.

credentials_delete

Delete a dataset version, moving it to the workspace Trash. This is a soft delete: the version stays in the Trash for 30 days and can be restored with ``trash_restore_version`` using the version's document id and ``parent_id`` set to the parent project's document id (both are in the delete response or ``trash_list``). After 30 days it is permanently removed.

versions_delete

Delete a datasource configuration. Does not delete already-mirrored images.

datasource_delete

Remove a Case from the live Dataset. Runs that already froze it stay readable.

workflow_evals_cases_delete

Delete a project, moving it to the workspace Trash. This is a soft delete: the project (including its versions, images, and models) stays in the Trash for 30 days and can be restored with ``trash_restore_project`` using the project's document id from the delete response or ``trash_list``. After 30 days it is permanently removed. Active trainings on the project are cancelled.

projects_delete

Delete a training run, moving it to the workspace Trash. This is a soft delete: the training stays in the Trash for 30 days and can be restored with ``trash_restore_training`` using the training id. After 30 days it is permanently removed. Deleting may repoint or remove the ``{project}/{version}`` serving alias; the response reports the alias action taken.

trainings_delete

Delete a saved Workflow, moving it to the workspace Trash. This is a soft delete: the workflow stays in the Trash for 30 days and can be restored with ``trash_restore_workflow`` using the workflow's document id from the delete response or ``trash_list``. After 30 days it is permanently removed.

workflows_delete

Delete an Eval with all its Runs, Executions, results, and owned artifacts. Two steps. First call without ``deletion_key``: nothing is deleted; returns ``{confirmationRequired: true, deletionKey, impact}``. Show the impact to the user and get explicit confirmation, then call again with ``deletion_key``. That admits deletion and returns ``{asyncTaskId, statusUrl}``; poll with workflow_evals_operation_get. Shared Specs and Datasets are kept.

workflow_evals_delete

Delete a Run with its Executions and results. Two steps. Without ``deletion_key`` nothing is deleted; returns ``{confirmationRequired: true, deletionKey, impact}``. After the user confirms, call again with the key; returns ``{asyncTaskId, statusUrl}``. Poll with workflow_evals_operation_get.

workflow_evals_runs_delete

Describe the tuning surface for a model type and get a ready-to-submit train recipe. Returns two things: - ``schema``: the valid tuning knobs for this model on this version, namely manifest hyperparameters with hard bounds (``valid``) and advisory ranges (``advice.low``/``advice.high``) for a deliberate, hypothesis-driven change. A descriptor's ``advice.default`` is the tuned value the server applies when you omit the key, so a sparse recipe is the good default; a descriptor with NO ``advice.default`` is one only the trainer can resolve (it derives the value from the dataset at train time), so leave those out unless you specifically intend to override the derivation. Also included: the task-supported online augmentation steps with their field contracts, the supported online preprocessing steps, and input/resolution rules. - ``template``: a ready-to-submit ``trainRecipe`` for this model type. Edit the knobs you want to change, then pass the whole dict as ``train_recipe`` to trainings_create. An unknown ``model_type`` fails with a 404 whose error body lists the valid model types for the project's task.

trainings_describe_recipe

Disable (or re-enable) an API key without revoking it. A disabled key is inactive and will be rejected by the platform until re-enabled. Protected keys cannot be disabled; disabling requires the Advanced API Keys plan feature, so the specific error returned depends on the workspace. A key that backs a dedicated deployment cannot be disabled from here either (the deployment would be paused): to rotate such a key use ``api_keys_roll``, which moves the deployment onto the replacement key. Returns the updated masked key metadata.

api_keys_disable

Pause Active Learning collection for a Project Deployment.

project_deployment_disable_active_learning

Enable Active Learning for a Project Deployment.

project_deployment_enable_active_learning

Check or trigger a dataset export for a version.

versions_export

Start a server-side export of a Run's results. Returns 202 with ``asyncTaskId``; poll workflow_evals_exports_get_job until it completes, then use its download URL (renew with workflow_evals_exports_download_url). A Run with retryable failed Cases is refused with 409 ``retryFirst`` unless ``allow_pending_retries`` is true.

workflow_evals_exports_start