Platform API OpenAPI
기계 판독 가능한 OpenAPI 사양이 포함된 Roboflow Platform API를 둘러보고 테스트하세요.
플랫폼 API를 다음에서 사용하세요 https://api.roboflow.com 워크스페이스, 프로젝트, 데이터셋, 학습, 워크플로 및 관련 리소스를 관리합니다.
Roboflow API 키로 다음에서 인증하세요 Authorization: Bearer 헤더 또는 api_key 쿼리 매개변수를 사용합니다. 참고 REST API로 인증하기.
모델 및 Workflow 실행 엔드포인트는 다음을 참조하세요 추론 서버 OpenAPI.
또한 원본 OpenAPI 문서를 다운로드할 수 있습니다.
워크스페이스 및 프로젝트
Checks your API key and returns the workspace it belongs to. Any valid key works, whatever its scopes. Without a key, the response explains how to send one. The endpoint answers every HTTP method the same way.
Roboflow API key or OAuth access token.
Successful response.
Confirms the key works, or explains how to send one when the request has no key.
URL slug of the workspace the key belongs to. Present only when the request has a valid key.
ID of the workspace the key belongs to. Present only when the request has a valid key.
The request is invalid.
The API key does not exist, was revoked, or is disabled.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The request rate is too high.
GET / HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"welcome": "Welcome to the Roboflow API.",
"instructions": "You are successfully authenticated.",
"docs": "https://docs.roboflow.com",
"workspace": "my-workspace",
"workspaceId": "Xy7AbCdEfGhIjKlMnOpQ"
}Returns the workspace and the projects your API key can list. Requires workspace:read. For a public Universe workspace that is not yours, only its public projects are returned.
Roboflow API key or OAuth access token.
Workspace URL slug.
Successful response.
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The request rate is too high.
GET /{workspace} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"workspace": {
"name": "Roboflow",
"url": "roboflow",
"members": 7,
"projects": [
{
"id": "roboflow/chess-sample-4ckfl",
"type": "object-detection",
"name": "Chess Sample",
"created": 1630335544.592,
"updated": 1630335741.988,
"images": 12,
"unannotated": 3,
"annotation": "pieces",
"versions": 3,
"public": false,
"multilabel": false,
"license": "Private",
"splits": {
"train": 9,
"valid": 2,
"test": 1
},
"colors": {
"white-king": "#C7FC00",
"black-king": "#8622FF"
},
"classes": {
"white-king": 8,
"black-king": 8
},
"preprocessing": {
"auto-orient": {
"enabled": true
}
},
"augmentation": {}
}
]
}
}Creates an empty project. Requires project:create. The URL slug is made from name and gets a random suffix when the slug is taken.
Roboflow API key or OAuth access token.
Workspace URL slug.
Display name. Letters, numbers, dashes, underscores, and spaces only.
Project type. The response reports both classification types as classification. anomaly-detection needs Anomaly Detection turned on for your workspace, creates a single-label classification project with the fixed classes normal and anomalous, and needs an annotation group that no other project type uses.
Annotation group: a noun for what you label (ex: sharks, defects). Projects in the same group share classes.
Private makes a private project, if your plan allows it. Any other value makes a public project on Roboflow Universe. Leave out for a private project. Required on public plans, which cannot create private projects.
ID of the project folder to create the project in.
The new project.
Workspace and project URL slugs joined by a slash.
Project type (ex: object-detection, classification, instance-segmentation).
Project display name.
Creation time in seconds since the Unix epoch.
Last update time in seconds since the Unix epoch.
Images in the project.
Images with no annotations.
Annotation group name.
Dataset versions generated from the project.
True when the project is public on Roboflow Universe.
True for multi-label classification projects.
Dataset license (ex: Private, CC BY 4.0).
Thumbnail shown for the project, or null when it has none.
Your plan does not allow private projects, or an anomaly-detection project cannot be created (the feature is off, or the annotation group is used by another project type).
Authentication is missing or invalid.
Public projects are turned off for this workspace.
The resource does not exist or is not accessible.
group is not an existing project folder.
name, type, annotation, or license is missing or invalid, or the workspace is not set up yet.
The request rate is too high.
POST /{workspace}/projects HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 93
{
"name": "Sharks Dataset",
"type": "object-detection",
"annotation": "sharks",
"license": "Private"
}{
"id": "my-workspace/sharks-dataset",
"type": "object-detection",
"name": "Sharks Dataset",
"created": 1688739471.567,
"updated": 1688739471.567,
"images": 0,
"unannotated": 0,
"annotation": "sharks",
"versions": 0,
"public": false,
"multilabel": false,
"license": "Private",
"splits": {},
"colors": {},
"classes": {}
}Starts a background task that copies a public Universe project's images and annotations into a new project in your workspace. The new project has no versions and no saved preprocessing or augmentation. On a Public plan, the new project is public. Poll the returned url, or Get Asynchronous Task Status, for the result. Requires project:create.
Roboflow API key or OAuth access token.
Workspace URL slug.
Send url or source_project.
Universe project URL. Extra path segments and query parameters are fine. The project slug is read from the second path segment.
Universe project URL slug. Takes precedence over url.
Accepted for asynchronous processing.
Asynchronous task ID.
URL to poll for the task status.
The request is invalid.
Authentication is missing or invalid.
The workspace does not have enough credits or image quota for the project's images.
The source project is not public.
No project has that slug, or the API key cannot access the workspace or lacks project:create.
Your workspace already owns the source project.
Neither url nor source_project was sent, or the url has no project slug.
The request rate is too high.
POST /{workspace}/projects/fork HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 87
{
"url": "https://universe.roboflow.com/roboflow-jvuqo/football-players-detection-3zvbc"
}{
"taskId": "Qm9yZWFsVGFzazEyMw",
"url": "https://api.roboflow.com/my-workspace/asynctasks/Qm9yZWFsVGFzazEyMw"
}Returns a project and its dataset versions, including the model trained on each version. Requires project:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Successful response.
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The request rate is too high.
GET /{workspace}/{project} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"workspace": {
"name": "Roboflow",
"url": "roboflow",
"members": 7
},
"project": {
"id": "roboflow/chess-sample-4ckfl",
"type": "object-detection",
"name": "Chess Sample",
"created": 1630335544.592,
"updated": 1630335741.988,
"images": 12,
"unannotated": 3,
"annotation": "pieces",
"versions": 3,
"public": false,
"multilabel": false,
"license": "Private",
"splits": {
"train": 9,
"valid": 2,
"test": 1
},
"colors": {
"white-king": "#C7FC00",
"black-king": "#8622FF"
},
"classes": {
"white-king": 8,
"black-king": 8
},
"preprocessing": {
"auto-orient": {
"enabled": true
}
},
"augmentation": {}
},
"versions": [
{
"id": "roboflow/chess-sample-4ckfl/1",
"name": "augmented",
"created": 1630335698.746,
"images": 30,
"splits": {
"train": 27,
"valid": 2,
"test": 1
},
"generating": false,
"progress": 1,
"model": {
"id": "chess-sample-4ckfl/1",
"start": 1630335799.682,
"end": 1630337523.889,
"fromScratch": false,
"tfjs": true,
"oak": true,
"map": "62.87",
"recall": "85.29",
"precision": "23.44"
},
"preprocessing": {
"resize": {
"enabled": true,
"format": "Stretch to",
"width": 416,
"height": 416
}
},
"augmentation": {
"flip": {
"enabled": true,
"horizontal": true,
"vertical": false
}
},
"exports": [
"yolov5pytorch"
],
"notes": "Fix: rotated box misalignment"
}
]
}Moves a project to Trash and cancels any training in progress on it. Requires project:update.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Successful response.
Always true.
Workspace URL slug.
Project URL slug.
Project ID. Pass it as the restore id.
Always true: the project is in Trash, not permanently deleted.
The request is invalid.
Authentication is missing or invalid.
The project belongs to another workspace.
The resource does not exist or is not accessible.
The request rate is too high.
DELETE /{workspace}/{project} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"deleted": true,
"type": "project",
"workspace": "my-workspace",
"project": "my-detector",
"projectId": "d_abc123",
"trash": true
}Returns the Dataset Health Check report for a project: image and annotation counts, class balance overall and per split, and the object count histogram. Heatmaps and per-image data are left out. Requires project:read. Any API key can read the report of a public project.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Set to true to recompute the report. Otherwise you get the last computed report, and it is computed only when none exists.
Successful response.
When the report was computed, in milliseconds since the Unix epoch.
Report format version.
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The request rate is too high.
GET /{workspace}/{project}/health HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"generated": 1793369145612,
"version": 3,
"stats": {
"images": 524,
"annotated": 524,
"unannotated": 0,
"empty": 0,
"labels": 4668,
"average": "8.9",
"singleClass": 0,
"multiClass": 0,
"numClasses": 2,
"classes": [
{
"count": 941,
"percent": "100.0",
"cls": "fair",
"description": "",
"name": "needle"
},
{
"count": 412,
"percent": "43.8",
"cls": "under",
"description": "Under Represented",
"name": "dial"
}
],
"classesBySplit": {
"train": [
{
"count": 820,
"percent": "100.0",
"cls": "fair",
"description": "",
"name": "needle"
},
{
"count": 360,
"percent": "43.9",
"cls": "under",
"description": "Under Represented",
"name": "dial"
}
],
"valid": [
{
"count": 121,
"percent": "100.0",
"cls": "fair",
"description": "",
"name": "needle"
},
{
"count": 52,
"percent": "43.0",
"cls": "under",
"description": "Under Represented",
"name": "dial"
}
],
"test": [
{
"count": 0,
"percent": "0.0",
"cls": "missing",
"description": "Missing",
"name": "needle"
},
{
"count": 0,
"percent": "0.0",
"cls": "missing",
"description": "Missing",
"name": "dial"
}
]
},
"histogram": {
"all": {
"1": 2,
"5": 229,
"10": 151
},
"needle": {
"1": 244,
"2": 188
},
"dial": {
"1": 239,
"2": 85
}
}
}
}Returns every trained model in a project: models trained on a dataset version and models that are not tied to one, such as Neural Architecture Search results. Requires model:infer.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Neural Architecture Search run ID. Returns only the models from that run, or an empty array when none match.
pVYKOWUB6AUIVJMgPc7u-410-rfdetrNasGroupSuccessful response.
Model ID to use for inference.
Dataset version the model was trained on. Not set for models that are not tied to a version.
Task the model performs (ex: object-detection).
Model architecture and size (ex: rfdetr-base).
Model display name.
Creation time.
child for models found by Neural Architecture Search, null for the baseline. Neural Architecture Search models only.
Neural Architecture Search run ID, shared by every model from the run.
True when anyone in the workspace starred the model. Neural Architecture Search models only.
Present and true when the model is the recommended pick for at least one metric and hardware target.
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The request rate is too high.
GET /{workspace}/{project}/models HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
[
{
"url": "my-project/3",
"version": "3",
"train": {
"status": "finished"
},
"taskType": "object-detection",
"modelType": "rfdetr-base",
"name": "My Model",
"created": "2026-04-01T00:00:00.000Z",
"metrics": {
"map50": 91,
"precision": 88,
"recall": 85
}
}
]Returns one dataset version with its project, its model, and its training runs. Use it to poll a new version until generating is false. Requires version:read. For a public Universe project, any API key can read it.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Dataset version number.
Successful response.
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
The version does not exist, or the API key cannot access it or lacks version:read.
The request rate is too high.
GET /{workspace}/{project}/{version} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"workspace": {
"name": "Roboflow",
"url": "roboflow",
"members": 7
},
"project": {
"id": "roboflow/chess-sample-4ckfl",
"type": "object-detection",
"name": "Chess Sample",
"created": 1630335544.592,
"updated": 1630335741.988,
"images": 12,
"unannotated": 3,
"annotation": "pieces",
"versions": 3,
"public": false,
"multilabel": false,
"license": "Private",
"splits": {
"train": 9,
"valid": 2,
"test": 1
},
"colors": {
"white-king": "#C7FC00",
"black-king": "#8622FF"
},
"classes": {
"white-king": 8,
"black-king": 8
},
"preprocessing": {
"auto-orient": {
"enabled": true
}
},
"augmentation": {}
},
"version": {
"id": "roboflow/chess-sample-4ckfl/1",
"name": "augmented",
"created": 1630335698.746,
"images": 30,
"splits": {
"train": 27,
"valid": 2,
"test": 1
},
"generating": false,
"progress": 1,
"model": {
"id": "chess-sample-4ckfl/1",
"endpoint": "https://serverless.roboflow.com/chess-sample-4ckfl/1",
"start": 1630335799.682,
"end": 1630337523.889,
"fromScratch": false,
"tfjs": true,
"oak": true,
"map": "62.87",
"recall": "85.29",
"precision": "23.44"
},
"preprocessing": {
"resize": {
"enabled": true,
"format": "Stretch to",
"width": 416,
"height": 416
}
},
"augmentation": {
"flip": {
"enabled": true,
"horizontal": true,
"vertical": false
}
},
"exports": [
"yolov5pytorch"
],
"modelType": "yolov8n",
"trainings": [
{
"id": "yy60TvWABInXY1BKypIV/1/training/0",
"versionId": "1",
"status": "finished",
"start": 1630335799682,
"end": 1630337523889,
"jobType": "fine-tune",
"modelType": "yolov8n",
"modelGroup": null,
"modelIds": [
"chess-sample-4ckfl/1"
]
}
],
"classes": [
"black-king",
"white-king"
]
}
}Moves a dataset version to Trash. Any training in progress on the version is canceled. Requires version:update.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Dataset version number.
Successful response.
Always true.
Workspace URL slug.
Project URL slug.
Project ID. Pass it as the restore parentId.
Version number. Pass it as the restore id.
Always true: the version is in Trash, not permanently deleted.
The request is invalid.
Authentication is missing or invalid.
The version belongs to another workspace.
The resource does not exist or is not accessible.
The request rate is too high.
DELETE /{workspace}/{project}/{version} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"deleted": true,
"type": "version",
"workspace": "my-workspace",
"project": "my-detector",
"projectId": "d_abc123",
"version": "3",
"trash": true
}API 키
Lists the workspace's API keys with masked metadata, and returns the workspace publishable key. Requires api-key:read. With an OAuth token, the user's role must allow viewing workspace API keys (owners and admins by default).
Roboflow API key or OAuth access token.
Workspace URL slug.
Set to true to include disabled keys.
falseSet to true to add folder names (folders) to folder-scoped keys.
falseSuccessful response.
The workspace publishable key, rf_ followed by the workspace id.
The request is invalid.
Authentication is missing or invalid.
The OAuth user's role does not allow viewing API keys.
The credential lacks the route's scope or the workspace is not the credential's.
The request rate is too high.
GET /{workspace}/api-keys HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"apiKeys": [
{
"keyId": "9f8c1a2b3d4e5f60",
"name": "production-server",
"prefix": "abcd",
"scopes": [
"model:infer"
],
"folderIds": [],
"default": false,
"protected": true,
"disabled": false,
"created_on": "2026-06-19T18:24:01.000Z",
"rotationDueAt": "2027-06-19T12:00:00.000Z",
"owners": [
"user_abc123"
],
"created_by": "user_abc123",
"customMetadata": {
"env": "prod"
}
}
],
"publishableKey": "text"
}Creates an API key and returns its secret once in key. Requires api-key:create. The new key can never have more scopes or folders than the caller. Sending a scopes array, folderIds, customMetadata, rotationDueAt or owners requires Advanced API Keys; omitting scopes or sending null does not.
Roboflow API key or OAuth access token.
Workspace URL slug.
Every field is optional. An empty body creates a key with the caller's own scopes and folders. Unknown fields return 400.
Display name for the key.
Limits the key to these scopes. Omitted: the key gets the calling credential's own scopes, on every plan. A full-access caller creates a full-access key. null: an unscoped (full-access) key. The caller must have full access itself. []: a valid key with no abilities, which you can grant scopes to later. A list: exactly those scopes. A section name (ex: model) grants all of that section's scopes. A role preset (ex: role:reviewer, or a custom role's name after role:) expands to that role's scopes, and role:owner means full access. Presets combine with explicit scopes. Sending an array (including []) requires Advanced API Keys.
["model:infer"]Limits the key to these project folders. Omitted, the key gets the caller's folders. A key for every folder needs a caller who can see every folder. A non-empty list requires Advanced API Keys.
Creates the key protected. See Protecting a Key.
Rotation due date as an ISO date or date-time (UTC), strictly in the future (ex: 2027-10-22). The owners get one reminder email in the 15 days before it. Requires Advanced API Keys.
2027-10-22Member ids to remind before rotationDueAt. Omitted while signed in with Advanced API Keys, you become the only owner if you can roll the key yourself from an enabled account with an email address. Omitted with an API key, the list stays empty. Each id must be a member who can roll the key (see List Owner Candidates). An empty list reminds everyone who can roll the key. Requires Advanced API Keys.
Created.
The new key's non-secret handle.
The secret key value. Returned only in this response. Store it now: no endpoint returns it again.
Display name.
Stored scopes, after role presets and sections expand. null for a full-access key.
Folders the key is limited to.
True when the key is protected.
Rotation due date, or null.
Member ids reminded before the due date.
The workspace publishable key.
The body is invalid (ex: an unknown scope or role, an unknown field, malformed metadata, a past due date).
Authentication is missing or invalid.
The request asks for scopes or folders the caller does not hold, the plan lacks Advanced API Keys for a field you sent, or an OAuth caller's role does not allow the action.
The credential lacks the route's scope or the workspace is not the credential's. Also returned when a folderIds entry does not exist.
The request rate is too high.
POST /{workspace}/api-keys HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 107
{
"name": "production-server",
"scopes": [
"model:infer"
],
"rotationDueAt": "2027-10-22",
"owners": [
"user_abc123"
]
}{
"keyId": "9f8c1a2b3d4e5f60",
"key": "AbCdEf0123456789xyz",
"name": "production-server",
"scopes": [
"model:infer"
],
"folderIds": [],
"protected": false,
"rotationDueAt": "2027-10-22T00:00:00.000Z",
"owners": [
"user_abc123"
],
"publishableKey": "rf_5f3Tq8k2ZbW1aXyZ"
}Returns the workspace publishable key. Requires workspace:read. A folder-scoped key gets 404: read publishableKey from the list or create response instead.
Roboflow API key or OAuth access token.
Workspace URL slug.
Successful response.
rf_ followed by the workspace id. Not a secret: it can only run inference and download models.
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
The credential lacks the route's scope or the workspace is not the credential's. Also returned for a folder-scoped credential.
The request rate is too high.
GET /{workspace}/api-keys/publishable HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"publishableKey": "rf_5f3Tq8k2ZbW1aXyZ"
}Lists the members who can roll a key, which are the only members you can set as its owners. Requires api-key:create or api-key:update, and Advanced API Keys. You must be able to grant the key's folders.
Roboflow API key or OAuth access token.
Workspace URL slug.
The keyId of an existing key. Do not send with folderIds.
9f8c1a2b3d4e5f60Folder ids for a key you are about to create, comma-separated or repeated. Do not send with keyId. Send neither for a key that reaches every folder, which needs a caller who can see every folder.
folderA,folderBSuccessful response.
Both keyId and folderIds were sent.
Authentication is missing or invalid.
The plan lacks Advanced API Keys, the caller cannot grant the folders, or an OAuth caller's role does not allow the action.
No active key with that keyId in the workspace (including one that was already rolled or revoked), or the credential lacks the route's scope, or the workspace is not the credential's. A folder-scoped caller also gets 404 for a key outside its folders.
The request rate is too high.
GET /{workspace}/api-keys/owner-candidates HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"members": [
{
"uid": "user_abc123",
"email": "ada@example.com",
"name": "Ada"
}
]
}Returns masked metadata for one key. Requires api-key:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
The key's keyId handle, from the list response. Never the secret key value.
9f8c1a2b3d4e5f60Successful response.
The request is invalid.
Authentication is missing or invalid.
The OAuth user's role does not allow reading API keys.
No active key with that keyId in the workspace (including one that was already rolled or revoked), or the credential lacks the route's scope, or the workspace is not the credential's. A folder-scoped caller also gets 404 for a key outside its folders.
The request rate is too high.
GET /{workspace}/api-keys/{keyId} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"apiKey": {
"keyId": "9f8c1a2b3d4e5f60",
"name": "production-server",
"prefix": "abcd",
"scopes": [
"model:infer"
],
"folderIds": [],
"default": false,
"protected": true,
"disabled": false,
"created_on": "2026-06-19T18:24:01.000Z",
"rotationDueAt": "2027-06-19T12:00:00.000Z",
"owners": [
"user_abc123"
],
"created_by": "user_abc123",
"customMetadata": {
"env": "prod"
}
}
}Updates a key's name, scopes, metadata or rotation schedule, protects it, or disables or re-enables it. Requires api-key:update. Changing scopes, metadata, disabled, rotationDueAt or owners requires Advanced API Keys.
Roboflow API key or OAuth access token.
Workspace URL slug.
The key's keyId handle, from the list response. Never the secret key value.
9f8c1a2b3d4e5f60Send only the fields you want to change. Omitted fields stay as they are. An empty body or an unknown field returns 400.
New display name. Renaming needs no plan feature.
Replaces the key's scopes. null makes the key full access (the caller must have full access). [] leaves a valid key with no abilities. A list sets exactly those scopes; section names and role: presets expand as on create. The new scopes must be a subset of the caller's. Refused with 409 on a protected key. Requires Advanced API Keys.
["model:infer","project:read"]Send true to protect the key. false returns 403: you can only unprotect a key in the dashboard.
true disables the key, false re-enables it. Disabling a protected key, or a key that backs a Dedicated Deployment, returns 409. Requires Advanced API Keys.
Rotation due date as an ISO date or date-time (UTC), strictly in the future (ex: 2027-10-22). The owners get one reminder email in the 15 days before it. null clears it. The key's current date is accepted even when it is already past. Requires Advanced API Keys.
Replaces the members reminded before the due date. Each id must be a member who can roll the key (see List Owner Candidates). An empty list reminds everyone who can roll the key. Requires Advanced API Keys.
Successful response.
The body is empty or invalid (ex: an unknown scope, an unknown field, a past due date).
Authentication is missing or invalid.
The body sends "protected": false, asks for scopes the caller cannot grant, needs Advanced API Keys, or an OAuth caller's role does not allow the action.
No active key with that keyId in the workspace (including one that was already rolled or revoked), or the credential lacks the route's scope, or the workspace is not the credential's. A folder-scoped caller also gets 404 for a key outside its folders.
The key is protected and cannot be disabled or given new scopes, or it backs a Dedicated Deployment and cannot be disabled.
The request rate is too high.
PATCH /{workspace}/api-keys/{keyId} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 22
{
"name": "renamed-key"
}{
"apiKey": {
"keyId": "9f8c1a2b3d4e5f60",
"name": "production-server",
"prefix": "abcd",
"scopes": [
"model:infer"
],
"folderIds": [],
"default": false,
"protected": true,
"disabled": false,
"created_on": "2026-06-19T18:24:01.000Z",
"rotationDueAt": "2027-06-19T12:00:00.000Z",
"owners": [
"user_abc123"
],
"created_by": "user_abc123",
"customMetadata": {
"env": "prod"
}
}
}Revokes the key permanently. Anything that uses it fails to authenticate at once. Requires api-key:revoke.
Roboflow API key or OAuth access token.
Workspace URL slug.
The key's keyId handle, from the list response. Never the secret key value.
9f8c1a2b3d4e5f60Successful response.
The keyId you sent.
The request is invalid.
Authentication is missing or invalid.
The OAuth user's role does not allow revoking API keys.
No active key with that keyId in the workspace (including one that was already rolled or revoked), or the credential lacks the route's scope, or the workspace is not the credential's. A folder-scoped caller also gets 404 for a key outside its folders.
The key is protected, or it backs a Dedicated Deployment. Unprotect it in the dashboard, or give the deployment another key or roll the key instead.
The request rate is too high.
DELETE /{workspace}/api-keys/{keyId} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"status": "revoked",
"keyId": "9f8c1a2b3d4e5f60"
}Revokes the key and creates its replacement in one call, and returns the new secret once in key. The replacement keeps the key's name, scopes, folders, metadata and disabled state, and Dedicated Deployments on the key move to it. Requires both api-key:revoke and api-key:create, and the caller must hold at least the key's scopes and folders.
Roboflow API key or OAuth access token.
Workspace URL slug.
The key's keyId handle, from the list response. Never the secret key value.
9f8c1a2b3d4e5f60Optional rotation schedule for the replacement. Send no body to carry the old key's schedule over. Both fields require Advanced API Keys.
The replacement's rotation due date (ISO date or date-time, UTC, in the future), or null for none. Omitted, the replacement is due the same number of days after the roll as the old key was after its creation, up to one year. A key without a date stays without one.
The replacement's owners. Omitted, the old key's owners carry over. An empty list reminds everyone who can roll the key.
Successful response.
The replacement's new handle. Nothing links it to the old key afterwards, so store both ids if you need to trace the rotation.
The replacement's secret value. Returned only in this response.
Display name, kept from the old key.
Scopes, kept from the old key. null for full access.
Folders, kept from the old key.
Always false: a protected key cannot be rolled.
True when the old key was disabled. A disabled key rolls to a disabled key.
The replacement's rotation due date, or null.
The replacement's owners.
The keyId of the key that was revoked.
The body is invalid (ex: an unknown field or a past due date).
Authentication is missing or invalid.
The caller cannot grant the key's scopes or folders, the plan lacks Advanced API Keys for a field you sent, or an OAuth caller's role does not allow the action.
No active key with that keyId in the workspace (including one that was already rolled or revoked), or the credential lacks the route's scope, or the workspace is not the credential's. A folder-scoped caller also gets 404 for a key outside its folders. A second roll of the same keyId gets this once the first roll has finished.
The key is protected, another roll of it is in progress, it is disabled while it backs a Dedicated Deployment, or a Dedicated Deployment on it is still being created. The key was not rolled.
A Dedicated Deployment on the key belongs to a folder whose usage is paused, so it could not be moved. The key was not rolled.
The request rate is too high.
The deployment service failed while moving a Dedicated Deployment. The key was not rolled, but a replacement with the same name may exist. The error sets "retryable".
POST /{workspace}/api-keys/{keyId}/roll HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 55
{
"rotationDueAt": "2027-10-22",
"owners": [
"user_abc123"
]
}{
"keyId": "0a1b2c3d4e5f6071",
"key": "NewSecretValue0123456789",
"name": "production-server",
"scopes": [
"model:infer"
],
"folderIds": [],
"protected": false,
"disabled": false,
"rotationDueAt": "2027-10-22T12:00:00.000Z",
"owners": [
"user_abc123"
],
"revokedKeyId": "9f8c1a2b3d4e5f60"
}프로젝트 폴더
Lists the project folders your credential can see, or one folder when you pass groupId. A key scoped to a folder sees that folder and the folders inside it. An OAuth token sees the folders its user can read. Folder access settings (auth_groups) are not returned. Requires folder:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
Folder ID. Returns only that folder.
Fh2kQ8vLx0aZ1bC3dE4fSuccessful response.
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
The workspace has no folders you can see, or groupId is not one of them. The body is empty.
The request rate is too high.
GET /{workspace}/groups HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": [
{
"id": "Fh2kQ8vLx0aZ1bC3dE4f",
"name": "Client Demos",
"owner": "wPqR7sT2uV9xY4zA1bC6",
"external_id": "jfowke123jfiowje",
"projects": [
"client-demo-project-1",
"another-project"
],
"child_ids": [],
"hasDeviceConfigPatch": false,
"created_on": "2026-04-01T12:00:00.000Z",
"updated_on": "2026-04-02T09:30:00.000Z"
}
]
}Creates a project folder and moves the listed projects into it. When Billing Folders is on, the folder also gets its own API key. Requires folder:create. Workspaces can limit who creates top-level folders.
Roboflow API key or OAuth access token.
Workspace URL slug.
Folder name. It cannot be blank, and no other project or Workflow folder at the same level can use it. Names are compared without case and without leading or trailing spaces, so demos and Demos count as the same name.
ID of the folder to create this one in. Leave out for a top-level folder. A subfolder gets its parent's auth_groups when you do not set them.
Project URL slugs (ex: dog-breeds-mi53). Every project must belong to this workspace.
Your ID for the folder in an external system.
Created.
ID of the new folder.
The name is blank or already used at that level (ex: Folder name is required).
Authentication is missing or invalid, a listed project is not in this workspace, or you cannot create a top-level folder.
The credential does not have access to this resource.
parent_id is not a folder in this workspace.
The request rate is too high.
POST /{workspace}/groups HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 111
{
"name": "Client Demos",
"projects": [
"client-demo-project-1",
"another-project"
],
"external_id": "jfowke123jfiowje"
}{
"id": "Fh2kQ8vLx0aZ1bC3dE4f"
}Renames a folder, changes its external ID or permission groups, or moves it under another folder. Send at least one field. To move projects in or out, use the folder's projects endpoint. Requires folder:update.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project folder ID.
Set to true to return the updated folder in data.
New name, with the same rules as when you create a folder. An empty string is ignored and keeps the current name. A name of only spaces returns 400.
Your ID for the folder in an external system.
ID of the folder to move this one into, or null to move it to the top level of the workspace.
Successful response.
true, or with returnUpdated=true a one-item array with the updated folder as stored, including auth_groups.
No field was sent, or the name breaks the naming rules.
Authentication is missing or invalid, the folder belongs to another workspace, or you do not have write access to move it.
The credential does not have access to this resource.
The folder or the new parent folder does not exist.
The request rate is too high.
POST /{workspace}/groups/{folderId} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 21
{
"name": "A new name"
}{
"data": true
}Deletes a folder. Its projects, Workflows, and subfolders are not deleted: they move to the parent folder, or to the top level of the workspace. Its folder API keys are revoked. Requires folder:delete.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project folder ID.
The folder holds too much to delete in one step, so it is deleted in the background. Poll task with the async tasks endpoint.
Async task ID.
Deletion attempt marker.
Completed with no response body.
The request is invalid.
Authentication is missing or invalid, the folder belongs to another workspace, or you do not have write access to delete it.
The credential does not have access to this resource.
The folder does not exist.
The request rate is too high.
DELETE /{workspace}/groups/{folderId} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"task": "text",
"generation": null
}Moves one or more projects into the folder, out of wherever they were. Requires folder:update.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project folder ID.
Project URL slugs (ex: dog-breeds-mi53). Every project must belong to this workspace.
Completed with no response body.
No content
The request is invalid.
Authentication is missing or invalid, the folder belongs to another workspace, or a project is not in this workspace.
The credential does not have access to this resource.
The folder does not exist.
The request rate is too high.
PATCH /{workspace}/groups/{folderId}/projects HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 32
{
"projects": [
"dog-breeds-mi53"
]
}No content
Moves one or more projects out of the folder to the top level of the workspace, not to the parent folder. Requires folder:update.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project folder ID.
Project URL slugs (ex: dog-breeds-mi53). Every project must belong to this workspace.
Completed with no response body.
No content
The request is invalid.
Authentication is missing or invalid, the folder belongs to another workspace, or a project is not in this workspace.
The credential does not have access to this resource.
The folder does not exist, or none of the projects exist.
The request rate is too high.
DELETE /{workspace}/groups/{folderId}/projects HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 32
{
"projects": [
"dog-breeds-mi53"
]
}No content
데이터셋 버전 및 학습
Starts generating a new dataset version from the project's current images, with the preprocessing and augmentation you send. The options replace the project's saved generation settings: a step you leave out is off for this version and is cleared from the project. Generation runs in the background; poll Get a Dataset Version until generating is false. Requires version:create. The new images count against your plan's generated image quota or credits.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Version name. Defaults to the creation date and time.
Version notes.
Successful response.
Number of the new version. Use it as {version} in other calls.
An option is invalid, or the workspace does not have enough image quota or credits for the images this version would generate.
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
Usage is paused for the project's folder.
A version of this project is already generating, or image.versions is above your plan's limit.
The project is in Trash, or a split rebalance is still running.
POST /{workspace}/{project}/generate HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 215
{
"versionName": "640 stretch, flips",
"preprocessing": {
"auto-orient": true,
"resize": {
"width": 640,
"height": 640,
"format": "Stretch to"
}
},
"augmentation": {
"image": {
"versions": 3
},
"flip": {
"horizontal": true,
"vertical": false
}
}
}{
"version": "4",
"message": "Dataset version generation initialized"
}Starts a background task that moves the project's images between the train, valid, and test splits. Versions you generate afterward use the new splits; existing versions do not change. You cannot generate a version or start training while the task runs. Poll the returned url, or Get Asynchronous Task Status, for the result. Requires project:update and the workspace permission to change splits.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
rebalance moves as few images as possible. shuffle randomly reassigns every image.
rebalancePossible values: Used only with shuffle. global shuffles the whole project. batch shuffles each upload batch and annotation job on its own.
globalPossible values: Move only images whose annotations use just these classes. Other images keep their split.
Accepted for asynchronous processing.
Asynchronous task ID.
URL to poll for the task status.
The request body is invalid (ex: a split value that is not a non-negative integer, all splits set to 0, an unknown mode or grouping, or an empty classes list).
Authentication is missing or invalid.
Your role cannot change splits, or you cannot write to the project's folder.
The resource does not exist or is not accessible.
The request rate is too high.
POST /{workspace}/{project}/splits/rebalance HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 44
{
"splits": {
"train": 70,
"valid": 20,
"test": 10
}
}{
"taskId": "Qm9yZWFsVGFzazEyMw",
"url": "https://api.roboflow.com/my-workspace/asynctasks/Qm9yZWFsVGFzazEyMw"
}Returns a download link for the version in an export format. The first request for a format starts the export and returns 202 with progress. Repeat the request until it returns 200 with export.link. Requires version:read. You can export public Universe projects from any workspace.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Dataset version number.
Export format. It must suit the project type (ex: coco, yolov8, yolov11, voc, createml, tfrecord for object detection; folder for classification; coco-segmentation or png-mask-semantic for semantic segmentation). yolo11 is accepted for yolov11.
yolov8Successful response.
The export is being prepared. Repeat the request until it returns 200.
The format does not suit the project type (the error lists the valid formats), or the version is still generating.
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The request rate is too high.
The export failed to start.
GET /{workspace}/{project}/{version}/{format} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"workspace": {
"name": "Roboflow",
"url": "roboflow",
"members": 7
},
"project": {
"id": "roboflow/chess-sample-4ckfl",
"type": "object-detection",
"name": "Chess Sample",
"created": 1630335544.592,
"updated": 1630335741.988,
"images": 12,
"unannotated": 3,
"annotation": "pieces",
"versions": 3,
"public": false,
"license": "Private",
"splits": {
"train": 9,
"valid": 2,
"test": 1
},
"colors": {
"white-king": "#C7FC00"
},
"classes": {
"white-king": 8
},
"icon": null
},
"version": {
"id": "roboflow/chess-sample-4ckfl/1",
"name": "augmented",
"created": 1630335698.746,
"images": 30,
"splits": {
"train": 27,
"valid": 2,
"test": 1
},
"preprocessing": {
"resize": {
"enabled": true,
"width": 416,
"height": 416,
"format": "Stretch to"
}
},
"augmentation": {
"image": {
"enabled": true,
"versions": 3
}
},
"exports": [
"yolov8"
]
},
"export": {
"format": "yolov8",
"link": "https://app.roboflow.com/ds/a1B2c3D4e5?key=f6G7h8I9j0",
"size": 2.31
},
"progress": 1
}Queues a training job on a dataset version. Requires training-job:create. The response has no body and no training ID; use the v2 trainings endpoints to find the training. On a version with several trainings, those endpoints are also how you get its results.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Dataset version number.
Architecture and size to train (ex: rfdetr-nano, rfdetr-small, yolov11n). It must suit the project type. An unknown or unsupported value returns 400 with the code invalid_model_type and the valid choices in availableModelTypes.
rfdetr-smallCheckpoint to start from: a model ID from this or another workspace you can access. Leave it out to start from the default public checkpoint.
Number of epochs. Values above 300 are lowered to 300. Defaults depend on the model type.
Training speed preset. accurate needs a plan that includes it. The model type takes precedence.
fastPossible values: Most credits the training may spend before Roboflow stops it and keeps the weights. Must be at least the model's minimum, and needs a plan with usage-based billing.
Most credits the Neural Architecture Search architecture search may spend. Neural Architecture Search model types only.
Completed with no response body.
No content
Training did not start. error.code says why (ex: invalid_model_type, invalid_credit_cap, train_not_enabled, insufficient_train_credits, train_quota_exhausted, accurate_train_not_available, nas_not_available_for_plan, sam3_not_available_for_plan). When the version is not ready, error.remedy names the fix: rebalance (images sit in the wrong splits), upload (add images), annotate (label images), regenerate (generate a new version), wait (a rebalance or generation is still running), or export.
Authentication is missing or invalid.
The API key lacks training-job:create, or the request sends a trainRecipe or stages without the online augmentation training feature.
The resource does not exist or is not accessible.
The version is a legacy single-model version that already has a training (error.code LEGACY_VERSION_SINGLE_MODEL). Generate a new version to train another model.
The request rate is too high.
POST /{workspace}/{project}/{version}/train HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 41
{
"modelType": "rfdetr-small",
"epochs": 100
}No content
Cancels the version's training and discards its weights. Works only when the version has exactly one training. If the job has run for less than 30 minutes, cancelling refunds its credits. After that, the request cancels nothing and returns outcome requires_confirmation until you send continueIfNoRefund: true. Requires training-job:create.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Dataset version number.
Send true to cancel a job that has run for 30 minutes or more, which gives no refund.
falseSuccessful response.
cancelled: the training is cancelled. pending: the cancel is recorded and finishes shortly. superseded: the training ended first, and status says how. requires_confirmation: nothing was cancelled because no refund is due; send continueIfNoRefund: true to cancel anyway.
True when outcome is cancelled.
True when the training's credits were refunded.
True when the running job was shut down.
True when the job had already ended.
Final training status. Present when outcome is superseded.
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
The version has no training to cancel.
The version has more than one training (error.code MULTIPLE_TRAININGS), or the training is not running (error.code CANNOT_CANCEL). For a version with several trainings, use the v2 endpoint and pass trainingId.
The request rate is too high.
POST /{workspace}/{project}/{version}/train/cancel HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 27
{
"continueIfNoRefund": true
}{
"outcome": "cancelled",
"success": true,
"refund": true,
"jobDeleted": true
}Asks the version's training to stop early and keep its weights. Works only when the version has exactly one training. During a Neural Architecture Search, it stops the architecture search. Requires training-job:create.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Dataset version number.
Successful response.
True when the stop request was recorded.
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
The version has no training to stop.
The version has more than one training (error.code MULTIPLE_TRAININGS), or the training is not running (error.code CANNOT_STOP). For a version with several trainings, use the v2 endpoint and pass trainingId.
The request rate is too high.
POST /{workspace}/{project}/{version}/train/stop HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"success": true
}Returns the status, models, and metrics of the version's training in one call. Works only when the version has exactly one training; for other versions, use Get a Training. Requires version:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Dataset version number.
Successful response.
Training ID. A 20-character hex ID for a training on a version that can hold several. For a legacy single-model version, a path of the form {projectId}/{version}/training/0, where projectId is the project's internal ID. null when the version has no training.
Dataset version number.
Training status: initializing, queued, generating, training, running, mining (Neural Architecture Search is searching architectures), finished, failed, cancelled, or stopped. not_started when the version has no training.
finishedFailure reason, up to 500 characters. Present only when the training failed.
Start time in milliseconds since the Unix epoch.
End time in milliseconds since the Unix epoch.
Kind of training: fine-tune, nas (Neural Architecture Search), fine-tune-multi-stage, external-upload, or unknown.
Architecture the training ran. A Neural Architecture Search training reports rfdetr-nas-parent.
True when the model weights were uploaded instead of trained on Roboflow.
Neural Architecture Search run ID, shared by every model from the run. null for other trainings.
Models the training produced.
The request is invalid.
Authentication is missing or invalid.
The API key lacks version:read.
The version does not exist.
The version has more than one training (error.code MULTIPLE_TRAININGS).
The request rate is too high.
GET /{workspace}/{project}/{version}/training/results HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"trainingId": "0a1b2c3d4e5f67890abc",
"versionId": "3",
"status": "finished",
"start": 1775001600000,
"end": 1775005200000,
"jobType": "fine-tune",
"modelType": "rfdetr-small",
"modelGroup": null,
"modelCount": 1,
"models": [
{
"modelId": "my-workspace/construction-safety-xpv3w-3-rfdetr-small-t2",
"modelType": "rfdetr-small",
"status": "finished",
"metrics": {
"map50": 91.2,
"map5095": 64.1,
"precision": 88.4,
"recall": 85,
"f1": 86.7,
"f1ConfThresh": 0.42
}
}
]
}Lists the trainings on a dataset version, each with the IDs of the models it produced. Requires version:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Dataset version number.
Successful response.
The request is invalid.
Authentication is missing or invalid.
The API key lacks version:read.
The resource does not exist or is not accessible.
The request rate is too high.
GET /{workspace}/{project}/{version}/v2/trainings HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"trainings": [
{
"id": "0a1b2c3d4e5f67890abc",
"versionId": "3",
"status": "finished",
"start": 1775001600000,
"end": 1775005200000,
"jobType": "fine-tune",
"modelType": "rfdetr-small",
"modelGroup": null,
"modelIds": [
"my-workspace/construction-safety-xpv3w-3-rfdetr-small-t2"
]
}
]
}Queues a training job on a dataset version and returns its training ID. Accepts the same fields as Start a Training Job. Requires training-job:create.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Dataset version number.
Architecture and size to train (ex: rfdetr-nano, rfdetr-small, yolov11n). It must suit the project type. An unknown or unsupported value returns 400 with the code invalid_model_type and the valid choices in availableModelTypes.
rfdetr-smallCheckpoint to start from: a model ID from this or another workspace you can access. Leave it out to start from the default public checkpoint.
Number of epochs. Values above 300 are lowered to 300. Defaults depend on the model type.
Training speed preset. accurate needs a plan that includes it. The model type takes precedence.
fastPossible values: Most credits the training may spend before Roboflow stops it and keeps the weights. Must be at least the model's minimum, and needs a plan with usage-based billing.
Most credits the Neural Architecture Search architecture search may spend. Neural Architecture Search model types only.
Successful response.
ID of the new training. Pass it to the v2 get, cancel, and stop endpoints.
Training status: initializing, queued, generating, training, running, mining (Neural Architecture Search is searching architectures), finished, failed, cancelled, or stopped. not_started when the version has no training.
finishedID of the training job.
Training did not start. error.code says why (ex: invalid_model_type, invalid_credit_cap, train_not_enabled, insufficient_train_credits, train_quota_exhausted, accurate_train_not_available, nas_not_available_for_plan, sam3_not_available_for_plan). When the version is not ready, error.remedy names the fix: rebalance (images sit in the wrong splits), upload (add images), annotate (label images), regenerate (generate a new version), wait (a rebalance or generation is still running), or export.
Authentication is missing or invalid.
The API key lacks training-job:create, or the request sends a trainRecipe or stages without the online augmentation training feature.
The resource does not exist or is not accessible.
The version is a legacy single-model version that already has a training (error.code LEGACY_VERSION_SINGLE_MODEL). Generate a new version to train another model.
The request rate is too high.
POST /{workspace}/{project}/{version}/v2/trainings HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 41
{
"modelType": "rfdetr-small",
"epochs": 100
}{
"trainingId": "0a1b2c3d4e5f67890abc",
"status": "queued",
"jobId": "train-0a1b2c3d"
}Returns one training's status, models, and metrics. Requires version:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Dataset version number.
Training to return. Leave it out when the version has only one training.
0a1b2c3d4e5f67890abcSend true to add the metrics for each epoch. Not supported on legacy single-model versions.
falseSuccessful response.
Training ID. A 20-character hex ID for a training on a version that can hold several. For a legacy single-model version, a path of the form {projectId}/{version}/training/0, where projectId is the project's internal ID. null when the version has no training.
Dataset version number.
Training status: initializing, queued, generating, training, running, mining (Neural Architecture Search is searching architectures), finished, failed, cancelled, or stopped. not_started when the version has no training.
finishedFailure reason, up to 500 characters. Present only when the training failed.
Start time in milliseconds since the Unix epoch.
End time in milliseconds since the Unix epoch.
Kind of training: fine-tune, nas (Neural Architecture Search), fine-tune-multi-stage, external-upload, or unknown.
Architecture the training ran. A Neural Architecture Search training reports rfdetr-nas-parent.
True when the model weights were uploaded instead of trained on Roboflow.
Neural Architecture Search run ID, shared by every model from the run. null for other trainings.
Models the training produced.
includeEpochs was sent for a legacy single-model version (error.code ENRICHMENT_UNSUPPORTED_FOR_LEGACY_TRAINING).
Authentication is missing or invalid.
The API key lacks version:read.
The version does not exist, or no training with that trainingId is on it (error.code TRAINING_NOT_FOUND).
trainingId was left out and the version has more than one training (error.code MULTIPLE_TRAININGS).
The request rate is too high.
GET /{workspace}/{project}/{version}/v2/trainings/get HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"trainingId": "0a1b2c3d4e5f67890abc",
"versionId": "3",
"status": "finished",
"start": 1775001600000,
"end": 1775005200000,
"jobType": "fine-tune",
"modelType": "rfdetr-small",
"modelGroup": null,
"modelCount": 1,
"models": [
{
"modelId": "my-workspace/construction-safety-xpv3w-3-rfdetr-small-t2",
"modelType": "rfdetr-small",
"status": "finished",
"metrics": {
"map50": 91.2,
"map5095": 64.1,
"precision": 88.4,
"recall": 85,
"f1": 86.7,
"f1ConfThresh": 0.42
}
}
]
}Describes what you can tune when you train one model type on this version, and returns a ready-to-submit trainRecipe for Create a Training Run. It does not start anything. Requires version:read. Requests are rate limited per API key and per workspace.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Dataset version number.
Model type you plan to train. It must suit the project type.
rfdetr-smallSuccessful response.
The modelType you sent.
The registry ID for that model type.
Model family (ex: rf-detr).
Task the model performs (ex: object-detection).
Plain-text instructions for editing and submitting the template.
modelType is missing (error.code missing_model_type), or the version's resize step has invalid dimensions. Generate a new version.
Authentication is missing or invalid.
The credential does not have access to this resource.
The version does not exist, or modelType is not a trainable model type for this project (error.code invalid_model_type, with the valid choices in error.availableModelTypes).
Too many requests. Wait for the time in the Retry-After header.
GET /{workspace}/{project}/{version}/v2/trainings/recipe?modelType=text HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"modelType": "rfdetr-small",
"canonicalModelType": "rfdetr-small",
"family": "rf-detr",
"taskType": "object-detection",
"availability": {
"entitled": true,
"runtimeEnabled": true
},
"schema": {
"hyperparameters": [
{
"key": "epochs",
"type": "int",
"valid": {
"ge": 1
},
"advice": {
"default": 100,
"low": 50,
"high": 150
}
}
],
"online_augmentation": {
"splits": [
"train"
],
"steps": [
{
"name": "flip",
"params": {
"horizontal": {
"type": "boolean",
"required": true
},
"vertical": {
"type": "boolean",
"required": true
}
},
"atLeastOne": [
"horizontal",
"vertical"
],
"probability": true
}
]
},
"online_preprocessing": {
"steps": []
},
"input": {
"onlineResizeAllowed": true,
"resizeFormats": [
"Stretch to"
],
"resolutionRounding": "Width, height, and resolution are rounded to the nearest multiple of 32, with a minimum of 32."
}
},
"template": {
"schema_version": 1,
"input": {
"width": 512,
"height": 512,
"resolution": 512,
"resize": {
"enabled": true,
"format": "Stretch to",
"width": 512,
"height": 512
},
"splits": [
"train",
"valid",
"test"
]
},
"online_preprocessing": [],
"online_augmentation": {
"splits": [
"train"
],
"steps": []
},
"source_version": {
"dataset_id": "AbC123xYz",
"version_id": "3",
"baked_preprocessing": {
"auto-orient": {
"enabled": true
}
},
"baked_augmentation": {},
"assertions": {
"resize_baked": false,
"augmentation_baked": false
}
},
"hyperparameters": {}
},
"usage": "The template is ready to submit verbatim as `trainRecipe` on a POST to this project/version's /v2/trainings path alongside `modelType`."
}Cancels one training on a version and discards its weights. If the job has run for less than 30 minutes, cancelling refunds its credits. After that, the request cancels nothing and returns outcome requires_confirmation until you send continueIfNoRefund: true. Requires training-job:create.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Dataset version number.
Training to cancel. Leave it out when the version has only one training.
Send true to cancel a job that has run for 30 minutes or more, which gives no refund.
falseSuccessful response.
cancelled: the training is cancelled. pending: the cancel is recorded and finishes shortly. superseded: the training ended first, and status says how. requires_confirmation: nothing was cancelled because no refund is due; send continueIfNoRefund: true to cancel anyway.
True when outcome is cancelled.
True when the training's credits were refunded.
True when the running job was shut down.
True when the job had already ended.
Final training status. Present when outcome is superseded.
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
No training with that trainingId on this version (error.code TRAINING_NOT_FOUND), or the version has no training (error.code NO_TRAINING).
trainingId was left out and the version has more than one training (error.code MULTIPLE_TRAININGS), or the training is not running (error.code CANNOT_CANCEL).
The request rate is too high.
POST /{workspace}/{project}/{version}/v2/trainings/cancel HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 63
{
"trainingId": "0a1b2c3d4e5f67890abc",
"continueIfNoRefund": true
}{
"outcome": "cancelled",
"success": true,
"refund": true,
"jobDeleted": true
}Asks one training on a version to stop early and keep its weights. During a Neural Architecture Search, it stops the architecture search. Requires training-job:create.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Dataset version number.
Training to stop. Leave it out when the version has only one training.
Successful response.
True when the stop request was recorded.
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
No training with that trainingId on this version (error.code TRAINING_NOT_FOUND), or the version has no training (error.code NO_TRAINING).
trainingId was left out and the version has more than one training (error.code MULTIPLE_TRAININGS), or the training is not running (error.code CANNOT_STOP).
The request rate is too high.
POST /{workspace}/{project}/{version}/v2/trainings/stop HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 37
{
"trainingId": "0a1b2c3d4e5f67890abc"
}{
"success": true
}Moves a finished, failed, cancelled, or stopped training and its models to the workspace Trash, where it stays for 30 days. Restore it with POST /{workspace}/trash/restore and type training. If the training served the version's {project}/{version} model ID, serving moves to the oldest remaining training. Requires version:update.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Dataset version number.
Training ID from List Training Runs.
0a1b2c3d4e5f67890abcSuccessful response.
Workspace URL slug.
Project URL slug.
Project ID.
Dataset version number.
Always true: the training went to Trash.
What happened to the {project}/{version} model ID. repointed: it now serves versionAliasTarget. deleted: no model is left to serve it until a new training finishes. unchanged: this training did not serve it. pending: the change is still being applied.
Model the {project}/{version} model ID now serves. Present only when versionAliasAction is repointed.
The training is still running (stop or cancel it first), or it is a legacy training, which you delete by deleting its version.
Authentication is missing or invalid.
Deleting is temporarily locked for the workspace after unusual delete activity (code destructive_actions_locked).
No training with that ID is on this version (error.code TRAINING_NOT_FOUND).
The request rate is too high.
DELETE /{workspace}/{project}/{version}/v2/trainings/{trainingId} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"deleted": true,
"type": "training",
"workspace": "my-workspace",
"project": "construction-safety-xpv3w",
"projectId": "AbC123xYz",
"version": "3",
"trainingId": "0a1b2c3d4e5f67890abc",
"trash": true,
"versionAliasAction": "repointed",
"versionAliasTarget": "construction-safety-xpv3w-3-rfdetr-small-t2"
}이미지 및 배치
Adds an image to the project and puts it in a batch. Send the image as a multipart file or a base64 body, or pass the image query parameter to have Roboflow fetch it from a URL. Uploading an image the project already has returns the existing image ID with duplicate set to true. Requires image:create. /{workspace}/{project}/upload works the same way.
Roboflow API key or OAuth access token.
Project URL slug.
URL of an image for Roboflow to fetch and add. URL-encode it. Use it when you do not send the image in the body.
https://i.imgur.com/PEEvqPN.pngFile name of the image. Roboflow infers it when you leave it out.
dock-cam-001.jpgSplit the image goes to.
trainPossible values: Name of the batch to add the image to. Without it, the image goes to the "Uploaded via API" batch.
Warehouse camsNote for the batch. The batch keeps the first note it gets. Annotation jobs made from the batch use it as their default instructions.
Label every forklift, even when it is partly hidden.Tag to add to the image. Repeat it to add more tags.
nightCustom metadata as a JSON object string. Keys use letters, numbers, underscores, and dots, and do not start with a dot. Keys that start with rf_internal are reserved.
{"camera_id":"cam001"}Position of the image in a sequence. Use it to keep images in order.
Total number of images in the sequence.
100000Inference ID from a Roboflow prediction. It links the image to that prediction in Model Monitoring.
The whole body is the image encoded as base64. A data URL prefix (ex: data:image/jpeg;base64,) is allowed. Send every option as a query parameter.
Successful response.
True when Roboflow added a new image.
True when the project already has this exact image. No new image is added, and id is the existing image.
Image ID. Use it to upload an annotation for the image.
No image was sent, the image is too large or not readable, metadata or notes is invalid, or Roboflow could not fetch the image URL (bad URL, private address, or a 4xx answer from the host). A failed fetch has a message that starts with "Could not fetch image URL".
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The request rate is too high.
The host of the image URL answered with a 5xx status or the connection failed. The response sets retryable to true, so send the same request again later.
POST /dataset/{project}/upload HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: multipart/form-data
Accept: */*
Content-Length: 134
{
"file": "binary",
"name": "dock-cam-001.jpg",
"split": "train",
"tag": "night",
"metadata": "{\"camera_id\":\"cam001\",\"temperature\":72.5}"
}{
"success": true,
"id": "YbNIgavTIk2xOOmJsHv5"
}Saves an annotation file on an image that is already in the project. Roboflow reads the format from the name query parameter, so it works with any supported format whose file references the image's file name. By default the image is added to the Dataset, which takes it out of its batch, job, and review flow. In an Action Recognition project, pass a video ID as imageId and send a roboflow-video-coco document; prediction, predictionRouting, and jobName return 400 for videos. Requires image:annotate.
Roboflow API key or OAuth access token.
Project URL slug.
Image ID returned by the upload, or a video ID in an Action Recognition project.
File name of the annotation file, with its extension. Roboflow reads the annotation format from it.
dock-cam-001.xmlAdd the image to the Dataset, so the next dataset version can include it. Send false to save the annotation and keep the image in its batch or job.
trueSplit to set on the image. val and validation both mean valid. Leave it out to keep the image's split. A video added without a split goes to train.
Replace an annotation the image already has. Without it the request fails with 409. Classification projects always replace.
falseMove the image into the annotation job with this name, and create the job if it does not exist. Leave it out to keep the image where it is.
Save the annotation as a model prediction instead of ground truth. A prediction never adds the image to the Dataset.
falseNeeds prediction=true and cannot be sent with jobName. review moves the image from its batch into a Review job, when the image is in a batch of this project and in no job. unassigned leaves batch and job membership alone.
unassignedPossible values: The contents of the annotation file (ex: Pascal VOC XML, COCO JSON, YOLO TXT). For a single-label classification project, send the class name. For multi-label, send comma-separated class names, or a CSV with a header row of class names and one row of 0 and 1 values (set name to _classes.csv). For an Action Recognition project, send one roboflow-video-coco document.
<annotation><filename>dock-cam-001.jpg</filename><object><name>forklift</name><bndbox><xmin>40</xmin><ymin>60</ymin><xmax>220</xmax><ymax>310</ymax></bndbox></object></annotation>Successful response.
Present and true when some shapes were invalid and left out.
Videos only. True when the video is in the Dataset after the save.
Videos only. Classes the save added to the project.
Roboflow could not parse the annotation or match it to the image, every shape is invalid, a classification file names no class, a label is too long, or predictionRouting is invalid or sent without prediction=true or with jobName.
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The image already has an annotation. Send overwrite=true to replace it.
The request rate is too high.
POST /dataset/{project}/annotate/{imageId}?name=text HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: text/plain
Accept: */*
Content-Length: 181
"<annotation><filename>dock-cam-001.jpg</filename><object><name>forklift</name><bndbox><xmin>40</xmin><ymin>60</ymin><xmax>220</xmax><ymax>310</ymax></bndbox></object></annotation>"{
"success": true
}Returns an image's file name, split, tags, metadata, annotation, image URLs, and embedding. For a video, urls.original and urls.thumb hold its poster image, urls.video is a short-lived download link, segments lists its action segments, and annotation is null. Requires image:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Image ID.
Return the annotation as a file in this export format (ex: voc, coco). Not supported for videos or with include.
vocSet to annotation to add the annotation group version, a signed image URL, and whether you can edit the annotation. Read annotationGroupVersion here before you save an annotation. You cannot use it with format.
annotationPossible values: Successful response.
format was sent for a video or together with include=annotation.
Authentication is missing or invalid.
The credential does not have access to this resource.
The image does not exist, belongs to another workspace, or is not in this project.
The request rate is too high.
GET /{workspace}/{project}/images/{imageId} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"image": {
"id": "YbNIgavTIk2xOOmJsHv5",
"name": "dock-cam-001.jpg",
"mediaType": "image",
"annotation": {
"key": "dock-cam-001.jpg",
"width": 1280,
"height": 720,
"boxes": [
{
"label": "forklift",
"x": 130,
"y": 185,
"width": 180,
"height": 250
}
]
},
"labels": null,
"split": "train",
"tags": [
"night"
],
"metadata": {
"camera_id": "cam001"
},
"created": 1767225600000,
"lastSet": 1767229200000,
"urls": {
"original": "https://source.roboflow.com/AbC123/YbNIgavTIk2xOOmJsHv5/original.jpg",
"thumb": "https://source.roboflow.com/AbC123/YbNIgavTIk2xOOmJsHv5/thumb.jpg",
"annotation": "https://source.roboflow.com/AbC123/YbNIgavTIk2xOOmJsHv5/annotation-forklifts.png"
},
"embedding": null
}
}Replaces the project's annotation on one image. The save works only when expectedGroupVersion matches the current annotationGroupVersion, so it never overwrites an edit made by someone else. The API key needs the image:read and image:annotate scopes, and the member behind it needs permission to annotate.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Image ID.
The project's annotation group. Read it from the group field of the image response.
The annotationGroupVersion that GET returned. Send it even when the image has no saved annotation, because a cleared annotation keeps its version. Send 0 only when GET returns 0.
A unique ID for this save.
Set to true to mark the image as null (no objects). boxes must then be empty.
Successful response.
The new version. Send it as expectedGroupVersion on your next save. A save identical to the stored annotation returns the current version.
The project's class names after the save.
The request body is invalid, the group does not match the project, or this image or annotation type cannot be edited.
Authentication is missing or invalid.
The credential does not have access to this resource.
The project or image is missing, or the API key cannot write to it.
The annotation changed since you read it, the save was busy, or the project has locked classes and a label is not one of them. Read the image again and retry.
The request rate is too high.
PUT /{workspace}/{project}/images/{imageId}/annotation HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 284
{
"group": "cats",
"expectedGroupVersion": 0,
"mutationId": "save-1",
"annotation": {
"boxes": [
{
"id": "1",
"label": "cat",
"x": 40,
"y": 60,
"width": 20,
"height": 30
},
{
"id": "2",
"label": "cat",
"type": "polygon",
"x": 120,
"y": 85,
"width": 40,
"height": 30,
"points": [
[
100,
70
],
[
140,
70
],
[
120,
100
]
]
}
]
},
"isNull": false
}{
"imageId": "abc123",
"annotationGroupVersion": 1,
"classes": [
"cat"
]
}Removes images from the project. An image that no other project uses is deleted. IDs that are not in the project are skipped. Requires project:update.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Image IDs to remove.
Completed with no response body.
No content
images is empty.
Authentication is missing or invalid.
The project belongs to another workspace, or deletions are paused because too many destructive actions ran in a short time.
The resource does not exist or is not accessible.
The request rate is too high.
DELETE /{workspace}/{project}/images HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 58
{
"images": [
"YbNIgavTIk2xOOmJsHv5",
"pX2b7RkqLw9Zs3TnVc1d"
]
}No content
Adds tags to an image, removes tags from it, or replaces all its tags. Use the image ID, not the file name: search the project to find an image's ID. Requires image:tag.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Image ID.
add keeps the existing tags, remove deletes the listed tags, and set replaces every tag with the list.
Tags to add, remove, or set.
Successful response.
operation is not add, remove, or set, or tags is missing, not an array, or holds an invalid tag.
Authentication is missing or invalid.
The credential does not have access to this resource.
The image does not exist, belongs to another workspace, or is not in this project.
The request rate is too high.
POST /{workspace}/{project}/images/{imageId}/tags HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 47
{
"operation": "add",
"tags": [
"reviewed",
"night"
]
}{
"success": true
}Sets and removes custom metadata and tags on one image, right away. The image can be in any project of the workspace. Requires image:tag.
Roboflow API key or OAuth access token.
Workspace URL slug.
Image ID.
Send at least one field. A key or tag cannot be both set and removed in one request. Keys use letters, numbers, underscores, and dots, and do not start with a dot. Keys that start with rf_internal are reserved.
Metadata keys to delete.
Tags to add.
Tags to remove.
Successful response.
The body is empty, a field has the wrong type, a key or tag is invalid, or the same key or tag is both set and removed.
Authentication is missing or invalid.
The credential does not have access to this resource.
The image does not exist or belongs to another workspace.
The request rate is too high.
POST /{workspace}/images/{imageId}/metadata HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 71
{
"metadata": {
"camera": "front",
"blur_score": 0.8
},
"addTags": [
"reviewed"
]
}{
"success": true
}Sets and removes custom metadata and tags on up to 1,000 images in the background. Poll the returned task URL until it finishes. An image that is missing or in another workspace fails on its own and does not stop the others. Requires image:tag.
Roboflow API key or OAuth access token.
Workspace URL slug.
Accepted for asynchronous processing.
Asynchronous task ID.
URL to poll for the task status. The finished task's result lists totalProcessed, succeeded, failed, and failedItems.
updates is empty or has more than 1,000 entries, an image ID is listed twice, or an entry is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The request rate is too high.
POST /{workspace}/images/metadata HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 138
{
"updates": [
{
"imageId": "abc123",
"metadata": {
"camera": "front"
},
"addTags": [
"reviewed"
]
},
{
"imageId": "def456",
"removeTags": [
"needs-review"
]
}
]
}{
"taskId": "Qm9yZWFsVGFzazEyMw",
"url": "https://api.roboflow.com/my-workspace/asynctasks/Qm9yZWFsVGFzazEyMw"
}Adds images or videos that are already in the Asset Library to a Project. Requires the image:create scope. API keys scoped to project folders cannot use it. The add runs as an async task.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Send exactly one of imageIds or query.
IDs of the Asset Library images or videos to add.
Asset Library search query. Every match is added. It must not be blank.
Project URL slug or ID. Requires query. Limits the query to images in that Project's dataset. Images that are only in its unassigned or annotating batches do not match. To match every image in a Project, put project: in query instead.
Project URL slug or ID to copy annotations from.
Accepted for asynchronous processing.
Async task ID.
ID of the target Project.
Name of the target Project.
URL slug of the target Project.
How the images were selected.
Number of images requested. Present when you send imageIds.
URL to poll for the task status. When the task completes, result has imagesLinked, imagesSkipped, and annotationsCopied.
The request is invalid.
Authentication is missing or invalid.
The workspace does not have enough credits.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The Project's folder is paused.
The request rate is too high.
POST /{workspace}/{project}/add-images HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 57
{
"query": "tag:review",
"sourceProjectId": "penguin-finder"
}{
"taskId": "lot2zfKP9IgekdhI6MYw",
"projectId": "hLP5yBav7euABHW96BwY",
"projectName": "penguin-finder",
"projectUrl": "penguin-finder",
"selectionMode": "imageIds",
"imageCount": 2,
"url": "https://api.roboflow.com/my-workspace/asynctasks/lot2zfKP9IgekdhI6MYw"
}Lists the upload batches in a project. Requires batch:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Include batches with no images.
falseSuccessful response.
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The request rate is too high.
GET /{workspace}/{project}/batches HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"batches": [
{
"id": "6VN0fFQIWU1E24bDjGsN",
"name": "Uploaded on 11/22/22 at 1:39 pm",
"images": 115,
"numJobs": 2,
"uploaded": {
"_seconds": 1669146024,
"_nanoseconds": 818000000
}
},
{
"id": "pX2b7RkqLw9Zs3TnVc1d",
"name": "Uploaded via API",
"images": 11,
"numJobs": 0,
"uploaded": {
"_seconds": 1669236873,
"_nanoseconds": 47000000
}
}
]
}Returns one upload batch. Requires batch:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Image batch ID.
Successful response.
Batch ID. Use it to create an annotation job from the batch.
Batch name. Uploads without a batch name go to "Uploaded via API".
Images in the batch.
Annotation jobs created from the batch.
Batch notes set at upload. Present only when set.
video for a batch of videos. Not set for image batches.
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
The batch does not exist in this project.
The request rate is too high.
GET /{workspace}/{project}/batches/{batchId} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "6VN0fFQIWU1E24bDjGsN",
"name": "Uploaded on 11/22/22 at 1:39 pm",
"images": 115,
"numJobs": 2,
"uploaded": {
"_seconds": 1669146024,
"_nanoseconds": 818000000
}
}Starts a dataset ZIP upload and returns a signed URL to PUT the ZIP to, plus a task ID to poll. Processing starts when the upload to the signed URL finishes. The ZIP can hold images and annotations in any supported format (ex: COCO, YOLO, Pascal VOC); for classification, folder names become class labels. Limits are 8 GB of extracted files and 100,000 files. Requires image:create.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Split for images whose folder does not set one.
trainPossible values: Batch name for the uploaded images. A ZIP with annotations creates one annotation job with this name, or "Uploaded via API" when you leave it out.
Tags to add to each uploaded image or video.
Replace the annotations on images that are already in the project. By default those images keep their annotations. Classification projects always replace the label and reject false with 400.
falseSuccessful response.
Task ID to poll for status.
URL to PUT the ZIP file to, with Content-Type application/zip. It expires after one hour.
annotationOverwrite is false in a classification project.
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The request rate is too high.
POST /{workspace}/{project}/upload/zip HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 62
{
"split": "train",
"batchName": "april-batch",
"tags": [
"outdoor"
]
}{
"taskId": "abc123",
"signedUrl": "https://storage.googleapis.com/roboflow-uploads/zip-uploads/abc123.zip?X-Goog-Signature=..."
}Returns the status of a dataset ZIP upload. Poll it until status is completed or failed. Requires image:create.
Roboflow API key or OAuth access token.
Workspace URL slug.
Asynchronous task ID.
Successful response.
created until the ZIP arrives, then running, then completed or failed.
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
The task does not exist or belongs to another workspace.
The request rate is too high.
GET /{workspace}/upload/zip/{taskId} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"status": "completed",
"progress": {
"current": 250,
"total": 250
},
"result": {
"uploaded": 248,
"duplicates": 0,
"annotated": 248,
"videosStaged": 0,
"videoIds": [],
"uploadErrors": [
{
"path": "train/broken.jpg",
"error": "Unsupported image format"
}
],
"annotationErrors": [],
"warnings": [],
"chunkCount": 3,
"failedChunks": 0
}
}Creates a pending video and returns a signed URL for its file. The video joins the workspace, and the project when you set one, after you PUT the file to signedUrl and Roboflow processes it.
Roboflow API key or OAuth access token.
Workspace URL slug.
File name of the video.
MIME type of the video file.
Project URL slug. Omit it to add the video to the workspace only. API keys scoped to project folders must set it.
Batch name. Requires project. Without it, the video gets a batch of its own.
One tag or a list of tags to add to the video.
Split the video goes to when you generate a version. Requires project. Defaults to train when you set project. The aliases val and validation map to valid.
Successful response.
ID of the new video. Use it to read the upload status.
URL to PUT the video file to. It expires after 60 minutes.
A field is invalid, or batch or split is set without project.
Authentication is missing or invalid.
The credential does not have access to this resource.
The project is missing or the API key cannot reach it.
The request rate is too high.
POST /{workspace}/upload/video HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 174
{
"name": "dock-cam.mp4",
"contentType": "video/mp4",
"project": "warehouse-actions",
"batch": "Warehouse cams",
"tag": [
"dock",
"night"
],
"metadata": {
"camera": "dock-1"
},
"split": "valid"
}{
"videoId": "abc123",
"signedUrl": "https://storage.googleapis.com/...",
"requiredHeaders": {
"x-goog-content-length-range": "1,3221225472",
"x-goog-if-generation-match": "0"
}
}Reads the processing status of a video upload.
Roboflow API key or OAuth access token.
Workspace URL slug.
Video ID returned when you prepared the upload.
Successful response.
ID of the video. When duplicate is true, this is the ID of the video that was already in the workspace.
pending while Roboflow processes the video, then uploaded or failed.
True when the same video was already in the workspace, so Roboflow reused it.
Why the upload failed. Present when status is failed.
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
The video is missing or the API key cannot reach it.
The request rate is too high.
GET /{workspace}/upload/video/{videoId} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"videoId": "abc123",
"status": "uploaded",
"resolvedBatch": {
"id": "def456",
"name": "Warehouse cams"
}
}주석
Adds comments to an image that is already in the project. Annotations do not change. Comments are attributed to the user of the API key. Requires the image:annotate scope and access to annotate the project. Video projects are not supported.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Image ID.
Successful response.
trueNumber of comments added.
1The comments are invalid, a comment has an unknown field, or the project is a video project. Nothing is saved.
Authentication is missing or invalid.
The credential does not have access to this resource.
The image is not in this project, or the API key does not have the image:annotate scope.
The request rate is too high.
POST /{workspace}/{project}/comments/{imageId} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 95
{
"comments": [
{
"message": "This box is too loose",
"position": {
"x": 120,
"y": 80
},
"resolved": false
}
]
}{
"success": true,
"created": 1
}Lists every annotation job in the project. Requires annotation-job:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Successful response.
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The request rate is too high.
GET /{workspace}/{project}/jobs HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"jobs": [
{
"id": "h2E42jt686yLyMIxxqOQ",
"name": "Test Job",
"owner": "holeSv3hwbzrOv37vH5b",
"project": "PBDhem3YRI1rKtQZSqRK",
"sourceBatch": "PBDhem3YRI1rKtQZSqRK/6VN0fFQIWU1E24bDjGsN",
"createdBy": "API",
"labeler": "korryn@roboflow.com",
"reviewer": "thomas@roboflow.com",
"status": "assigned",
"instructionsText": "Please label all the raccoons in the images using polygons",
"numImages": 25,
"annotated": 12,
"unannotated": 2,
"approved": 0,
"rejected": 0,
"created": {
"_seconds": 1669148192,
"_nanoseconds": 651000000
}
}
]
}Moves images from a batch into a new annotation job and assigns a labeler and a reviewer, who get an email. Both must be workspace members. When you leave out instructionText, the job uses the batch notes. Requires annotation-job:create.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Job name.
ID of the batch to take images from.
Number of images to put in the job.
Email of the workspace member who labels the images.
Email of the workspace member who reviews the labels. Without Role Based Access Control, use the labeler's email.
Instructions for the labeler. When you leave it out, the job uses the batch notes set at upload.
Successful response.
Job ID.
Workspace ID.
Project ID.
Project ID and batch ID joined by a slash.
User ID of the creator, or API for jobs created with the API.
Labeler email.
Reviewer email.
assigned while labeling, review while in review, complete once added to the dataset.
Instructions shown to the labeler.
What opened the job (ex: vision_events). Absent for jobs created by hand.
Set for video batches.
A required field is missing, the batch does not exist, it has fewer images than num_images, or the labeler or reviewer is not in the workspace.
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
Another job is being created from this project. Retry in a moment.
The request rate is too high.
POST /{workspace}/{project}/jobs HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 191
{
"name": "Job created by API",
"batch": "6VN0fFQIWU1E24bDjGsN",
"num_images": 10,
"labelerEmail": "lenny@roboflow.com",
"reviewerEmail": "lenny@roboflow.com",
"instructionText": "Label every forklift."
}{
"id": "h2E42jt686yLyMIxxqOQ",
"name": "Test Job",
"owner": "holeSv3hwbzrOv37vH5b",
"project": "PBDhem3YRI1rKtQZSqRK",
"sourceBatch": "PBDhem3YRI1rKtQZSqRK/6VN0fFQIWU1E24bDjGsN",
"createdBy": "API",
"labeler": "korryn@roboflow.com",
"reviewer": "thomas@roboflow.com",
"status": "assigned",
"instructionsText": "Please label all the raccoons in the images using polygons",
"numImages": 25,
"annotated": 12,
"unannotated": 2,
"approved": 0,
"rejected": 0,
"created": {
"_seconds": 1669148192,
"_nanoseconds": 651000000
}
}Returns one annotation job, with its image counts and status. Requires annotation-job:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Job ID.
Successful response.
Job ID.
Workspace ID.
Project ID.
Project ID and batch ID joined by a slash.
User ID of the creator, or API for jobs created with the API.
Labeler email.
Reviewer email.
assigned while labeling, review while in review, complete once added to the dataset.
Instructions shown to the labeler.
What opened the job (ex: vision_events). Absent for jobs created by hand.
Set for video batches.
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
No job with this ID in the project.
The request rate is too high.
GET /{workspace}/{project}/jobs/{jobId} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "h2E42jt686yLyMIxxqOQ",
"name": "Test Job",
"owner": "holeSv3hwbzrOv37vH5b",
"project": "PBDhem3YRI1rKtQZSqRK",
"sourceBatch": "PBDhem3YRI1rKtQZSqRK/6VN0fFQIWU1E24bDjGsN",
"createdBy": "API",
"labeler": "korryn@roboflow.com",
"reviewer": "thomas@roboflow.com",
"status": "assigned",
"instructionsText": "Please label all the raccoons in the images using polygons",
"numImages": 25,
"annotated": 12,
"unannotated": 2,
"approved": 0,
"rejected": 0,
"created": {
"_seconds": 1669148192,
"_nanoseconds": 651000000
}
}Lists the Auto Label foundation models your workspace can see, with the credits each uses per image. A model your plan does not include has available set to false. Pass a model's id as modelType to preview it or start a job. Requires annotation-job:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
Successful response.
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The request rate is too high.
GET /{workspace}/autolabel/models HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"models": [
{
"id": "gemini-3-8-flash-boxes",
"aliases": [
"gemini-boxes"
],
"name": "Gemini 3.8 Flash (Boxes)",
"family": "gemini-3-8-flash",
"familyName": "Gemini 3.8 Flash",
"labelType": "Box labels",
"description": "Gemini 3.8 Flash detects your classes with bounding boxes",
"guidance": "Alternative to GPT-6 Astra for open-vocabulary detection, niche class names, visible text, and object relationships, at a lower token price. Reports fixed confidence, so thresholds do not apply.",
"projectTypes": [
"object-detection"
],
"outputFormat": "bbox",
"ontologyFormat": "classes",
"fixedConfidence": true,
"creditsPerImage": 2,
"isDefault": false,
"available": true
}
]
}Runs one image through a foundation model and returns the predictions with a summary per class. Previews are free, create no job, and are limited to 200 per workspace per day. Leave out ontology to use the project's classes. Requires annotation-job:create.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
A model id from List Auto Label models.
gemini-3-8-flash-boxesMaps prompts to class names. Send an object of prompt to class name, an array of class names (each is also its prompt), or an array of { class, prompt } objects. Leave it out to use the project's classes, or the trained model's classes for custom_roboflow.
{"a dog":"dog","a cat":"cat"}Class names, each used as its own prompt.
SAM 3 models only. Lowest confidence returned.
Successful response.
The modelType you sent.
Present when a Workflow step failed, so an empty result is not a real negative.
image or modelType is missing (errorType MISSING_PREVIEW_PARAMS), the model is unknown (UNKNOWN_MODEL_TYPE), the project has no classes to use (DATASET_HAS_NO_CLASSES), or there are more classes than the model takes (TOO_MANY_CLASSES). The body is { error, errorType }.
Authentication is missing or invalid.
Your plan does not include this model, or a workspace admin turned it off.
The resource does not exist or is not accessible.
The workspace used its 200 previews for the day.
The model provider failed. The body sets "retryable".
The model is not available right now.
The preview timed out. Retry.
POST /{workspace}/{project}/autolabel/preview HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 128
{
"modelType": "gemini-3-8-flash-boxes",
"image": {
"type": "url",
"value": "https://example.com/image.jpg"
},
"ontology": {
"a dog": "dog"
}
}{
"model": "gemini-3-8-flash-boxes",
"predictions": [
{
"x": 320,
"y": 240,
"width": 180,
"height": 140,
"class": "dog",
"confidence": 0.9
}
],
"summary": {
"totalDetections": 1,
"byClass": {
"dog": {
"count": 1,
"maxConfidence": 0.9
}
},
"classesWithNoDetections": []
}
}Starts a job that labels the images of a batch and puts them in a new annotation job for review. Credits are charged when the job starts. The job runs in the background: poll Get Auto Label job status with the returned jobId. Requires annotation-job:create. With an OAuth access token the job runs on the project's billing API key, and a token limited to project folders can only start jobs with foundation models.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
ID of the image batch to label.
A model id from List Auto Label models (ex: sam3-rle, gpt-6-astra-boxes), sam3, custom_roboflow with the model in modelOptions.modelId, or workflow with the Workflow fields below.
Maps prompts to class names. Send an object of prompt to class name, an array of class names (each is also its prompt), or an array of { class, prompt } objects. Leave it out to use the project's classes, or the trained model's classes for custom_roboflow.
{"a dog":"dog","a cat":"cat"}Class names, each used as its own prompt.
Images to label. Defaults to the whole batch. A job labels at most 10,000 images.
Confidence threshold for every class without its own threshold.
Workspace member who reviews the labels. Defaults to the workspace owner.
Run non-max suppression on the predictions.
trueKeep annotations already on the images and add the new ones. false replaces them.
falseKeep annotations already on the images and add only new ones that do not overlap an existing annotation of the same class. Takes precedence over preserveExistingAnnotations.
falseKeypoint detection projects only. Keypoints below this confidence are saved as not visible.
0.6modelType workflow only. URL slug of a saved Workflow in this workspace.
modelType workflow only. Required. The Workflow's workspace URL slug.
modelType workflow only. Required. Workflow output that holds the predictions.
modelType workflow only. Workflow input that takes the image.
imageSuccessful response.
Auto Label job ID. Use it to get the job status.
The annotation job that receives the labels for review.
The request is invalid. errorType names the problem (ex: MISSING_BATCH_ID, UNKNOWN_MODEL_TYPE, MISSING_ONTOLOGY, UNSUPPORTED_PROJECT_TYPE, MISSING_KEYPOINT_SKELETON, MISSING_MODEL_ID, MODEL_CLASSES_UNAVAILABLE, NO_MATCHING_CLASSES, DATASET_HAS_NO_CLASSES, NUM_IMAGES_TO_LABEL_EXCEEDS_BATCH, NO_IMAGES_TO_LABEL, REVIEWER_NOT_IN_WORKSPACE, MISSING_WORKFLOW_FIELDS, INVALID_WORKFLOW_CLASS_MAPPING, WORKFLOW_UNAVAILABLE). No job is created and no credits are used. The body is { error, errorType }.
Authentication is missing or invalid.
The workspace does not have enough credits (errorType INSUFFICIENT_CREDITS). The body is { error, errorType }.
Your plan does not include the model (MANAGED_TEMPLATE_PLAN_REQUIRED), the workspace turned off its blocks (WORKFLOW_BLOCKS_DISABLED), or a folder-scoped OAuth token named a custom model or saved Workflow (FOLDER_SCOPED_TOKEN_REFERENCE). The body is { error, errorType }.
The batch is not in this project (errorType BATCH_NOT_FOUND). The body is { error, errorType }.
Another job is being created on this project. Retry in a moment.
The job has more than 10,000 images (errorType TOO_MANY_IMAGES). The body includes maxImages.
The project's billing folder has paused usage.
The request rate is too high.
POST /{workspace}/{project}/autolabel HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 98
{
"batchId": "6VN0fFQIWU1E24bDjGsN",
"modelType": "sam3-rle",
"ontology": {
"a dog": "dog",
"a cat": "cat"
}
}{
"jobId": "0b6f3c1e-8f0a-4a52-9d1b-3f0c2c9a7e11",
"annotationJobId": "h2E42jt686yLyMIxxqOQ",
"message": "Automatic labeling job created"
}Returns the progress of an Auto Label job. Requires annotation-job:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
The jobId returned when you started the job.
Successful response.
pending while images are labeled, processing_completion while results are saved, then done. A job still pending after 12 hours is stopped and marked done.
The model the job runs (ex: sam3, workflow, custom_roboflow).
Images in the job.
Images labeled so far.
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
No Auto Label job with this ID in the workspace.
The request rate is too high.
GET /{workspace}/autolabel/jobs/{jobId} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "0b6f3c1e-8f0a-4a52-9d1b-3f0c2c9a7e11",
"status": "pending",
"modelType": "sam3",
"projectType": "object-detection",
"projectId": "PBDhem3YRI1rKtQZSqRK",
"annotationJobId": "h2E42jt686yLyMIxxqOQ",
"numImages": 100,
"numImagesSentBack": 40,
"subjobs": [
{
"id": "subjob-1",
"status": "done"
},
{
"id": "subjob-2",
"status": "pending"
}
],
"ontology": {
"a dog": "dog"
},
"confidenceThresholds": {
"dog": 0.5
},
"startTime": {
"_seconds": 1767225600,
"_nanoseconds": 0
}
}워크플로
Lists the Workflows in the workspace, without their specifications. Requires workflow:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
Successful response.
okThe request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The request rate is too high.
GET /{workspace}/workflows HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"workflows": [
{
"id": "wf_abc123",
"owner": "holeSv3hwbzrOv37vH5b",
"name": "Slow webhooks",
"url": "slow-webhooks",
"createTime": {
"_seconds": 1776013533,
"_nanoseconds": 0
},
"updateTime": {
"_seconds": 1776013533,
"_nanoseconds": 0
},
"createdByAI": false,
"editedByAI": false
}
],
"status": "ok"
}Returns a Workflow and its specification. Public Workflows need no API key. Private ones need workflow:read. Without the Workflow Versions feature, you can read only the 3 newest versions.
Roboflow API key or OAuth access token.
Workspace URL slug.
Workflow URL slug or ID.
Version ID from List Workflow versions. Returns that version's specification in config. Needs an API key.
Successful response.
okThe Workflow uses a block your workspace turned off.
The Workflow is private and the request has no API key.
The version is older than your plan's version history.
No Workflow with this slug or ID that your key can read, or no such version.
The request rate is too high.
GET /{workspace}/workflows/{workflowId} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"workflow": {
"id": "wf_abc123",
"owner": "holeSv3hwbzrOv37vH5b",
"name": "Slow webhooks",
"url": "slow-webhooks",
"createTime": {
"_seconds": 1776013533,
"_nanoseconds": 0
},
"updateTime": {
"_seconds": 1776013533,
"_nanoseconds": 0
},
"createdByAI": false,
"editedByAI": false,
"config": "{\"specification\":{\"version\":\"1.0\",\"inputs\":[],\"steps\":[],\"outputs\":[]}}",
"lastVersionConfig": "{\"specification\":{\"version\":\"1.0\",\"inputs\":[],\"steps\":[],\"outputs\":[]}}"
},
"status": "ok"
}Moves a Workflow to Trash. Requires workflow:update.
Roboflow API key or OAuth access token.
Workspace URL slug.
Workflow URL slug.
Successful response.
Always true.
Workspace URL slug.
Workflow URL slug from the request.
Workflow ID. Pass it as the restore id.
Always true: the Workflow is in Trash, not permanently deleted.
The request is invalid.
Authentication is missing or invalid.
The Workflow belongs to another workspace.
No Workflow with this URL slug exists in the workspace.
The request rate is too high.
DELETE /{workspace}/workflows/{workflowId} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"deleted": true,
"type": "workflow",
"workspace": "my-workspace",
"workflow": "slow-webhooks",
"workflowId": "wf_abc123",
"trash": true
}Lists the saved versions of a Workflow, newest first, and when each was deployed. Without the Workflow Versions feature, only the 3 newest are returned. Requires workflow:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
Workflow URL slug or ID.
Successful response.
limited when your plan shows only the 3 newest versions.
All versions, including ones your plan hides.
okThe request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
No Workflow with this slug or ID that your key can read.
The request rate is too high.
GET /{workspace}/workflows/{workflowId}/versions HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"versions": [
{
"id": "v_2",
"name": "Saved on Apr 12, 2026",
"createdAt": "2026-04-12T17:05:33.000Z",
"email": "API",
"isDeployed": true
}
],
"deployments": [
{
"id": "d_1",
"versionId": "v_2",
"createdAt": "2026-04-12T17:05:33.000Z",
"userEmail": "API"
}
],
"workflowVersionsAccess": "full",
"totalVersionCount": 1,
"status": "ok"
}Creates a Workflow. Send the fields in a JSON body. The same fields also work as query parameters, but then template is required, and long specifications can be cut off. Requires workflow:create.
Roboflow API key or OAuth access token.
Workspace URL slug.
Display name. A number is added when the name is taken.
URL slug. A number is added when the slug is taken.
The Workflow as a JSON string in the stored shape { "specification": { ... } }. It must parse as JSON. Workflows with blocks your workspace turned off are rejected.
{"specification":{"version":"1.0","inputs":[],"steps":[],"outputs":[]}}JSON string of template metadata. Required only when you send the fields as query parameters.
Project folder to create the Workflow in. With a folder-scoped key it must be one of the key's folders. Left out, the Workflow goes to the workspace root, or to the key's folder when the key has exactly one.
Successful response.
okA required field is missing, config is not valid JSON, or the Workflow uses a block your workspace turned off.
Authentication is missing or invalid.
A folder-scoped key named a folder outside its scope, or has several folders and no folderId was sent.
The folder does not exist.
The request rate is too high.
POST /{workspace}/createWorkflow HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 137
{
"name": "My Workflow",
"url": "my-workflow",
"config": "{\"specification\":{\"version\":\"1.0\",\"inputs\":[],\"steps\":[],\"outputs\":[]}}"
}{
"workflows": {
"id": "wf_xyz789",
"owner": "holeSv3hwbzrOv37vH5b",
"name": "My Workflow",
"url": "my-workflow",
"createTime": {
"_seconds": 1776013533,
"_nanoseconds": 0
},
"updateTime": {
"_seconds": 1776013533,
"_nanoseconds": 0
},
"createdByAI": false,
"editedByAI": false
},
"status": "ok"
}Replaces a Workflow's name, URL slug, and specification. Each update saves a new version and deploys it, so devices running the Workflow pick it up. Requires workflow:update.
Roboflow API key or OAuth access token.
Workspace URL slug.
Workflow ID (not the URL slug).
Display name. Must not be used by another Workflow in the workspace.
URL slug. Devices that use the old slug are moved to the new one.
The Workflow as a JSON string in the stored shape { "specification": { ... } }. It must parse as JSON. Workflows with blocks your workspace turned off are rejected.
{"specification":{"version":"1.0","inputs":[],"steps":[],"outputs":[]}}Successful response.
okA field is missing, config is not valid JSON, the name or slug is taken, or the Workflow uses a block your workspace turned off.
Authentication is missing or invalid.
The Workflow is in another workspace, or it is a project base Workflow.
No Workflow with this ID.
The request rate is too high.
POST /{workspace}/updateWorkflow HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 154
{
"id": "wf_xyz789",
"name": "My Workflow",
"url": "my-workflow",
"config": "{\"specification\":{\"version\":\"1.0\",\"inputs\":[],\"steps\":[],\"outputs\":[]}}"
}{
"workflow": {
"id": "wf_abc123",
"owner": "holeSv3hwbzrOv37vH5b",
"name": "Slow webhooks",
"url": "slow-webhooks",
"createTime": {
"_seconds": 1776013533,
"_nanoseconds": 0
},
"updateTime": {
"_seconds": 1776013533,
"_nanoseconds": 0
},
"createdByAI": false,
"editedByAI": false
},
"status": "ok"
}Copies a Workflow from any workspace into this one. Requires workflow:create.
Roboflow API key or OAuth access token.
Workspace URL slug.
URL slug of the workspace that owns the Workflow.
URL slug of the Workflow to copy.
Name of the copy. Defaults to the source name.
URL slug of the copy. Made from the name when left out.
Project folder for the copy. Same rules as createWorkflow.
Successful response.
URL slug of the copy.
ID of the copy.
okA required field is missing or a field is invalid.
Authentication is missing or invalid.
The source is a project base Workflow, or a folder-scoped key cannot place the copy.
The source workspace or Workflow does not exist.
The request rate is too high.
POST /{workspace}/forkWorkflow HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 106
{
"source_workspace": "other-workspace",
"source_workflow": "their-workflow",
"name": "My Fork",
"url": "my-fork"
}{
"workflow": "my-fork",
"workflow_id": "wf_fork123",
"status": "ok"
}Creates a token that runs one Workflow from a public client. Only Roboflow's own documentation workspace can call it. Every other workspace gets 403. Requires workflow:update.
Roboflow API key or OAuth access token.
Workspace URL slug.
Workflow ID.
Successful response.
okThe request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The request rate is too high.
POST /{workspace}/workflowToken HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 13
{
"id": "text"
}{
"token": "text",
"status": "ok"
}에이전트
Sends one message to Roboflow Agent and waits for the whole turn to finish, then returns the reply as one JSON object (not a stream). A turn that builds or edits Workflows can take minutes. Omit conversation_id to start a new conversation; the response returns its ID. The Agent can create Workflows, edit Workflows linked to the conversation, and answer questions about your workspace. A Workflow the Agent creates is saved and live right away. An edit publishes when the Workflow is set to Auto-publish, and stays a draft when it is Protected; publish a draft with the publish endpoint. Requires the workflow:create and workflow:update scopes, and the key's user needs the Manage Workflows permission. The Agent acts as the user who created the key. A workspace-wide key created by Roboflow (with no user) acts as the workspace creator; a folder- or scope-limited key like that is refused. A folder-scoped key limits the Agent to Workflows and models in its folders. Each turn spends Roboflow credits, unless the workspace runs the Agent on its own LLM key.
Roboflow API key or OAuth access token.
Workspace URL slug.
The instruction or question for the Agent.
ID of a conversation in this workspace to continue. Omit to start a new conversation.
agent lets the Agent make changes. plan makes it outline what it would do without making changes. Any other value means agent.
agentPossible values: Successful response.
The Agent's reply.
Conversation ID. Pass it back as conversation_id to continue the conversation.
message is missing or not a string, or the workspace AI policy refuses the workspace's own LLM key (error_type WORKSPACE_LLM_KEY).
Authentication is missing or invalid.
The workspace has no credit system, its plan is not chosen yet (error_type FEATURE_NOT_AVAILABLE), or it is out of credits (error_type CREDIT_LIMIT_REACHED).
The key's user lacks the Manage Workflows permission, the key has no user to act as, Agent features are turned off for the workspace (error_type AGENT_DISABLED), conversation_id is not a conversation in this workspace, or the conversation references Workflows outside the key's folders.
The resource does not exist or is not accessible.
Workspace usage is paused (error_type USAGE_DISABLED).
The workspace's own LLM provider key hit its rate limit (error_type WORKSPACE_LLM_KEY, retryable true). Roboflow's own rate limit also returns 429.
The workspace's own LLM provider returned an error (error_type WORKSPACE_LLM_KEY). Check code and retryable.
The workspace requires its own LLM key, but the key cannot be used (error_type WORKSPACE_LLM_KEY).
POST /{workspace}/agent/chat HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 67
{
"message": "Build me a workflow that detects cars and counts them"
}{
"text": "I created a Workflow called Car Counter that detects and counts cars.",
"workflows": [
{
"id": "Qm3RtY8vLp2KsW6nHx0J",
"url": "car-counter-1747252800000",
"name": "Car Counter",
"specification": {
"version": "1.0",
"inputs": [
{
"type": "InferenceImage",
"name": "image"
}
],
"steps": [
{
"type": "roboflow_core/roboflow_object_detection_model@v2",
"name": "model",
"images": "$inputs.image",
"model_id": "rfdetr-base",
"class_filter": [
"car"
]
}
],
"outputs": [
{
"type": "JsonField",
"name": "predictions",
"selector": "$steps.model.predictions"
}
]
}
}
],
"conversation_id": "4Fq9ZtLw2XbN7cRkV1sA"
}Publishes the latest draft version of a Workflow, so the draft the Agent saved becomes the version that runs. workflowId takes the Workflow's URL slug or its ID. There must be an unpublished draft. Requires the workflow:update scope, and the key's user needs the Manage Workflows and Publish Workflows permissions and write access to the Workflow. A project's base Workflow cannot be published through this endpoint.
Roboflow API key or OAuth access token.
Workspace URL slug.
Workflow URL slug.
Successful response.
Workflow ID.
Workflow URL slug.
ID of the version that is now published.
The Workflow has no unpublished draft.
Authentication is missing or invalid.
Agent features are turned off for the workspace (error_type AGENT_DISABLED), the Workflow is outside the key's folders or the user cannot write to it, the user lacks the Manage Workflows or Publish Workflows permission, the key has no user to act as, or the Workflow is a project's base Workflow.
No Workflow with this URL slug or ID in the workspace.
The request rate is too high.
The draft uses a block that is turned off in this workspace, or another server error.
POST /{workspace}/agent/workflows/{workflowId}/publish HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"workflowId": "Qm3RtY8vLp2KsW6nHx0J",
"workflowUrl": "car-counter-1747252800000",
"versionId": "8hTq2LmZ0pXc4VnB7wRe",
"status": "published"
}Lists every Agent conversation in the workspace, from any member and from both the app and the API, most recently updated first. There is no paging. A folder-scoped key only sees conversations whose Workflows are all in its folders, plus conversations without Workflows that were started with that folder scope. Requires the workflow:read scope.
Roboflow API key or OAuth access token.
Workspace URL slug.
api returns conversations started through the Agent API. web returns all others. Any other value is ignored.
Workflow URL slug or ID. Returns only conversations linked to this Workflow.
Successful response.
The request is invalid.
Authentication is missing or invalid.
The workflow filter names a Workflow outside the key's folders, or the key cannot access the workspace.
The workflow filter names no Workflow in the workspace.
The request rate is too high.
GET /{workspace}/agent/conversations HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"conversations": [
{
"id": "4Fq9ZtLw2XbN7cRkV1sA",
"name": "Car Counter",
"type": "workflow",
"source": "api",
"workflowIds": [
"Qm3RtY8vLp2KsW6nHx0J"
],
"created_on": "2026-05-14T20:00:00.000Z",
"updated_on": "2026-05-14T20:05:00.000Z",
"sharing": {
"scope": "private"
}
}
]
}Returns one Agent conversation with all of its messages, oldest first. Requires the workflow:read scope.
Roboflow API key or OAuth access token.
Workspace URL slug.
Conversation ID.
Successful response.
Conversation ID.
Conversation title. Generated after the first reply. Missing until then, unless a linked Workflow's name stands in.
Conversation kind. workflow once the Agent has created a Workflow in it. Missing on a conversation with no kind yet.
Where the conversation started: api for the Agent API, web for the app. Missing on older web conversations.
IDs of the Workflows the conversation created or edited.
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
No conversation with this ID in the workspace, or it references Workflows outside the key's folders.
The request rate is too high.
GET /{workspace}/agent/conversations/{conversationId} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "4Fq9ZtLw2XbN7cRkV1sA",
"name": "Car Counter",
"type": "workflow",
"source": "api",
"created_on": "2026-05-14T20:00:00.000Z",
"updated_on": "2026-05-14T20:05:00.000Z",
"workflowIds": [
"Qm3RtY8vLp2KsW6nHx0J"
],
"messages": [
{
"id": "a0c3e1d2-5b7f-4e8a-9c6d-1f2e3a4b5c6d",
"role": "user",
"parts": [
{
"type": "text",
"text": "Build me a workflow that detects cars and counts them"
}
],
"content": "",
"createdAt": "2026-05-14T20:00:00.000Z"
},
{
"id": "msg_7KpQ2mX9vB",
"role": "assistant",
"parts": [
{
"type": "text",
"text": "I created a Workflow called Car Counter that detects and counts cars."
}
],
"content": "",
"createdAt": "2026-05-14T20:05:00.000Z"
}
]
}검색
Searches public Roboflow Universe projects by text and returns up to 12 results per page, for at most 10 pages. By default, results leave out forked projects and projects with 24 or fewer images. Any valid API key works, with any scope.
Roboflow API key or OAuth access token.
Search text, up to 500 characters. Add filters to it (ex: class:helmet, tag:construction, images>100, stars>=5, sort:downloads, like:). A project type in the text (ex: object detection) filters by type, and the word model returns only projects with a trained model. Send workspace/project or workspace/project/version to look up one public project directly. Characters other than letters, numbers, underscores, spaces, and : < > = - + , / " are removed.
hard hatsPage of 12 results to return, starting at 1. Values above 10 return page 10, and values that are not a number return page 1.
1Set to true to return only projects with a trained model. Any non-empty value turns the filter on.
trueReturn only projects of this type (ex: object-detection, classification, instance-segmentation). It replaces a project type written in the query text.
object-detectionSet to true to add modelVersions to each result. Projects that are no longer public are then left out, so count can be lower than the page size.
falsePossible values: Successful response.
The search text after cleanup (lowercase, unsupported characters removed). null for a search by image with no text.
What the search used.
Page returned. A direct workspace/project lookup always returns page 1.
Results per page. Always 12.
Results on this page.
The query text is missing, longer than 500 characters, has no search terms left after unsupported characters are removed, or uses a filter Roboflow cannot parse.
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The request rate is too high.
The search service failed or returned an unexpected response. Retry the request.
GET /universe/search?q=text HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"query": "hard hats",
"query_type": "text",
"page": 1,
"page_size": 12,
"count": 1,
"results": [
{
"name": "Hard Hat Workers",
"url": "https://universe.roboflow.com/joseph-nelson/hard-hat-workers",
"workspace": {
"name": "Joseph Nelson",
"url": "joseph-nelson"
},
"projectId": "Ha6Lp2WbUrXIUcxF0rM5",
"type": "object-detection",
"annotation": "workers",
"thumbnail": "https://source.roboflow.com/7vzb8WTEaqT2bQ2yp3Rs/Ys2rE4lWJ7c8PqRUDb6z/thumb.jpg",
"annotationThumbnail": "https://source.roboflow.com/7vzb8WTEaqT2bQ2yp3Rs/Ys2rE4lWJ7c8PqRUDb6z/annotation-workers.png",
"classes": [
"head",
"helmet",
"person"
],
"classCount": 3,
"images": 7041,
"description": "Workers with and without hard hats on construction sites.",
"tags": [
"construction",
"safety"
],
"license": "Public Domain",
"updated": "2026-03-14T18:22:05.000Z",
"stars": 42,
"views": 120345,
"downloads": 15210,
"modelCount": 2,
"latestVersion": 14,
"latestModelVersion": 14
}
]
}Searches public Roboflow Universe projects for images that look like the one you send, optionally refined with text. Results and paging work like the GET search. The model, projectType, and includeModelVersions filters go in the query string. Any valid API key works, with any scope.
Roboflow API key or OAuth access token.
Set to true to return only projects with a trained model. Any non-empty value turns the filter on.
trueReturn only projects of this type (ex: object-detection, classification, instance-segmentation). It replaces a project type written in the query text.
object-detectionSet to true to add modelVersions to each result. Projects that are no longer public are then left out, so count can be lower than the page size.
falsePossible values: The query image as base64, with or without a data:image/...;base64, prefix. Up to 4 MiB of base64 (4,194,304 characters) and 8192 x 8192 pixels. Roboflow shrinks it to 1024 pixels on its longest side before searching.
Optional text that refines the image search. Search text, up to 500 characters. Add filters to it (ex: class:helmet, tag:construction, images>100, stars>=5, sort:downloads, like:). A project type in the text (ex: object detection) filters by type, and the word model returns only projects with a trained model. Send workspace/project or workspace/project/version to look up one public project directly. Characters other than letters, numbers, underscores, spaces, and : < > = - + , / " are removed.
Page of 12 results to return, starting at 1. Values above 10 return page 10, and values that are not a number return page 1.
1Successful response.
The search text after cleanup (lowercase, unsupported characters removed). null for a search by image with no text.
What the search used.
Page returned. A direct workspace/project lookup always returns page 1.
Results per page. Always 12.
Results on this page.
image is missing, is not a decodable base64 image, or is over the size limits, or q is longer than 500 characters or uses a filter Roboflow cannot parse.
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The request rate is too high.
The search service failed or returned an unexpected response. Retry the request.
POST /universe/search HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 70
{
"image": "/9j/4AAQSkZJRgABAQAAAQABAAD...",
"q": "class:helmet",
"page": 1
}{
"query": "hard hats",
"query_type": "text",
"page": 1,
"page_size": 12,
"count": 1,
"results": [
{
"name": "Hard Hat Workers",
"url": "https://universe.roboflow.com/joseph-nelson/hard-hat-workers",
"workspace": {
"name": "Joseph Nelson",
"url": "joseph-nelson"
},
"projectId": "Ha6Lp2WbUrXIUcxF0rM5",
"type": "object-detection",
"annotation": "workers",
"thumbnail": "https://source.roboflow.com/7vzb8WTEaqT2bQ2yp3Rs/Ys2rE4lWJ7c8PqRUDb6z/thumb.jpg",
"annotationThumbnail": "https://source.roboflow.com/7vzb8WTEaqT2bQ2yp3Rs/Ys2rE4lWJ7c8PqRUDb6z/annotation-workers.png",
"classes": [
"head",
"helmet",
"person"
],
"classCount": 3,
"images": 7041,
"description": "Workers with and without hard hats on construction sites.",
"tags": [
"construction",
"safety"
],
"license": "Public Domain",
"updated": "2026-03-14T18:22:05.000Z",
"stars": 42,
"views": 120345,
"downloads": 15210,
"modelCount": 2,
"latestVersion": 14,
"latestModelVersion": 14
}
]
}Searches the images in one project with filters, text, or a similar image, and pages through results with offset and limit. An API key from the project's workspace can search any of its projects. An API key from another workspace can search public projects only. Requires image:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Text to sort results by semantic similarity.
Image ID to sort results by visual similarity.
Base64 image to sort results by visual similarity.
Return only images with this tag.
Return only images with at least one annotation of this class.
Return only images in the project's Dataset.
Return only images in any batch of the project.
Return only images in this batch.
Return only images in any annotation job of the project.
Return only images in this annotation job.
Results to skip.
0Results to return. Values over 250 return 250.
50Successful response.
Images that match.
A field name in fields is unknown, mediaTypes is invalid, or a membership filter is not a boolean.
Authentication is missing or invalid, or the project does not belong to this workspace.
The credential does not have access to this resource.
The project does not exist, or it is private and the API key is from another workspace.
The request rate is too high.
POST /{workspace}/{project}/search HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 95
{
"prompt": "forklift at night",
"in_dataset": true,
"limit": 50,
"fields": [
"id",
"name",
"tags",
"url"
]
}{
"offset": 0,
"total": 292,
"results": [
{
"id": "image123",
"mediaType": "image",
"name": "humpbackwhale.jpg",
"owner": "owner123",
"url": "https://source.roboflow.com/owner123/image123/original.jpg",
"annotations": {
"count": 5,
"classes": {
"whale": 1,
"fish": 4
}
},
"labels": [],
"tags": [
"cam_x13"
]
}
]
}Searches the images across a workspace with a RoboQL query, the same syntax as dataset search in the web app. To get the next page, send the continuationToken from the response. The API key must belong to this workspace; keys from other workspaces cannot search it, even when it has public projects. Requires image:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
RoboQL query: the filters from the web app dataset search plus project: and dataset:, with free text for semantic search. Leave it out or empty to match every image.
""Results per page.
50Token from the previous page. Send it with the same query to get the next page.
Project folder IDs to limit results to. Not allowed with a folder-scoped API key.
Successful response.
Images that match.
Send it in the next request to get the next page. Not present when there are no results.
query is not a string or is not valid RoboQL, a project: or dataset: filter names a project outside the workspace, mediaTypes is invalid, or includeProjectGroupIds was sent with a folder-scoped API key.
Authentication is missing or invalid.
The credential does not have access to this resource.
The workspace does not exist, or the API key is from another workspace.
The request rate is too high.
POST /{workspace}/search/v1 HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 108
{
"query": "project:my-project nighttime",
"pageSize": 10,
"fields": [
"tags",
"width",
"height",
"filename",
"split"
]
}{
"total": 42,
"continuationToken": "WzE3Njc5MDAwMDAwMDAsImltYWdlMTIzIl0=",
"results": [
{
"id": "image123",
"mediaType": "image",
"filename": "night-001.jpg",
"width": 1280,
"height": 720,
"tags": [
"night"
],
"projectData": {
"my-project": {
"inDataset": true,
"split": "train"
}
}
}
]
}Starts building a ZIP dataset, in the format you choose, from the workspace images that match a RoboQL query. The images keep their original files. Poll Get image search export status with the returned link until ready is true. Exports are deleted after 7 days. Requires image:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
RoboQL query that selects the images (ex: tag:review split:train). Required unless you send dataset. Semantic (free text) search is not supported. Use filters such as class:, tag:, split:, or filename:.
Export format (ex: coco, yolov8, voc). With dataset, it must be a format the project type supports.
Project URL slug. Limits the export to this project and uses its annotation group. Cannot be sent with annotationGroup.
Annotation group to export annotations from. Cannot be sent with dataset.
Name of the export. Defaults to -search-export.
Accepted for asynchronous processing.
Always true.
Export link. Pass it to Get image search export status.
query and dataset are both missing, format is missing, dataset and annotationGroup are both sent, query uses semantic search, or format does not fit the project type.
Authentication is missing or invalid.
The project named in dataset belongs to another workspace.
The project named in dataset does not exist.
The request rate is too high.
Roboflow could not start the export.
POST /{workspace}/search/export HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 78
{
"query": "tag:review split:train",
"format": "coco",
"dataset": "hard-hats-x1y2z"
}{
"success": true,
"link": "a1b2c3d4e5"
}Returns whether an image search export is ready and, when it is, a download URL that works for 15 minutes. ready stays false until the ZIP is built. A link that does not exist, or an export that failed, also returns ready false, so stop polling after a while. Requires image:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
Export link returned when you started the export.
Successful response.
True when the ZIP is built and link holds its download URL.
Signed download URL for the ZIP, valid for 15 minutes. Only when ready is true.
The request is invalid.
Authentication is missing or invalid.
The export belongs to another workspace.
The resource does not exist or is not accessible.
The request rate is too high.
Roboflow could not create the download URL.
GET /{workspace}/search/export/{link} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"ready": true,
"link": "https://storage.googleapis.com/roboflow-exports/my-workspace/search/a1b2c3d4e5/coco.zip?X-Goog-Signature=..."
}휴지통 및 작업
Lists the projects, dataset versions, Workflows, and trainings in the workspace Trash that are still inside the 30-day retention window. Requires project:read. With an OAuth token, the user also needs permission to view Trash.
Roboflow API key or OAuth access token.
Workspace URL slug.
Successful response.
The request is invalid.
Authentication is missing or invalid.
The OAuth user does not have permission to view Trash.
The resource does not exist or is not accessible.
The request rate is too high.
GET /{workspace}/trash HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"items": [
{
"type": "project",
"id": "d_abc123",
"name": "My Detector",
"url": "my-detector",
"projectType": "object-detection",
"annotation": "vehicles",
"icon": null,
"iconOwner": null,
"iconHasAnnotation": false,
"cleanupDeleteImages": false,
"deletedAt": "2026-04-20T17:05:33.000Z",
"scheduledCleanupAt": "2026-05-20T17:05:33.000Z",
"deletedBy": "uid-of-user",
"deletedByName": "Alice"
},
{
"type": "version",
"id": "3",
"name": "augmented-416",
"parentId": "d_xyz789",
"parentName": "My Other Project",
"parentUrl": "my-other-project",
"parentInTrash": false,
"deletedAt": "2026-04-21T12:14:02.000Z",
"scheduledCleanupAt": "2026-05-21T12:14:02.000Z",
"deletedBy": "uid-of-user",
"deletedByName": "Bob"
}
],
"sections": {
"projects": [],
"versions": [],
"workflows": [],
"trainings": []
}
}Restores one item from Trash to where it was deleted from. Take type, id, and parentId from the item in the Trash list. The required scope depends on type: project:update for a project, version:update for a version or training, and workflow:update for a Workflow. The item must belong to the workspace in the URL.
Roboflow API key or OAuth access token.
Workspace URL slug.
Kind of item to restore.
The item's id from the Trash list. For a version, the version number.
Required for a version: the parentId (project ID) from the Trash list.
Successful response.
Always true.
Kind of item restored.
ID of the item restored.
type or id is missing, type is not supported, parentId is missing for a version, the item is not in Trash or is past retention, or its parent project or version is still in Trash.
The API key does not have the scope this type needs.
The item belongs to another workspace, or the OAuth user cannot restore it.
The item does not exist.
The training is already being permanently deleted and cannot be restored.
The request rate is too high.
POST /{workspace}/trash/restore HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 49
{
"type": "version",
"id": "3",
"parentId": "d_abc123"
}{
"restored": true,
"type": "version",
"id": "3"
}Returns the status of a long-running task. Endpoints that run in the background (ex: fork a Universe project, rebalance splits, add Asset Library images, update metadata on many images) answer with a taskId and a url that points here. Poll it until status is completed or failed. Any API key from the workspace in the URL works; no scope is required.
Roboflow API key or OAuth access token.
Workspace URL slug.
Asynchronous task ID.
Successful response.
The task ID from the request.
Task state: created, running, completed, or failed. completed and failed are final.
runningName of the step a multi-step task is on. Only some tasks return it.
When the task was created.
When the task last changed.
Present when status is completed. Its shape depends on the endpoint that started the task, and it is null when the task saved no result.
Present when status is failed. The failure message, or "Task failed".
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
The task does not exist or belongs to another workspace, or the API key is from another workspace.
The request rate is too high.
GET /{workspace}/asynctasks/{taskId} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"taskId": "abc123",
"status": "completed",
"progress": {
"current": 100,
"total": 100
},
"createdAt": "2026-10-01T12:00:00.000Z",
"updatedAt": "2026-10-01T12:03:10.000Z",
"result": {
"forked": true,
"datasetUrl": "football-players-detection-3zvbc-a1b2c",
"id": "my-workspace/football-players-detection-3zvbc-a1b2c",
"name": "Football Players Detection",
"url": "https://app.roboflow.com/my-workspace/football-players-detection-3zvbc-a1b2c"
}
}배포
Returns the project's base Workflow, the model it runs, whether it can serve inference, and its Active Learning settings. Creates the base Workflow if the project has none. Requires project:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Successful response.
True when this request created the base Workflow.
Get only. Whether a new GPT-6 Astra or GPT-6.1 Sol endpoint would run for this workspace.
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The request rate is too high.
GET /{workspace}/{project}/deploy HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"project": {
"id": "abc123",
"url": "my-project",
"name": "My Project",
"owner": "my-workspace-id",
"type": "object-detection",
"classes": [
"cat",
"dog"
],
"multilabel": false
},
"workflow": {
"id": "wf_xyz",
"name": "My Project Base Workflow",
"url": "my-project-base-workflow",
"workspaceUrl": "my-workspace",
"inferencePath": "/infer/workflows/my-workspace/my-project-base-workflow"
},
"model": {
"id": "rfdetr-medium",
"kind": "pretrained",
"displayName": "RF-DETR Medium",
"modelId": "rfdetr-medium"
},
"deployability": {
"status": "deployable",
"modelWasConfigured": false,
"selectedModelId": null,
"selectionReason": null
},
"activeLearning": {
"enabled": false,
"collectionLimits": {
"dataPercentage": 100,
"minutelyUsageLimit": 10,
"hourlyUsageLimit": 100,
"dailyUsageLimit": 1000,
"labelingBatchesRecreationFrequency": "daily",
"usageQuotaName": "upload_quota_active_learning",
"imageCompressionLevel": 95,
"maxImageHeight": 1080,
"maxImageWidth": 1920,
"persistPredictions": true
},
"filters": []
},
"baseWorkflowWasCreated": false
}Sets the model the project's base Workflow runs. The model must fit the project type. Requires project:update.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Successful response.
True when this request created the base Workflow.
Get only. Whether a new GPT-6 Astra or GPT-6.1 Sol endpoint would run for this workspace.
model is missing or invalid, or the model does not fit the project type.
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The request rate is too high.
POST /{workspace}/{project}/deploy/model HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 55
{
"model": {
"type": "model_id",
"modelId": "rfdetr-medium"
}
}{
"project": {
"id": "abc123",
"url": "my-project",
"name": "My Project",
"owner": "my-workspace-id",
"type": "object-detection",
"classes": [
"cat",
"dog"
],
"multilabel": false
},
"workflow": {
"id": "wf_xyz",
"name": "My Project Base Workflow",
"url": "my-project-base-workflow",
"workspaceUrl": "my-workspace",
"inferencePath": "/infer/workflows/my-workspace/my-project-base-workflow"
},
"model": {
"id": "rfdetr-medium",
"kind": "pretrained",
"displayName": "RF-DETR Medium",
"modelId": "rfdetr-medium"
},
"deployability": {
"status": "deployable",
"modelWasConfigured": false,
"selectedModelId": null,
"selectionReason": null
},
"activeLearning": {
"enabled": false,
"collectionLimits": {
"dataPercentage": 100,
"minutelyUsageLimit": 10,
"hourlyUsageLimit": 100,
"dailyUsageLimit": 1000,
"labelingBatchesRecreationFrequency": "daily",
"usageQuotaName": "upload_quota_active_learning",
"imageCompressionLevel": 95,
"maxImageHeight": 1080,
"maxImageWidth": 1920,
"persistPredictions": true
},
"filters": []
},
"baseWorkflowWasCreated": false
}Returns the project's base Workflow, its model, and its Active Learning settings. Requires project:read and the Active Learning permission in the workspace.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Successful response.
The request is invalid.
Authentication is missing or invalid.
You do not have the Active Learning permission in this workspace.
The resource does not exist or is not accessible.
The request rate is too high.
GET /{workspace}/{project}/deploy/active-learning HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"project": {
"id": "abc123",
"url": "my-project",
"name": "My Project",
"owner": "my-workspace-id",
"type": "object-detection",
"classes": [
"cat",
"dog"
],
"multilabel": false
},
"workflow": {
"id": "wf_xyz",
"name": "My Project Base Workflow",
"url": "my-project-base-workflow",
"workspaceUrl": "my-workspace",
"inferencePath": "/infer/workflows/my-workspace/my-project-base-workflow"
},
"model": {
"id": "rfdetr-medium",
"kind": "pretrained",
"displayName": "RF-DETR Medium",
"modelId": "rfdetr-medium"
},
"deployability": {
"status": "deployable",
"modelWasConfigured": false,
"selectedModelId": null,
"selectionReason": null
},
"activeLearning": {
"enabled": false,
"collectionLimits": {
"dataPercentage": 100,
"minutelyUsageLimit": 10,
"hourlyUsageLimit": 100,
"dailyUsageLimit": 1000,
"labelingBatchesRecreationFrequency": "daily",
"usageQuotaName": "upload_quota_active_learning",
"imageCompressionLevel": 95,
"maxImageHeight": 1080,
"maxImageWidth": 1920,
"persistPredictions": true
},
"filters": []
}
}Turns on image collection in the project's base Workflow. If no model is set, picks one first. Calling it again changes nothing. Requires project:update.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Successful response.
The base Workflow is not deployable, or no model could be set.
Authentication is missing or invalid.
You do not have the Active Learning permission in this workspace.
The resource does not exist or is not accessible.
The request rate is too high.
POST /{workspace}/{project}/deploy/active-learning/enable HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"project": {
"id": "abc123",
"url": "my-project",
"name": "My Project",
"owner": "my-workspace-id",
"type": "object-detection",
"classes": [
"cat",
"dog"
],
"multilabel": false
},
"workflow": {
"id": "wf_xyz",
"name": "My Project Base Workflow",
"url": "my-project-base-workflow",
"workspaceUrl": "my-workspace",
"inferencePath": "/infer/workflows/my-workspace/my-project-base-workflow"
},
"model": {
"id": "rfdetr-medium",
"kind": "pretrained",
"displayName": "RF-DETR Medium",
"modelId": "rfdetr-medium"
},
"deployability": {
"status": "deployable",
"modelWasConfigured": false,
"selectedModelId": null,
"selectionReason": null
},
"activeLearning": {
"enabled": false,
"collectionLimits": {
"dataPercentage": 100,
"minutelyUsageLimit": 10,
"hourlyUsageLimit": 100,
"dailyUsageLimit": 1000,
"labelingBatchesRecreationFrequency": "daily",
"usageQuotaName": "upload_quota_active_learning",
"imageCompressionLevel": 95,
"maxImageHeight": 1080,
"maxImageWidth": 1920,
"persistPredictions": true
},
"filters": []
}
}Turns off image collection. Your collection limits and filters are kept. Requires project:update.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Successful response.
The request is invalid.
Authentication is missing or invalid.
You do not have the Active Learning permission in this workspace.
The resource does not exist or is not accessible.
The request rate is too high.
POST /{workspace}/{project}/deploy/active-learning/disable HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"project": {
"id": "abc123",
"url": "my-project",
"name": "My Project",
"owner": "my-workspace-id",
"type": "object-detection",
"classes": [
"cat",
"dog"
],
"multilabel": false
},
"workflow": {
"id": "wf_xyz",
"name": "My Project Base Workflow",
"url": "my-project-base-workflow",
"workspaceUrl": "my-workspace",
"inferencePath": "/infer/workflows/my-workspace/my-project-base-workflow"
},
"model": {
"id": "rfdetr-medium",
"kind": "pretrained",
"displayName": "RF-DETR Medium",
"modelId": "rfdetr-medium"
},
"deployability": {
"status": "deployable",
"modelWasConfigured": false,
"selectedModelId": null,
"selectionReason": null
},
"activeLearning": {
"enabled": false,
"collectionLimits": {
"dataPercentage": 100,
"minutelyUsageLimit": 10,
"hourlyUsageLimit": 100,
"dailyUsageLimit": 1000,
"labelingBatchesRecreationFrequency": "daily",
"usageQuotaName": "upload_quota_active_learning",
"imageCompressionLevel": 95,
"maxImageHeight": 1080,
"maxImageWidth": 1920,
"persistPredictions": true
},
"filters": []
}
}Saves collection limits and, when you send them, filters. Enable Active Learning on the project first: the call fails when collection was never turned on. It does not turn collection on or off. Requires project:update.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Successful response.
collectionLimits or filters are invalid (the body has error and details), or a detectionSize filter was sent for a project that is not object detection or instance segmentation.
Authentication is missing or invalid.
You do not have the Active Learning permission in this workspace.
The resource does not exist or is not accessible.
The request rate is too high.
POST /{workspace}/{project}/deploy/active-learning/configuration HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 472
{
"collectionLimits": {
"dataPercentage": 50,
"minutelyUsageLimit": 10,
"hourlyUsageLimit": 100,
"dailyUsageLimit": 1000,
"labelingBatchesRecreationFrequency": "daily",
"usageQuotaName": "default",
"imageCompressionLevel": 85,
"imageName": "camera-1",
"maxImageHeight": 1080,
"maxImageWidth": 1920,
"registrationTags": [
"production"
],
"persistPredictions": true
},
"filters": [
{
"type": "classConfidence",
"classFilterMode": "any",
"classes": [
"cat"
],
"confidenceLowerBound": 0.2,
"confidenceUpperBound": 0.8
}
]
}{
"project": {
"id": "abc123",
"url": "my-project",
"name": "My Project",
"owner": "my-workspace-id",
"type": "object-detection",
"classes": [
"cat",
"dog"
],
"multilabel": false
},
"workflow": {
"id": "wf_xyz",
"name": "My Project Base Workflow",
"url": "my-project-base-workflow",
"workspaceUrl": "my-workspace",
"inferencePath": "/infer/workflows/my-workspace/my-project-base-workflow"
},
"model": {
"id": "rfdetr-medium",
"kind": "pretrained",
"displayName": "RF-DETR Medium",
"modelId": "rfdetr-medium"
},
"deployability": {
"status": "deployable",
"modelWasConfigured": false,
"selectedModelId": null,
"selectionReason": null
},
"activeLearning": {
"enabled": false,
"collectionLimits": {
"dataPercentage": 100,
"minutelyUsageLimit": 10,
"hourlyUsageLimit": 100,
"dailyUsageLimit": 1000,
"labelingBatchesRecreationFrequency": "daily",
"usageQuotaName": "upload_quota_active_learning",
"imageCompressionLevel": 95,
"maxImageHeight": 1080,
"maxImageWidth": 1920,
"persistPredictions": true
},
"filters": []
}
}Lists the review queue: batches of collected images and the annotation jobs made from them, with totals. Requires project:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
Page number, from 1.
1Items per page.
10Text matched against queue names, types, IDs, reviewers, and labelers.
Reviewer email, or unassigned for items with no reviewer.
not_started for batches, in_progress for annotation jobs.
allPossible values: createdPossible values: descPossible values: Successful response.
The request is invalid.
Authentication is missing or invalid.
You do not have the Active Learning permission in this workspace.
The resource does not exist or is not accessible.
The request rate is too high.
GET /{workspace}/{project}/deploy/active-learning/images HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"activeLearningImages": {
"totalImagesReadyForReview": 0,
"totalImagesBeingReviewed": 0,
"batches": [],
"annotationJobs": [],
"latestBatch": null,
"latestAnnotationJob": null,
"sampleImages": [],
"reviewQueueCounts": {
"all": 0,
"notStarted": 0,
"inProgress": 0
},
"reviewQueuePage": {
"page": 1,
"pageSize": 20,
"totalItems": 0,
"totalPages": 1,
"items": [],
"search": "",
"status": "all",
"sortBy": "created",
"sortDirection": "desc",
"reviewer": ""
}
}
}모니터링
Get inference counts, confidence, and inference time for the Workspace's models, with the same numbers for the period of the same length before. Available on Enterprise plans. Requires workspace-stats:read. Each API key can make 50 requests per minute.
Roboflow API key or OAuth access token.
Workspace URL slug.
Start of the time range in UTC (ex: 2026-10-01 00:00:00). Defaults to 24 hours before the request.
2026-10-01 00:00:00End of the time range in UTC. Defaults to the time of the request.
2026-10-08 00:00:00Comma-separated model IDs without versions. Omit to include every model.
license-plate-detector,truck-detectorSuccessful response.
Totals across the selected models, then one row per model and predicted class. A null value means there were no inferences for it in that period.
Inferences in the time range.
Inferences in the period of the same length before the time range.
Failed inferences in the time range.
Failed inferences in the previous period.
Average prediction confidence, from 0 to 1.
Average prediction confidence in the previous period.
Average inference time in seconds, including image preprocessing.
Average inference time in seconds in the previous period.
A time is not a valid date, or the Workspace is not on an Enterprise plan.
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
More than 50 requests in a minute from this API key. X-RateLimit-Reset gives the time the limit resets.
The statistics could not be fetched.
GET /{workspace}/inference-stats HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"num_inferences": 120,
"prev_num_inferences": 290,
"num_errors": 0,
"prev_num_errors": 0,
"avg_confidence": 0.925,
"prev_avg_confidence": 0.861,
"avg_response_time": 0.165,
"prev_avg_response_time": 0.044,
"inference_stats": [
{
"model_name": "cards-3z9gn",
"predicted_class": "Playingcards",
"num_inferences": 106,
"prev_num_inferences": 190,
"num_errors": null,
"prev_num_errors": null,
"avg_confidence": 0.931,
"prev_avg_confidence": 0.936,
"avg_response_time": 0.177,
"prev_avg_response_time": 0.055,
"median_confidence": 0.927,
"class_count": 211,
"deployment_types": "hosted",
"inference_server_versions": "0.15.3,0.16.0",
"model_num_inferences": 107,
"prev_model_num_inferences": 190
}
]
}Attach custom metadata to inferences so you can filter and group them in Model Monitoring. Requires model:infer.
Roboflow API key or OAuth access token.
Workspace URL slug.
Successful response.
Present when the metadata was saved.
Present instead of status when the metadata could not be saved. The status code is still 200.
The body is missing data, or a field_name or field_value is longer than 100 characters.
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The request rate is too high.
POST /{workspace}/inference-stats/metadata HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 234
{
"data": [
{
"inference_ids": [
"a12a19a9-a933-44c9-970c-a55ea03bb453"
],
"field_name": "camera_location",
"field_value": "canada"
},
{
"inference_ids": [
"accf0af9-bdf0-4b22-8106-6988d4cada5a"
],
"field_name": "camera_location",
"field_value": "emea"
}
]
}{
"status": "ok"
}비전 이벤트
Creates one Vision Event. Only eventId, eventType, useCaseId, and timestamp are strictly checked. Problems in other fields come back as warnings, and the event is still stored. Sending an eventId that already exists replaces the earlier event. A useCaseId that matches no active use case (ex: an archived one) also stores the event, with an entity_not_found warning. The workspace comes from the API key. Requires the vision-events:write or device:update scope.
Roboflow API key or OAuth access token.
Unique event ID. Use a UUID (v4). An event sent with an eventId that already exists replaces the earlier event.
ID of the use case the event belongs to. solution and solutionId are deprecated aliases.
When the event happened, in ISO 8601. A timestamp more than one year old or later than tomorrow is stored, but returns an invalid_value warning.
Index in images of the image to show first.
A note about the event. With operator_feedback, this holds the reviewer's note.
The event's money value in the smallest unit of the use case currency (ex: cents for USD). Omitted, the use case default applies. An invalid value is dropped with a warning. operator_feedback events never carry a value.
Set by Edge Device Backup when the device closed the event before its video finished uploading.
Created.
Present when the request used a deprecated field name (solution or solutionId) instead of useCaseId.
eventId, eventType, useCaseId, or timestamp is missing or invalid, or useCaseId and a deprecated alias (solution, solutionId) disagree.
Authentication is missing or invalid.
The API key lacks the vision-events:write or device:update scope or cannot access the workspace.
The resource does not exist or is not accessible.
The request rate is too high.
POST /vision-events HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 412
{
"eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"eventType": "quality_check",
"useCaseId": "a1b3c8e1",
"timestamp": "2026-01-15T10:30:00Z",
"deviceId": "camera-node-5",
"images": [
{
"sourceId": "Pq7sV2kWx9LmN4rT6yZb",
"objectDetections": [
{
"class": "defect",
"x": 100,
"y": 200,
"width": 50,
"height": 30,
"confidence": 0.95
}
]
}
],
"eventData": {
"result": "fail",
"externalId": "batch-001"
},
"customMetadata": {
"line": "A1",
"temperature": 72.5
}
}{
"eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"created": true,
"warnings": [
{
"type": "invalid_value",
"path": "eventData.result",
"value": "failed",
"valueType": "string"
}
]
}Creates up to 100 Vision Events in one request. Each event is checked the same way as in Create a Vision Event. If any event fails the required field check, no event is stored and the error names the event's index. An empty events array stores nothing and returns created 0. The workspace comes from the API key. Requires the vision-events:write or device:update scope.
Roboflow API key or OAuth access token.
Created.
Number of events stored.
Present when the request used a deprecated field name (solution or solutionId) instead of useCaseId.
events is missing or has more than 100 items, or one event fails the required field check.
Authentication is missing or invalid.
The API key lacks the vision-events:write or device:update scope or cannot access the workspace.
The resource does not exist or is not accessible.
The request rate is too high.
POST /vision-events/batch HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 346
{
"events": [
{
"eventId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"eventType": "quality_check",
"useCaseId": "a1b3c8e1",
"timestamp": "2026-01-15T10:30:00Z",
"eventData": {
"result": "pass"
}
},
{
"eventId": "9c4d6a2e-81f3-4b7a-bc9e-3f1a2d4e5c6b",
"eventType": "quality_check",
"useCaseId": "a1b3c8e1",
"timestamp": "2026-01-15T10:31:00Z",
"eventData": {
"result": "fail"
}
}
]
}{
"created": 2,
"eventIds": [
"f47ac10b-58cc-4372-a567-0e02b2c3d479",
"9c4d6a2e-81f3-4b7a-bc9e-3f1a2d4e5c6b"
]
}Uploads one image to the workspace, not to a project, for use in Vision Events. Put the returned sourceId in images[].sourceId or images[].inputSourceId when you create an event. The workspace comes from the API key. Requires the vision-events:write or device:update scope.
Roboflow API key or OAuth access token.
Custom name for the image. The name form field wins when you send both.
The image file. Supported formats are JPEG, PNG, WebP, GIF, TIFF, BMP, HEIC, and AVIF. Any form field name works for the file.
Custom name for the image.
JSON object of metadata to store with the image. Same limits as event customMetadata. Keys that start with rf_internal are reserved and rejected.
Created.
Put it in images[].sourceId or images[].inputSourceId when you create an event.
Public URL of the uploaded image.
The body is not multipart/form-data, it has no file, or metadata is not valid JSON or breaks its limits.
Authentication is missing or invalid.
The API key lacks the vision-events:write or device:update scope or cannot access the workspace.
The resource does not exist or is not accessible.
The request rate is too high.
POST /vision-events/upload HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: multipart/form-data
Accept: */*
Content-Length: 92
{
"name": "inspection-photo.jpg",
"metadata": "{\"camera\": \"cam-1\", \"shift\": \"morning\"}"
}{
"success": true,
"sourceId": "Pq7sV2kWx9LmN4rT6yZb",
"url": "https://storage.googleapis.com/roboflow-platform-sources/Xk2mP9qLr4TzW8vN1bYc/Pq7sV2kWx9LmN4rT6yZb/original.jpg"
}Creates a pending video in the workspace and returns a signed URL. Send the file with a PUT request to signedUrl, with every header in requiredHeaders, within 60 minutes. Videos can be up to 3 GB. Put the returned videoId in videos[].sourceId when you create an event; you do not need to wait for processing first. The workspace comes from the API key. Requires the vision-events:write or device:update scope.
Roboflow API key or OAuth access token.
File name of the video.
MIME type of the video file.
Created.
Put it in videos[].sourceId when you create the event.
URL to PUT the video file to. It expires after 60 minutes.
name is missing, contentType is not video/mp4 or video/quicktime, or the body has another field.
Authentication is missing or invalid.
The API key lacks the vision-events:write or device:update scope or cannot access the workspace.
The resource does not exist or is not accessible.
The request rate is too high.
POST /vision-events/videos/prepare-upload HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 52
{
"name": "line-3-clip.mp4",
"contentType": "video/mp4"
}{
"success": true,
"videoId": "Kq4vX8mNp2RtY6wZ1bCd",
"signedUrl": "https://storage.googleapis.com/roboflow-platform-video-uploads/staging/Kq4vX8mNp2RtY6wZ1bCd?X-Goog-Signature=...",
"requiredHeaders": {
"x-goog-content-length-range": "1,3221225472",
"x-goog-if-generation-match": "0"
}
}Returns the processing status and details of a video prepared for Vision Events, without a playback URL. Use it to tell a video that is still processing from one that failed. Requires the vision-events:read or device:read scope.
Roboflow API key or OAuth access token.
Video ID returned when you prepared the upload.
Successful response.
pending from the moment the upload is prepared until Roboflow finishes processing the file, then uploaded or failed. A video whose file is never sent stays pending.
Public URL of a still frame from the video. It returns 404 until status is uploaded.
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
The video does not exist, belongs to another workspace, or was not prepared for Vision Events.
The request rate is too high.
GET /vision-events/videos/{videoId} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"videoId": "Kq4vX8mNp2RtY6wZ1bCd",
"status": "uploaded",
"posterUrl": "https://storage.googleapis.com/roboflow-platform-sources/Xk2mP9qLr4TzW8vN1bYc/Kq4vX8mNp2RtY6wZ1bCd/thumb.jpg",
"durationSeconds": 12.4,
"contentType": "video/mp4",
"sizeBytes": 18350080,
"filename": "line-3-clip.mp4"
}Returns the video's status and details plus a signed URL that plays or downloads it. The URL works for 60 minutes, and anyone holding it can play the clip; the response is sent with Cache-Control private, no-store. Requires the vision-events:read or device:read scope.
Roboflow API key or OAuth access token.
Video ID returned when you prepared the upload.
Successful response.
pending from the moment the upload is prepared until Roboflow finishes processing the file, then uploaded or failed. A video whose file is never sent stays pending.
Public URL of a still frame from the video. It returns 404 until status is uploaded.
Signed URL that plays the video. It expires after 60 minutes. null until status is uploaded.
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
The video does not exist, belongs to another workspace, or was not prepared for Vision Events.
The request rate is too high.
GET /vision-events/videos/{videoId}/url HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"videoId": "Kq4vX8mNp2RtY6wZ1bCd",
"status": "uploaded",
"posterUrl": "https://storage.googleapis.com/roboflow-platform-sources/Xk2mP9qLr4TzW8vN1bYc/Kq4vX8mNp2RtY6wZ1bCd/thumb.jpg",
"durationSeconds": 12.4,
"contentType": "video/mp4",
"sizeBytes": 18350080,
"filename": "line-3-clip.mp4",
"url": null
}Returns the events of one use case that match the filters, newest first, from the workspace's retention window. Page with cursor. To run a saved filter, send savedFilterId with only useCaseId, limit, and cursor. The workspace comes from the API key. Requires the vision-events:read or device:read scope. imageMetadataFilters and savedFilterId need vision-events:read, and savedFilterId does not work with device API keys.
Roboflow API key or OAuth access token.
Use case to query. solution and solutionId are deprecated aliases.
One event type. For several, use eventTypes.
true for events with ingestion warnings, false for events without.
100nextCursor from the previous page.
Start the first page at this event. Ignored with cursor. The response sets anchorFound.
Run this saved filter of the use case instead of sending filters. Send only useCaseId, limit, and cursor with it. Relative dates resolve on the first page and stay fixed for later pages.
Successful response.
true when more events match.
Send as cursor to get the next page. null when hasMore is false.
Returned when you sent anchorEventId. false when that event is not in the retention window.
The workspace's retention window in days.
Present when the request used a deprecated field name (solution or solutionId) instead of useCaseId.
A filter is invalid or an unknown field was sent, useCaseId is missing, or savedFilterId was sent with other filters.
Authentication is missing or invalid.
The API key lacks the scope a filter needs, or a device API key sent savedFilterId.
The savedFilterId does not exist in this use case, or the use case does not exist or is archived.
The saved filter can no longer be read. Save it again from the Search tab.
The request rate is too high.
POST /vision-events/query HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 227
{
"useCaseId": "a1b3c8e1",
"startTime": "2026-01-14T00:00:00Z",
"endTime": "2026-01-15T23:59:59Z",
"eventTypes": [
"quality_check"
],
"customMetadataFilters": [
{
"field": "temperature",
"operator": "gt",
"value": 70,
"type": "number"
}
],
"limit": 50
}{
"events": [
{
"eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"eventType": "quality_check",
"timestamp": "2026-01-15T10:30:00.000Z",
"deviceId": "camera-node-5",
"images": [
{
"sourceId": "Pq7sV2kWx9LmN4rT6yZb",
"objectDetections": [
{
"class": "defect",
"x": 100,
"y": 200,
"width": 50,
"height": 30,
"confidence": 0.95
}
]
}
],
"videos": [
{
"sourceId": "Kq4vX8mNp2RtY6wZ1bCd",
"label": "line-3 camera"
}
],
"eventData": {
"result": "fail",
"externalId": "batch-001"
},
"customMetadata": {
"line": "A1",
"temperature": 72.5
}
}
],
"hasMore": true,
"nextCursor": "eyJ0aW1lc3RhbXAiOiIyMDI2LTAxLTE1IiwiZXZlbnRJZCI6ImExYjJjM2Q0In0",
"lookbackDays": 14
}Deletes Vision Events from one Use Case by event ID. Deleted events no longer appear in query results or the dashboard. IDs that match no live event in the Use Case are listed in notFound; the rest of the request still succeeds. The workspace comes from the API key. Requires the vision-events:manage scope. Keys with only vision-events:write or device:update, such as edge device keys, cannot delete events.
Roboflow API key or OAuth access token.
ID of the Use Case the events belong to.
IDs of the events to delete. Duplicates count once.
Successful response.
Number of events deleted.
Requested event IDs that matched no live event in the Use Case.
Present when the request used a deprecated field name (solution or solutionId) instead of useCaseId.
useCaseId is missing, eventIds is empty or holds an empty or non-string value, more than 1,000 event IDs were sent, or useCaseId and a deprecated alias disagree.
Authentication is missing or invalid.
The API key lacks the vision-events:manage scope or cannot access the workspace.
The resource does not exist or is not accessible.
The request rate is too high.
POST /vision-events/delete HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 123
{
"useCaseId": "assembly-line-qa",
"eventIds": [
"a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"f47ac10b-58cc-4372-a567-0e02b2c3d479"
]
}{
"deleted": 1,
"notFound": [
"f47ac10b-58cc-4372-a567-0e02b2c3d479"
]
}Returns the custom metadata keys that events in a use case used within the workspace's retention window, with the value types seen for each key. Use them in customMetadataFilters when you query events. Requires the vision-events:read or device:read scope.
Roboflow API key or OAuth access token.
Use case ID.
Successful response.
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The request rate is too high.
GET /vision-events/custom-metadata-schema/{useCaseId} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"useCaseId": "a1b3c8e1",
"fields": {
"production_line": {
"types": [
"string"
]
},
"temperature": {
"types": [
"number"
]
},
"is_overtime": {
"types": [
"boolean"
]
}
}
}Lists the workspace's use cases with one status, whether or not they have events. Requires the vision-events:read or device:read scope.
Roboflow API key or OAuth access token.
Use case status to list. Use inactive to list archived use cases.
activePossible values: Successful response.
The workspace's retention window in days.
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The request rate is too high.
GET /vision-events/use-cases HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"useCases": [
{
"id": "a1b3c8e1",
"name": "Manufacturing Line 1",
"status": "active",
"workspaceId": "Xk2mP9qLr4TzW8vN1bYc",
"automationsCount": 1,
"defaultValueBaseUnits": 5000,
"defaultValueCurrency": "USD",
"createdAt": "2026-01-10T08:00:00.000Z",
"updatedAt": "2026-01-15T10:30:00.000Z"
}
],
"lookbackDays": 14
}Creates an active use case in the workspace. Use the returned id as useCaseId when you create events. Requires the vision-events:manage scope.
Roboflow API key or OAuth access token.
Unique within the workspace. Leading and trailing spaces are trimmed.
Value given to new events that don't send valueBaseUnits, in the smallest unit of the currency (ex: cents for USD).
Three-letter currency code for event values (ex: USD, EUR, JPY), in any case. Defaults to USD. An unsupported code returns 400.
Created.
Use it as useCaseId when you create events.
name is missing or too long, a default value field is invalid, or another use case already has this name.
Authentication is missing or invalid.
The API key lacks the vision-events:manage scope or cannot access the workspace.
The resource does not exist or is not accessible.
The request rate is too high.
POST /vision-events/use-cases HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 89
{
"name": "Manufacturing Line 1",
"defaultValueBaseUnits": 5000,
"defaultValueCurrency": "USD"
}{
"id": "a1b3c8e1",
"name": "Manufacturing Line 1"
}Renames a use case, sets its status, or sets its default event value. A new default applies only to events created afterward. Requires the vision-events:manage scope.
Roboflow API key or OAuth access token.
Use case ID.
Send at least one field.
New name. Unique within the workspace.
Value given to new events that don't send valueBaseUnits. null removes the default.
Three-letter currency code (ex: USD, EUR, JPY), in any case. Send defaultValueBaseUnits too when you change the currency of a use case that has a default value.
Successful response.
The default event value after the update. null when unset.
The currency after the update. USD when unset.
No field was sent, a field is invalid, another use case already has this name, or the currency changed without defaultValueBaseUnits on a use case that has a default value.
Authentication is missing or invalid.
The API key lacks the vision-events:manage scope or cannot access the workspace.
The use case does not exist in the workspace.
The request rate is too high.
PUT /vision-events/use-cases/{useCaseId} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 31
{
"name": "Manufacturing Line 2"
}{
"id": "a1b3c8e1",
"name": "Manufacturing Line 2",
"defaultValueBaseUnits": 5000,
"defaultValueCurrency": "USD"
}Archives a use case by setting its status to inactive. Its events are kept. It leaves the default use case list, and events sent to it afterward are still stored, but each returns an entity_not_found warning. Archiving an archived use case succeeds. Requires the vision-events:manage scope.
Roboflow API key or OAuth access token.
Use case ID.
Successful response.
The request is invalid.
Authentication is missing or invalid.
The API key lacks the vision-events:manage scope or cannot access the workspace.
The use case does not exist in the workspace.
The request rate is too high.
POST /vision-events/use-cases/{useCaseId}/archive HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"success": true
}Restores an archived use case by setting its status back to active. Requires the vision-events:manage scope.
Roboflow API key or OAuth access token.
Use case ID.
Successful response.
The use case is not archived.
Authentication is missing or invalid.
The API key lacks the vision-events:manage scope or cannot access the workspace.
The use case does not exist in the workspace.
The request rate is too high.
POST /vision-events/use-cases/{useCaseId}/unarchive HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"success": true
}배포 관리자
Returns every device in the workspace that your API key can see. Devices in folders outside a folder-scoped key's access are left out. Requires device:read. A device-scoped API key gets 403.
Roboflow API key or OAuth access token.
Workspace URL slug.
Only return devices in this folder. Pass a folder ID, or global for devices at the workspace root. Subfolders are not included.
globalSuccessful response.
folder is not a string.
Authentication is missing or invalid.
A device-scoped API key called a workspace-wide route, or a device other than its own.
The folder does not exist or your API key cannot see it.
The request rate is too high.
GET /{workspace}/devices/v2 HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": [
{
"id": "8Fq2LmX0pQ7rT1vW",
"name": "Line 3 Camera",
"status": "online",
"last_heartbeat": "2026-10-28T12:00:00.000Z",
"server_url": "http://192.168.1.20:9001",
"platform": "Linux",
"platform_release": "5.15.148-tegra",
"platform_version": "#1 SMP PREEMPT Mon Jun 16 08:24:48 PDT 2025",
"architecture": "aarch64",
"hostname": "jetson-line-3",
"ip_address": "192.168.1.20",
"rfdm_version": "1.4.2",
"rfdm_update": null,
"config_delivery": {
"verified": false
},
"type": "jetson",
"hardware": {
"processor": "aarch64",
"gpu": null,
"total_memory_mb": 7620,
"total_disk_space_mb": 118662
},
"network_interfaces": [],
"discovered_cameras": [],
"tags": [
"production",
"line-3"
],
"created_at": "2026-01-15T08:30:00.000Z"
}
]
}Creates a device and an API key bound to it, and returns an install ID for setting it up. The device starts from the workspace default config, merged with the config of the folder it goes in. Requires device:update. A device-scoped API key gets 403.
Roboflow API key or OAuth access token.
Workspace URL slug.
Device name. Must not be empty.
Device type (ex: edge, ai1). ai1 sets up an AI1 camera stream and inference image. secure-gateway needs the Secure Gateway feature on the workspace and runtime docker.
Set to roboflow-os for a Roboflow OS device. Only valid when device_type is edge.
Container runtime the installer sets up. Required for device_type secure-gateway.
Workflow URL slug to assign to the device. For an AI1 device it becomes the Workflow of the camera stream.
Tags for the device. Each tag is trimmed and must not be empty. Duplicates are removed.
ID of the folder to put the device in. Leave it out to create the device at the workspace root.
Provision the device for offline use. Only valid for AI1 and Roboflow OS devices, on workspaces with Roboflow Lite mode.
ID of a device in the same workspace to copy the configuration from. Its streams, install history, and queued changes are not copied.
Created.
ID of the new device.
Install ID. Use it to install Deployment Manager on the device. It expires after 10 minutes.
Data for the offline provisioning QR code. Only returned for devices created in offline mode.
A field is not valid (ex: an empty device_name, os without device_type edge, offline_mode on a device that is not AI1 or Roboflow OS).
Authentication is missing or invalid.
A device-scoped API key was used, offline_mode is set but Roboflow Lite mode is off, Secure Gateway is not on for the workspace, or sourceDeviceId is in another workspace.
sourceDeviceId, workflow_id, or projectGroupId does not exist or your API key cannot see it.
The request rate is too high.
POST /{workspace}/devices/v2 HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 70
{
"device_name": "Line 3 Camera",
"device_type": "edge",
"tags": [
"line-3"
]
}{
"deviceId": "8Fq2LmX0pQ7rT1vW",
"installId": "MFRGGZDFMZTWQ2LK"
}Returns the workspace default device config: the base default config with the workspace patch merged in, plus the patch itself. New devices start from it. Stream credentials are removed. Requires device:read. A device-scoped API key gets 403.
Roboflow API key or OAuth access token.
Workspace URL slug.
Successful response.
The request is invalid.
Authentication is missing or invalid.
A device-scoped API key called a workspace-wide route, or a device other than its own.
The resource does not exist or is not accessible.
The request rate is too high.
GET /{workspace}/devices/v2/default-config HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"config": {
"version": "1.0.0",
"config": {
"inference": {
"confidence": 0.7
},
"log_shipping_level": "INFO"
},
"services": {}
},
"patch": {
"config": {
"inference": {
"confidence": 0.7
}
}
}
}Returns one device, with its network interfaces from the latest telemetry. Requires device:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
Deployment Manager device ID.
Successful response.
A Deployment Manager device: its stored record joined with the latest heartbeat. A device that has not sent a heartbeat yet has status unknown and most fields null.
Device ID.
Device name.
online when the last heartbeat is less than 5 minutes old, offline when it is older, and unknown when the device never sent one.
Time of the last heartbeat.
Server URL the device reports in its telemetry.
Operating system (ex: Linux).
Kernel release.
Kernel version string.
CPU architecture (ex: aarch64, x86_64).
Device hostname.
IP address the device reports.
Version of Roboflow Deployment Manager (RFDM) running on the device.
Device type the device reports.
Tags on the device.
When the device was created.
The request is invalid.
Authentication is missing or invalid.
A device-scoped API key called a workspace-wide route, or a device other than its own.
The device does not exist, belongs to another workspace, or is in a folder your API key cannot see.
The request rate is too high.
GET /{workspace}/devices/v2/{deviceId} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "8Fq2LmX0pQ7rT1vW",
"name": "Line 3 Camera",
"status": "online",
"last_heartbeat": "2026-10-28T12:00:00.000Z",
"server_url": "http://192.168.1.20:9001",
"platform": "Linux",
"platform_release": "5.15.148-tegra",
"platform_version": "#1 SMP PREEMPT Mon Jun 16 08:24:48 PDT 2025",
"architecture": "aarch64",
"hostname": "jetson-line-3",
"ip_address": "192.168.1.20",
"rfdm_version": "1.4.2",
"rfdm_update": null,
"config_delivery": {
"verified": false
},
"type": "jetson",
"hardware": {
"processor": "aarch64",
"gpu": null,
"total_memory_mb": 7620,
"total_disk_space_mb": 118662
},
"network_interfaces": [],
"discovered_cameras": [],
"tags": [
"production",
"line-3"
],
"created_at": "2026-01-15T08:30:00.000Z"
}Returns the device configuration. Stream credentials are removed and stream URLs lose their user info, but environment variables are returned as stored, so treat the response as sensitive. The response has an ETag header. Send it back in If-None-Match to get 304 when nothing changed. Requires device:read. Rate-limited to 30 requests per minute per device.
Roboflow API key or OAuth access token.
Workspace URL slug.
Deployment Manager device ID.
Seconds to wait for a change when If-None-Match matches the current config, up to 45. The response comes as soon as the config changes, or 304 when the time runs out.
0ETag from an earlier response.
Successful response.
The device configuration document. Top-level fields include device_id, device_name, workspace_id, version, config (the runtime config, including device_type and stream), services (container definitions with image, volumes, and environment_variables), environment_variables, and pendingUpdates (changes queued for a maintenance window). RFDM can write more fields, so read only the ones you need.
The config has not changed since the ETag you sent.
The request is invalid.
Authentication is missing or invalid.
A device-scoped API key called a workspace-wide route, or a device other than its own.
The device does not exist, belongs to another workspace, is in a folder your API key cannot see, or has no stored config.
Rate limit exceeded: 30 requests per minute per device. The response sets Retry-After.
GET /{workspace}/devices/v2/{deviceId}/config HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"device_id": "8Fq2LmX0pQ7rT1vW",
"device_name": "Line 3 Camera",
"workspace_id": "aBcD1234",
"version": "1.0.0",
"config": {
"device_type": "edge",
"stream": {
"entrance-cam": {
"video_reference": "rtsp://192.168.1.100:554/live",
"workflow_id": "count-people",
"stream_credentials_set": true
}
}
},
"services": {
"inference": {
"image": "roboflow/roboflow-inference-server-jetson-6.2.0",
"environment_variables": {}
}
}
}Returns the device's saved config revisions, newest first. Requires device:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
Deployment Manager device ID.
Revisions per page. Values outside 1 to 500 are clamped.
10next_cursor from the previous page: the save time of the last revision returned, as an ISO 8601 timestamp.
Successful response.
cursor is not a valid timestamp.
Authentication is missing or invalid.
A device-scoped API key called a workspace-wide route, or a device other than its own.
The device does not exist, belongs to another workspace, or is in a folder your API key cannot see.
The request rate is too high.
GET /{workspace}/devices/v2/{deviceId}/config/history HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": [
{
"revision_id": "rev_8d1f2a",
"created_at": "2026-10-20T14:30:00.000Z",
"created_by": "u7Qx2Lm9"
}
],
"pagination": {
"next_cursor": "2026-10-20T14:30:00.000Z",
"has_more": true,
"limit": 10
}
}Returns the device's streams, including streams in the device config that have not reported in yet, which come back as provisioning. Credentials are removed from sources. Requires device:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
Deployment Manager device ID.
Successful response.
The request is invalid.
Authentication is missing or invalid.
A device-scoped API key called a workspace-wide route, or a device other than its own.
The device does not exist, belongs to another workspace, or is in a folder your API key cannot see.
The request rate is too high.
GET /{workspace}/devices/v2/{deviceId}/streams HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": [
{
"id": "entrance-cam",
"name": "entrance-cam",
"status": "running",
"provisioning": false,
"mode": "continuous",
"pipeline_id": "entrance-cam",
"workflow_id": "count-people",
"source": "rtsp://192.168.1.100:554/live",
"configured_source": null,
"started_at": "2026-10-28T10:00:00.000Z",
"last_event_at": "2026-10-28T12:30:00.000Z",
"camera_fps": 29.97,
"inference_fps": 12.4,
"sharpness": 82,
"cloud_fallback": null,
"error": null,
"error_code": null,
"error_message": null,
"error_retryable": null
}
]
}Returns one stream. A stream that is only in the device config comes back as provisioning. Requires device:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
Deployment Manager device ID.
Stream ID, pipeline ID, or stream key in the device config.
Set to status_events to add the stream's 20 most recent events from the last 7 days.
Successful response.
Stream ID.
Stream name.
Stream status (ex: running, stopped). A stream in the device config that has not reported in yet is provisioning.
True when the stream is in the config but has not reported in yet.
triggered when the stream runs its Workflow only when triggered, continuous otherwise. Null when the stream has no config entry.
Inference pipeline ID.
Workflow the stream runs.
Live video source. URL user info is removed (ex: rtsp://admin:pass@192.168.1.100/live becomes rtsp://192.168.1.100/live), and keys such as password, token, and api_key are dropped from objects.
Source from the device config, cleaned the same way. Filled in only when there is no live source.
When the stream started.
When the stream last changed.
Camera frame rate from the device.
Inference frame rate from the device.
Focus score of the latest frame, from 0 (blurry) to 100 (sharp).
Free-text error from the device, with credentials masked. An error sent as an object is returned as a JSON string.
Code of the latest stream failure (ex: STREAM_SOURCE_UNAVAILABLE). Null when the stream is healthy.
Text that goes with error_code, with credentials masked.
True when the device retries the stream by itself.
include has a value other than status_events.
Authentication is missing or invalid.
A device-scoped API key called a workspace-wide route, or a device other than its own.
The device or stream does not exist, or the device is not visible to your API key.
The request rate is too high.
GET /{workspace}/devices/v2/{deviceId}/streams/{streamId} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "entrance-cam",
"name": "entrance-cam",
"status": "running",
"provisioning": false,
"mode": "continuous",
"pipeline_id": "entrance-cam",
"workflow_id": "count-people",
"source": "rtsp://192.168.1.100:554/live",
"configured_source": null,
"started_at": "2026-10-28T10:00:00.000Z",
"last_event_at": "2026-10-28T12:30:00.000Z",
"camera_fps": 29.97,
"inference_fps": 12.4,
"sharpness": 82,
"cloud_fallback": null,
"error": null,
"error_code": null,
"error_message": null,
"error_retryable": null
}Returns the newest device log lines that match the filters, oldest first on the page. Pass next_cursor as cursor to page back through older lines. Requires device:read. Rate-limited to 120 requests per minute per workspace, separate from log upload.
Roboflow API key or OAuth access token.
Workspace URL slug.
Deployment Manager device ID.
Lines per page. Values outside 1 to 1000 are clamped.
100Only lines at or after this time (ISO 8601).
2026-10-28T00:00:00ZOnly lines at or before this time (ISO 8601).
2026-10-28T00:00:00ZComma-separated service names.
inference,managerComma-separated severities.
WARN,ERRORnext_cursor from the previous page. Returns lines older than it.
2026-10-28T00:00:00ZSuccessful response.
start_time, end_time, or cursor is not a valid timestamp.
Authentication is missing or invalid.
A device-scoped API key called a workspace-wide route, or a device other than its own.
The device does not exist, belongs to another workspace, or is in a folder your API key cannot see.
Rate limit exceeded: 120 requests per minute per workspace. The body is plain text.
GET /{workspace}/devices/v2/{deviceId}/logs HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": [
{
"timestamp": "2026-10-28T12:01:00.000Z",
"service": "inference",
"severity": "INFO",
"message": "Model loaded"
}
],
"pagination": {
"next_cursor": "2026-10-28T12:01:00.000Z",
"has_more": true,
"limit": 100
}
}Returns device health over a time window: hardware metrics in fixed buckets, Docker and NTP health, container status per service, FPS per stream, the latest hardware report, and network interfaces. Requires device:read. Rate-limited to 60 requests per minute per device, with at most 10 in 10 seconds. This quota is shared with the device's own telemetry upload.
Roboflow API key or OAuth access token.
Workspace URL slug.
Deployment Manager device ID.
Time window. Each has a fixed bucket size: 1h uses 2 minutes, 24h uses 30 minutes, 7d uses 4 hours, and 14d uses 8 hours.
24hPossible values: Comma-separated sections: metrics, system_status, services, service_history, stream_fps, hardware, network_interfaces. Defaults to every section except service_history. service_history adds services. An unknown section returns 400.
metrics,stream_fpsSuccessful response.
Each section is present only when you ask for it with include.
Time window used.
Bucket size (ex: 30 MINUTE).
Bucket size, in seconds.
Present and true when the container query hit its cap of 2,000 rows, so older service history can be missing.
Present and true when the FPS query hit its cap of 5,000 rows, so some buckets are missing.
time_period or include has a value that is not valid. valid_values lists the allowed ones.
Authentication is missing or invalid.
A device-scoped API key called a workspace-wide route, or a device other than its own.
The device does not exist, belongs to another workspace, or is in a folder your API key cannot see.
Rate limit exceeded: 60 requests per minute or 10 in 10 seconds per device. The response sets Retry-After.
GET /{workspace}/devices/v2/{deviceId}/telemetry HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"time_period": "24h",
"bucket_interval": "30 MINUTE",
"fill_interval_seconds": 1800,
"buckets": [
{
"bucket_start": "2026-10-28T00:00:00.000Z",
"cpu_pct": 42.5,
"used_memory_mb": 3200,
"total_memory_mb": 7620,
"used_disk_space_mb": 15000,
"total_disk_space_mb": 118662,
"gpu_pct": 78.2,
"network_upload_bytes_per_sec": 5120,
"network_download_bytes_per_sec": 20480
}
],
"metadata": {
"data_points": 48,
"time_range": {
"start": "2026-10-27T12:30:00.000Z",
"end": "2026-10-28T12:00:00.000Z"
}
}
}Returns the device's events (ex: boots, stream starts and stops, errors), newest first. By default, repeats of the same event for the same entity collapse into one state change. Set dedupe=false to read every raw row (ex: periodic telemetry). Requires device:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
Deployment Manager device ID.
Events per page. Values outside 1 to 1000 are clamped.
100Only events from this kind of entity (ex: device, stream, container).
Only events from this entity.
Only events with this name.
Only events at or after this time (ISO 8601). Timestamps with no zone are read as UTC.
2026-10-28T00:00:00ZOnly events before this time (ISO 8601).
2026-10-28T00:00:00Znext_cursor or prev_cursor from a previous page.
backward pages to older events, forward to newer ones.
backwardPossible values: Set to false to read raw rows. Needs both entity_type and entity_id, returns event_end_timestamp as null, and is rate-limited to 30 requests per minute per device.
truePossible values: Successful response.
A parameter is not valid: dedupe is not true or false, dedupe=false without entity_type and entity_id, an unknown direction, a malformed cursor, or a timestamp that cannot be read.
Authentication is missing or invalid.
A device-scoped API key called a workspace-wide route, or a device other than its own.
The device does not exist, belongs to another workspace, or is in a folder your API key cannot see.
Rate limit exceeded: 30 raw reads (dedupe=false) per minute per device. The response sets Retry-After.
GET /{workspace}/devices/v2/{deviceId}/events HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": [
{
"id": "0f8b1c2e-3d4a-4b5c-9d6e-7f8091a2b3c4",
"event": "stream_started",
"entity_type": "stream",
"entity_id": "entrance-cam",
"event_description": "Stream started",
"error_code": null,
"metadata": {
"workflow_id": "count-people"
},
"device_timestamp": "2026-10-28 10:00:00.000",
"server_timestamp": "2026-10-28 10:00:01.120",
"event_end_timestamp": null
}
],
"pagination": {
"next_cursor": "eyJ0aW1lc3RhbXAiOiIyMDI2LTEwLTI4IDEwOjAwOjAwLjAwMCIsImlkIjoiMGY4YjFjMmUifQ",
"prev_cursor": null,
"has_more": true,
"limit": 100
}
}Returns the services declared in the device config, joined to their live state: container state, image pull state, and a status that depends on the service kind (ex: PLC connection, Event Store capacity). Requires device:read. Rate-limited to 30 requests per minute per device, shared with the other service routes.
Roboflow API key or OAuth access token.
Workspace URL slug.
Deployment Manager device ID.
Comma-separated sections to add: status, config, signals, metrics. Defaults to status. config returns environment variable values as stored, which often hold credentials. An unknown section returns 400.
statusExample: status,metricsOnly return services of this kind (ex: plc_relay).
Window for the metrics section.
24hPossible values: Successful response.
Device ID.
Present and true when the metrics query hit its row cap. The newest rows are kept, so older containers report null metrics. Use a shorter time_period.
include or time_period has a value that is not valid. valid_values lists the allowed ones.
Authentication is missing or invalid.
A device-scoped API key called a workspace-wide route, or a device other than its own.
The device does not exist, belongs to another workspace, or is in a folder your API key cannot see.
Rate limit exceeded: 30 requests per minute per device. The response sets Retry-After.
GET /{workspace}/devices/v2/{deviceId}/services HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"device_id": "text",
"services": [
{
"name": "plc-relay",
"kind": "plc_relay",
"image": "repo.roboflow.com/roboflow-edge/plc-relay",
"tag": "1.2.0",
"tag_is_canonical": true,
"automatic_updates": true,
"signal_conflicts": [],
"has_pending_changes": false,
"state": "running",
"state_reported_at": "2026-10-28T11:58:00.000Z",
"state_received_at": "2026-10-28T11:58:01.000Z",
"error_code": null,
"image_state": "pull_succeeded",
"image_state_reported_at": "2026-10-20T09:00:00.000Z",
"image_state_received_at": "2026-10-20T09:00:02.000Z",
"status": {
"connected": true,
"driver": "ethernet_ip",
"plc_ip": "192.168.1.50",
"tags": {
"Line_Speed": 42.5,
"Machine_Running": true
},
"tag_count": 2,
"reported_at": "2026-10-28T11:59:00.000Z",
"connection_changed_at": "2026-10-27T08:00:00.000Z",
"stale": false
}
}
],
"unassociated_signals": {
"ANY_ADDITIONAL_PROPERTY": {
"event": "text",
"event_description": null,
"error_code": null,
"metadata": null,
"reported_at": null,
"received_at": null,
"ttl_s": null,
"expired": true
}
},
"metrics_truncated": true
}Returns one service, in the same shape as an entry in List Device Services. Requires device:read. Rate-limited to 30 requests per minute per device, shared with the other service routes.
Roboflow API key or OAuth access token.
Workspace URL slug.
Deployment Manager device ID.
Service name, as declared in the device config.
Comma-separated sections to add: status, config, signals, metrics. Defaults to status. config returns environment variable values as stored, which often hold credentials. An unknown section returns 400.
statusExample: status,metricsWindow for the metrics section.
24hPossible values: Successful response.
One service declared in the device config, joined to its live state. config, status, signals, and metrics are only present when you ask for them with include.
Service name in the device config.
Service kind, resolved from the image. An image Roboflow does not publish is custom.
Configured image.
Configured image tag.
True when the tag is the version Roboflow ships for this kind. Null when Roboflow does not pin a version for it.
Whether automatic updates are on for the service. Null when not set.
Entity IDs this service shares with another declared service. When it is not empty, status is null because the readings cannot be told apart. Give each service its own DEVICE_EVENT_ENTITY_ID to fix it.
True when a change to the service waits for a maintenance window.
Container state (ex: running). Null when the last report is past its TTL or the service never reported. Use state_received_at to tell them apart.
When the device says the state changed. Null when the device sent no timestamp.
When Roboflow received the state.
Error code sent with the current state.
Latest image pull state (ex: pull_succeeded). Null when it is past its TTL.
When the device says the image state changed.
When Roboflow received the image state.
status section: current state with fields that depend on the kind (ex: connected and tags for plc_relay, record and storage counts for event_store). Null for kinds with no telemetry, before the first report, and when signal_conflicts is not empty.
Get a Device Service only. Present and true when the metrics query hit its row cap, so older containers report null metrics.
include or time_period has a value that is not valid. valid_values lists the allowed ones.
Authentication is missing or invalid.
A device-scoped API key called a workspace-wide route, or a device other than its own.
The device does not exist or is not visible to your API key, or it declares no service with this name.
Rate limit exceeded: 30 requests per minute per device. The response sets Retry-After.
GET /{workspace}/devices/v2/{deviceId}/services/{serviceName} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"name": "plc-relay",
"kind": "plc_relay",
"image": "repo.roboflow.com/roboflow-edge/plc-relay",
"tag": "1.2.0",
"tag_is_canonical": true,
"automatic_updates": true,
"signal_conflicts": [],
"has_pending_changes": false,
"state": "running",
"state_reported_at": "2026-10-28T11:58:00.000Z",
"state_received_at": "2026-10-28T11:58:01.000Z",
"error_code": null,
"image_state": "pull_succeeded",
"image_state_reported_at": "2026-10-20T09:00:00.000Z",
"image_state_received_at": "2026-10-20T09:00:02.000Z",
"status": {
"connected": true,
"driver": "ethernet_ip",
"plc_ip": "192.168.1.50",
"tags": {
"Line_Speed": 42.5,
"Machine_Running": true
},
"tag_count": 2,
"reported_at": "2026-10-28T11:59:00.000Z",
"connection_changed_at": "2026-10-27T08:00:00.000Z",
"stale": false
}
}Returns one named metric of one service over time, for charting. Roboflow finds the entity ID and event names for the service kind, and returns every raw sample. time_period selects samples by when Roboflow received them, so a device with a wrong clock still returns current data. Requires device:read. Rate-limited to 30 requests per minute per device, shared with the other service routes.
Roboflow API key or OAuth access token.
Workspace URL slug.
Deployment Manager device ID.
Service name, as declared in the device config.
Metric name. event_store has records, records_percent, images, bytes_used, bytes_percent, backed_up_records, backed_up_bytes_percent, pending_records, pending_bytes, draft_records, oldest_draft_age_seconds, and disk_percent_used. plc_relay has connected. opcua_server has session_count and refused_total. Other kinds have none.
bytes_percentTime window to read.
24hPossible values: Successful response.
Service name.
Service kind.
Metric returned.
A boolean metric is returned as 1 or 0.
Time window used.
Metric names for this kind.
True when the window held more than 5,000 samples. The newest are kept, so covered_from can be later than the start of time_period.
Time of the first point, on the device clock.
Time of the last point, on the device clock.
metric is missing or not valid for the service kind (valid_values lists the names), time_period is not valid, or the metric has no signal on this device.
Authentication is missing or invalid.
A device-scoped API key called a workspace-wide route, or a device other than its own.
The device does not exist or is not visible to your API key, or it declares no service with this name.
Another service on the device sends this metric under the same entity ID, so the samples cannot be told apart. services lists them and remediation says how to fix it.
Rate limit exceeded: 30 requests per minute per device. The response sets Retry-After.
GET /{workspace}/devices/v2/{deviceId}/services/{serviceName}/series?metric=text HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"device_id": "8Fq2LmX0pQ7rT1vW",
"service": "event-store",
"kind": "event_store",
"metric": "bytes_percent",
"metric_type": "number",
"time_period": "24h",
"available_metrics": [
"records",
"records_percent",
"bytes_used",
"bytes_percent"
],
"truncated": false,
"covered_from": "2026-10-27T12:01:00.000Z",
"covered_to": "2026-10-28T12:00:00.000Z",
"points": [
{
"timestamp": "2026-10-28T12:00:00.000Z",
"value": 41.7
}
]
}클라우드 스트리밍
사용 클라우드 스트리밍 관리형 카메라 처리를 위해 사용합니다. 다음을 읽어 범위 및 자격 증명 요구 사항 작업을 시작하기 전에.
v1 제어 API는 소스 검색, 임시 세션 할당, 소스 미리보기, Workflow 작업, 출력 감시 권한 및 완료된 파일 결과를 포함합니다. 소스 관리, 재시작, 승격, 처리 추정 및 브라우저 캡처는 여전히 앱 작업입니다. results 엔드포인트는 실시간 JSON 폴링 API가 아닙니다. 이 참조에는 Cloud Streaming SDK 메서드가 정의되어 있지 않습니다.
Lists registered sources without stream credentials. Temporary sessions are excluded unless requested. The response contains sources only, not jobs or a webcam-availability flag. Requires video-inference-job:read. Use a workspace API key or OAuth access token for the workspace in the path. Device-bound keys are not accepted.
Roboflow API key or OAuth access token.
Workspace URL slug.
Include workspace temporary sessions.
falseSuccessful response.
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The request rate is too high.
A required upstream service is temporarily unavailable.
GET /{workspace}/video-sources/v1 HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"sources": [
{
"id": "SOURCE_ID",
"workspace": "WORKSPACE_ID",
"kind": "usb",
"name": "Warehouse camera",
"status": "connected",
"availableProcessorSizes": [
"gpu-s-v1",
"gpu-m-v1",
"gpu-l-v1"
],
"persistentWorkflowsAvailable": true
}
]
}Inspect a saved Workflow before selecting imageOutput and workflowParameters. This does not start processing. Requires video-inference-job:read. Use a workspace API key or OAuth access token for the workspace in the path. Device-bound keys are not accepted.
Roboflow API key or OAuth access token.
Workspace URL slug.
Saved Workflow URL slug in this workspace.
warehouse-monitorSuccessful response.
True when static analysis was used because interface discovery failed. In that case, isImage=false is not proof that the output is not an image.
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The request rate is too high.
A required upstream service is temporarily unavailable.
GET /{workspace}/video-sources/v1/workflow-interface?workflowUrl=text HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"outputs": [
{
"name": "label_visualization_output",
"kinds": [
"image"
],
"isImage": true
}
],
"degraded": false,
"parameters": []
}Allocates one WHIP publishing session. The publishing grant admits one publisher within two minutes. At most four unexpired publishing grants may be outstanding per workspace. Repeating the same request and Idempotency-Key returns the same live session, not a renewed grant. A stopped session cannot be revived by replay. Its jobs end when the publisher is lost or the session is stopped. This is source allocation, not a browser capture, recording or reconnect API. Requires video-inference-job:create. Use a workspace API key or OAuth access token for the workspace in the path. Device-bound and folder-scoped credentials are not accepted.
Roboflow API key or OAuth access token.
Workspace URL slug.
A unique key for one start attempt. Reuse the same key, request and credential after a lost response. Use a new key only for a new attempt.
run-warehouse-camera-001Pattern: ^[A-Za-z0-9._:-]+$Session display name.
Browser previewOptional enabled temporary-source cell allowed for this workspace. Omit for server placement.
^[a-z0-9-]{1,63}$Successful response.
Allocated temporary source ID.
^tmp-[a-f0-9]{40}$Deadline to admit the publisher. Unix time in milliseconds.
Credentialed single-publisher WHIP URL. Use unchanged and never log, persist or share it.
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The idempotency key conflicts, the prior session ended, temporary sessions are unavailable, placement failed, or the publishing-grant limit was reached.
The request rate is too high.
A required upstream service is temporarily unavailable.
POST /{workspace}/video-sources/v1/temporary HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Idempotency-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 26
{
"name": "Browser preview"
}{
"source": {
"id": "tmp-0000000000000000000000000000000000000000",
"kind": "temporary",
"name": "Browser preview",
"status": "awaiting_video",
"persistentWorkflowsAvailable": false
},
"sourceId": "tmp-0000000000000000000000000000000000000000",
"grantExpiresAt": 1800000120000,
"whipUrl": "https://relay.example.invalid/src-SESSION_ID/whip?key=PUBLISH_GRANT"
}Invalidates the session's publisher credential, requests publisher disconnection and cancels its jobs. Use this only for a temporary source. Requires video-inference-job:create. Use a workspace API key or OAuth access token for the workspace in the path. Device-bound and folder-scoped credentials are not accepted.
Roboflow API key or OAuth access token.
Workspace URL slug.
Cloud Streaming source ID from the source list.
^tmp-[a-f0-9]{40}$Successful response.
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The request rate is too high.
A required upstream service is temporarily unavailable.
POST /{workspace}/video-sources/v1/{sourceId}/stop-session HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"source": {
"id": "SOURCE_ID",
"workspace": "WORKSPACE_ID",
"kind": "usb",
"name": "Warehouse camera",
"status": "connected",
"availableProcessorSizes": [
"gpu-s-v1",
"gpu-m-v1",
"gpu-l-v1"
],
"persistentWorkflowsAvailable": true
},
"stopRequested": true
}Requests source demand and placement, not Workflow inference. For connector sources, renew the five-minute demand lease while viewing. Direct-source grants include expiresAt; reacquire before it expires. Returns raw-source playback credentials or an uploaded-file playback URL. These grants are sensitive and can include a long-lived connector source credential. Requires video-inference-job:create. Use a workspace API key or OAuth access token for the workspace in the path. Device-bound and folder-scoped credentials are not accepted.
Roboflow API key or OAuth access token.
Workspace URL slug.
Cloud Streaming source ID from the source list.
^[^/\\]+$Optional source placement cell. Omit for server selection.
Successful response.
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
Source placement is unavailable, conflicts with active/fixed placement, or the temporary session has ended.
The request rate is too high.
A required upstream service is temporarily unavailable.
POST /{workspace}/video-sources/v1/{sourceId}/preview HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 2
{}{
"kind": "live",
"cell": "CELL_ID",
"placementGeneration": 1,
"whepUrl": "https://relay.example.invalid/src-SOURCE_ID/whep?key=READ_GRANT"
}Starts metered processing. Send a new Idempotency-Key for one intentional run; retry uncertain responses with the same key, body and API key. Different keys can create separate billable jobs. A successful start can be queued or waiting, not yet running. Public requests choose a GPU profile; app automatic sizing and priced validation are not available as request fields. Requires a workspace API key with video-inference-job:create, workflow:read and model:infer. OAuth access tokens, device-bound keys and folder-scoped keys cannot start jobs. The same admitted API key supplies execution authority.
Roboflow API key or OAuth access token.
Workspace URL slug.
Cloud Streaming source ID from the source list.
^[^/\\]+$A unique key for one start attempt. Reuse the same key, request and credential after a lost response. Use a new key only for a new attempt.
run-warehouse-camera-001Pattern: ^[A-Za-z0-9._:-]+$Identical request replayed under the same key and credential; returns the original job.
New job created. Read its state before assuming processing has started.
Invalid or unknown field, conflicting Workflow fields, excessive specification/parameter size, invalid capture options, or incompatible source, lifetime, recovery or compute settings.
Authentication is missing or invalid.
Required scopes, eligible workspace credit standing or environment capability are missing, or an OAuth, folder-scoped or device-bound credential cannot start this job. Some access denials are hidden as 404.
The resource does not exist or is not accessible.
The idempotency key belongs to different parameters or credentials, the prior job is no longer available, or source/cell placement or capacity conflicts.
The request rate is too high.
A required upstream service is temporarily unavailable.
POST /{workspace}/video-sources/v1/{sourceId}/jobs HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Idempotency-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 179
{
"workflowUrl": "warehouse-monitor",
"imageOutput": "label_visualization_output",
"purpose": "deployment",
"recoveryPolicy": "always",
"tier": "gpu",
"processorSize": "gpu-s-v1",
"maxFps": 15
}{
"job": {
"id": "JOB_ID",
"sourceId": "SOURCE_ID",
"state": "running",
"purpose": "deployment",
"mode": "stream",
"tier": "gpu",
"processorSize": "gpu-s-v1",
"workflowUrl": "warehouse-monitor",
"imageOutput": "label_visualization_output",
"executionGeneration": 1,
"cancelRequested": false
}
}Lists workspace job records. This route does not expose source, processor or execution credentials. It does not accept source or state filters. Requires video-inference-job:read. Use a workspace API key or OAuth access token for the workspace in the path. Device-bound keys are not accepted.
Roboflow API key or OAuth access token.
Workspace URL slug.
Successful response.
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The request rate is too high.
A required upstream service is temporarily unavailable.
GET /{workspace}/video-jobs/v1 HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"jobs": [
{
"id": "JOB_ID",
"sourceId": "SOURCE_ID",
"state": "running",
"purpose": "deployment",
"mode": "stream",
"tier": "gpu",
"processorSize": "gpu-s-v1",
"workflowUrl": "warehouse-monitor",
"imageOutput": "label_visualization_output",
"executionGeneration": 1,
"cancelRequested": false
}
]
}Read the current job without changing its state. Follow executionGeneration and successorJobId when observing replacement executions. A persistent waiting or blocked job still represents enabled intent until explicitly cancelled. Requires video-inference-job:read. Use a workspace API key or OAuth access token for the workspace in the path. Device-bound keys are not accepted.
Roboflow API key or OAuth access token.
Workspace URL slug.
Job ID.
^[^/\\]+$Successful response.
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The request rate is too high.
A required upstream service is temporarily unavailable.
GET /{workspace}/video-jobs/v1/{jobId} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"job": {
"id": "JOB_ID",
"sourceId": "SOURCE_ID",
"state": "running",
"purpose": "deployment",
"mode": "stream",
"tier": "gpu",
"processorSize": "gpu-s-v1",
"workflowUrl": "warehouse-monitor",
"imageOutput": "label_visualization_output",
"executionGeneration": 1,
"cancelRequested": false
}
}Requests an explicit stop. Persistent intent is disabled; queued jobs can be cancelled immediately. Active processors learn of cancellation through status updates, so the response is not a guarantee that shutdown has already finished. Re-read the job and any replacement identified by successorJobId. Repeating cancellation does not start a new job. Requires video-inference-job:create. Use a workspace API key or OAuth access token for the workspace in the path. Device-bound and folder-scoped credentials are not accepted.
Roboflow API key or OAuth access token.
Workspace URL slug.
Job ID.
^[^/\\]+$Successful response.
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The request rate is too high.
A required upstream service is temporarily unavailable.
POST /{workspace}/video-jobs/v1/{jobId}/cancel HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"job": {
"id": "JOB_ID",
"sourceId": "SOURCE_ID",
"state": "running",
"purpose": "deployment",
"mode": "stream",
"tier": "gpu",
"processorSize": "gpu-s-v1",
"workflowUrl": "warehouse-monitor",
"imageOutput": "label_visualization_output",
"executionGeneration": 1,
"cancelRequested": false
}
}Extends an active temporary-source preview's owner lease to at least two minutes from now, including while queued. It never revives an expired or stopped job and cannot extend the one-hour preview maximum. Keep this lease renewed while the temporary preview is in use; a video watch is a separate lease. Requires video-inference-job:create. Use a workspace API key or OAuth access token for the workspace in the path. Device-bound and folder-scoped credentials are not accepted.
Roboflow API key or OAuth access token.
Workspace URL slug.
Job ID.
^[^/\\]+$Successful response.
True if renewed; false if the job is expired, stopping or terminal. Stop using an expired job rather than assuming it was revived.
This is not a preview job on a temporary source.
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The request rate is too high.
A required upstream service is temporarily unavailable.
POST /{workspace}/video-jobs/v1/{jobId}/hold-preview HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"held": true
}Requests publication for at least 60 seconds on a claimed or running job. Renew at least every 30 seconds while viewing; renewal never shortens the lease. One image output is selected for the whole job, so another viewer's output selection changes every viewer's stream. Request a fresh grant after a new execution; match executionGeneration when provided. This does not create durable frame history. Requires video-inference-job:create. Use a workspace API key or OAuth access token for the workspace in the path. Device-bound and folder-scoped credentials are not accepted.
Roboflow API key or OAuth access token.
Workspace URL slug.
Job ID.
^[^/\\]+$Name of a Workflow image output, without a selector prefix. Null or omission uses the job's default selection.
label_visualization_outputSuccessful response.
Generation associated with this grant, when present on the job. Match it to the current job and request a fresh grant after execution changes.
Credentialed WHEP URL for annotated output. Use unchanged; do not log, persist or share it.
Credentialed RTSPS URL for the same output, or null when the cell has no public RTSPS listener.
Opaque execution-scoped credential. It changes on a new claim. Do not log, persist or share it. Its presence does not establish a public processor polling contract.
The job is not claimed/running, cancellation is pending, the output is not accepted as image-producing, or the Workflow changed while selecting output. With degraded static analysis, a declared output may be accepted without proof that it is an image; a non-image output will not publish video.
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The request rate is too high.
A required upstream service is temporarily unavailable.
POST /{workspace}/video-jobs/v1/{jobId}/watch HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 39
{
"output": "label_visualization_output"
}{
"watch": {
"requestedUntil": 1800000060000,
"output": "label_visualization_output"
},
"executionGeneration": 1,
"whepUrl": "https://relay.example.invalid/out-JOB_ID-g1/whep?key=JOB_READ_GRANT",
"rtspsUrl": null,
"processorAccessToken": "EXECUTION_SCOPED_TOKEN"
}Returns signed URLs after a batch job's result files have been uploaded. This is not live JSON polling, a stream recording endpoint or durable live result history. A JSON-only job may omit video.mp4. URLs expire after one hour. Requires video-inference-job:read. Use a workspace API key or OAuth access token for the workspace in the path. Device-bound keys are not accepted.
Roboflow API key or OAuth access token.
Workspace URL slug.
Job ID.
^[^/\\]+$Successful response.
The request is invalid.
Authentication is missing or invalid.
The credential does not have access to this resource.
The job does not exist/is not accessible, or results have not been uploaded. A completed status alone does not guarantee the files are ready.
The request rate is too high.
A required upstream service is temporarily unavailable.
GET /{workspace}/video-jobs/v1/{jobId}/results HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"files": {
"video.mp4": "https://storage.example.invalid/video.mp4?signature=DOWNLOAD_GRANT",
"frames.jsonl": "https://storage.example.invalid/frames.jsonl?signature=DOWNLOAD_GRANT",
"meta.json": "https://storage.example.invalid/meta.json?signature=DOWNLOAD_GRANT"
}
}모델 평가
Lists the model evaluations in a workspace, newest first. Filter by one of project, version, or model per request. Requires model-eval:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug. An unknown slug returns an empty list.
chess-pieces-fmhpzDataset version number. Alias: versionId.
4Model ID, with or without the workspace prefix. Alias: modelId. An unknown ID returns an empty list.
my-workspace/chess-pieces-fmhpz-4-rfdetr-small-t1Return only evaluations with this status.
donePossible values: Page size. Values above 200 are lowered to 200.
50Successful response.
More than one of project, version, and model was sent (error: invalid_filter_combination), a filter was repeated (error: invalid_filter), or status is not allowed (error: invalid_status).
Authentication is missing or invalid.
The API key lacks model-eval:read.
The resource does not exist or is not accessible.
The request rate is too high.
GET /{workspace}/model-evals HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"evals": [
{
"evalId": "huUF720inUcymARwqAGK",
"project": "chess-pieces-fmhpz",
"versionId": "4",
"modelId": "my-workspace/chess-pieces-fmhpz-4-rfdetr-small-t1",
"status": "done",
"createdAt": "2026-04-27T20:04:10.904Z",
"medianLatencyMs": 11.9
}
]
}Compare models on one Dataset Version. The operation includes models that have no evaluation. It is read-only and does not start evaluations.
Roboflow API key or OAuth access token.
Workspace URL slug.
Project URL slug.
chess-piecesPositive Dataset Version number.
131Pattern: ^[1-9][0-9]*$Metric used to calculate the Pareto frontier. The response lists supported choices in availableMetrics.
mAP5095Possible values: Successful response.
Project URL slug.
Dataset Version number.
Metric used to calculate onFrontier. Null when the Project type has no supported default metric.
A required parameter is missing, malformed, or unsupported for this comparison.
Authentication is missing or invalid.
The Workspace does not have Model Evaluation access.
The Project or Version is missing or inaccessible. API-key scope failures can also return this status.
The request rate is too high.
GET /{workspace}/model-evals/compare?project=text&version=text HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"project": "chess",
"version": "131",
"frontierMetric": "mAP5095",
"availableMetrics": [
"mAP",
"mAP5095",
"mAP75",
"precision",
"recall",
"f1"
],
"models": [
{
"modelId": "acme/chess-fast",
"evaluationId": "eval-fast",
"metrics": {
"mAP": 0.84,
"mAP5095": 0.61,
"mAP75": 0.68,
"f1": 0.79,
"precision": 0.82,
"recall": 0.76
},
"medianLatencyMs": 3,
"onFrontier": true,
"exclusionReason": null
},
{
"modelId": "acme/chess-new",
"evaluationId": null,
"metrics": {},
"medianLatencyMs": null,
"onFrontier": false,
"exclusionReason": "evaluation_unavailable"
}
]
}Returns one evaluation. When status is done, the response adds summary with the headline test-split metrics. Poll this endpoint until status is done before you call the other evaluation endpoints. Requires model-eval:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
Model evaluation ID.
huUF720inUcymARwqAGKSuccessful response.
Model evaluation ID.
Project URL slug. null if the project was deleted.
Dataset version number.
Model ID ({workspace}/{model-slug}), the same ID the models and inference endpoints use. {project}/{version} for an evaluation that ran on a version instead of one model. null if the model can no longer be found.
pending while the model compiles for inference, running once the evaluation job starts, then done or failed.
The request is invalid.
Authentication is missing or invalid.
The API key lacks model-eval:read.
The evaluation does not exist or belongs to another workspace (error: model_eval_not_found).
The request rate is too high.
GET /{workspace}/model-evals/{evaluationId} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"evalId": "huUF720inUcymARwqAGK",
"project": "chess-pieces-fmhpz",
"versionId": "4",
"modelId": "my-workspace/chess-pieces-fmhpz-4-rfdetr-small-t1",
"status": "done",
"createdAt": "2026-04-27T20:04:10.904Z",
"summary": {
"mAP": 0.924,
"mIoU": null,
"precision": 0.85,
"recall": 0.85,
"medianLatencyMs": 11.9
}
}Returns the main accuracy metrics for each split. Check taskType before you read the splits: detection splits have mAP by object size and class, semantic segmentation splits have mIoU and pixel-level metrics by class. Requires model-eval:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
Model evaluation ID.
huUF720inUcymARwqAGKSuccessful response.
Model evaluation ID.
Project URL slug. null if the project was deleted.
Dataset version number.
Model ID ({workspace}/{model-slug}), the same ID the models and inference endpoints use. {project}/{version} for an evaluation that ran on a version instead of one model. null if the model can no longer be found.
Which shape each split has. object-detection-like splits carry mAP fields. semantic-segmentation and action-recognition splits carry mIoU and pixel (or timeline) metrics. anomaly-detection splits carry auroc, averagePrecision, precision, recall, f1, falsePositiveRate, and threshold.
A query parameter is invalid (error: invalid_split or invalid_confidence). The body lists the allowed values in allowed or available.
Authentication is missing or invalid.
The API key lacks model-eval:read.
The evaluation does not exist or belongs to another workspace (error: model_eval_not_found), or its saved data is missing (error: report_not_found).
The evaluation has not finished (error: model_eval_not_done). Poll Get a Model Evaluation until status is done.
The request rate is too high.
GET /{workspace}/model-evals/{evaluationId}/map-results HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"evalId": "huUF720inUcymARwqAGK",
"project": "chess-pieces-fmhpz",
"versionId": "4",
"modelId": "my-workspace/chess-pieces-fmhpz-4-rfdetr-small-t1",
"taskType": "object-detection-like",
"splits": {
"test": {
"map50": 0.924,
"map50_95": 0.756,
"map75": 0.924,
"byObjectSize": {
"small": {
"map50": 0.904,
"map50_95": 0.648,
"map75": 0.904
},
"medium": {
"map50": 0.991,
"map50_95": 0.857,
"map75": 0.991
},
"large": null
},
"perClass": {
"Car-rims": {
"map50": 0.924,
"map50_95": 0.756,
"map75": 0.924,
"byObjectSize": {
"small": {
"map50": 0.9,
"map50_95": 0.65,
"map75": 0.85
},
"medium": {
"map50": 0.99,
"map50_95": 0.85,
"map75": 0.99
},
"large": null
}
}
}
}
}
}Returns precision, recall, and F1 at each confidence threshold, with the F1-optimal threshold, for each split and class. Use it to pick a confidence threshold for deployment. Requires model-eval:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
Model evaluation ID.
huUF720inUcymARwqAGKSuccessful response.
Model evaluation ID.
Project URL slug. null if the project was deleted.
Dataset version number.
Model ID ({workspace}/{model-slug}), the same ID the models and inference endpoints use. {project}/{version} for an evaluation that ran on a version instead of one model. null if the model can no longer be found.
A query parameter is invalid (error: invalid_split or invalid_confidence). The body lists the allowed values in allowed or available.
Authentication is missing or invalid.
The API key lacks model-eval:read.
The evaluation does not exist or belongs to another workspace (error: model_eval_not_found), or its saved data is missing (error: report_not_found).
The evaluation has not finished (error: model_eval_not_done). Poll Get a Model Evaluation until status is done.
The request rate is too high.
GET /{workspace}/model-evals/{evaluationId}/confidence-sweep HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"evalId": "huUF720inUcymARwqAGK",
"project": "chess-pieces-fmhpz",
"versionId": "4",
"modelId": "my-workspace/chess-pieces-fmhpz-4-rfdetr-small-t1",
"splits": {
"test": {
"perThreshold": {
"0.20": {
"precision": 0.45,
"recall": 0.92,
"f1": 0.605
},
"0.37": {
"precision": 0.85,
"recall": 0.85,
"f1": 0.85
},
"0.50": {
"precision": 0.91,
"recall": 0.78,
"f1": 0.84
}
},
"optimalThreshold": 0.37,
"optimalMetrics": {
"precision": 0.85,
"recall": 0.85,
"f1": 0.85
},
"perClass": {
"Car-rims": {
"perThreshold": {
"0.37": {
"precision": 0.85,
"recall": 0.85,
"f1": 0.85
}
},
"optimalThreshold": 0.37,
"optimalMetrics": {
"precision": 0.85,
"recall": 0.85,
"f1": 0.85
}
}
}
}
}
}Returns metrics for each class on one split. Requires model-eval:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
Model evaluation ID.
huUF720inUcymARwqAGKSplit to report. all is not accepted, because per-class metrics use a per-split threshold.
testPossible values: Successful response.
Model evaluation ID.
Project URL slug. null if the project was deleted.
Dataset version number.
Model ID ({workspace}/{model-slug}), the same ID the models and inference endpoints use. {project}/{version} for an evaluation that ran on a version instead of one model. null if the model can no longer be found.
object-detection-like, semantic-segmentation, or action-recognition. Says which fields each class has.
IoU threshold used, when the evaluation reports one.
A query parameter is invalid (error: invalid_split or invalid_confidence). The body lists the allowed values in allowed or available.
Authentication is missing or invalid.
The API key lacks model-eval:read.
The evaluation does not exist or belongs to another workspace (error: model_eval_not_found), or its saved data is missing (error: report_not_found).
The evaluation has not finished (error: model_eval_not_done). Poll Get a Model Evaluation until status is done.
The request rate is too high.
GET /{workspace}/model-evals/{evaluationId}/performance-by-class HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"evalId": "huUF720inUcymARwqAGK",
"project": "chess-pieces-fmhpz",
"versionId": "4",
"modelId": "my-workspace/chess-pieces-fmhpz-4-rfdetr-small-t1",
"taskType": "object-detection-like",
"split": "test",
"iouThreshold": null,
"classes": [
{
"className": "Car-rims",
"map50": 0.924,
"map50_95": 0.756,
"map75": 0.924,
"precision": 0.85,
"recall": 0.85,
"f1": 0.85,
"optimalThreshold": 0.37
},
{
"className": "music-note",
"map50": null,
"map50_95": null,
"map75": null,
"precision": 0,
"recall": 0,
"f1": 0,
"optimalThreshold": 0.5
}
]
}Returns the confusion matrix, built from the per-image results at one confidence threshold. Requires model-eval:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
Model evaluation ID.
huUF720inUcymARwqAGKSplit to count. all adds up every split.
allPossible values: Confidence threshold as an integer percentage from 0 to 100. Selects which saved report to read. Leave it out for the default report (usually 20). A threshold the evaluation did not save returns 400 invalid_confidence with the saved thresholds in available.
37Successful response.
Model evaluation ID.
Project URL slug. null if the project was deleted.
Dataset version number.
Model ID ({workspace}/{model-slug}), the same ID the models and inference endpoints use. {project}/{version} for an evaluation that ran on a version instead of one model. null if the model can no longer be found.
Split the matrix covers. all adds up train, valid, and test.
Confidence threshold of the report, from 0 to 1.
Class names, in matrix order. The last entry is usually background.
A query parameter is invalid (error: invalid_split or invalid_confidence). The body lists the allowed values in allowed or available.
Authentication is missing or invalid.
The API key lacks model-eval:read.
The evaluation does not exist or belongs to another workspace (error: model_eval_not_found), or its saved data is missing (error: report_not_found).
The evaluation has not finished (error: model_eval_not_done). Poll Get a Model Evaluation until status is done.
The request rate is too high.
GET /{workspace}/model-evals/{evaluationId}/confusion-matrix HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"evalId": "huUF720inUcymARwqAGK",
"project": "chess-pieces-fmhpz",
"versionId": "4",
"modelId": "my-workspace/chess-pieces-fmhpz-4-rfdetr-small-t1",
"split": "test",
"confidenceThreshold": 0.2,
"classes": [
"Car-rims",
"music-note",
"background"
],
"matrix": [
[
20,
0,
0
],
[
0,
0,
0
],
[
80,
0,
0
]
]
}Returns the clusters of visually similar images and the model's average metrics on each, so you can find groups of images where the model struggles. Each image's cluster and coordinate come from Get Image Predictions. Requires model-eval:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
Model evaluation ID.
huUF720inUcymARwqAGKConfidence threshold as an integer percentage from 0 to 100. Selects which saved report to read. Leave it out for the default report (usually 20). A threshold the evaluation did not save returns 400 invalid_confidence with the saved thresholds in available.
37Successful response.
Model evaluation ID.
Project URL slug. null if the project was deleted.
Dataset version number.
Model ID ({workspace}/{model-slug}), the same ID the models and inference endpoints use. {project}/{version} for an evaluation that ran on a version instead of one model. null if the model can no longer be found.
Confidence threshold of the report, from 0 to 1.
A query parameter is invalid (error: invalid_split or invalid_confidence). The body lists the allowed values in allowed or available.
Authentication is missing or invalid.
The API key lacks model-eval:read.
The evaluation does not exist or belongs to another workspace (error: model_eval_not_found), or its saved data is missing (error: report_not_found).
The evaluation has not finished (error: model_eval_not_done). Poll Get a Model Evaluation until status is done.
The request rate is too high.
GET /{workspace}/model-evals/{evaluationId}/vector-analysis HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"evalId": "huUF720inUcymARwqAGK",
"project": "chess-pieces-fmhpz",
"versionId": "4",
"modelId": "my-workspace/chess-pieces-fmhpz-4-rfdetr-small-t1",
"confidenceThreshold": 0.2,
"clustering": {
"method": "hdbscan",
"nClusters": 54,
"metrics": {
"noiseRatio": 0.078,
"silhouetteScore": 0.489
},
"parameters": {
"min_cluster_size": 2,
"min_samples": 1,
"cluster_selection_method": "eom",
"metric": "euclidean"
},
"processingTimeSeconds": 8.36
},
"preprocessing": {
"method": "umap",
"originalDimensions": 768,
"targetDimensions": 10,
"nNeighbors": 30,
"minDistance": 0.05
},
"clusters": [
{
"id": -1,
"numImages": 15,
"splitDistribution": {
"train": 12,
"valid": 2,
"test": 1
},
"metrics": {
"f1Mean": 0.462,
"f1Std": 0.219,
"f1Min": 0.129,
"f1Max": 0.8,
"precisionMean": 0.33,
"recallMean": 0.952,
"perplexityMean": null,
"perplexityStd": null,
"perplexityMin": null,
"perplexityMax": null
},
"sampleImages": [
"img1.jpg",
"img2.jpg"
]
}
]
}Returns per-image results: true and false positive counts, precision, recall, F1, cluster, and confusion entries. Each page reads the whole saved report, so prefer a few large pages over many small ones. Requires model-eval:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
Model evaluation ID.
huUF720inUcymARwqAGKSplit to return.
allPossible values: Confidence threshold as an integer percentage from 0 to 100. Selects which saved report to read. Leave it out for the default report (usually 20). A threshold the evaluation did not save returns 400 invalid_confidence with the saved thresholds in available.
37Return only the records for this image name.
abc.jpgReturn only the record for this evaluated input. Use it when one image has several inputs (ex: tiles or crops).
Send true to add geometry to the record: the saved predictions, ground truth, class names, and a temporary image URL. Needs imageName or evalInputId, and the filters must match one record.
falsePage size. Values above 1000 are lowered to 1000.
200Records to skip before the page starts.
0Successful response.
Model evaluation ID.
Project URL slug. null if the project was deleted.
Dataset version number.
Model ID ({workspace}/{model-slug}), the same ID the models and inference endpoints use. {project}/{version} for an evaluation that ran on a version instead of one model. null if the model can no longer be found.
Confidence threshold of the report, from 0 to 1.
Records that match the filters, before paging.
A query parameter is invalid (error: invalid_split, invalid_confidence, or invalid_image_predictions_query, for ex: includeGeometry without imageName or evalInputId), or includeGeometry matched more than one record (error: eval_input_ambiguous). Narrow the match with evalInputId and split.
Authentication is missing or invalid.
The API key lacks model-eval:read.
The evaluation does not exist or belongs to another workspace (error: model_eval_not_found), or its saved data is missing (error: report_not_found).
The evaluation has not finished (error: model_eval_not_done). Poll Get a Model Evaluation until status is done.
The request rate is too high.
GET /{workspace}/model-evals/{evaluationId}/image-predictions HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"evalId": "huUF720inUcymARwqAGK",
"project": "chess-pieces-fmhpz",
"versionId": "4",
"modelId": "my-workspace/chess-pieces-fmhpz-4-rfdetr-small-t1",
"split": "test",
"confidenceThreshold": 0.2,
"totalImages": 192,
"offset": 0,
"limit": 50,
"images": [
{
"imageId": "1QKLCUsfAzFiCIb6YCJj",
"imageName": "abc.jpg",
"evalInputId": null,
"split": "test",
"augmentations": 2,
"cluster": {
"id": 4,
"embedding2D": [
7.49,
-5.14
]
},
"stats": {
"truePositives": 2,
"falsePositives": 7,
"falseNegatives": 0,
"precision": 0.222,
"recall": 1,
"f1": 0.364
},
"confusion": [
[
0,
0,
2
],
[
2,
0,
7
]
]
}
]
}Returns the model improvement recommendations for a finished evaluation. It does not generate them. When none exist yet, the response is 200 with generated set to false. Requires model-eval:read.
Roboflow API key or OAuth access token.
Workspace URL slug.
Model evaluation ID.
huUF720inUcymARwqAGKSuccessful response.
Model evaluation ID.
Project URL slug. null if the project was deleted.
Dataset version number.
Model ID ({workspace}/{model-slug}), the same ID the models and inference endpoints use. {project}/{version} for an evaluation that ran on a version instead of one model. null if the model can no longer be found.
False when the evaluation has no recommendations yet. The other fields are then left out.
When the recommendations were generated.
The request is invalid.
Authentication is missing or invalid.
The API key lacks model-eval:read.
The evaluation does not exist or belongs to another workspace (error: model_eval_not_found).
The evaluation has not finished (error: model_eval_not_done).
The request rate is too high.
GET /{workspace}/model-evals/{evaluationId}/recommendations HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"evalId": "huUF720inUcymARwqAGK",
"project": "chess-pieces-fmhpz",
"versionId": "4",
"modelId": "my-workspace/chess-pieces-fmhpz-4-rfdetr-small-t1",
"generated": true,
"generatedAt": "2026-04-27T20:05:37.512Z",
"recommendations": {
"summary": {
"confidenceThreshold": 37,
"split": "test",
"generatedAt": "2026-04-27T20:05:37.512Z",
"count": 2,
"f1": 0.85,
"precision": 0.85,
"recall": 0.85
},
"items": [
{
"id": "56bcd423-38ff-45f9-b3e0-662a71ce44e6",
"type": "missed_detection",
"analysis": {
"affected_class": "Car-rims",
"count": 3
}
},
{
"id": "150e49a8-3a61-479a-9e18-3eb751494a70",
"type": "class_imbalance",
"analysis": {
"affected_class": "Car-rims",
"current_count": 20,
"total_gt_instances": 20,
"median_count": 10
}
}
]
}
}결제
Returns credit usage grouped by API key prefix and billing feature, with each row attributed to the billing folder that owns the key, or to the workspace. Requires workspace-stats:read and a workspace with Billing Folders turned on. Limited to 10 requests per minute per API key and per IP address.
Roboflow API key or OAuth access token.
Workspace URL slug.
Start of the period, inclusive (ISO 8601). Defaults to 7 days ago.
2025-01-01T00:00:00.000ZEnd of the period, exclusive (ISO 8601). Defaults to now.
2025-02-01T00:00:00.000ZOnly usage billed to these API key prefixes: the first 5 characters of each key (ex: rf_ab for rf_abCdEfGhIjK). Exact match.
["rf_ab","rf_de"]Only these billing features (ex: train, serverless-inference-run).
["train","serverless-inference-run"]Successful response.
One row per API key prefix and feature, sorted by feature, then prefix.
First 5 characters of the API key the usage was billed to.
Billing feature (ex: train, serverless-inference-run).
Credits used.
Individual usage events.
First usage event in the period.
Last usage event in the period.
ID of the folder or workspace the usage is attributed to.
Name of that folder or workspace.
folder when the API key belongs to a billing folder, otherwise workspace.
Billing Folders is not turned on for the workspace, or a field is invalid (ex: a date that is not ISO 8601).
Authentication is missing or invalid.
The credential does not have access to this resource.
The resource does not exist or is not accessible.
The folder that owns the API key has its usage paused.
More than 10 requests in a minute from this API key or IP address. retryAfter gives the seconds to wait.
POST /{workspace}/billing-usage-report HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 158
{
"startAt": "2025-01-01T00:00:00.000Z",
"endAt": "2025-02-01T00:00:00.000Z",
"api_key_prefixes": [
"rf_ab",
"rf_de"
],
"features": [
"train",
"serverless-inference-run"
]
}[
{
"api_key_prefix": "rf_ab",
"feature": "train",
"total_credits_used": 150.5,
"usage_events": 12,
"earliest_usage": "2025-01-02T10:30:00.000Z",
"latest_usage": "2025-01-28T14:15:00.000Z",
"billing_entity_id": "folder-id-123",
"billing_entity_name": "My Project Folder",
"billing_entity_type": "folder"
}
]마지막 업데이트
도움이 되었나요?