agent_chat
ChatGPTChat 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_result
ChatGPTCollect the result of an agent_chat run that was still working. Waits briefly for the run to finish, then returns either the completed chat response (same shape as `agent_chat) or {"status": "running", "run_id": ...}. Keep calling with the same run_id until the status is no longer running. The run keeps executing server-side between calls; polling never restarts or duplicates it. A "severed" status means the connection to the run was cut mid-flight; the run usually still finishes server-side, so read the reply from the conversation (agent_conversation_get`) instead of re-sending the message.
agent_conversation_get
ChatGPTGet a single agent conversation with its message history. Returns the conversation metadata and the ordered list of the most recent `message_limit messages (role + text parts), plus total_messages with the full history size. Pass the same conversation_id back to agent_chat` to continue the conversation.
agent_conversations_list
ChatGPTList Roboflow agent conversations in the workspace. Returns conversation metadata (id, name, source, timestamps, linked workflow ids). Use `agent_conversation_get to load the full message history for a single conversation, or pass the conversation id back to agent_chat` to resume it.
agent_workflow_publish
ChatGPTPublish the latest agent-edited draft of a workflow. The agent never publishes its edits to an existing workflow; it saves them as a draft. This tool promotes the latest draft to a published version so it goes live for callers using the workflow by id (`workflows_run). Errors with 400 if there is no draft to publish (i.e. the published version already matches the latest draft). Returns { workflowId, workflowUrl, versionId, status }`.
annotation_batches_admin_get
ChatGPTGet details about one annotation-board batch.
annotation_batches_admin_images_list
ChatGPTList image IDs in a batch with cursor pagination.
annotation_batches_admin_list
ChatGPTList annotation-board batches with cursor pagination.
annotation_batches_create
ChatGPTMove selected images from one batch into a new batch.
annotation_batches_delete
ChatGPTDelete a batch. By default its images move to unassigned and remain accessible.
annotation_batches_get
ChatGPTGet details about one upload batch.
annotation_batches_list
ChatGPTList upload batches in a project.
annotation_batches_merge
ChatGPTMove all images from source batches into a target batch and remove the emptied sources.
annotation_board_status
ChatGPTSummarize a project's Annotate board: Unassigned, Annotating, Review, and Dataset. Proxies GET /:workspace/:project/annotation-board. Returns column counts and progress, plus per-labeler and per-reviewer rollups. Use annotation_jobs_list and annotation_batches_admin_list when you need more pages of items.
annotation_editor_open
ChatGPTOpen the Roboflow annotation editor for one image. Use this when a person needs to inspect or edit image annotations visually. Changes are saved only when the person chooses Save in the widget.
annotation_editor_read
ChatGPTReload the editor snapshot and revision after a save or conflict.
annotation_editor_save
ChatGPTSave the user's annotation edits using the loaded group revision. A conflict requires reloading and reconciling edits. Never blindly retry.
annotation_jobs_accept_into_dataset
ChatGPTFinalize selected job images into the Dataset and assign splits.
annotation_jobs_create
ChatGPTCreate a job and move images from a batch into it.
annotation_jobs_delete_annotations
ChatGPTDelete the project's annotation data for every image assigned to a job.
annotation_jobs_get
ChatGPTGet details about one annotation job.
annotation_jobs_images_add
ChatGPTMove images into an existing job and reconcile assignment and Dataset counters.
annotation_jobs_images_list
ChatGPTList image IDs assigned to a job with cursor pagination.
annotation_jobs_images_reassign
ChatGPTCreate a job from selected images, removing their prior assignment or Dataset membership.
annotation_jobs_list
ChatGPTList annotation jobs and return a continuation token when more exist.
annotation_jobs_move_to_unassigned
ChatGPTRemove a job while moving its images to an unassigned batch so they remain accessible.
annotation_jobs_return_for_edits
ChatGPTMove a review job back to labeling, optionally with a new labeler.
annotation_jobs_review_image
ChatGPTSet the explicit review status for one image in a job.
annotation_jobs_review_images
ChatGPTSet a status for every job image matching the supplied current status.
annotation_jobs_submit_for_review
ChatGPTAdvance a labeling job into review.
annotation_jobs_update
ChatGPTUpdate exactly one of a job's labeler, reviewer, or instructions.
annotations_save
ChatGPTSave an annotation for an existing image. By default this only stores the annotation: it does not change whether the image belongs to the project Dataset. Pass add_to_dataset=true to also add the image to the Dataset. That membership is what makes the image count toward a dataset version, so an image that is uploaded and annotated but never added to the Dataset will show up as 0 images in versions_generate. Set prediction_routing to `review to request an automatic move from the target-project batch into a Review job only when the image has target-project batch membership and no target-project annotation-job membership. Set it to unassigned` to suppress that move and preserve existing batch, annotation-job, and Dataset memberships. Prediction uploads never add Dataset membership, even when add_to_dataset is true, and existing Dataset membership is preserved. Neither value guarantees movement to a named queue. Saving onto an image that already has annotations fails with a 409 conflict unless you pass overwrite=true, which replaces the existing annotation. Classification projects never hit that conflict: their saves already overwrite.
api_keys_create
ChatGPTCreate 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_disable
ChatGPTDisable (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_get
ChatGPTGet metadata for a single API key by its keyId. Secret values are never returned. The key is identified by its non-secret `keyId` handle (not the secret key string).
api_keys_get_publishable
ChatGPTGet the workspace's publishable key (`rf_<workspaceId>`). The publishable key is the non-secret workspace identifier used with Roboflow.js and browser-side inference SDKs. It is browser-safe and cannot manage workspace data or read private resources. It is not a true secret, but it is not powerless: anyone who holds it can run inference and download the workspace's deployed models. Embed it in client-side code as intended; do not treat it as a capability to hand to untrusted parties.
api_keys_list
ChatGPTList all API keys for the workspace. Secret key values are never returned — keys are represented by their non-secret `keyId handle and a masked prefix. Returns { api_keys, publishable_key } where publishable_key is the workspace's rf_<workspaceId>` key (safe to embed in client-side code).
api_keys_protect
ChatGPTMark an API key as protected so it cannot be revoked or disabled. Protection is one-way from the API: a protected key can only be unprotected in the Roboflow dashboard at `app.roboflow.com/settings/api. The API, CLI, and MCP cannot unprotect a key, so there is deliberately no api_keys_unprotect` tool. Returns the updated masked key metadata.
api_keys_revoke
ChatGPTPermanently revoke (delete) an API key. Revocation is irreversible — the key can never be recovered or re-enabled. Protected keys cannot be revoked; an admin must first unprotect the key in the Roboflow dashboard at `app.roboflow.com/settings/api. A key that backs a dedicated deployment cannot be revoked from here either (the deployment would be paused): to rotate such a key — for example after a leak — use api_keys_roll, which moves the deployment onto the replacement key. Returns { status, key_id }`.
api_keys_roll
ChatGPTRoll (rotate) an API key: revoke it and mint a replacement in one step. This is the rotation path for a leaked or compromised key. The replacement keeps the old key's whole identity — name, scopes, folders, protection and disabled state — so nothing the key was allowed to do changes; only the secret does. Any dedicated deployment anchored on the old key is moved onto the replacement automatically, which is why roll is allowed where `api_keys_disable and api_keys_revoke refuse. The old secret stops working immediately and its key_id is retired; the roll cannot be undone. Protected keys cannot be rolled (unprotect in the dashboard first), and a disabled key that backs a dedicated deployment must be re-enabled before it can be rolled. The new secret key is returned ONCE and cannot be retrieved again. Store it immediately in a .gitignore'd .env file and update every consumer of the old key; never echo it in logs or tool output. Returns { key_id, key, name, scopes, folder_ids, protected, disabled, revoked_key_id }. key_id is the new key's non-secret handle; revoked_key_id` is the handle that was rolled.
api_keys_update
ChatGPTUpdate the name, scopes, or custom_metadata of an existing API key. Only fields you provide are sent; omitted fields are left unchanged. Omitting `name leaves the name unchanged; omitting custom_metadata leaves the metadata unchanged. Omitting scopes leaves the key's scopes unchanged, while passing a list replaces them entirely (including role:<name> presets). To widen a scoped key back to full access, pass ["role:owner"] (subject to the usual subset rules and the Advanced API Keys feature). To protect or disable a key use api_keys_protect or api_keys_disable`. Protection cannot be changed here (unprotecting is dashboard-only). Returns the updated masked key metadata.
async_tasks_get
ChatGPTPoll an async task by id. Poll every 5 seconds; processing may take up to 30 seconds to start. Returns { taskId, status, progress, result?, error? }. status is one of created, running, completed, failed.
autolabel_job_get
ChatGPTGet per-subjob status and progress for an auto-label job. Returns status, model/project type, image counts, subjob progress, ontology, confidence thresholds, and the linked annotation job id.
autolabel_models_list
ChatGPTList the foundation models available for hosted auto-labeling in this workspace. Returns `{models: [...]}. Each entry's id (e.g. gpt-6-astra-boxes, sam3-rle, gemini-boxes) is a valid model value for autolabel_start with model_type='foundational'. Entries carry guidance on when to prefer each model, projectTypes / excludedProjectTypes they support, ontologyFormat (promptMap: prompts are sent to the model; classes: only class names are used), creditsPerImage, isDefault (the recommended starting point when the project type supports it; otherwise the first entry that does), and available with an unavailableReason when the workspace's plan blocks a model. Call this before autolabel_start to pick a model instead of assuming which ones exist. When the user has not chosen a model, follow up with autolabel_preview` to compare the candidates on one sample image before committing to a job.
autolabel_preview
ChatGPTPreview one image with a foundation model to judge it before starting an auto-label job. Previews are for comparing candidate models on a few sample images. They create no job and spend no credits, but they are rate limited per workspace (the limit is shared with the Roboflow app), and past the limit the call fails with a 429 that says when to try again. Labeling a batch must go through autolabel_start: do not preview images one at a time and keep the predictions as labels. Use this as the model-selection loop when the user has not picked a model: 1. Call autolabel_models_list and order the candidates (the default first, then whatever the guidance recommends for the ontology at hand). 2. Pick one representative image from the batch (e.g. from the batch or image listing tools) and preview it with the first candidate. 3. Judge the summary: entries in classesWithNoDetections, a suspiciously low totalDetections, or blockErrors mean the model likely will not label this data well. Preview the next candidate and compare. 4. Start the real job with the winner via autolabel_start, using the same ontology. Returns `{model, summary, predictions, blockErrors?}`; summary.byClass carries per-class counts and max confidence, and predictions are trimmed to class, confidence, and box geometry (polygon and mask geometry is dropped to keep responses small).
autolabel_start
ChatGPTStart a hosted auto-label job over a batch of images. Call `autolabel_models_list first to pick a foundation model; its entry ids (e.g. 'gpt-6-astra-boxes', the default for object detection) are valid model values. If the user has not chosen a model, run autolabel_preview on a sample image per candidate and start the job with the best one. Returns {jobId, annotationJobId, message}. Poll progress with autolabel_job_get using the returned jobId`.
batch_processing_asset_library_job_create
ChatGPTQueue 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_task_get
ChatGPTPoll the launch receipt until its durable job is registered.
batch_processing_guide
ChatGPTRoute a bulk image/video processing request onto batch processing: pick the staging mode, settle the batch id, and return the exact inference-cli commands for the whole run. Every batch processing job runs a Workflow over a Data Staging batch; the input paths differ only in who fills it. Files already in Roboflow (Asset Library): batch_processing_asset_library_job_create, and the platform selects and stages them for you. External files (local disk, cloud bucket, references file) when you only want the outputs: stage them with the inference-cli and drive the run with batch_processing_run (nothing is imported; the classic ETL shape). External files you want INSIDE Roboflow for labeling/training/curation: that is an import, not a job; mirror them with a datasource (bucket mirror, connect_cloud_storage), then run an Asset Library job over the imported images if you also want bulk predictions (the classic ELT shape). Staging uploads are client-side: this MCP server cannot read the user's filesystem or cloud credentials, so files are staged with the inference-cli on the user's machine (pip install inference-cli). Call this with whatever you already know (local dir, bucket path, workflow, images vs videos); it returns the install line and the ordered stage/inspect/process/monitor/export commands. Read the roboflow://skills/roboflow-batch-processing/SKILL resource for the full recipe, and prefer batch_processing_run to drive the run server-side once files are staged. Requires the batch-processing feature on the workspace.
batch_processing_job_abort
ChatGPTAbort a running batch processing job. Already-produced partial results stay available in the job's staging batches.
batch_processing_job_get
ChatGPTGet a job's status and per-stage progress. Poll this to track a running job: `job.isTerminal says whether it finished and job.error whether it failed; stages carries per-stage progress and outputBatches. When the export stage completes, download results from the <job-id>-export staging batch via batch_processing_staging_batch_files_list`.
batch_processing_job_logs
ChatGPTFetch a job's processing logs (paginated). Use this to diagnose failed or slow jobs; pair with batch_processing_job_get for stage status.
batch_processing_job_restart
ChatGPTRestart a failed or aborted job, optionally overriding compute parameters. Consumes credits like a fresh run.
batch_processing_jobs_list
ChatGPTList the workspace's batch processing jobs. Returns `{jobs, nextPageToken?} with each job's full definition omitted (use batch_processing_job_get for one job's detail). Each entry carries inputSource`: 'asset-library' (platform-staged selection) or 'staged-batch' (a batch the caller staged).
batch_processing_run
ChatGPTMaster tool: drive a batch processing run over a staging batch you name (stage -> ingest -> job -> results) through repeated resumable calls. For Asset Library selections, use batch_processing_asset_library_job_create instead. Every batch processing job runs a Workflow over a Data Staging batch; the input paths differ only in who fills it. Files already in Roboflow (Asset Library): batch_processing_asset_library_job_create, and the platform selects and stages them for you. External files (local disk, cloud bucket, references file) when you only want the outputs: stage them with the inference-cli and drive the run with batch_processing_run (nothing is imported; the classic ETL shape). External files you want INSIDE Roboflow for labeling/training/curation: that is an import, not a job; mirror them with a datasource (bucket mirror, connect_cloud_storage), then run an Asset Library job over the imported images if you also want bulk predictions (the classic ELT shape). Each call reads current state, advances what it can, and returns immediately: 'staging_required' (batch missing; response contains the inference-cli commands to run), 'ingest_in_progress', 'ingest_failed', 'running' (job started or working; includes stage progress), 'completed' (includes result files with download URLs), or 'failed' (includes logs). This server never sleeps on your behalf; non-terminal responses carry retryAfterSeconds, so wait that long and call again with the returned job_id to resume; omit optional creation settings and the stored paid-job definition remains authoritative. The job is started under an id derived from (workspace, batch, workflow), so retrying after a lost response re-registers the same job rather than starting a second one. Starting the job consumes credits. For the advanced knobs (max_runtime_seconds, max_parallel_tasks, max_image_failure_rate, image_outputs_to_save) use batch_processing_staged_job_start instead.
batch_processing_staged_job_start
ChatGPTStart a batch processing job: run a Workflow over a staged batch. This launches asynchronous compute and consumes credits. The batch must be staged first (see `batch_processing_guide) and fully ingested (batch_processing_staging_batch_get). Returns {jobId, ...}; poll batch_processing_job_get and fetch results from the <job-id>-export` staging batch when it finishes. Re-running with the same job_id and identical settings is idempotent; a divergent definition is rejected (409).
batch_processing_staging_batch_files_list
ChatGPTList a staged batch's files with time-limited signed download URLs. Use this to download the results of a finished job (the `<job-id>-export batch). Job-result batches are multipart: when the batch has exactly one part it is selected automatically (and echoed as partName); with several parts, pass part_name (see batch_processing_staging_batch_get parts). Download URLs expire after ~24h; archives (.tar/.tar.gz) must be unpacked after download. Returns {files, returned, nextPageToken?, truncated, partName?}. Results are returned in whole upstream pages so nextPageToken always continues exactly where files ended. Listings are capped at 10,000 entries per call; past that, pull results with the inference-cli's export-batch` (resumable) instead.
batch_processing_staging_batch_get
ChatGPTGet a staged batch's metadata, file count, and ingest progress. Sharded, cloud-storage, and references ingests register files asynchronously: the count stays low until ingest workers finish. Poll this until `ingest.pending is false and ingest.failed is false before starting a job. For multipart batches (e.g. job results) the response includes parts`.
batch_processing_staging_batches_list
ChatGPTList the workspace's data-staging batches (inputs and job results). Returns `{batches, nextPageToken?}. Batches expire about 7 days after creation. Job results appear as platform-generated batches named <job-id>-processing and <job-id>-export`.
connect_cloud_storage
ChatGPTConnect 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.
credentials_delete
ChatGPTDelete a credential. Datasources still referencing it will fail to run.
credentials_list
ChatGPTList cloud-storage credentials in the workspace. Secrets are masked server-side, so only non-sensitive fields (id, type, name, description) come back. Returns `{ credentials }`.
datasets_rebalance_splits
ChatGPTEnqueue an async rebalance of a project's train/valid/test splits. Use this to fix a starved or empty split — an empty test split blocks training, and this is the only way to move images between splits after upload. train, valid and test are relative weights, not percentages: they do not have to sum to 100, and each must be a whole number (70, not 70.5). mode="rebalance" moves the fewest images needed to reach the ratios; mode="shuffle" reassigns every image. Returns the platform's 202 payload verbatim — at minimum { taskId, url }, where url points at the async-task polling endpoint. Poll completion with async_tasks_get(task_id=taskId) every 5 seconds until status is terminal (completed or failed).
datasource_create
ChatGPTCreate 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_delete
ChatGPTDelete a datasource configuration. Does not delete already-mirrored images.
datasource_get
ChatGPTGet full detail for a single datasource, including its bucket, mirror rules, and latest job summary.
datasource_job_get
ChatGPTGet the status and statistics of a single datasource mirror run. Poll this with a `batchId from datasource_trigger to track a run. Returns the job's status (running/completed/failed), per-stage counters (enqueued/completed/failed), any errors, and timestamps (startedAt/completedAt/lastSyncedAt`).
datasource_trigger
ChatGPTStart a mirror run for a datasource. This kicks off a job that ingests bucket contents into your workspace. Depending on the saved mirror rules, it can overwrite imported images or metadata and remove images whose source objects disappeared. It can consume compute/storage credits. Returns `{batchIds} for the run(s) that were started. Use datasource_validate` first if you are unsure the bucket is reachable.
datasource_update
ChatGPTUpdate a datasource. Only the fields you pass are changed. To replace the bucket, pass `bucket_type, bucket_name and region together (endpoint` is optional and only applied with them). Returns the updated datasource.
datasource_validate
ChatGPTCheck that Roboflow can access the datasource's bucket. Returns `{checks, errors} where checks reports whether listFiles/headFile/getFile succeeded plus a per-mirror headGlobFile` result. Use it to self-diagnose a misconfigured credential or bucket before triggering a run.
datasources_list
ChatGPTList datasource (cloud-bucket mirror) configurations in the workspace. Returns `{ datasources } where each entry is trimmed to {id, name, credentialId, validated, requireVpce, latestJob}. Use datasource_get` for a single config's full detail.
devices_create
ChatGPTProvision 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_get
ChatGPTGet a single device by id. Returns the Device object. 404 if the device does not exist or belongs to a different workspace. When inspecting a device, also call `devices_get_config for its running services and devices_get_default_config for the workspace's recommended versions — comparing the two services` maps reveals whether the device is up to date or pinned to an older build of any service.
devices_get_config
ChatGPTGet the device's current runtime configuration. Returns the full RFDM config JSON: `device_id, device_name, workspace_id, version, last_updated, config, services. The response passes through environment_variables and any embedded integration credentials, so treat the payload as sensitive. Tip: pair this with devices_get_default_config and diff the services` map. The default config carries the workspace's recommended version for each service, so comparing the two tells you whether the device is up to date or pinned to an older build.
devices_get_config_history
ChatGPTList prior configuration revisions, newest first. Returns `{data: ConfigRevision[], pagination: {next_cursor, has_more, limit}}. Each ConfigRevision carries revision_id, created_at, and created_by`.
devices_get_default_config
ChatGPTGet the workspace's default device configuration. Returns `{config, patch}: config is the base default config with the workspace's config_patch applied (the template used when provisioning new devices, including default service versions), and patch is the raw workspace-level patch object. Useful for inspecting which service versions a fresh device would be created with, or for seeding a payload to devices_update_config. Requires the device:read` scope. Device-scoped api_keys are rejected with 403 — this endpoint is workspace-wide.
devices_get_deployments
ChatGPTGet the device's deployment history with per-deployment activity. This is the device Activity tab as structured JSON: each config revision becomes a half-open deployment window (newest window open-ended), annotated with what happened while it was live: - `exception_issues — exceptions grouped by fingerprint with occurrence counts, last_seen, and the latest description; drill into one with devices_get_exception_occurrences - error_event_issues — error events grouped by entity/event/error_code - execution_environment — the inference runtime reported during the window (versions, GPU, loaded models) - workflow_edits — workflow publishes that landed mid-deployment - container_pulls — image pulls (and failures) during the window - stats — unique/unhandled exception counts and error event count - config_changed_paths (opt-in) — dotted config paths changed vs the prior revision, values omitted - trends (opt-in) — bucketed occurrence time series per issue Returns {device_id, deployments: Deployment[], pagination: {next_cursor, has_more, limit}}. Prefer this over raw devices_get_events` when diagnosing what a deployment broke. Rate-limited per-device: 30 requests / minute.
devices_get_event_store_stats
ChatGPTReport a device's local event store against its capacity limits. Thin view over `devices_get_services(kind='event_store'). Returns {device_id, services: Service[]}; each status carries records / records_limit / records_percent, images, bytes_used / bytes_limit / bytes_percent, a backup block (Vision Events upload progress: enabled, backed_up_*, pending_*), a drafts block, disk, capacity_blocked, unuploaded_records, and last_cleanup. Reading it correctly: - capacity_blocked is null until the device reports a transition. The service emits only capacity_blocked / capacity_cleared, so silence is genuinely unknown and false would assert healthy. It also reads true only while a fresh stats sample has not contradicted it. - drafts is null on firmware predating the draft lifecycle, which is not the same as a device reporting zero drafts. - stale: true with all counters null means no recent stats sample: a device that only ever reported a cleanup is not a healthy, current event store. - reported_at is the device's clock and may be null; the received_at fields are the platform's. For a trend (fill rate, backup backlog), use devices_get_service_series with metrics such as records_percent, bytes_percent, pending_records, or disk_percent_used`.
devices_get_events
ChatGPTList device and stream lifecycle events. Returns `{data: Event[], pagination: {next_cursor, prev_cursor, has_more, limit}}. By default the feed models **state transitions**: consecutive rows carrying the same event name for the same entity collapse into one row unless the previous row's TTL has elapsed. That is right for lifecycle events and wrong for periodic telemetry, which reuses a single event name for every sample: plc_snapshot ticks every 60s with ttl_s: 300, so a deduped read returns roughly one row where the raw read returns them all. Pass dedupe=False to read raw rows. It requires **both** entity_type and entity_id (an entity id is only unique within its type), reports event_end_timestamp as null (an "end" is derived from the dedup window and means nothing for a sampled reading), and is rate-limited at 30 requests / minute per device, in the same bucket as devices_get_services and devices_get_service_series. The deduped default is not rate-limited. For charting a named sidecar metric, prefer devices_get_service_series`, which resolves the entity id and the dedup behavior for you.
devices_get_exception_occurrences
ChatGPTList raw occurrences of one exception fingerprint, newest first. Use after `devices_get_deployments to see exactly when a grouped exception fired — each row is {id, timestamp, error_code}. Pair the timestamps with devices_get_logs (start_time / end_time around an occurrence) to read the surrounding log context. Returns {data: [...], pagination: {next_cursor, has_more, limit}}`.
devices_get_logs
ChatGPTFetch device logs from Elasticsearch. Rate-limited at two tiers: 5 requests / minute per IP, and 50 requests / minute globally across all callers (Elasticsearch protection). Returns `{data: LogEntry[], pagination: {next_cursor, has_more, limit}}`.
devices_get_plc_status
ChatGPTAnswer "is this PLC connected?" for a device's PLC relay sidecars. Thin view over `devices_get_services(kind='plc_relay'). Returns {device_id, services: Service[]}; each status carries: - connected: reconciled across the every-60s snapshot and the transition-only connectivity events by recency, connectivity winning ties, so an older optimistic snapshot can never mask a newer disconnect. null means unknown, not disconnected: the two slots could not be ordered on one clock. - driver, plc_ip - tags / tag_count: the tag map and its size, **withheld (null) whenever connected is not true**. Those readings predate the drop, and a frozen part count shown as current is how an operator ends up trusting a dead line. - reported_at: device clock, from the snapshot; connection_changed_at: device clock, from the last connectivity transition. Both null when that slot never reported. - stale: true: the reading that decided connected is old (over 30 minutes), which is different from absent. For connectivity history, use devices_get_service_series with metric='connected'` (charts as 1/0).
devices_get_service_series
ChatGPTChart one named sidecar metric over time. The metric name resolves to the right entity id, event names, and metadata key for that service's kind, and the read skips the dedup window that would otherwise collapse periodic telemetry. Use this for trend questions instead of raw `devices_get_events. Returns {device_id, service, kind, metric, metric_type, time_period, available_metrics, truncated, covered_from, covered_to, points: [{timestamp, value}]}. - metric_type is number or boolean. A boolean charts as 1/0, so the type is what tells a 1 meaning "true" from a 1 meaning "one". - An unknown metric returns 400 listing the valid names for that kind in valid_values; available_metrics on a successful response says the same thing. - truncated: true means the window held more than the 5,000 sample cap. The newest samples are kept, so covered_from / covered_to report the interval actually returned, which can be shorter than the requested window. plc_snapshot ticks every 60s (10,080 samples over 7d), so narrow the window for full coverage. - Two clocks: time_period selects by when the platform *received* a sample, while each point's timestamp (and therefore covered_from / covered_to) is what the device reported. On a badly-skewed device those can fall outside the requested window; that is the device's own account, not a filtering error. - 409 means two services of this kind claim the same entity id, so the samples cannot be attributed to one of them; the response names the claimants. Rate-limited per-device: 30 requests / minute, in one bucket shared with devices_get_services, the per-sidecar tools, and devices_get_events(dedupe=False)`.
devices_get_services
ChatGPTList the sidecar containers a device runs and what each is doing. Joins the device's declared `services config with the same latest-value status cache the Device Manager UI subscribes to. Returns {device_id, services: Service[], unassociated_signals}. Each Service carries name, kind (resolved from the image; an unrecognized container is custom), image/tag, tag_is_canonical, automatic_updates, has_pending_changes, state plus state_reported_at / state_received_at, image_state, signal_conflicts, and the typed status for its kind. Reading the nulls correctly: - state and image_state are null once the last report has aged past its TTL; the matching *_received_at still carries a timestamp, so "stale reading" stays distinguishable from "never reported". - status is null until the service has reported, for kinds that emit no telemetry (rtsp_simulator, device_hmi, custom), and whenever signal_conflicts is non-empty. - signal_conflicts lists entity ids more than one declared service claims. Ids derive from the **kind**, so two services of the same kind collide unless each sets a distinct DEVICE_EVENT_ENTITY_ID. The reading cannot be attributed, so it is withheld rather than guessed. - unassociated_signals holds telemetry that matched no declared service (a custom container, or an entity-id override we could not resolve). It needs include=['signals'] and is omitted when a kind filter is applied. Two clocks, everywhere in this response: *_reported_at is the device's own claim and is null when the device sent none (it is never backfilled), while *_received_at is when the platform recorded it. Freshness reads received_at; ordering two signals from one device reads reported_at. Never compare one against the other. metrics_truncated: true means the metrics aggregation hit its row cap and some services report metrics: null for that reason rather than never having reported. Narrow time_period. Rate-limited per-device: 30 requests / minute, in one bucket shared with devices_get_service_series, the per-sidecar tools, and devices_get_events(dedupe=False)`.
devices_get_snapshot
ChatGPTGet the full current state of a device in one call. Prefer this as the FIRST call when diagnosing a device — it aggregates what would otherwise take six requests: - `device — identity, online/offline status, hardware summary, network interfaces, discovered cameras - streams — {total, running, data} including config-only (provisioning) streams - services / services_summary — per-service container status and healthy/total counts - telemetry — the latest non-empty 1h telemetry bucket (cpu, memory, disk, gpu, network throughput) - system_status — current docker daemon and NTP health - hardware — most recent startup hardware report - current_deployment — the live config revision with its exception/error issues and execution environment - recent_events — the 20 most recent lifecycle events Sections are best-effort: a failed section is null and named in the top-level errors array. Follow up with the focused tools (devices_get_deployments, devices_get_logs, devices_get_telemetry) for history and detail. The services section here is container status only. For typed sidecar state (is the PLC connected, is the event store full) call devices_get_services` or the per-sidecar tools. Rate-limited per-device: 30 requests / minute.
devices_get_telemetry
ChatGPTGet aggregated hardware metrics and device health sections. Rate-limited per-device: 60 requests / minute steady, plus a burst limit of 10 requests / 10 seconds. By default returns `{time_period, bucket_interval, fill_interval_seconds, buckets, stream_fps, system_status, services, hardware, network_interfaces, metadata}: - buckets — cpu/memory/disk/gpu plus network_upload_bytes_per_sec / network_download_bytes_per_sec - stream_fps — one series per running pipeline (pipeline_id, stream_name, stream_id) with a buckets array in ascending time order, each entry {bucket_start, camera_fps, inference_fps} - system_status — per-bucket docker daemon and NTP health (up / partial / missing; missing = no telemetry samples in that bucket) - services — per-service container status with the latest container sample (image, cpu, memory); add service_history to include for per-bucket history - hardware — most recent startup hardware report (OS, CPU, Jetson/JetPack, GPU driver, uptime, NTP) - network_interfaces — most recent interface snapshot Pass include=metrics for the compact time-series-only response, or include=stream_fps` when you only need camera vs. inference frame rates.
devices_list
ChatGPTList devices registered in the workspace. Returns a list of Device objects with id, name, status, last_heartbeat, platform/hardware info, tags, and created_at. `status is online if a heartbeat was received within the last 5 minutes, otherwise offline (or unknown for devices that have never reported). Requires the device:read` scope. Device-scoped api_keys cannot call this endpoint and will receive 403.
devices_streams_get
ChatGPTGet a single stream by id. Returns the Stream object. Streams that exist only in the device config are returned as synthesized `provisioning` entries rather than 404; 404 only if the stream exists neither live nor in config.
devices_streams_list
ChatGPTList streams configured on the device. Returns a list of Stream objects, including streams that exist only in the device config and have not been reported by the device yet (`status: "provisioning", provisioning: true). mode is "triggered" for trigger-driven streams, "continuous" otherwise. Credential-bearing fields (URL userinfo, password, credential, etc.) are redacted from the source and configured_source` fields.
devices_update_config
ChatGPTUpdate the device's runtime configuration. Requires the `device:update` scope. The merge is a Firestore shallow update: omitted top-level fields stay as-is, but any top-level field you supply replaces its entire nested object wholesale. The payload is validated against the RFDM config schema, and a new entry is appended to the config history.
folders_list
ChatGPTList the workspace folders visible to this credential. Returns `{ folders: [{id, name, parent_id, child_ids, projects, external_id}, ...] }. projects holds the URLs of the projects in the folder; parent_id and child_ids describe the folder tree. child_ids names only folders this credential can list, but parent_id is the platform's value, so the top of a folder-scoped credential's subtree can point at a folder that is not in the list. A folder-scoped credential sees only its own folders. An empty list means no folders are visible to this credential, not necessarily that the workspace has none. Pass folder_id` to fetch a single folder; an unknown id also yields an empty list.
get_aws_storage_credential_setup_link
ChatGPTGet a Roboflow app link to set up an AWS S3 storage credential. This tool does not create a credential. It returns `manual_entry_required with a url for the Roboflow form, a docs_url for prerequisites, and aws_setup` guidance for the correct AWS account. Only the non-secret name, credential_type, and description are passed here. The user enters AWS access keys or role details in the Roboflow app, never in chat or this tool. IAM uses AWS access keys; AssumeRole uses an AWS IAM role. Recommend a credential dedicated to Roboflow with read-only or bucket-scoped access. After the user completes the form, use credentials_list to find its id.
image_upload
ChatGPTPrepare a signed URL for uploading a zip of images and optional annotations. Use this when a client can zip local images, plus any annotation files, and HTTP PUT the zip to the returned signed URL. This tool does not read, zip, or upload local files. To mirror images from cloud storage (S3/GCS), use the datasource tools. Returns a signed upload URL, task ID, and client-side instructions. The MCP server never receives file bytes. Requires the project slug, plus optional split, batch name, tags and annotation_overwrite. Local file paths are used by the client after this tool returns, not passed here. Remaining steps after this returns (detailed in the response instructions): 1. Zip the images and any annotation files (even one image → zip). Paths inside the zip set splits: train/, valid/ and test/ folders override the split argument per image. 2. HTTP PUT the zip to signedUrl. 3. Poll image_upload_status(task_id) every few seconds until completed or failed. Annotation files in the zip are imported with the same parser as the web uploader: COCO JSON (e.g. one _annotations.coco.json per split folder), YOLO TXT (with data.yaml or classes.txt for class names), Pascal VOC XML, CreateML JSON, CSV, and the other formats it accepts. Annotations are matched to images by file name. In classification projects, an image's parent folder is its class (cat/img1.jpg). Images with annotations are added straight to the Dataset, so there is no annotation job to accept (with annotation review turned on for the workspace, they wait in a review job instead). Images without annotations land in a batch: label them later with annotations_save and pass add_to_dataset=true there, which is what makes them usable for training. An image already in the project counts as a duplicate and is not stored again, but its annotation from the zip is still saved. An image that already has an annotation in this project's annotation group (for example from another project in the workspace that uses the same group) keeps it and is listed in annotationErrors, unless annotation_overwrite is true. Up to 2 GB / 10k files. Signed URL expires in 1 hour.
image_upload_status
ChatGPTCheck the status of an image zip upload task. Use after the zip has been PUT to the signed URL (image_upload step 2). Poll every 3–5 seconds until status is completed or failed. Returns status (created, running, completed or failed), progress, and, once finished, a result with uploaded, duplicates and annotated counts, plus uploadErrors, annotationErrors and warnings (for example annotation files that matched no image, or files that were ignored). Error lists stop at 100 entries. Status stays "created" until the first chunk of images finishes; progress gets a total as soon as processing starts. If the task is still "created" with no progress 10 minutes after a successful PUT, the zip was not processed (for example it held no supported image files): stop polling, fix the zip and start over with a new image_upload call. The zip is processed in chunks. If any chunk fails, status is "failed", failedChunks is above 0, and uploadErrors holds an entry whose path names the chunk (e.g. "chunk-0"). That chunk's images may already be stored without their annotations, and its counts are missing from the totals. Re-uploading the same zip with a new image_upload call is safe and repairs this: stored images come back as duplicates and their missing annotations are saved. Images whose annotations were saved the first time are then listed in annotationErrors as "Image was already annotated", which is expected.
images_batch_update_metadata
ChatGPTBatch-update metadata and tags on multiple images (async). Each item in updates must contain an 'imageId' and at least one mutation bucket. Same conflict rules as the single-image endpoint. Returns { taskId, url } with status 202. Poll completion via async_tasks_get with the returned taskId.
images_search
ChatGPTSearch images in one project by what they show, with optional filters. query is semantic search: results are ranked by how well they match the text, but the query does not narrow them, so total does not change with it. Narrow results with tag, class_name, in_dataset, batch, batch_id, annotation_job and annotation_job_id. There is no split filter here. For RoboQL (split:, metadata:, filename:, NOT, OR, and so on), use images_workspace_search with project:<slug> in the query, e.g. 'project:my-project split:valid'. Returns { offset, total, results }.
images_update_metadata
ChatGPTUpdate metadata and tags on a single image. Metadata and tags can be useful to find images later in the platform. Common metadata include photo location, camera, date. Provide at least one of: metadata, remove_metadata, add_tags, remove_tags. The same key cannot appear in both metadata and remove_metadata; the same tag cannot appear in both add_tags and remove_tags. Returns { success: true } on success.
images_workspace_search
ChatGPTSearch images across the entire workspace using RoboQL. The workspace is determined automatically from the API key — no workspace or project parameter is needed. Just provide a query. Use RoboQL syntax to filter by project, Dataset membership, split, class, tag, metadata, and more; combine filters with AND, OR, NOT and parentheses. This is the tool for split filters and other RoboQL queries scoped to one project: add project:<slug>. Request the url field when you need a direct image URL. Returns results with a continuationToken for pagination.
media_analyze
ChatGPTAnalyze an image or short video with a vision model to understand its contents. Returns a structured analysis: a summary, the distinct objects present with approximate counts, the best-fitting CV task (detection, segmentation, classification, OCR, tracking...), candidate class names, whether those classes fall within the 80 COCO classes (drives model-family selection), motion notes for video, and workflow recommendations. Pass any public HTTPS URL directly — image results from images_search, images_workspace_search, or universe_dataset_images_search already include a usable url field. For a local file on the user's machine, call media_upload first and analyze the URL it produces. This is a stateless one-shot primitive: nothing is recorded in a conversation. Costs workspace credits (one vision-model call per invocation). Storage allows videos up to 100 MB, but ANALYSIS is capped at ~15 MB by the vision gateway's url fetcher; trim longer footage before analyzing.
media_trim
ChatGPTCut a clip from an Asset Library video and get an analyzable public url. Use after media_upload_finalize returns needsTrim: true. The simplest call is media_trim(video_asset_id) with no window: the server cuts the longest clip the ~15 MB analysis budget allows from the start (typically up to ~95 seconds; often the entire video, since long windows are re-encoded, downscaled to at most 1280px, to fit). Pass start_seconds/duration_seconds only when your user cares about a specific segment. The response tells you exactly what happened: clipSeconds (what was actually cut), requestedSeconds, clamped: true when the server shrank the window, plus authoritative videoDurationSeconds and maxClipSeconds from the server-side probe. Report the real clipSeconds to your user; to cover the rest of a long video, cut the next clip at start_seconds + clipSeconds and repeat. Only the published clip is re-encoded; the full-quality video stays untouched in the Asset Library.
media_upload
ChatGPTPrepare a local image or video for analysis with media_analyze. Returns a short-lived signed upload URL plus step-by-step instructions; the upload itself completes client-side (the MCP server never receives file bytes). After the PUT, call media_upload_finalize to validate the bytes. For images and small videos it returns a durable url to pass straight to media_analyze; for videos over the analysis budget it returns needsTrim: true with a videoAssetId, and you call media_trim to get the analyzable clip url. Only needed for files on the user's machine; media already reachable by an HTTPS URL (including Roboflow-hosted images) can go straight to media_analyze. Finalized images and videos are saved into the workspace Asset Library (reusable across the workspace; re-uploading identical bytes reuses the existing asset instead of duplicating it). The analyzable copy ends up on a public CDN at an unguessable URL.
media_upload_finalize
ChatGPTValidate a staged upload (from media_upload) and publish it. Checks the uploaded bytes match the declared media type and size limits. Images become workspace Asset Library assets (the response includes their sourceId) and return a durable public url to pass to media_analyze. Videos always become Asset Library records (videoAssetId). Small videos also return a durable url right away (needsTrim: false). Videos over the analysis budget return needsTrim: true: call media_trim(video_asset_id) with no window to get the maximal analyzable clip, and read the authoritative numbers from its response. If you passed duration_seconds here, the response also includes maxClipSeconds and wholeVideoFits (true when one clip covers the entire video, so there is nothing to ask the user). Ask YOUR USER which segment matters only when the video is longer than one clip can cover. The full video stays in the Asset Library either way. The staged object is removed whether validation passes or fails, so a failed finalize means starting over with a fresh media_upload.
meta_feedback_send
ChatGPTSend product feedback about Roboflow to the Roboflow team. Records a bug report, missing-feature request, UX friction note, or documentation issue against the current workspace. Use when the user wants to report a problem with Roboflow or send feedback. Returns confirmation that the feedback was recorded.
model_evals_compare
ChatGPTCompare 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_get
ChatGPTGet the top-level summary for a single model evaluation. Returns the eval metadata plus a `summary of mAP / precision / recall on done evals, and an app_url deep link into the UI panel. The modelUrl field is the resolvable public model id (feed it to models_get / models_infer); modelId` is the eval's internal id.
model_evals_get_confidence_sweep
ChatGPTGet the precision/recall/F1 confidence sweep for an eval. For each split returns `perThreshold (metrics keyed by threshold like "0.20"), the optimalThreshold and optimalMetrics, and perClass` sweeps.
model_evals_get_confusion_matrix
ChatGPTGet the confusion matrix for an eval. Returns `{split, confidenceThreshold, classes, matrix} where matrix[actual][predicted]` is the count.
model_evals_get_image_predictions
ChatGPTGet per-image prediction stats for an eval (paginated). Returns `{split, confidenceThreshold, totalImages, offset, limit, images: [...]}`. Each image carries TP/FP/FN counts, precision, recall, F1, the assigned cluster, and a per-class confusion list.
model_evals_get_map_results
ChatGPTGet per-split mAP results for an eval. Returns `{splits: {train, valid, test}} where each split has overall map50 / map50_95 / map75, byObjectSize (small/medium/large), and perClass` breakdowns.
model_evals_get_performance_by_class
ChatGPTGet per-class performance metrics for a single split. Returns `{split, classes: [{className, map50, map50_95, map75, precision, recall, f1, optimalThreshold}, ...]}`.
model_evals_get_recommendations
ChatGPTGet the LLM-generated recommendations for an eval, if available. Returns `{generated: false} until the recommendations job has run. When ready, returns {generated: true, generatedAt, recommendations: {summary, items}}`.
model_evals_get_vector_analysis
ChatGPTGet UMAP + HDBSCAN clustering of image embeddings for an eval. Returns `{clustering, preprocessing, clusters: [...]} — useful for finding pockets of poor-performing images. Each cluster carries numImages, splitDistribution`, F1 stats, and sample image refs.
model_evals_list
ChatGPTList model evaluations in the current workspace. Returns `{evals: [...]} where each entry has evalId, status, project (URL slug), versionId, modelId, modelUrl, and createdAt. Use model_evals_get for the headline summary (mAP/precision/recall) on a specific eval. Two model identifiers are returned and they are NOT interchangeable: modelId is the eval's internal id (the model_id filter key here); modelUrl is the resolvable public id that models_get / models_infer accept and that joins to models_list[].url and trainings_get results. At most one of project_id / version_number / model_id` may be set per call (most-specific wins). Combinations return 400.
models_custom_weights_upload_guide
ChatGPTGet 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_get
ChatGPTGet details for a trained model.
models_infer
ChatGPTRun hosted inference on an image using a trained model. The model id is passed straight to the inference server, which resolves the model and its task from the id — no project-type derivation is needed. Returns JSON predictions only. For visualized/annotated images, run a Workflow with a visualization block instead.
models_list
ChatGPTList trained models associated with a project. Returns `{models, total, returned, limit, offset, truncated}. Each row carries metrics, and (for NAS children) nasFamily and group, plus a derived recommended flag when the model is the recommended pick for any (metric, hardware) bucket on its parent version. metrics is sparse and its keys depend on the run. An ordinary training carries accuracy only, e.g. {map50, precision, recall, f1}. latency and paretoOptimalFor come from NAS mining, so they appear on NAS children and not on ordinary trainings; metrics may also be null. Do not assume a key is present - read what is there. Two shapes of NAS child are in the data. Newer runs report latency as a map keyed by target hardware (e.g. {"AI1": 6.69, "T4": 1.98}) and paretoOptimalFor entries as "<hardware>:<metric>" (e.g. "T4:map_50_95"). Older runs report a scalar latency with a sibling metrics.hardware (e.g. "gpu") and bare-metric paretoOptimalFor entries (e.g. "map_50"). Branch on the type of latency rather than indexing it. recommended is the flattened union of the platform's per-hardware winners, so more than one row in a group carries it and it cannot tell you which hardware a child won; paretoOptimalFor is frontier membership, not the recommendation. The authoritative map, recommendedByHardware, exists only on legacy version-based summaries and is absent from modern MMPV runs. NAS children with nasFamily: "baseline" are stock RF-DETR models trained on the same data; they carry no paretoOptimalFor and are never recommended. A project with NAS runs can have hundreds of models, so the result is always bounded: filter with version_number and/or group=<modelGroup> (the canonical "list NAS models per run" path), and page with limit/offset. truncated` is true when more rows remain past the page.
models_star_nas
ChatGPTStar or unstar a NAS-trained model. NAS-only by design — the server rejects non-NAS modelTypes with a `MODEL_NOT_NAS` error. Starring triggers TRT compilation for the model's recommended hardware so the model becomes deployable as an edge target.
project_deployment_configure_active_learning
ChatGPTConfigure how a Project Deployment collects Active Learning data.
project_deployment_disable_active_learning
ChatGPTPause Active Learning collection for a Project Deployment.
project_deployment_enable_active_learning
ChatGPTEnable Active Learning for a Project Deployment.
project_deployment_get
ChatGPTGet the stable live endpoint state for a project.
project_deployment_launch
ChatGPTCreate or prepare a stable Project Deployment. Use this when the user wants to deploy a project, bootstrap an empty dataset with SAM3/CLIP, collect production data, or start Active Learning before a custom model has been trained. Also use it for greenfield "detect/segment/classify X" requests when the user has not provided a dataset yet; for example, "I want to detect forklifts" should surface a SAM3 + Active Learning Project Deployment as the recommended path before the classic train-first dataset flow.
project_deployment_list_review_queues
ChatGPTList Active Learning review queues fed by production inference.
project_deployment_run
ChatGPTRun inference through the project's stable live endpoint.
project_deployment_set_model
ChatGPTChange the default model behind a Project Deployment without changing its endpoint.
projects_create
ChatGPTCreate a new computer vision project, including Action Recognition. Action Recognition projects are video-only. The annotation group is not private to the project: projects that use the same group share annotations on the images they have in common. If another project already uses the name, including a project in the Trash, the new project silently joins that group: images uploaded to it that are already stored in the workspace come with their annotations from that group, and uploading them with annotations fails with "Image was already annotated" unless image_upload's annotation_overwrite is set. Unless the user wants shared annotations, check the annotation values from projects_list and trash_list first and pick a name no other project uses. Returns the created project's id, name, type, and url.
projects_delete
ChatGPTDelete 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_fork
ChatGPTEnqueue an async fork of a public Universe project into your workspace. Provide either a Universe url or source_project. Returns the platform's 202 payload verbatim — at minimum { taskId, url }, where url points at the async-task polling endpoint. Poll completion with async_tasks_get(task_id=taskId) every 5 seconds until status is terminal (completed or failed). Processing may take up to 30 seconds to start.
projects_get
ChatGPTGet detailed info about a project including versions, classes, splits, and trained models. Returns full project details with workspace, project info, versions, and classes.
projects_health
ChatGPTGet dataset health check for a project. Running this for the first time or with regenerate=True might take up to a couple minutes. Returns class balance, image quality issues, annotation statistics, and other dataset health metrics.
projects_list
ChatGPTList projects in the workspace associated with the credential. Returns `{ projects, total, limit, offset } where projects holds up to limit entries (id, name, type, image count, and more) and total is the full workspace project count. Page with offset when total exceeds limit`.
trainings_cancel
ChatGPTCancel an in-flight training run. Works for any architecture. For NAS runs the underlying handler accepts the `mining` status — same call cancels mining or training phases.
trainings_create
ChatGPTCreate 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_delete
ChatGPTDelete 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_describe_recipe
ChatGPTDescribe 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_get
ChatGPTGet a training's status, produced models, and metrics. With `training_id, returns that run: { trainingId, status, createdAt, modelType, modelGroup, modelCount, models: [ { modelId, nasFamily, metrics, recommended }, ... ], recommendedByHardware?, mining? }. createdAt is when the run was launched (ISO 8601 UTC), or null if unknown. Statuses are surfaced verbatim — 'failed', 'cancelled', and 'stopped' are distinct. Without training_id: returns the version's sole run, or all runs when a version owns several trainings. Multi-run responses are sorted oldest-to-newest by launch time. For headline metrics (mAP/precision/recall) on a specific model, use model_evals_list to find the version's evaluations and then model_evals_get and its siblings. Those tools require the model-eval:read scope, so eval lookup is deliberately kept out of this tool — monitoring a run only needs version:read`. For full per-model metadata on a NAS run, call models_list with the returned modelGroup.
trainings_list
ChatGPTList the trainings on a dataset version. A version may own many trainings. Returns one entry per run: `{ trainingId, status, createdAt, modelType, modelGroup, modelIds }. createdAt is when the run was launched (ISO 8601 UTC), or null if unknown. Entries are sorted oldest-to-newest by createdAt. Statuses are surfaced verbatim (e.g. 'finished', 'failed', 'cancelled', 'stopped', 'running'). Pick a trainingId` and pass it to trainings_get, trainings_cancel, or trainings_stop.
trainings_stop
ChatGPTRequest an early stop on an in-flight training run. Distinct from cancel: the run finishes the current phase gracefully (mining or training) instead of terminating immediately.
trash_list
ChatGPTList soft-deleted items currently in the workspace Trash. Deleted projects, versions, workflows, and trainings stay in the Trash for 30 days before permanent removal. Use the returned item type and document id with the matching `trash_restore_*` tool to recover an item.
trash_restore_project
ChatGPTRestore a soft-deleted project from the workspace Trash. Undoes `projects_delete` while the project is still within its 30-day retention window.
trash_restore_training
ChatGPTRestore a soft-deleted training run from the workspace Trash. Undoes `trainings_delete` while the training is still within its 30-day retention window.
trash_restore_version
ChatGPTRestore a soft-deleted dataset version from the workspace Trash. Undoes `versions_delete while the version is still within its 30-day retention window. parent_id` is the parent project's document id.
trash_restore_workflow
ChatGPTRestore a soft-deleted workflow from the workspace Trash. Undoes `workflows_delete` while the workflow is still within its 30-day retention window.
universe_dataset_images_search
ChatGPTSearch images inside a public Universe dataset given its URL. Accepts a full Universe dataset URL and derives the workspace and project slugs from it before searching the dataset's images.
universe_search
ChatGPTSearch Roboflow Universe for datasets or models. The query supports operators mixed with free-text: - Add 'model' to only return datasets with trained models - 'class:helmet,person' filters by class names - 'images>500' filters by image count (also >=, <, <=) - 'sort:stars' sorts results (stars, images, downloads, views, updated) - 'object detection' filters by project type - 'updated:30d' filters by recency Example: 'fire smoke class:fire,smoke images>200 model sort:stars'
versions_delete
ChatGPTDelete 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_export
ChatGPTCheck or trigger a dataset export for a version.
versions_generate
ChatGPTCreate a new dataset version with optional preprocessing and augmentation. Preprocessing and augmentation choices are user decisions: confirm the desired options with the user before generating rather than assuming defaults. This operation can take several minutes for large datasets. Returns the generated version number, image count, and split sizes.
versions_get
ChatGPTGet info about a dataset version including splits and its trainings. Returns version details with id, name, images, splits, preprocessing, augmentation, and a `trainings summary (one entry per training on the version: trainingId, status, modelType, modelGroup, modelIds). Use trainings_get for a single run's detail and metrics. Readiness fields report generation state for callers that need to poll: generating is true only while generation looks actively in progress, and ready is true once generation is not active AND at least one train/valid/test split count is present. Generation usually takes several minutes and can take up to about an hour on large datasets, with progress stuck at 0 or null for most of that wait: that is normal, not stuck. Poll this tool roughly once a minute until ready is true. Trainability floors (min images per split, labels, NAS mins) are enforced by the platform train endpoint; if ready` is false only because splits are empty/insufficient, waiting will not help. Call trainings_create and surface that error.
video_segments_annotate
ChatGPTAnnotate one Action Recognition video Source with a complete video-coco document. Use the final videoId from upload status. Preserve the video's native PTS, frame indices, and rational time base. The API creates unknown classes unless the project locks them. It controls overwrite, split, and Dataset membership. No training starts.
video_upload
ChatGPTPrepare a signed URL for uploading one local video (MP4 or MOV) into a project. Use this to put a video into a project, for example an Action Recognition project you will label with video_segments_annotate. This tool does not read or upload local files: the client HTTP PUTs the bytes to the returned signed URL. The MCP server never receives file bytes. Returns signedUrl, requiredHeaders, videoId, and client-side instructions. Remaining steps after this returns (detailed in the response instructions): 1. HTTP PUT the raw video file to signedUrl with every requiredHeaders entry plus a Content-Type header. 2. Poll video_upload_status(video_id) every few seconds until status is "uploaded" or "failed". Use the videoId from the "uploaded" response. Re-uploading identical bytes creates no new video. It updates the existing one instead: its split and metadata change to this call's values and the tags are added. Up to 3 GB per video. Signed URL expires in 1 hour.
video_upload_status
ChatGPTCheck the ingestion status of a video uploaded with video_upload. Use after the video has been PUT to the signed URL (video_upload step 1). Poll every 3-5 seconds while status is "pending"; "uploaded" and "failed" are terminal, and "failed" includes a message. When status is "uploaded", the response videoId is the final video ID (the canonical Source ID). Pass that videoId to video_segments_annotate. It can differ from the id you polled with: when an identical video already existed, the upload is deduplicated, duplicate is true, and videoId names the existing video. That video takes the split and metadata of the new upload, gains its tags, and resolvedBatch is null. Otherwise resolvedBatch names the batch the video joined.
vision_events_custom_metadata_schema_get
ChatGPTGet the custom-metadata schema discovered for a use case. Custom metadata is arbitrary key/value data attached to events at ingestion time. This returns the fields seen so far and their value types, which is what you need to build `customMetadataFilters for vision_events_query. Keys attached to individual images (images[].metadata) are listed separately by vision_events_image_metadata_schema_get. Returns {useCaseId, fields} where fields` maps each field name to the value types observed for it (string, number, and/or boolean).
vision_events_image_metadata_schema_get
ChatGPTGet the per-image metadata schema discovered for a use case. Per-image metadata is key/value data attached to an individual image inside an event (for example the camera or station that captured it), as opposed to the event-level `customMetadata covered by vision_events_custom_metadata_schema_get. In vision_events_query results it appears on each image as images[].metadata. This returns the keys seen so far and their value types, which is what you need to build imageMetadataFilters for vision_events_query. Returns {useCaseId, fields} where fields maps each key to the value types observed for it (string, number, and/or boolean). A key holding date-like strings may instead report a raw storage type such as DateTime64(9); such a key is not returned in images[].metadata and cannot be used in imageMetadataFilters`.
vision_events_query
ChatGPTQuery production vision events for a use case, with filters and pagination. This is the primary tool for answering questions like "what safety alerts fired in the last week?" or "how many failed quality checks did device X report yesterday?". Combine `start_time/end_time with event_types for time-bounded reporting, then page with cursor. Returns {events, nextCursor, hasMore, lookbackDays}. hasMore is true when more pages exist; pass nextCursor back as cursor to fetch them. lookbackDays is the workspace's maximum history window, queries cannot see events older than that regardless of start_time. Each event generally carries eventId, eventType, timestamp, eventData (type-specific), images with their detections, and event-level customMetadata. Each image may also carry its own metadata, a flat map of per-image keys (string, number, or boolean values) returned as images[].metadata. Fields such as deviceId, streamId, workflowId, and displayImagePosition appear only when set on the event. The use case is not echoed back per event because the result is already scoped to the use_case_id you passed, so don't rely on a useCaseId/solution field being present on each event. To filter on metadata, discover the keys first: vision_events_custom_metadata_schema_get lists the event-level keys for customMetadataFilters and vision_events_image_metadata_schema_get lists the per-image keys for imageMetadataFilters. Pass either list through additional_filters. An imageMetadataFilters item matches an event when any of its images satisfies it, while neq/not_in` match only when none of its images does.
vision_events_saved_filter_create
ChatGPTSave a named filter for a use case, shared with the whole workspace. Everyone in the workspace sees it in the use case's Search tab. Needs the Create Vision Events permission. A use case holds at most 100 saved filters; a duplicate name or a full use case is refused with a 409. Returns `{savedFilter}`.
vision_events_saved_filter_delete
ChatGPTDelete a saved filter for everyone in the workspace. Allowed for the person who saved it, or with `vision-events:manage and the Manage Vision Events permission. A plain API key is never the person who saved a filter, so with one this needs vision-events:manage. Events are not affected. Returns {success}`.
vision_events_saved_filter_get
ChatGPTGet one saved filter. Returns `{savedFilter}`.
vision_events_saved_filter_update
ChatGPTRename a saved filter, save over its filters, or both. Saving over replaces the filter's chips for everyone in the workspace and needs `vision-events:write with the Create Vision Events permission; it works on any saved filter, and changing someone else's is recorded in the workspace audit log. Renaming needs the person who saved the filter, or vision-events:manage with the Manage Vision Events permission. A plain API key is never the person who saved a filter, so with one, renaming needs vision-events:manage. Returns {savedFilter}`.
vision_events_saved_filters_list
ChatGPTList the filters saved for a use case. Saved filters are named Search-tab filter sets, shared with the whole workspace. Run one with `vision_events_query and its saved_filter_id. Returns {savedFilters}, sorted by name. Each carries id, name, filters (the chips, in the shape described on vision_events_saved_filter_create), createdBy and updatedBy (user ids), and createdAt/updatedAt`.
vision_events_use_case_archive
ChatGPTArchive a vision-event use case. Sets the use case to `inactive: it is hidden from the default active listing and incoming events for it are rejected at ingestion, so this can disrupt a live pipeline. The use case and its existing events are preserved and it can be restored with vision_events_use_case_unarchive. Returns {success}`.
vision_events_use_case_create
ChatGPTCreate 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_rename
ChatGPTRename an existing vision-event use case. Only the display name changes; the `id and all associated events are preserved. Returns {id, name}`.
vision_events_use_case_unarchive
ChatGPTRestore a previously archived vision-event use case. The reverse of `vision_events_use_case_archive; the use case returns to the default active listing. Returns {success}`.
vision_events_use_cases_list
ChatGPTList the vision-event use cases in the workspace. Use cases are the logical buckets events are grouped under; every query is scoped to one. Call this first to discover the `id values to pass as use_case_id to vision_events_query. Returns {useCases, lookbackDays}. Each use case reliably carries id (the value to pass as use_case_id elsewhere), name, and status`; other fields (timestamps, and any per-use-case counts or event-type summaries) may or may not be present depending on the workspace, so treat them as optional rather than guaranteed.
workflow_evals_bindings_suggest
ChatGPTPropose a BindingSet mapping a Spec's inputs/outputs onto a Workflow Subject. Returns the proposal and the normalized `workflowSubject`. Nothing is saved; show the proposal to the user and confirm it with workflow_evals_bindings_validate. Saved Workflow Subjects also need workflow:read.
workflow_evals_bindings_validate
ChatGPTValidate a BindingSet against a Spec, Dataset, and Subject. Returns `{valid, diagnostics, ...}` with the planned capture contract. A valid BindingSet is what an Eval Run executes against. Saved Workflow Subjects also need workflow:read.
workflow_evals_case_assets_upload
ChatGPTStart uploading a local image as Case input. The MCP server never receives bytes. Returns `{uploadId, artifactId, uploadUrl, requiredHeaders, expiresInSeconds} and instructions. Then: 1. HTTP PUT the file bytes to uploadUrl with exactly requiredHeaders. 2. Call workflow_evals_case_assets_upload_complete(eval_dataset_id, upload_id). 3. Use {'artifactId': ...}` as the image input in workflow_evals_cases_create.
workflow_evals_case_assets_upload_complete
ChatGPTVerify 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_imports_get
ChatGPTPoll a Case import. `status is queued, running, completed, partially_completed, failed, or cancelled; progress` has discovered, processed, adopted, failed, total. List Cases with workflow_evals_cases_list while it runs.
workflow_evals_case_preparations_cases
ChatGPTList candidate outputs per Case. Each success has a short-lived `candidateOutput.readUrl. Fetching readUrl` returns the raw Workflow output keyed by output name.
workflow_evals_case_preparations_get
ChatGPTGet a Case preparation's state and progress (current one when no ID is given). Returns `{}` when the Eval has no current preparation.
workflow_evals_cases_create
ChatGPTAdd 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_delete
ChatGPTRemove a Case from the live Dataset. Runs that already froze it stay readable.
workflow_evals_cases_get
ChatGPTGet one complete Case with short-lived read URLs for its assets and its `revision`.
workflow_evals_cases_import
ChatGPTBulk-import images from Roboflow sources, project datasets, or uploaded artifacts. Returns 202 `{intakeId, asyncTaskId, status, pollUrl}`; poll with workflow_evals_case_imports_get. Imported Cases start with incomplete ground truth and cannot be run until it is filled in (workflow_evals_cases_replace). At most 10,000 Cases per intake. Source imports need image:read; dataset imports need project:read and image:read.
workflow_evals_cases_list
ChatGPTList Cases in an Eval Dataset (summaries, no media bytes).
workflow_evals_cases_replace
ChatGPTReplace a Case atomically (full replacement, not a field patch). Read workflow_evals_cases_get first and preserve its name, groundTruthState, slices, and evidenceRefs unless deliberately changing them. Set ground_truth_state to complete only when approving the ground truth. Runs that froze the Case keep their copy.
workflow_evals_create
ChatGPTCreate 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_datasets_compatible_specs
ChatGPTList Specs whose input and ground-truth requirements this Dataset satisfies.
workflow_evals_datasets_create
ChatGPTCreate 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_get
ChatGPTGet an Eval Dataset and its derived summary (no Cases inline) plus `revision`.
workflow_evals_datasets_list
ChatGPTList Eval Datasets with declared contracts, Case counts, slices, and completeness.
workflow_evals_datasets_update
ChatGPTUpdate Eval Dataset metadata (name/description).
workflow_evals_datasets_update_contract
ChatGPTReplace 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_delete
ChatGPTDelete 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_embeddings_cancel
ChatGPTRequest cooperative cancellation of an embedding job.
workflow_evals_embeddings_get
ChatGPTGet embedding analysis jobs. Never launches analysis. With `provider or async_task_id, returns {job} (job is null when none exists). With neither, returns {jobs: {<provider>: job | null}} for every provider, plus errors: {<provider>: message} for providers that could not be read. Completed jobs have result.url: a file with 2D points per Case (coordinates 8..92) plus skipped` Cases. New Runs start these jobs on their own.
workflow_evals_embeddings_start
ChatGPTGenerate (or reuse) a 2D embedding projection of an Execution's input images. New Runs schedule this automatically; use it for older Runs or explicit retries. Returns the job; poll with workflow_evals_embeddings_get.
workflow_evals_executions_configuration
ChatGPTGet an Execution's frozen Subject manifest, BindingSet, and linked plan.
workflow_evals_executions_get
ChatGPTGet one Execution's lifecycle, frozen Subject identity, and result availability.
workflow_evals_executions_input_cases
ChatGPTPage through an Execution's input Cases for a client-owned (local) runner. Only needed when the Run uses a local runtime. Each item has the `case, shardIndex, and checkpoint (absent means not yet submitted); artifactReadUrls` holds short-lived input image URLs. Run inference yourself, then submit each output with workflow_evals_executions_submit_capture.
workflow_evals_executions_list
ChatGPTList a Run's Executions (one per evaluated Workflow Subject).
workflow_evals_executions_submit_capture
ChatGPTSubmit one Case's Workflow output from a local runner. The platform scores it. Identical repeats are idempotent; different bytes for the same attempt return 409; a stale attempt returns 412.
workflow_evals_exports_download_url
ChatGPTGet a fresh short-lived download URL for a completed export.
workflow_evals_exports_get_job
ChatGPTPoll an export. `{asyncTaskId, state, progress, result?}; result` has the artifact and download URL.
workflow_evals_exports_start
ChatGPTStart 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_get
ChatGPTGet one Eval by ID or by its readable URL (exactly one). Returns setup `state and diagnostics, current Spec/Dataset projections, subjects, subjectBindings, serverConfiguration, recent Runs, and the revision` used for updates.
workflow_evals_list
ChatGPTList Evals in the workspace, newest first. Returns `{items, nextCursor?}. Items include setup state (draft/ready), runCount, and lastRunAt`.
workflow_evals_operation_get
ChatGPTPoll a Workflow Evals deletion operation. Returns a sanitized receipt `{operationId, kind, state, resource}`, readable even after the deleted resource is gone.
workflow_evals_results_case_get
ChatGPTGet one Case's result: inputs, frozen ground truth, bound actual values, and Check results. The raw Workflow output is omitted by default (`rawOutputOmitted: true); the values the Checks scored are in actualValues and caseResult.boundOutputs`.
workflow_evals_results_cases_list
ChatGPTList per-Case results for an Execution with compact `checkResults by Check ID. Use failed_check=True` to find failures, then workflow_evals_results_case_get for details.
workflow_evals_results_compare
ChatGPTCompare 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_overview
ChatGPTGet an Execution's aggregate per-Check performance and runtime summary.
workflow_evals_runs_cancel
ChatGPTRequest cancellation of a queued or running Run. Idempotent.
workflow_evals_runs_configuration
ChatGPTGet a Run's frozen shared configuration: Spec, Dataset snapshot, and Case selection.
workflow_evals_runs_delete
ChatGPTDelete 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_get
ChatGPTGet a Run's lifecycle state, child Execution counts, and `retry eligibility. Poll this while the Run is active; refresh results once it is terminal. With wait_seconds the tool polls for you and returns early when the state is one of completed, partially_completed, failed, or cancelled`.
workflow_evals_runs_list
ChatGPTList an Eval's Runs, newest first. `limit=1` gives the latest Run.
workflow_evals_runs_rescore
ChatGPTScore retained Workflow outputs against a revised Spec without re-running Workflows. Creates a new derived Run. Incompatible Executions return rerun-required diagnostics.
workflow_evals_specs_compatible_datasets
ChatGPTList Eval Datasets whose inputs and ground truth satisfy a Spec.
workflow_evals_specs_create
ChatGPTValidate, 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_get
ChatGPTGet the current live Spec and its `revision`.
workflow_evals_specs_list
ChatGPTList live Specs in the workspace. Returns `{items, nextCursor?}`.
workflow_evals_specs_update
ChatGPTReplace a live Spec's policy and/or metadata. The full result is recompiled. Existing Runs keep the Spec they froze.
workflow_evals_specs_validate
ChatGPTValidate an unsaved Spec: compile diagnostics plus derived ground-truth requirements. Saves nothing.
workflow_evals_update
ChatGPTUpdate an Eval under optimistic concurrency. Omitted fields are preserved; `clear_fields sets fields to null. The response re-derives draft/ready`. Existing Runs never change.
workflow_specs_validate
ChatGPTValidate a Workflow JSON definition without executing it. Check whether a workflow definition is syntactically and semantically correct before saving or running it. Example workflow definition — detects objects, enlarges bounding boxes, crops, runs a second detection filtering for dogs, and classifies the breed only when exactly one dog is found: .. code-block:: json { "version": "1.0", "inputs": [ {"type": "WorkflowImage", "name": "image"} ], "steps": [ { "type": "ObjectDetectionModel", "name": "first_detection", "image": "$inputs.image", "model_id": "yolov8n-640" }, { "type": "DetectionsTransformation", "name": "enlarging_boxes", "predictions": "$steps.first_detection.predictions", "operations": [ {"type": "DetectionsOffset", "offset_x": 50, "offset_y": 50} ] }, { "type": "Crop", "name": "first_crop", "image": "$inputs.image", "predictions": "$steps.enlarging_boxes.predictions" }, { "type": "ObjectDetectionModel", "name": "second_detection", "image": "$steps.first_crop.crops", "model_id": "yolov8n-640", "class_filter": ["dog"] }, { "type": "ContinueIf", "name": "continue_if", "condition_statement": { "type": "StatementGroup", "statements": [ { "type": "BinaryStatement", "left_operand": { "type": "DynamicOperand", "operand_name": "prediction", "operations": [{"type": "SequenceLength"}] }, "comparator": {"type": "(Number) =="}, "right_operand": { "type": "StaticOperand", "value": 1 } } ] }, "evaluation_parameters": { "prediction": "$steps.second_detection.predictions" }, "next_steps": ["$steps.classification"] }, { "type": "ClassificationModel", "name": "classification", "image": "$steps.first_crop.crops", "model_id": "dog-breed-xpaq6/1" } ], "outputs": [ { "type": "JsonField", "name": "dog_classification", "selector": "$steps.classification.predictions" } ] } Key patterns shown above: - `$inputs.<name> references a workflow input. - $steps.<step_name>.<output> references another step's output. - ContinueIf enables conditional branching based on runtime values. - Steps can chain: detect → transform → crop → detect → classify. Returns validation status. A valid workflow returns {"status": "ok"}`. An invalid one returns error details.
workflows_create
ChatGPTCreate 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_delete
ChatGPTDelete 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_get
ChatGPTGet details for a saved workflow.
workflows_list
ChatGPTList saved workflows in the current workspace. Returns up to `limit workflows plus total, the full workspace workflow count. Page with offset when total exceeds limit`.
workflows_run
ChatGPTExecute a saved Workflow on one or more images. Runs a previously created Workflow against the provided images on the Roboflow serverless infrastructure. This always hits the latest published version of the workflow, never an unpublished draft. Images are processed synchronously; calls with many images take proportionally longer. Workflow blocks may send data to external services or change existing records. Execution therefore requires the same care as those configured actions. Returns workflow outputs as defined by the workflow's output blocks.
workflows_update
ChatGPTUpdate an existing saved Workflow's name and definition. Validate the config with workflow_specs_validate before updating. Validation and execution support OAuth and API-key connections with the required permissions. Block types and their schemas are in the roboflow://workflows/blocks resources. Use workflows_get to retrieve the current workflow first, then modify the config as needed.
agent_chat
Claudeagent_conversation_get
Claudeagent_conversations_list
Claudeagent_workflow_publish
Claudeannotation_batches_get
Claudeannotation_batches_list
Claudeannotation_jobs_create
Claudeannotations_save
Claudeasync_tasks_get
Claudeautolabel_job_get
Claudeautolabel_start
Claudedevices_create
Claudedevices_get
Claudedevices_get_config
Claudedevices_get_config_history
Claudedevices_get_default_config
Claudedevices_get_events
Claudedevices_get_logs
Claudedevices_get_telemetry
Claudedevices_list
Claudedevices_streams_get
Claudedevices_streams_list
Claudedevices_update_config
Claudeimage_upload
Claudeimage_upload_status
Claudeimages_batch_update_metadata
Claudeimages_search
Claudeimages_update_metadata
Claudeimages_workspace_search
Claudemeta_feedback_send
Claudemodel_evals_get
Claudemodel_evals_get_confidence_sweep
Claudemodel_evals_get_confusion_matrix
Claudemodel_evals_get_image_predictions
Claudemodel_evals_get_map_results
Claudemodel_evals_get_performance_by_class
Claudemodel_evals_get_recommendations
Claudemodel_evals_get_vector_analysis
Claudemodel_evals_list
Claudemodels_get
Claudemodels_get_training_status
Claudemodels_infer
Claudemodels_list
Claudemodels_star_nas
Claudemodels_train
Claudeprojects_create
Claudeprojects_fork
Claudeprojects_get
Claudeprojects_health
Claudeprojects_list
Claudetrainings_cancel
Claudetrainings_get_results
Claudetrainings_stop
Claudeuniverse_dataset_images_search
Claudeuniverse_search
Claudeversions_export
Claudeversions_generate
Claudeversions_get
Claudeworkflow_blocks_get_schema
Claudeworkflow_blocks_list
Claudeworkflow_specs_run
Claudeworkflow_specs_validate
Claudeworkflows_create
Claudeworkflows_get
Claudeworkflows_list
Claudeworkflows_run
Claudeworkflows_update
Claude
