For the complete documentation index, see llms.txt. This page is also available as Markdown.

Platform API OpenAPI

기계 판독 가능한 OpenAPI 사양이 포함된 Roboflow Platform API를 둘러보고 테스트하세요.

플랫폼 API를 다음에서 사용하세요 https://api.roboflow.com 워크스페이스, 프로젝트, 데이터셋, 학습, 워크플로 및 관련 리소스를 관리합니다.

Roboflow API 키로 다음에서 인증하세요 Authorization: Bearer 헤더 또는 api_key 쿼리 매개변수를 사용합니다. 참고 REST API로 인증하기.

이 문서는 이 사이트에 문서화된 공개 Platform API 작업에 대한 초기 참고 자료입니다. Platform API가 아직 완전한 기계 판독 가능 스키마를 게시하지 않았기 때문에 일부 요청 및 응답 객체는 계속 열려 있습니다.

모델 및 Workflow 실행 엔드포인트는 다음을 참조하세요 추론 서버 OpenAPI.

또한 원본 OpenAPI 문서를 다운로드할 수 있습니다.

워크스페이스 및 프로젝트

Verify credentials and get the authenticated workspace

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Responses
200

Successful response.

application/json
welcomestringRequired
instructionsstringRequired

Confirms the key works, or explains how to send one when the request has no key.

docsstring · uriRequired
workspacestringOptional

URL slug of the workspace the key belongs to. Present only when the request has a valid key.

workspaceIdstringOptional

ID of the workspace the key belongs to. Present only when the request has a valid key.

get/
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"
}

Get a workspace and its projects

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Responses
200

Successful response.

application/json
get/{workspace}
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": {}
      }
    ]
  }
}

Create a project

post

Creates an empty project. Requires project:create. The URL slug is made from name and gets a random suffix when the slug is taken.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Body
namestring · max: 256Required

Display name. Letters, numbers, dashes, underscores, and spaces only.

typestring · enumRequired

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.

Possible values:
annotationstring · max: 256Required

Annotation group: a noun for what you label (ex: sharks, defects). Projects in the same group share classes.

licensestring · enumOptional

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.

Possible values:
groupstringOptional

ID of the project folder to create the project in.

Responses
200

The new project.

application/json
idstringOptional

Workspace and project URL slugs joined by a slash.

typestringOptional

Project type (ex: object-detection, classification, instance-segmentation).

namestringOptional

Project display name.

creatednumberOptional

Creation time in seconds since the Unix epoch.

updatednumberOptional

Last update time in seconds since the Unix epoch.

imagesintegerOptional

Images in the project.

unannotatedintegerOptional

Images with no annotations.

annotationstringOptional

Annotation group name.

versionsintegerOptional

Dataset versions generated from the project.

publicbooleanOptional

True when the project is public on Roboflow Universe.

multilabelbooleanOptional

True for multi-label classification projects.

licensestringOptional

Dataset license (ex: Private, CC BY 4.0).

iconobject · nullableOptional

Thumbnail shown for the project, or null when it has none.

Other propertiesanyOptional
post/{workspace}/projects
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": {}
}

Fork a Universe project

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Body

Send url or source_project.

urlstringOptional

Universe project URL. Extra path segments and query parameters are fine. The project slug is read from the second path segment.

source_projectstringOptional

Universe project URL slug. Takes precedence over url.

Responses
202

Accepted for asynchronous processing.

application/json
taskIdstringOptional

Asynchronous task ID.

urlstring · uriOptional

URL to poll for the task status.

post/{workspace}/projects/fork
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"
}

Get a project and its versions

get

Returns a project and its dataset versions, including the model trained on each version. Requires project:read.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

Responses
200

Successful response.

application/json
get/{workspace}/{project}
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"
    }
  ]
}

Move a project to Trash

delete

Moves a project to Trash and cancels any training in progress on it. Requires project:update.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

Responses
200

Successful response.

application/json
deletedbooleanOptional

Always true.

typestring · enumOptionalPossible values:
workspacestringOptional

Workspace URL slug.

projectstringOptional

Project URL slug.

projectIdstringOptional

Project ID. Pass it as the restore id.

trashbooleanOptional

Always true: the project is in Trash, not permanently deleted.

delete/{workspace}/{project}
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
}

Get dataset health metrics

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

Query parameters
regeneratebooleanOptional

Set to true to recompute the report. Otherwise you get the last computed report, and it is computed only when none exists.

Responses
200

Successful response.

application/json
generatedintegerOptional

When the report was computed, in milliseconds since the Unix epoch.

versionintegerOptional

Report format version.

get/{workspace}/{project}/health
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
      }
    }
  }
}

List models for a project

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

Query parameters
groupstringOptional

Neural Architecture Search run ID. Returns only the models from that run, or an empty array when none match.

Example: pVYKOWUB6AUIVJMgPc7u-410-rfdetrNasGroup
Responses
200

Successful response.

application/json
urlstringOptional

Model ID to use for inference.

versionstringOptional

Dataset version the model was trained on. Not set for models that are not tied to a version.

taskTypestringOptional

Task the model performs (ex: object-detection).

modelTypestringOptional

Model architecture and size (ex: rfdetr-base).

namestringOptional

Model display name.

createdstring · date-timeOptional

Creation time.

nasFamilystring · nullableOptional

child for models found by Neural Architecture Search, null for the baseline. Neural Architecture Search models only.

groupstringOptional

Neural Architecture Search run ID, shared by every model from the run.

favoritedbooleanOptional

True when anyone in the workspace starred the model. Neural Architecture Search models only.

recommendedbooleanOptional

Present and true when the model is the recommended pick for at least one metric and hardware target.

get/{workspace}/{project}/models
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
    }
  }
]

Get a dataset version

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

versioninteger · min: 1Required

Dataset version number.

Responses
200

Successful response.

application/json
get/{workspace}/{project}/{version}
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"
    ]
  }
}

Move a dataset version to Trash

delete

Moves a dataset version to Trash. Any training in progress on the version is canceled. Requires version:update.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

versioninteger · min: 1Required

Dataset version number.

Responses
200

Successful response.

application/json
deletedbooleanOptional

Always true.

typestring · enumOptionalPossible values:
workspacestringOptional

Workspace URL slug.

projectstringOptional

Project URL slug.

projectIdstringOptional

Project ID. Pass it as the restore parentId.

versionstringOptional

Version number. Pass it as the restore id.

trashbooleanOptional

Always true: the version is in Trash, not permanently deleted.

delete/{workspace}/{project}/{version}
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 키

List workspace API keys

get

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).

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Query parameters
includeDisabledbooleanOptional

Set to true to include disabled keys.

Default: false
includeFoldersbooleanOptional

Set to true to add folder names (folders) to folder-scoped keys.

Default: false
Responses
200

Successful response.

application/json
publishableKeystringRequired

The workspace publishable key, rf_ followed by the workspace id.

get/{workspace}/api-keys
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"
}

Create a workspace API key

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Body

Every field is optional. An empty body creates a key with the caller's own scopes and folders. Unknown fields return 400.

namestring · max: 200Optional

Display name for the key.

scopesstring[] · nullableOptional

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.

Example: ["model:infer"]
folderIdsstring[]Optional

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.

protectedbooleanOptional

Creates the key protected. See Protecting a Key.

rotationDueAtstringOptional

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.

Example: 2027-10-22
ownersstring[] · max: 50Optional

Member 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.

Responses
201

Created.

application/json
keyIdstringRequired

The new key's non-secret handle.

keystringRequired

The secret key value. Returned only in this response. Store it now: no endpoint returns it again.

namestringRequired

Display name.

scopesstring[] · nullableRequired

Stored scopes, after role presets and sections expand. null for a full-access key.

folderIdsstring[]Required

Folders the key is limited to.

protectedbooleanRequired

True when the key is protected.

rotationDueAtstring · nullableRequired

Rotation due date, or null.

ownersstring[]Required

Member ids reminded before the due date.

publishableKeystringRequired

The workspace publishable key.

post/{workspace}/api-keys
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"
}

Get the workspace publishable API key

get

Returns the workspace publishable key. Requires workspace:read. A folder-scoped key gets 404: read publishableKey from the list or create response instead.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Responses
200

Successful response.

application/json
publishableKeystringRequired

rf_ followed by the workspace id. Not a secret: it can only run inference and download models.

get/{workspace}/api-keys/publishable
GET /{workspace}/api-keys/publishable HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
  "publishableKey": "rf_5f3Tq8k2ZbW1aXyZ"
}

List members who can own an API key

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Query parameters
keyIdstringOptional

The keyId of an existing key. Do not send with folderIds.

Example: 9f8c1a2b3d4e5f60
folderIdsstringOptional

Folder 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.

Example: folderA,folderB
Responses
200

Successful response.

application/json
get/{workspace}/api-keys/owner-candidates
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"
    }
  ]
}

Get an API key

get

Returns masked metadata for one key. Requires api-key:read.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

keyIdstringRequired

The key's keyId handle, from the list response. Never the secret key value.

Example: 9f8c1a2b3d4e5f60
Responses
200

Successful response.

application/json
get/{workspace}/api-keys/{keyId}
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"
    }
  }
}

Update an API key

patch

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

keyIdstringRequired

The key's keyId handle, from the list response. Never the secret key value.

Example: 9f8c1a2b3d4e5f60
Body

Send only the fields you want to change. Omitted fields stay as they are. An empty body or an unknown field returns 400.

namestring · max: 200Optional

New display name. Renaming needs no plan feature.

scopesstring[] · nullableOptional

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.

Example: ["model:infer","project:read"]
protectedbooleanOptional

Send true to protect the key. false returns 403: you can only unprotect a key in the dashboard.

disabledbooleanOptional

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.

rotationDueAtstring · nullableOptional

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.

ownersstring[] · max: 50Optional

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.

Responses
200

Successful response.

application/json
patch/{workspace}/api-keys/{keyId}
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"
    }
  }
}

Revoke an API key

delete

Revokes the key permanently. Anything that uses it fails to authenticate at once. Requires api-key:revoke.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

keyIdstringRequired

The key's keyId handle, from the list response. Never the secret key value.

Example: 9f8c1a2b3d4e5f60
Responses
200

Successful response.

application/json
statusstring · enumRequiredPossible values:
keyIdstringRequired

The keyId you sent.

delete/{workspace}/api-keys/{keyId}
DELETE /{workspace}/api-keys/{keyId} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
  "status": "revoked",
  "keyId": "9f8c1a2b3d4e5f60"
}

Roll an API key

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

keyIdstringRequired

The key's keyId handle, from the list response. Never the secret key value.

Example: 9f8c1a2b3d4e5f60
Body

Optional rotation schedule for the replacement. Send no body to carry the old key's schedule over. Both fields require Advanced API Keys.

rotationDueAtstring · nullableOptional

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.

ownersstring[] · max: 50Optional

The replacement's owners. Omitted, the old key's owners carry over. An empty list reminds everyone who can roll the key.

Responses
200

Successful response.

application/json
keyIdstringRequired

The replacement's new handle. Nothing links it to the old key afterwards, so store both ids if you need to trace the rotation.

keystringRequired

The replacement's secret value. Returned only in this response.

namestringRequired

Display name, kept from the old key.

scopesstring[] · nullableRequired

Scopes, kept from the old key. null for full access.

folderIdsstring[]Required

Folders, kept from the old key.

protectedbooleanRequired

Always false: a protected key cannot be rolled.

disabledbooleanRequired

True when the old key was disabled. A disabled key rolls to a disabled key.

rotationDueAtstring · nullableRequired

The replacement's rotation due date, or null.

ownersstring[]Required

The replacement's owners.

revokedKeyIdstringRequired

The keyId of the key that was revoked.

post/{workspace}/api-keys/{keyId}/roll
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"
}

프로젝트 폴더

List or get project folders

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Query parameters
groupIdstringOptional

Folder ID. Returns only that folder.

Example: Fh2kQ8vLx0aZ1bC3dE4f
Responses
200

Successful response.

application/json
get/{workspace}/groups
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"
    }
  ]
}

Create a project folder

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Body
namestringRequired

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.

parent_idstringOptional

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.

projectsstring[]Optional

Project URL slugs (ex: dog-breeds-mi53). Every project must belong to this workspace.

external_idstringOptional

Your ID for the folder in an external system.

Responses
201

Created.

application/json
idstringOptional

ID of the new folder.

post/{workspace}/groups
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"
}

Update a project folder

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

folderIdstringRequired

Project folder ID.

Query parameters
returnUpdatedbooleanOptional

Set to true to return the updated folder in data.

Body
namestringOptional

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.

external_idstringOptional

Your ID for the folder in an external system.

parent_idstring · nullableOptional

ID of the folder to move this one into, or null to move it to the top level of the workspace.

Responses
200

Successful response.

application/json
dataone ofOptional

true, or with returnUpdated=true a one-item array with the updated folder as stored, including auth_groups.

booleanOptional
or
post/{workspace}/groups/{folderId}
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
}

Delete a project folder

delete

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

folderIdstringRequired

Project folder ID.

Responses
202

The folder holds too much to delete in one step, so it is deleted in the background. Poll task with the async tasks endpoint.

application/json
taskstringOptional

Async task ID.

generationstring | integer · nullableOptional

Deletion attempt marker.

delete/{workspace}/groups/{folderId}
DELETE /{workspace}/groups/{folderId} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
  "task": "text",
  "generation": null
}

Add projects to a folder

patch

Moves one or more projects into the folder, out of wherever they were. Requires folder:update.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

folderIdstringRequired

Project folder ID.

Body
projectsstring[]Required

Project URL slugs (ex: dog-breeds-mi53). Every project must belong to this workspace.

Responses
204

Completed with no response body.

No content

patch/{workspace}/groups/{folderId}/projects
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

Remove projects from a folder

delete

Moves one or more projects out of the folder to the top level of the workspace, not to the parent folder. Requires folder:update.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

folderIdstringRequired

Project folder ID.

Body
projectsstring[]Required

Project URL slugs (ex: dog-breeds-mi53). Every project must belong to this workspace.

Responses
204

Completed with no response body.

No content

delete/{workspace}/groups/{folderId}/projects
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

데이터셋 버전 및 학습

Generate a dataset version

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

Body
versionNamestringOptional

Version name. Defaults to the creation date and time.

versionNotesstringOptional

Version notes.

Responses
200

Successful response.

application/json
versionstringOptional

Number of the new version. Use it as {version} in other calls.

messagestringOptional
post/{workspace}/{project}/generate
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"
}

Rebalance train, validation, and test splits

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

Body
modestring · enumOptional

rebalance moves as few images as possible. shuffle randomly reassigns every image.

Default: rebalancePossible values:
groupingstring · enumOptional

Used only with shuffle. global shuffles the whole project. batch shuffles each upload batch and annotation job on its own.

Default: globalPossible values:
classesstring[] · min: 1Optional

Move only images whose annotations use just these classes. Other images keep their split.

Responses
202

Accepted for asynchronous processing.

application/json
taskIdstringOptional

Asynchronous task ID.

urlstring · uriOptional

URL to poll for the task status.

post/{workspace}/{project}/splits/rebalance
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"
}

Export a dataset version

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

versioninteger · min: 1Required

Dataset version number.

formatstringRequired

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.

Example: yolov8
Responses
200

Successful response.

application/json
progressnumber · enumOptionalPossible values:
get/{workspace}/{project}/{version}/{format}
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
}

Start a training job

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

versioninteger · min: 1Required

Dataset version number.

Body
modelTypestringRequired

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.

Example: rfdetr-small
checkpointstringOptional

Checkpoint to start from: a model ID from this or another workspace you can access. Leave it out to start from the default public checkpoint.

epochsinteger · min: 1 · max: 300Optional

Number of epochs. Values above 300 are lowered to 300. Defaults depend on the model type.

speedstring · enumOptional

Training speed preset. accurate needs a plan that includes it. The model type takes precedence.

Default: fastPossible values:
trainingCreditCapnumberOptional

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.

nasMiningCreditCapnumberOptional

Most credits the Neural Architecture Search architecture search may spend. Neural Architecture Search model types only.

Responses
204

Completed with no response body.

No content

post/{workspace}/{project}/{version}/train
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

Cancel a queued training job

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

versioninteger · min: 1Required

Dataset version number.

Body
continueIfNoRefundbooleanOptional

Send true to cancel a job that has run for 30 minutes or more, which gives no refund.

Default: false
Responses
200

Successful response.

application/json
outcomestring · enumOptional

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.

Possible values:
successbooleanOptional

True when outcome is cancelled.

refundbooleanOptional

True when the training's credits were refunded.

jobDeletedbooleanOptional

True when the running job was shut down.

jobAlreadyGonebooleanOptional

True when the job had already ended.

statusstringOptional

Final training status. Present when outcome is superseded.

post/{workspace}/{project}/{version}/train/cancel
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
}

Stop an active training job

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

versioninteger · min: 1Required

Dataset version number.

Responses
200

Successful response.

application/json
successbooleanOptional

True when the stop request was recorded.

post/{workspace}/{project}/{version}/train/stop
POST /{workspace}/{project}/{version}/train/stop HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
  "success": true
}

Get training results

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

versioninteger · min: 1Required

Dataset version number.

Responses
200

Successful response.

application/json
trainingIdstring · nullableOptional

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.

versionIdstringOptional

Dataset version number.

statusstringOptional

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.

Example: finished
exceptionstringOptional

Failure reason, up to 500 characters. Present only when the training failed.

startinteger · nullableOptional

Start time in milliseconds since the Unix epoch.

endinteger · nullableOptional

End time in milliseconds since the Unix epoch.

jobTypestringOptional

Kind of training: fine-tune, nas (Neural Architecture Search), fine-tune-multi-stage, external-upload, or unknown.

modelTypestringOptional

Architecture the training ran. A Neural Architecture Search training reports rfdetr-nas-parent.

externalUploadbooleanOptional

True when the model weights were uploaded instead of trained on Roboflow.

modelGroupstring · nullableOptional

Neural Architecture Search run ID, shared by every model from the run. null for other trainings.

modelCountintegerOptional

Models the training produced.

get/{workspace}/{project}/{version}/training/results
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
      }
    }
  ]
}

List training runs

get

Lists the trainings on a dataset version, each with the IDs of the models it produced. Requires version:read.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

versioninteger · min: 1Required

Dataset version number.

Responses
200

Successful response.

application/json
get/{workspace}/{project}/{version}/v2/trainings
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"
      ]
    }
  ]
}

Create a training run

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

versioninteger · min: 1Required

Dataset version number.

Body
modelTypestringRequired

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.

Example: rfdetr-small
checkpointstringOptional

Checkpoint to start from: a model ID from this or another workspace you can access. Leave it out to start from the default public checkpoint.

epochsinteger · min: 1 · max: 300Optional

Number of epochs. Values above 300 are lowered to 300. Defaults depend on the model type.

speedstring · enumOptional

Training speed preset. accurate needs a plan that includes it. The model type takes precedence.

Default: fastPossible values:
trainingCreditCapnumberOptional

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.

nasMiningCreditCapnumberOptional

Most credits the Neural Architecture Search architecture search may spend. Neural Architecture Search model types only.

Responses
200

Successful response.

application/json
trainingIdstringOptional

ID of the new training. Pass it to the v2 get, cancel, and stop endpoints.

statusstringOptional

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.

Example: finished
jobIdstringOptional

ID of the training job.

post/{workspace}/{project}/{version}/v2/trainings
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"
}

Get a training run

get

Returns one training's status, models, and metrics. Requires version:read.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

versioninteger · min: 1Required

Dataset version number.

Query parameters
trainingIdstringOptional

Training to return. Leave it out when the version has only one training.

Example: 0a1b2c3d4e5f67890abc
includeEpochsbooleanOptional

Send true to add the metrics for each epoch. Not supported on legacy single-model versions.

Default: false
Responses
200

Successful response.

application/json
trainingIdstring · nullableOptional

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.

versionIdstringOptional

Dataset version number.

statusstringOptional

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.

Example: finished
exceptionstringOptional

Failure reason, up to 500 characters. Present only when the training failed.

startinteger · nullableOptional

Start time in milliseconds since the Unix epoch.

endinteger · nullableOptional

End time in milliseconds since the Unix epoch.

jobTypestringOptional

Kind of training: fine-tune, nas (Neural Architecture Search), fine-tune-multi-stage, external-upload, or unknown.

modelTypestringOptional

Architecture the training ran. A Neural Architecture Search training reports rfdetr-nas-parent.

externalUploadbooleanOptional

True when the model weights were uploaded instead of trained on Roboflow.

modelGroupstring · nullableOptional

Neural Architecture Search run ID, shared by every model from the run. null for other trainings.

modelCountintegerOptional

Models the training produced.

get/{workspace}/{project}/{version}/v2/trainings/get
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
      }
    }
  ]
}

Get the accepted training recipe

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

versioninteger · min: 1Required

Dataset version number.

Query parameters
modelTypestringRequired

Model type you plan to train. It must suit the project type.

Example: rfdetr-small
Responses
200

Successful response.

application/json
modelTypestringOptional

The modelType you sent.

canonicalModelTypestringOptional

The registry ID for that model type.

familystringOptional

Model family (ex: rf-detr).

taskTypestringOptional

Task the model performs (ex: object-detection).

usagestringOptional

Plain-text instructions for editing and submitting the template.

get/{workspace}/{project}/{version}/v2/trainings/recipe
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`."
}

Cancel a queued training run

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

versioninteger · min: 1Required

Dataset version number.

Body
trainingIdstringOptional

Training to cancel. Leave it out when the version has only one training.

continueIfNoRefundbooleanOptional

Send true to cancel a job that has run for 30 minutes or more, which gives no refund.

Default: false
Responses
200

Successful response.

application/json
outcomestring · enumOptional

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.

Possible values:
successbooleanOptional

True when outcome is cancelled.

refundbooleanOptional

True when the training's credits were refunded.

jobDeletedbooleanOptional

True when the running job was shut down.

jobAlreadyGonebooleanOptional

True when the job had already ended.

statusstringOptional

Final training status. Present when outcome is superseded.

post/{workspace}/{project}/{version}/v2/trainings/cancel
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
}

Stop an active training run

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

versioninteger · min: 1Required

Dataset version number.

Body
trainingIdstringOptional

Training to stop. Leave it out when the version has only one training.

Responses
200

Successful response.

application/json
successbooleanOptional

True when the stop request was recorded.

post/{workspace}/{project}/{version}/v2/trainings/stop
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
}

Move a training run to Trash

delete

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

versioninteger · min: 1Required

Dataset version number.

trainingIdstringRequired

Training ID from List Training Runs.

Example: 0a1b2c3d4e5f67890abc
Responses
200

Successful response.

application/json
deletedboolean · enumOptionalPossible values:
typestring · enumOptionalPossible values:
workspacestringOptional

Workspace URL slug.

projectstringOptional

Project URL slug.

projectIdstringOptional

Project ID.

versionstringOptional

Dataset version number.

trainingIdstringOptional
trashboolean · enumOptional

Always true: the training went to Trash.

Possible values:
versionAliasActionstring · enumOptional

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.

Possible values:
versionAliasTargetstringOptional

Model the {project}/{version} model ID now serves. Present only when versionAliasAction is repointed.

delete/{workspace}/{project}/{version}/v2/trainings/{trainingId}
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"
}

이미지 및 배치

Upload an image

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
projectstringRequired

Project URL slug.

Query parameters
imagestring · uriOptional

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.

Example: https://i.imgur.com/PEEvqPN.png
namestringOptional

File name of the image. Roboflow infers it when you leave it out.

Example: dock-cam-001.jpg
splitstring · enumOptional

Split the image goes to.

Default: trainPossible values:
batchstringOptional

Name of the batch to add the image to. Without it, the image goes to the "Uploaded via API" batch.

Example: Warehouse cams
notesstring · max: 2000Optional

Note for the batch. The batch keeps the first note it gets. Annotation jobs made from the batch use it as their default instructions.

Example: Label every forklift, even when it is partly hidden.
tagstringOptional

Tag to add to the image. Repeat it to add more tags.

Example: night
metadatastringOptional

Custom 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.

Example: {"camera_id":"cam001"}
sequence_numberintegerOptional

Position of the image in a sequence. Use it to keep images in order.

sequence_sizeintegerOptional

Total number of images in the sequence.

Default: 100000
inference_idstringOptional

Inference ID from a Roboflow prediction. It links the image to that prediction in Model Monitoring.

Body
or
stringOptional

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.

Responses
200

Successful response.

application/json
successbooleanOptional

True when Roboflow added a new image.

duplicatebooleanOptional

True when the project already has this exact image. No new image is added, and id is the existing image.

idstringOptional

Image ID. Use it to upload an annotation for the image.

post/dataset/{project}/upload
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"
}

Upload an annotation

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
projectstringRequired

Project URL slug.

imageIdstringRequired

Image ID returned by the upload, or a video ID in an Action Recognition project.

Query parameters
namestringRequired

File name of the annotation file, with its extension. Roboflow reads the annotation format from it.

Example: dock-cam-001.xml
addToDatasetbooleanOptional

Add 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.

Default: true
splitstring · enumOptional

Split 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.

Possible values:
overwritebooleanOptional

Replace an annotation the image already has. Without it the request fails with 409. Classification projects always replace.

Default: false
jobNamestringOptional

Move 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.

predictionbooleanOptional

Save the annotation as a model prediction instead of ground truth. A prediction never adds the image to the Dataset.

Default: false
predictionRoutingstring · enumOptional

Needs 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.

Default: unassignedPossible values:
Body
stringOptional

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.

Example: <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>
or
Responses
200

Successful response.

application/json
successbooleanOptional
warningsbooleanOptional

Present and true when some shapes were invalid and left out.

inDatasetbooleanOptional

Videos only. True when the video is in the Dataset after the save.

createdClassesstring[]Optional

Videos only. Classes the save added to the project.

post/dataset/{project}/annotate/{imageId}
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
}

Get image details

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

imageIdstringRequired

Image ID.

Query parameters
formatstringOptional

Return the annotation as a file in this export format (ex: voc, coco). Not supported for videos or with include.

Example: voc
includestring · enumOptional

Set 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.

Example: annotationPossible values:
Responses
200

Successful response.

application/json
get/{workspace}/{project}/images/{imageId}
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
  }
}

Save an image annotation with a version check

put

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

imageIdstringRequired

Image ID.

Body
groupstring · min: 1 · max: 200Required

The project's annotation group. Read it from the group field of the image response.

expectedGroupVersionintegerRequired

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.

mutationIdstring · min: 1 · max: 128Required

A unique ID for this save.

isNullbooleanRequired

Set to true to mark the image as null (no objects). boxes must then be empty.

Responses
200

Successful response.

application/json
imageIdstringRequired
annotationGroupVersionintegerRequired

The new version. Send it as expectedGroupVersion on your next save. A save identical to the stored annotation returns the current version.

classesstring[]Required

The project's class names after the save.

put/{workspace}/{project}/images/{imageId}/annotation
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"
  ]
}

Delete images from a project

delete

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

Body
imagesstring[] · min: 1Required

Image IDs to remove.

Responses
204

Completed with no response body.

No content

delete/{workspace}/{project}/images
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

Add or remove image tags

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

imageIdstringRequired

Image ID.

Body
operationstring · enumRequired

add keeps the existing tags, remove deletes the listed tags, and set replaces every tag with the list.

Possible values:
tagsstring[]Required

Tags to add, remove, or set.

Responses
200

Successful response.

application/json
successbooleanOptional
post/{workspace}/{project}/images/{imageId}/tags
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
}

Update metadata and tags for one image

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

imageIdstringRequired

Image ID.

Body

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.

removeMetadatastring[]Optional

Metadata keys to delete.

addTagsstring[]Optional

Tags to add.

removeTagsstring[]Optional

Tags to remove.

Responses
200

Successful response.

application/json
successbooleanOptional
post/{workspace}/images/{imageId}/metadata
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
}

Update metadata and tags for multiple images

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Body
Responses
202

Accepted for asynchronous processing.

application/json
taskIdstringOptional

Asynchronous task ID.

urlstringOptional

URL to poll for the task status. The finished task's result lists totalProcessed, succeeded, failed, and failedItems.

post/{workspace}/images/metadata
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"
}

Add Asset Library images to a project

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

Body

Send exactly one of imageIds or query.

imageIdsstring[] · min: 1 · max: 500Optional

IDs of the Asset Library images or videos to add.

querystring · min: 1 · max: 2000Optional

Asset Library search query. Every match is added. It must not be blank.

sourceProjectIdstring · min: 1Optional

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.

copyAnnotationsFromProjectIdstring · min: 1Optional

Project URL slug or ID to copy annotations from.

Responses
202

Accepted for asynchronous processing.

application/json
taskIdstringRequired

Async task ID.

projectIdstringRequired

ID of the target Project.

projectNamestringOptional

Name of the target Project.

projectUrlstringOptional

URL slug of the target Project.

selectionModestring · enumRequired

How the images were selected.

Possible values:
imageCountintegerOptional

Number of images requested. Present when you send imageIds.

urlstring · uriRequired

URL to poll for the task status. When the task completes, result has imagesLinked, imagesSkipped, and annotationsCopied.

post/{workspace}/{project}/add-images
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"
}

List image batches

get

Lists the upload batches in a project. Requires batch:read.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

Query parameters
showEmptybooleanOptional

Include batches with no images.

Default: false
Responses
200

Successful response.

application/json
get/{workspace}/{project}/batches
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
      }
    }
  ]
}

Get an image batch

get

Returns one upload batch. Requires batch:read.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

batchIdstringRequired

Image batch ID.

Responses
200

Successful response.

application/json
idstringOptional

Batch ID. Use it to create an annotation job from the batch.

namestringOptional

Batch name. Uploads without a batch name go to "Uploaded via API".

imagesintegerOptional

Images in the batch.

numJobsintegerOptional

Annotation jobs created from the batch.

notesstringOptional

Batch notes set at upload. Present only when set.

mediaTypestringOptional

video for a batch of videos. Not set for image batches.

Other propertiesanyOptional
get/{workspace}/{project}/batches/{batchId}
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
  }
}

Start a dataset ZIP upload

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

Body
splitstring · enumOptional

Split for images whose folder does not set one.

Default: trainPossible values:
batchNamestringOptional

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.

tagsstring[]Optional

Tags to add to each uploaded image or video.

annotationOverwritebooleanOptional

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.

Default: false
Responses
200

Successful response.

application/json
taskIdstringOptional

Task ID to poll for status.

signedUrlstringOptional

URL to PUT the ZIP file to, with Content-Type application/zip. It expires after one hour.

post/{workspace}/{project}/upload/zip
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=..."
}

Get dataset ZIP upload status

get

Returns the status of a dataset ZIP upload. Poll it until status is completed or failed. Requires image:create.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

taskIdstringRequired

Asynchronous task ID.

Responses
200

Successful response.

application/json
statusstring · enumOptional

created until the ZIP arrives, then running, then completed or failed.

Possible values:
get/{workspace}/upload/zip/{taskId}
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
  }
}

Prepare a video upload

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Body
namestring · min: 1 · max: 1024Required

File name of the video.

contentTypestring · enumRequired

MIME type of the video file.

Possible values:
projectstringOptional

Project URL slug. Omit it to add the video to the workspace only. API keys scoped to project folders must set it.

batchstring · min: 1 · max: 1024Optional

Batch name. Requires project. Without it, the video gets a batch of its own.

tagone ofOptional

One tag or a list of tags to add to the video.

string · min: 1Optional
or
string[]Optional
splitstring · enumOptional

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.

Possible values:
Responses
200

Successful response.

application/json
videoIdstringRequired

ID of the new video. Use it to read the upload status.

signedUrlstring · uriRequired

URL to PUT the video file to. It expires after 60 minutes.

post/{workspace}/upload/video
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"
  }
}

Get video upload status

get

Reads the processing status of a video upload.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

videoIdstringRequired

Video ID returned when you prepared the upload.

Responses
200

Successful response.

application/json
videoIdstringRequired

ID of the video. When duplicate is true, this is the ID of the video that was already in the workspace.

statusstring · enumRequired

pending while Roboflow processes the video, then uploaded or failed.

Possible values:
duplicatebooleanOptional

True when the same video was already in the workspace, so Roboflow reused it.

messagestringOptional

Why the upload failed. Present when status is failed.

get/{workspace}/upload/video/{videoId}
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"
  }
}

주석

Add comments to an image

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

imageIdstringRequired

Image ID.

Body
Responses
200

Successful response.

application/json
successbooleanOptionalExample: true
createdintegerOptional

Number of comments added.

Example: 1
post/{workspace}/{project}/comments/{imageId}
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
}

List annotation jobs

get

Lists every annotation job in the project. Requires annotation-job:read.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

Responses
200

Successful response.

application/json
get/{workspace}/{project}/jobs
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
      }
    }
  ]
}

Create an annotation job

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

Body
namestringRequired

Job name.

batchstringRequired

ID of the batch to take images from.

num_imagesinteger · min: 1Required

Number of images to put in the job.

labelerEmailstring · emailRequired

Email of the workspace member who labels the images.

reviewerEmailstring · emailRequired

Email of the workspace member who reviews the labels. Without Role Based Access Control, use the labeler's email.

instructionTextstringOptional

Instructions for the labeler. When you leave it out, the job uses the batch notes set at upload.

Responses
200

Successful response.

application/json
idstringOptional

Job ID.

namestringOptional
ownerstringOptional

Workspace ID.

projectstringOptional

Project ID.

sourceBatchstringOptional

Project ID and batch ID joined by a slash.

createdBystringOptional

User ID of the creator, or API for jobs created with the API.

labelerstringOptional

Labeler email.

reviewerstring · nullableOptional

Reviewer email.

statusstring · enumOptional

assigned while labeling, review while in review, complete once added to the dataset.

Possible values:
instructionsTextstringOptional

Instructions shown to the labeler.

numImagesintegerOptional
annotatedintegerOptional
unannotatedintegerOptional
approvedintegerOptional
rejectedintegerOptional
sourcestringOptional

What opened the job (ex: vision_events). Absent for jobs created by hand.

mediaTypestringOptional

Set for video batches.

Other propertiesanyOptional
post/{workspace}/{project}/jobs
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
  }
}

Get an annotation job

get

Returns one annotation job, with its image counts and status. Requires annotation-job:read.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

jobIdstringRequired

Job ID.

Responses
200

Successful response.

application/json
idstringOptional

Job ID.

namestringOptional
ownerstringOptional

Workspace ID.

projectstringOptional

Project ID.

sourceBatchstringOptional

Project ID and batch ID joined by a slash.

createdBystringOptional

User ID of the creator, or API for jobs created with the API.

labelerstringOptional

Labeler email.

reviewerstring · nullableOptional

Reviewer email.

statusstring · enumOptional

assigned while labeling, review while in review, complete once added to the dataset.

Possible values:
instructionsTextstringOptional

Instructions shown to the labeler.

numImagesintegerOptional
annotatedintegerOptional
unannotatedintegerOptional
approvedintegerOptional
rejectedintegerOptional
sourcestringOptional

What opened the job (ex: vision_events). Absent for jobs created by hand.

mediaTypestringOptional

Set for video batches.

Other propertiesanyOptional
get/{workspace}/{project}/jobs/{jobId}
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
  }
}

List Auto Label foundation models

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Responses
200

Successful response.

application/json
get/{workspace}/autolabel/models
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
    }
  ]
}

Preview an Auto Label model

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

Body
modelTypestringRequired

A model id from List Auto Label models.

Example: gemini-3-8-flash-boxes
ontologyone ofOptional

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.

Example: {"a dog":"dog","a cat":"cat"}
or
string[]Optional

Class names, each used as its own prompt.

or
confidenceThresholdnumber · max: 1Optional

SAM 3 models only. Lowest confidence returned.

Responses
200

Successful response.

application/json
modelstringOptional

The modelType you sent.

blockErrorsstring[]Optional

Present when a Workflow step failed, so an empty result is not a real negative.

post/{workspace}/{project}/autolabel/preview
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": []
  }
}

Create an Auto Label job

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

Body
batchIdstringRequired

ID of the image batch to label.

modelTypestringRequired

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.

ontologyone ofOptional

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.

Example: {"a dog":"dog","a cat":"cat"}
or
string[]Optional

Class names, each used as its own prompt.

or
numImagesToLabelinteger · min: 1 · max: 10000Optional

Images to label. Defaults to the whole batch. A job labels at most 10,000 images.

defaultConfidencenumber · max: 1Optional

Confidence threshold for every class without its own threshold.

reviewerEmailstring · emailOptional

Workspace member who reviews the labels. Defaults to the workspace owner.

runNMSbooleanOptional

Run non-max suppression on the predictions.

Default: true
preserveExistingAnnotationsbooleanOptional

Keep annotations already on the images and add the new ones. false replaces them.

Default: false
mergeExistingAnnotationsbooleanOptional

Keep 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.

Default: false
keypointConfidenceThresholdnumber · max: 1Optional

Keypoint detection projects only. Keypoints below this confidence are saved as not visible.

Default: 0.6
workflowIdstringOptional

modelType workflow only. URL slug of a saved Workflow in this workspace.

workspaceNamestringOptional

modelType workflow only. Required. The Workflow's workspace URL slug.

selectedOutputNamestringOptional

modelType workflow only. Required. Workflow output that holds the predictions.

imageInputNamestringOptional

modelType workflow only. Workflow input that takes the image.

Default: image
Responses
200

Successful response.

application/json
jobIdstringOptional

Auto Label job ID. Use it to get the job status.

annotationJobIdstringOptional

The annotation job that receives the labels for review.

messagestringOptional
post/{workspace}/{project}/autolabel
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"
}

Get Auto Label job status

get

Returns the progress of an Auto Label job. Requires annotation-job:read.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

jobIdstringRequired

The jobId returned when you started the job.

Responses
200

Successful response.

application/json
idstringOptional
statusstring · enumOptional

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.

Possible values:
modelTypestringOptional

The model the job runs (ex: sam3, workflow, custom_roboflow).

projectTypestringOptional
projectIdstringOptional
annotationJobIdstringOptional
numImagesintegerOptional

Images in the job.

numImagesSentBackintegerOptional

Images labeled so far.

confidenceThresholdsobject · nullableOptional
get/{workspace}/autolabel/jobs/{jobId}
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
  }
}

워크플로

List Workflows

get

Lists the Workflows in the workspace, without their specifications. Requires workflow:read.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Responses
200

Successful response.

application/json
statusstringOptionalExample: ok
get/{workspace}/workflows
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"
}

Get a Workflow

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

workflowIdstringRequired

Workflow URL slug or ID.

Query parameters
workflow_versionstringOptional

Version ID from List Workflow versions. Returns that version's specification in config. Needs an API key.

Responses
200

Successful response.

application/json
statusstringOptionalExample: ok
get/{workspace}/workflows/{workflowId}
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"
}

Move a Workflow to Trash

delete

Moves a Workflow to Trash. Requires workflow:update.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

workflowIdstringRequired

Workflow URL slug.

Responses
200

Successful response.

application/json
deletedbooleanOptional

Always true.

typestring · enumOptionalPossible values:
workspacestringOptional

Workspace URL slug.

workflowstringOptional

Workflow URL slug from the request.

workflowIdstringOptional

Workflow ID. Pass it as the restore id.

trashbooleanOptional

Always true: the Workflow is in Trash, not permanently deleted.

delete/{workspace}/workflows/{workflowId}
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
}

List Workflow versions

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

workflowIdstringRequired

Workflow URL slug or ID.

Responses
200

Successful response.

application/json
workflowVersionsAccessstring · enumOptional

limited when your plan shows only the 3 newest versions.

Possible values:
totalVersionCountintegerOptional

All versions, including ones your plan hides.

statusstringOptionalExample: ok
get/{workspace}/workflows/{workflowId}/versions
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"
}

Create a Workflow

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Body
namestringRequired

Display name. A number is added when the name is taken.

urlstringRequired

URL slug. A number is added when the slug is taken.

configstringRequired

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.

Example: {"specification":{"version":"1.0","inputs":[],"steps":[],"outputs":[]}}
templatestringOptional

JSON string of template metadata. Required only when you send the fields as query parameters.

folderIdstringOptional

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.

Responses
200

Successful response.

application/json
statusstringOptionalExample: ok
post/{workspace}/createWorkflow
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"
}

Update a Workflow

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Body
idstringRequired

Workflow ID (not the URL slug).

namestringRequired

Display name. Must not be used by another Workflow in the workspace.

urlstringRequired

URL slug. Devices that use the old slug are moved to the new one.

configstringRequired

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.

Example: {"specification":{"version":"1.0","inputs":[],"steps":[],"outputs":[]}}
Responses
200

Successful response.

application/json
statusstringOptionalExample: ok
post/{workspace}/updateWorkflow
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"
}

Fork a Workflow

post

Copies a Workflow from any workspace into this one. Requires workflow:create.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Body
source_workspacestringRequired

URL slug of the workspace that owns the Workflow.

source_workflowstringRequired

URL slug of the Workflow to copy.

namestringOptional

Name of the copy. Defaults to the source name.

urlstringOptional

URL slug of the copy. Made from the name when left out.

folderIdstringOptional

Project folder for the copy. Same rules as createWorkflow.

Responses
200

Successful response.

application/json
workflowstringOptional

URL slug of the copy.

workflow_idstringOptional

ID of the copy.

statusstringOptionalExample: ok
post/{workspace}/forkWorkflow
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"
}

Create a Workflow token

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Body
idstringRequired

Workflow ID.

Responses
200

Successful response.

application/json
tokenstringOptional
statusstringOptionalExample: ok
post/{workspace}/workflowToken
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"
}

에이전트

Send a message to Roboflow Agent

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Body
messagestringRequired

The instruction or question for the Agent.

conversation_idstringOptional

ID of a conversation in this workspace to continue. Omit to start a new conversation.

modestring · enumOptional

agent lets the Agent make changes. plan makes it outline what it would do without making changes. Any other value means agent.

Default: agentPossible values:
Responses
200

Successful response.

application/json
textstringRequired

The Agent's reply.

conversation_idstringRequired

Conversation ID. Pass it back as conversation_id to continue the conversation.

post/{workspace}/agent/chat
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"
}

Publish a Workflow created by Roboflow Agent

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

workflowIdstringRequired

Workflow URL slug.

Responses
200

Successful response.

application/json
workflowIdstringRequired

Workflow ID.

workflowUrlstringRequired

Workflow URL slug.

versionIdstringRequired

ID of the version that is now published.

statusstring · enumRequiredPossible values:
post/{workspace}/agent/workflows/{workflowId}/publish
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"
}

List Roboflow Agent conversations

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Query parameters
sourcestring · enumOptional

api returns conversations started through the Agent API. web returns all others. Any other value is ignored.

Possible values:
workflowstringOptional

Workflow URL slug or ID. Returns only conversations linked to this Workflow.

Responses
200

Successful response.

application/json
get/{workspace}/agent/conversations
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"
      }
    }
  ]
}

Get a Roboflow Agent conversation

get

Returns one Agent conversation with all of its messages, oldest first. Requires the workflow:read scope.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

conversationIdstringRequired

Conversation ID.

Responses
200

Successful response.

application/json
idstringRequired

Conversation ID.

namestringOptional

Conversation title. Generated after the first reply. Missing until then, unless a linked Workflow's name stands in.

typestring · enumOptional

Conversation kind. workflow once the Agent has created a Workflow in it. Missing on a conversation with no kind yet.

Possible values:
sourcestring · enumOptional

Where the conversation started: api for the Agent API, web for the app. Missing on older web conversations.

Possible values:
workflowIdsstring[]Required

IDs of the Workflows the conversation created or edited.

created_onstring · date-timeRequired
updated_onstring · date-timeRequired
get/{workspace}/agent/conversations/{conversationId}
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"
    }
  ]
}

검색

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Query parameters
qstring · max: 500Required

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.

Example: hard hats
pageinteger · min: 1 · max: 10Optional

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.

Default: 1
modelstringOptional

Set to true to return only projects with a trained model. Any non-empty value turns the filter on.

Example: true
projectTypestringOptional

Return only projects of this type (ex: object-detection, classification, instance-segmentation). It replaces a project type written in the query text.

Example: object-detection
includeModelVersionsstring · enumOptional

Set 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.

Default: falsePossible values:
Responses
200

Successful response.

application/json
querystring · nullableRequired

The search text after cleanup (lowercase, unsupported characters removed). null for a search by image with no text.

query_typestring · enumRequired

What the search used.

Possible values:
pageintegerRequired

Page returned. A direct workspace/project lookup always returns page 1.

page_sizeintegerRequired

Results per page. Always 12.

countintegerRequired

Results on this page.

get/universe/search
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
    }
  ]
}

Search public Universe projects by image

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Query parameters
modelstringOptional

Set to true to return only projects with a trained model. Any non-empty value turns the filter on.

Example: true
projectTypestringOptional

Return only projects of this type (ex: object-detection, classification, instance-segmentation). It replaces a project type written in the query text.

Example: object-detection
includeModelVersionsstring · enumOptional

Set 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.

Default: falsePossible values:
Body
imagestringRequired

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.

qstring · max: 500Optional

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.

pageinteger · min: 1 · max: 10Optional

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.

Default: 1
Responses
200

Successful response.

application/json
querystring · nullableRequired

The search text after cleanup (lowercase, unsupported characters removed). null for a search by image with no text.

query_typestring · enumRequired

What the search used.

Possible values:
pageintegerRequired

Page returned. A direct workspace/project lookup always returns page 1.

page_sizeintegerRequired

Results per page. Always 12.

countintegerRequired

Results on this page.

post/universe/search
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
    }
  ]
}

Search images in a project

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

Body
promptstringOptional

Text to sort results by semantic similarity.

like_imagestringOptional

Image ID to sort results by visual similarity.

image_base64stringOptional

Base64 image to sort results by visual similarity.

tagstringOptional

Return only images with this tag.

class_namestringOptional

Return only images with at least one annotation of this class.

in_datasetbooleanOptional

Return only images in the project's Dataset.

batchbooleanOptional

Return only images in any batch of the project.

batch_idstringOptional

Return only images in this batch.

annotation_jobbooleanOptional

Return only images in any annotation job of the project.

annotation_job_idstringOptional

Return only images in this annotation job.

offsetintegerOptional

Results to skip.

Default: 0
limitinteger · min: 1 · max: 250Optional

Results to return. Values over 250 return 250.

Default: 50
Responses
200

Successful response.

application/json
offsetintegerOptional
totalintegerOptional

Images that match.

post/{workspace}/{project}/search
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"
      ]
    }
  ]
}

Search images across a workspace

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Body
querystringOptional

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.

Default: ""
pageSizeinteger · min: 1Optional

Results per page.

Default: 50
continuationTokenstringOptional

Token from the previous page. Send it with the same query to get the next page.

includeProjectGroupIdsstring[]Optional

Project folder IDs to limit results to. Not allowed with a folder-scoped API key.

Responses
200

Successful response.

application/json
totalintegerOptional

Images that match.

continuationTokenstringOptional

Send it in the next request to get the next page. Not present when there are no results.

post/{workspace}/search/v1
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"
        }
      }
    }
  ]
}

Export image search results

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Body
querystringOptional

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:.

formatstringRequired

Export format (ex: coco, yolov8, voc). With dataset, it must be a format the project type supports.

datasetstringOptional

Project URL slug. Limits the export to this project and uses its annotation group. Cannot be sent with annotationGroup.

annotationGroupstringOptional

Annotation group to export annotations from. Cannot be sent with dataset.

namestringOptional

Name of the export. Defaults to -search-export.

Responses
202

Accepted for asynchronous processing.

application/json
successbooleanRequired

Always true.

linkstringRequired

Export link. Pass it to Get image search export status.

post/{workspace}/search/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"
}
get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

linkstringRequired

Export link returned when you started the export.

Responses
200

Successful response.

application/json
readybooleanRequired

True when the ZIP is built and link holds its download URL.

linkstring · uriOptional

Signed download URL for the ZIP, valid for 15 minutes. Only when ready is true.

get/{workspace}/search/export/{link}
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=..."
}

휴지통 및 작업

List deleted resources

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Responses
200

Successful response.

application/json
get/{workspace}/trash
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": []
  }
}

Restore a deleted resource

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Body
typestring · enumRequired

Kind of item to restore.

Possible values:
idstringRequired

The item's id from the Trash list. For a version, the version number.

parentIdstringOptional

Required for a version: the parentId (project ID) from the Trash list.

Responses
200

Successful response.

application/json
restoredbooleanOptional

Always true.

typestringOptional

Kind of item restored.

idstringOptional

ID of the item restored.

post/{workspace}/trash/restore
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"
}

Get asynchronous task status

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

taskIdstringRequired

Asynchronous task ID.

Responses
200

Successful response.

application/json
taskIdstringRequired

The task ID from the request.

statusstringRequired

Task state: created, running, completed, or failed. completed and failed are final.

Example: running
stepstringOptional

Name of the step a multi-step task is on. Only some tasks return it.

createdAtstring · date-timeOptional

When the task was created.

updatedAtstring · date-timeOptional

When the task last changed.

resultone of · nullableOptional

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.

or
arrayOptional
errorstringOptional

Present when status is failed. The failure message, or "Task failed".

get/{workspace}/asynctasks/{taskId}
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"
  }
}

배포

Get project deployment settings

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

Responses
200

Successful response.

application/json
baseWorkflowWasCreatedbooleanOptional

True when this request created the base Workflow.

openAiDetectionAvailabilitystring · enumOptional

Get only. Whether a new GPT-6 Astra or GPT-6.1 Sol endpoint would run for this workspace.

Possible values:
get/{workspace}/{project}/deploy
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
}

Select the deployed project model

post

Sets the model the project's base Workflow runs. The model must fit the project type. Requires project:update.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

Body
Responses
200

Successful response.

application/json
baseWorkflowWasCreatedbooleanOptional

True when this request created the base Workflow.

openAiDetectionAvailabilitystring · enumOptional

Get only. Whether a new GPT-6 Astra or GPT-6.1 Sol endpoint would run for this workspace.

Possible values:
post/{workspace}/{project}/deploy/model
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
}

Get Active Learning settings

get

Returns the project's base Workflow, its model, and its Active Learning settings. Requires project:read and the Active Learning permission in the workspace.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

Responses
200

Successful response.

application/json
get/{workspace}/{project}/deploy/active-learning
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": []
  }
}

Enable Active Learning

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

Responses
200

Successful response.

application/json
post/{workspace}/{project}/deploy/active-learning/enable
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": []
  }
}

Disable Active Learning

post

Turns off image collection. Your collection limits and filters are kept. Requires project:update.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

Responses
200

Successful response.

application/json
post/{workspace}/{project}/deploy/active-learning/disable
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": []
  }
}

Update Active Learning settings

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

Body
Responses
200

Successful response.

application/json
post/{workspace}/{project}/deploy/active-learning/configuration
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": []
  }
}

List Active Learning images

get

Lists the review queue: batches of collected images and the annotation jobs made from them, with totals. Requires project:read.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

projectstringRequired

Project URL slug.

Query parameters
pageinteger · min: 1Optional

Page number, from 1.

Default: 1
pageSizeinteger · min: 1 · max: 50Optional

Items per page.

Default: 10
searchstringOptional

Text matched against queue names, types, IDs, reviewers, and labelers.

reviewerstringOptional

Reviewer email, or unassigned for items with no reviewer.

statusstring · enumOptional

not_started for batches, in_progress for annotation jobs.

Default: allPossible values:
sortBystring · enumOptionalDefault: createdPossible values:
sortDirectionstring · enumOptionalDefault: descPossible values:
Responses
200

Successful response.

application/json
get/{workspace}/{project}/deploy/active-learning/images
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 usage statistics

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Query parameters
startTimestringOptional

Start of the time range in UTC (ex: 2026-10-01 00:00:00). Defaults to 24 hours before the request.

Example: 2026-10-01 00:00:00
endTimestringOptional

End of the time range in UTC. Defaults to the time of the request.

Example: 2026-10-08 00:00:00
modelNamesstringOptional

Comma-separated model IDs without versions. Omit to include every model.

Example: license-plate-detector,truck-detector
Responses
200

Successful response.

application/json

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.

num_inferencesinteger · nullableOptional

Inferences in the time range.

prev_num_inferencesinteger · nullableOptional

Inferences in the period of the same length before the time range.

num_errorsinteger · nullableOptional

Failed inferences in the time range.

prev_num_errorsinteger · nullableOptional

Failed inferences in the previous period.

avg_confidencenumber · nullableOptional

Average prediction confidence, from 0 to 1.

prev_avg_confidencenumber · nullableOptional

Average prediction confidence in the previous period.

avg_response_timenumber · nullableOptional

Average inference time in seconds, including image preprocessing.

prev_avg_response_timenumber · nullableOptional

Average inference time in seconds in the previous period.

Other propertiesanyOptional
get/{workspace}/inference-stats
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 metadata to inference records

post

Attach custom metadata to inferences so you can filter and group them in Model Monitoring. Requires model:infer.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Body
Responses
200

Successful response.

application/json
statusstring · enumOptional

Present when the metadata was saved.

Possible values:
errorstringOptional

Present instead of status when the metadata could not be saved. The status code is still 200.

post/{workspace}/inference-stats/metadata
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"
}

비전 이벤트

Create a Vision Event

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Body
eventIdstring · max: 256Required

Unique event ID. Use a UUID (v4). An event sent with an eventId that already exists replaces the earlier event.

eventTypestring · enumRequiredPossible values:
useCaseIdstring · max: 256Required

ID of the use case the event belongs to. solution and solutionId are deprecated aliases.

timestampstring · date-timeRequired

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.

deviceIdstring · max: 256Optional
streamIdstring · max: 256Optional
workflowIdstring · max: 256Optional
workflowVersionstring · max: 64Optional
displayImagePositioninteger · max: 999Optional

Index in images of the image to show first.

commentstring · max: 1000Optional

A note about the event. With operator_feedback, this holds the reviewer's note.

valueBaseUnitsinteger · min: -10000000000 · max: 10000000000Optional

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.

autoFinalizedAtstring · date-timeOptional

Set by Edge Device Backup when the device closed the event before its video finished uploading.

Responses
201

Created.

application/json
eventIdstringRequired
createdbooleanRequired
deprecationsstring[]Optional

Present when the request used a deprecated field name (solution or solutionId) instead of useCaseId.

post/vision-events
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"
    }
  ]
}

Create Vision Events in a batch

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Body
Responses
201

Created.

application/json
createdintegerRequired

Number of events stored.

eventIdsstring[]Required
deprecationsstring[]Optional

Present when the request used a deprecated field name (solution or solutionId) instead of useCaseId.

post/vision-events/batch
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"
  ]
}

Upload a Vision Event image

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Query parameters
namestringOptional

Custom name for the image. The name form field wins when you send both.

Body
filestring · binaryRequired

The image file. Supported formats are JPEG, PNG, WebP, GIF, TIFF, BMP, HEIC, and AVIF. Any form field name works for the file.

namestringOptional

Custom name for the image.

metadatastringOptional

JSON object of metadata to store with the image. Same limits as event customMetadata. Keys that start with rf_internal are reserved and rejected.

Responses
201

Created.

application/json
successbooleanRequired
sourceIdstringRequired

Put it in images[].sourceId or images[].inputSourceId when you create an event.

urlstring · uriRequired

Public URL of the uploaded image.

post/vision-events/upload
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"
}

Prepare a Vision Event video upload

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Body
namestring · min: 1 · max: 1024Required

File name of the video.

contentTypestring · enumRequired

MIME type of the video file.

Possible values:
Responses
201

Created.

application/json
successbooleanRequired
videoIdstringRequired

Put it in videos[].sourceId when you create the event.

signedUrlstring · uriRequired

URL to PUT the video file to. It expires after 60 minutes.

post/vision-events/videos/prepare-upload
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"
  }
}

Get Vision Event video status

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
videoIdstring · max: 256Required

Video ID returned when you prepared the upload.

Responses
200

Successful response.

application/json
videoIdstringRequired
statusstring · enumRequired

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.

Possible values:
posterUrlstring · uriRequired

Public URL of a still frame from the video. It returns 404 until status is uploaded.

durationSecondsnumber · nullableOptional
contentTypestring · nullableOptional
sizeBytesinteger · nullableOptional
filenamestring · nullableOptional
get/vision-events/videos/{videoId}
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"
}

Get a Vision Event video playback URL

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
videoIdstring · max: 256Required

Video ID returned when you prepared the upload.

Responses
200

Successful response.

application/json
videoIdstringRequired
statusstring · enumRequired

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.

Possible values:
posterUrlstring · uriRequired

Public URL of a still frame from the video. It returns 404 until status is uploaded.

durationSecondsnumber · nullableOptional
contentTypestring · nullableOptional
sizeBytesinteger · nullableOptional
filenamestring · nullableOptional
urlstring · nullableRequired

Signed URL that plays the video. It expires after 60 minutes. null until status is uploaded.

get/vision-events/videos/{videoId}/url
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
}

Query Vision Events

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Body
useCaseIdstring · max: 256Required

Use case to query. solution and solutionId are deprecated aliases.

startTimestring · date-timeOptional
endTimestring · date-timeOptional
eventTypestring · enumOptional

One event type. For several, use eventTypes.

Possible values:
hasWarningsbooleanOptional

true for events with ingestion warnings, false for events without.

limitinteger · min: 1 · max: 1000OptionalDefault: 100
cursorstringOptional

nextCursor from the previous page.

anchorEventIdstring · max: 256Optional

Start the first page at this event. Ignored with cursor. The response sets anchorFound.

savedFilterIdstringOptional

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.

Responses
200

Successful response.

application/json
hasMorebooleanRequired

true when more events match.

nextCursorstring · nullableRequired

Send as cursor to get the next page. null when hasMore is false.

anchorFoundbooleanOptional

Returned when you sent anchorEventId. false when that event is not in the retention window.

lookbackDaysintegerRequired

The workspace's retention window in days.

deprecationsstring[]Optional

Present when the request used a deprecated field name (solution or solutionId) instead of useCaseId.

post/vision-events/query
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
}

Delete Vision Events

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Body
useCaseIdstringRequired

ID of the Use Case the events belong to.

eventIdsstring[] · min: 1 · max: 1000Required

IDs of the events to delete. Duplicates count once.

Responses
200

Successful response.

application/json
deletedintegerRequired

Number of events deleted.

notFoundstring[]Required

Requested event IDs that matched no live event in the Use Case.

deprecationsstring[]Optional

Present when the request used a deprecated field name (solution or solutionId) instead of useCaseId.

post/vision-events/delete
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"
  ]
}

Get a custom metadata schema

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
useCaseIdstring · min: 1 · max: 256Required

Use case ID.

Responses
200

Successful response.

application/json
useCaseIdstringRequired
get/vision-events/custom-metadata-schema/{useCaseId}
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"
      ]
    }
  }
}

List Vision Event use cases

get

Lists the workspace's use cases with one status, whether or not they have events. Requires the vision-events:read or device:read scope.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Query parameters
statusstring · enumOptional

Use case status to list. Use inactive to list archived use cases.

Default: activePossible values:
Responses
200

Successful response.

application/json
lookbackDaysintegerRequired

The workspace's retention window in days.

get/vision-events/use-cases
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
}

Create a Vision Event use case

post

Creates an active use case in the workspace. Use the returned id as useCaseId when you create events. Requires the vision-events:manage scope.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Body
namestring · min: 1 · max: 256Required

Unique within the workspace. Leading and trailing spaces are trimmed.

defaultValueBaseUnitsinteger · min: -10000000000 · max: 10000000000Optional

Value given to new events that don't send valueBaseUnits, in the smallest unit of the currency (ex: cents for USD).

defaultValueCurrencystringOptional

Three-letter currency code for event values (ex: USD, EUR, JPY), in any case. Defaults to USD. An unsupported code returns 400.

Responses
201

Created.

application/json
idstringRequired

Use it as useCaseId when you create events.

namestringRequired
post/vision-events/use-cases
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"
}

Update a Vision Event use case

put

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
useCaseIdstring · min: 1 · max: 256Required

Use case ID.

Body

Send at least one field.

namestring · min: 1 · max: 256Optional

New name. Unique within the workspace.

statusstring · enumOptionalPossible values:
defaultValueBaseUnitsinteger · min: -10000000000 · max: 10000000000 · nullableOptional

Value given to new events that don't send valueBaseUnits. null removes the default.

defaultValueCurrencystringOptional

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.

Responses
200

Successful response.

application/json
idstringRequired
namestringRequired
defaultValueBaseUnitsinteger · nullableRequired

The default event value after the update. null when unset.

defaultValueCurrencystringRequired

The currency after the update. USD when unset.

put/vision-events/use-cases/{useCaseId}
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"
}

Archive a Vision Event use case

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
useCaseIdstring · min: 1 · max: 256Required

Use case ID.

Responses
200

Successful response.

application/json
successbooleanRequired
post/vision-events/use-cases/{useCaseId}/archive
POST /vision-events/use-cases/{useCaseId}/archive HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
  "success": true
}

Unarchive a Vision Event use case

post

Restores an archived use case by setting its status back to active. Requires the vision-events:manage scope.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
useCaseIdstring · min: 1 · max: 256Required

Use case ID.

Responses
200

Successful response.

application/json
successbooleanRequired
post/vision-events/use-cases/{useCaseId}/unarchive
POST /vision-events/use-cases/{useCaseId}/unarchive HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
  "success": true
}

배포 관리자

List Deployment Manager devices

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Query parameters
folderstringOptional

Only return devices in this folder. Pass a folder ID, or global for devices at the workspace root. Subfolders are not included.

Example: global
Responses
200

Successful response.

application/json
get/{workspace}/devices/v2
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"
    }
  ]
}

Register a Deployment Manager device

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Body
device_namestringRequired

Device name. Must not be empty.

device_typestringOptional

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.

osstring · enumOptional

Set to roboflow-os for a Roboflow OS device. Only valid when device_type is edge.

Possible values:
runtimestring · enumOptional

Container runtime the installer sets up. Required for device_type secure-gateway.

Possible values:
workflow_idstringOptional

Workflow URL slug to assign to the device. For an AI1 device it becomes the Workflow of the camera stream.

tagsstring[]Optional

Tags for the device. Each tag is trimmed and must not be empty. Duplicates are removed.

projectGroupIdstring · nullableOptional

ID of the folder to put the device in. Leave it out to create the device at the workspace root.

offline_modebooleanOptional

Provision the device for offline use. Only valid for AI1 and Roboflow OS devices, on workspaces with Roboflow Lite mode.

sourceDeviceIdstringOptional

ID of a device in the same workspace to copy the configuration from. Its streams, install history, and queued changes are not copied.

Responses
201

Created.

application/json
deviceIdstringRequired

ID of the new device.

installIdstringRequired

Install ID. Use it to install Deployment Manager on the device. It expires after 10 minutes.

offlineProvisioningQrPayloadstringOptional

Data for the offline provisioning QR code. Only returned for devices created in offline mode.

post/{workspace}/devices/v2
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"
}

Get the default device configuration

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Responses
200

Successful response.

application/json
get/{workspace}/devices/v2/default-config
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
      }
    }
  }
}

Get a device

get

Returns one device, with its network interfaces from the latest telemetry. Requires device:read.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

deviceIdstringRequired

Deployment Manager device ID.

Responses
200

Successful response.

application/json

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.

idstringOptional

Device ID.

namestring · nullableOptional

Device name.

statusstring · enumOptional

online when the last heartbeat is less than 5 minutes old, offline when it is older, and unknown when the device never sent one.

Possible values:
last_heartbeatstring · nullableOptional

Time of the last heartbeat.

server_urlstring · nullableOptional

Server URL the device reports in its telemetry.

platformstring · nullableOptional

Operating system (ex: Linux).

platform_releasestring · nullableOptional

Kernel release.

platform_versionstring · nullableOptional

Kernel version string.

architecturestring · nullableOptional

CPU architecture (ex: aarch64, x86_64).

hostnamestring · nullableOptional

Device hostname.

ip_addressstring · nullableOptional

IP address the device reports.

rfdm_versionstring · nullableOptional

Version of Roboflow Deployment Manager (RFDM) running on the device.

typestring · nullableOptional

Device type the device reports.

tagsstring[]Optional

Tags on the device.

created_atstring · nullableOptional

When the device was created.

get/{workspace}/devices/v2/{deviceId}
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"
}

Get device configuration

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

deviceIdstringRequired

Deployment Manager device ID.

Query parameters
waitinteger · max: 45Optional

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.

Default: 0
Header parameters
If-None-MatchstringOptional

ETag from an earlier response.

Responses
200

Successful response.

application/json

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.

Other propertiesanyOptional
get/{workspace}/devices/v2/{deviceId}/config
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": {}
    }
  }
}

Get device configuration history

get

Returns the device's saved config revisions, newest first. Requires device:read.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

deviceIdstringRequired

Deployment Manager device ID.

Query parameters
limitinteger · min: 1 · max: 500Optional

Revisions per page. Values outside 1 to 500 are clamped.

Default: 10
cursorstringOptional

next_cursor from the previous page: the save time of the last revision returned, as an ISO 8601 timestamp.

Responses
200

Successful response.

application/json
get/{workspace}/devices/v2/{deviceId}/config/history
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
  }
}

List device streams

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

deviceIdstringRequired

Deployment Manager device ID.

Responses
200

Successful response.

application/json
get/{workspace}/devices/v2/{deviceId}/streams
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
    }
  ]
}

Get a device stream

get

Returns one stream. A stream that is only in the device config comes back as provisioning. Requires device:read.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

deviceIdstringRequired

Deployment Manager device ID.

streamIdstringRequired

Stream ID, pipeline ID, or stream key in the device config.

Query parameters
includestring · enumOptional

Set to status_events to add the stream's 20 most recent events from the last 7 days.

Possible values:
Responses
200

Successful response.

application/json
idstring · nullableOptional

Stream ID.

namestring · nullableOptional

Stream name.

statusstring · nullableOptional

Stream status (ex: running, stopped). A stream in the device config that has not reported in yet is provisioning.

provisioningbooleanOptional

True when the stream is in the config but has not reported in yet.

modestring,null · enum · nullableOptional

triggered when the stream runs its Workflow only when triggered, continuous otherwise. Null when the stream has no config entry.

Possible values:
pipeline_idstring · nullableOptional

Inference pipeline ID.

workflow_idstring · nullableOptional

Workflow the stream runs.

sourcestring | object | array · nullableOptional

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.

configured_sourcestring | object | array · nullableOptional

Source from the device config, cleaned the same way. Filled in only when there is no live source.

started_atstring · nullableOptional

When the stream started.

last_event_atstring · nullableOptional

When the stream last changed.

camera_fpsnumber · nullableOptional

Camera frame rate from the device.

inference_fpsnumber · nullableOptional

Inference frame rate from the device.

sharpnessnumber · nullableOptional

Focus score of the latest frame, from 0 (blurry) to 100 (sharp).

errorstring · nullableOptional

Free-text error from the device, with credentials masked. An error sent as an object is returned as a JSON string.

error_codestring · nullableOptional

Code of the latest stream failure (ex: STREAM_SOURCE_UNAVAILABLE). Null when the stream is healthy.

error_messagestring · nullableOptional

Text that goes with error_code, with credentials masked.

error_retryableboolean · nullableOptional

True when the device retries the stream by itself.

get/{workspace}/devices/v2/{deviceId}/streams/{streamId}
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
}

Get device logs

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

deviceIdstringRequired

Deployment Manager device ID.

Query parameters
limitinteger · min: 1 · max: 1000Optional

Lines per page. Values outside 1 to 1000 are clamped.

Default: 100
start_timestringOptional

Only lines at or after this time (ISO 8601).

Example: 2026-10-28T00:00:00Z
end_timestringOptional

Only lines at or before this time (ISO 8601).

Example: 2026-10-28T00:00:00Z
servicestringOptional

Comma-separated service names.

Example: inference,manager
severitystringOptional

Comma-separated severities.

Example: WARN,ERROR
cursorstringOptional

next_cursor from the previous page. Returns lines older than it.

Example: 2026-10-28T00:00:00Z
Responses
200

Successful response.

application/json
get/{workspace}/devices/v2/{deviceId}/logs
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
  }
}

Get device telemetry

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

deviceIdstringRequired

Deployment Manager device ID.

Query parameters
time_periodstring · enumOptional

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.

Default: 24hPossible values:
includestringOptional

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.

Example: metrics,stream_fps
Responses
200

Successful response.

application/json

Each section is present only when you ask for it with include.

time_periodstringOptional

Time window used.

bucket_intervalstringOptional

Bucket size (ex: 30 MINUTE).

fill_interval_secondsintegerOptional

Bucket size, in seconds.

services_truncatedbooleanOptional

Present and true when the container query hit its cap of 2,000 rows, so older service history can be missing.

stream_fps_truncatedbooleanOptional

Present and true when the FPS query hit its cap of 5,000 rows, so some buckets are missing.

get/{workspace}/devices/v2/{deviceId}/telemetry
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"
    }
  }
}

Get device events

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

deviceIdstringRequired

Deployment Manager device ID.

Query parameters
limitinteger · min: 1 · max: 1000Optional

Events per page. Values outside 1 to 1000 are clamped.

Default: 100
entity_typestringOptional

Only events from this kind of entity (ex: device, stream, container).

entity_idstringOptional

Only events from this entity.

eventstringOptional

Only events with this name.

start_timestringOptional

Only events at or after this time (ISO 8601). Timestamps with no zone are read as UTC.

Example: 2026-10-28T00:00:00Z
end_timestringOptional

Only events before this time (ISO 8601).

Example: 2026-10-28T00:00:00Z
cursorstringOptional

next_cursor or prev_cursor from a previous page.

directionstring · enumOptional

backward pages to older events, forward to newer ones.

Default: backwardPossible values:
dedupestring · enumOptional

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.

Default: truePossible values:
Responses
200

Successful response.

application/json
get/{workspace}/devices/v2/{deviceId}/events
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
  }
}

List device services

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

deviceIdstringRequired

Deployment Manager device ID.

Query parameters
includestringOptional

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.

Default: statusExample: status,metrics
kindstringOptional

Only return services of this kind (ex: plc_relay).

time_periodstring · enumOptional

Window for the metrics section.

Default: 24hPossible values:
Responses
200

Successful response.

application/json
device_idstringOptional

Device ID.

metrics_truncatedbooleanOptional

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.

get/{workspace}/devices/v2/{deviceId}/services
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
}

Get a device service

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

deviceIdstringRequired

Deployment Manager device ID.

serviceNamestringRequired

Service name, as declared in the device config.

Query parameters
includestringOptional

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.

Default: statusExample: status,metrics
time_periodstring · enumOptional

Window for the metrics section.

Default: 24hPossible values:
Responses
200

Successful response.

application/json

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.

namestringOptional

Service name in the device config.

kindstring · enumOptional

Service kind, resolved from the image. An image Roboflow does not publish is custom.

Possible values:
imagestring · nullableOptional

Configured image.

tagstring · nullableOptional

Configured image tag.

tag_is_canonicalboolean · nullableOptional

True when the tag is the version Roboflow ships for this kind. Null when Roboflow does not pin a version for it.

automatic_updatesboolean · nullableOptional

Whether automatic updates are on for the service. Null when not set.

signal_conflictsstring[]Optional

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.

has_pending_changesbooleanOptional

True when a change to the service waits for a maintenance window.

statestring · nullableOptional

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.

state_reported_atstring · nullableOptional

When the device says the state changed. Null when the device sent no timestamp.

state_received_atstring · nullableOptional

When Roboflow received the state.

error_codestring · nullableOptional

Error code sent with the current state.

image_statestring · nullableOptional

Latest image pull state (ex: pull_succeeded). Null when it is past its TTL.

image_state_reported_atstring · nullableOptional

When the device says the image state changed.

image_state_received_atstring · nullableOptional

When Roboflow received the image state.

statusobject · nullableOptional

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.

metrics_truncatedbooleanOptional

Get a Device Service only. Present and true when the metrics query hit its row cap, so older containers report null metrics.

get/{workspace}/devices/v2/{deviceId}/services/{serviceName}
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
  }
}

Get a device service metric series

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

deviceIdstringRequired

Deployment Manager device ID.

serviceNamestringRequired

Service name, as declared in the device config.

Query parameters
metricstringRequired

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.

Example: bytes_percent
time_periodstring · enumOptional

Time window to read.

Default: 24hPossible values:
Responses
200

Successful response.

application/json
device_idstringOptional
servicestringOptional

Service name.

kindstringOptional

Service kind.

metricstringOptional

Metric returned.

metric_typestring · enumOptional

A boolean metric is returned as 1 or 0.

Possible values:
time_periodstringOptional

Time window used.

available_metricsstring[]Optional

Metric names for this kind.

truncatedbooleanOptional

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.

covered_fromstring · nullableOptional

Time of the first point, on the device clock.

covered_tostring · nullableOptional

Time of the last point, on the device clock.

get/{workspace}/devices/v2/{deviceId}/services/{serviceName}/series
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 메서드가 정의되어 있지 않습니다.

List Cloud Streaming sources

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Query parameters
includeTemporarybooleanOptional

Include workspace temporary sessions.

Default: false
Responses
200

Successful response.

application/json
get/{workspace}/video-sources/v1
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 Workflow interface

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Query parameters
workflowUrlstring · min: 1Required

Saved Workflow URL slug in this workspace.

Example: warehouse-monitor
Responses
200

Successful response.

application/json
degradedbooleanRequired

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.

get/{workspace}/video-sources/v1/workflow-interface
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": []
}

Allocate a temporary source

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Header parameters
Idempotency-Keystring · min: 8 · max: 128Required

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.

Example: run-warehouse-camera-001Pattern: ^[A-Za-z0-9._:-]+$
Body
namestring · min: 1 · max: 100Optional

Session display name.

Default: Browser preview
cellstringOptional

Optional enabled temporary-source cell allowed for this workspace. Omit for server placement.

Pattern: ^[a-z0-9-]{1,63}$
Responses
200

Successful response.

application/json
sourceIdstringRequired

Allocated temporary source ID.

Pattern: ^tmp-[a-f0-9]{40}$
grantExpiresAtinteger · int64Required

Deadline to admit the publisher. Unix time in milliseconds.

whipUrlstring · uriRequired

Credentialed single-publisher WHIP URL. Use unchanged and never log, persist or share it.

post/{workspace}/video-sources/v1/temporary
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"
}

End a temporary source session

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

sourceIdstringRequired

Cloud Streaming source ID from the source list.

Pattern: ^tmp-[a-f0-9]{40}$
Responses
200

Successful response.

application/json
stopRequestedconst: Required
post/{workspace}/video-sources/v1/{sourceId}/stop-session
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
}

Preview raw source video

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

sourceIdstring · min: 1 · max: 256Required

Cloud Streaming source ID from the source list.

Pattern: ^[^/\\]+$
Body
cellstring · nullableOptional

Optional source placement cell. Omit for server selection.

Responses
200

Successful response.

application/json
or
post/{workspace}/video-sources/v1/{sourceId}/preview
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"
}

Start a Workflow job

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

sourceIdstring · min: 1 · max: 256Required

Cloud Streaming source ID from the source list.

Pattern: ^[^/\\]+$
Header parameters
Idempotency-Keystring · min: 8 · max: 128Required

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.

Example: run-warehouse-camera-001Pattern: ^[A-Za-z0-9._:-]+$
Body
anyOptional
or
anyOptional
Responses
200

Identical request replayed under the same key and credential; returns the original job.

application/json
post/{workspace}/video-sources/v1/{sourceId}/jobs
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
  }
}

List Workflow jobs

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Responses
200

Successful response.

application/json
get/{workspace}/video-jobs/v1
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
    }
  ]
}

Get a Workflow job

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

jobIdstring · min: 1 · max: 256Required

Job ID.

Pattern: ^[^/\\]+$
Responses
200

Successful response.

application/json
get/{workspace}/video-jobs/v1/{jobId}
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
  }
}

Stop a Workflow job

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

jobIdstring · min: 1 · max: 256Required

Job ID.

Pattern: ^[^/\\]+$
Responses
200

Successful response.

application/json
post/{workspace}/video-jobs/v1/{jobId}/cancel
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
  }
}

Renew a temporary preview owner lease

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

jobIdstring · min: 1 · max: 256Required

Job ID.

Pattern: ^[^/\\]+$
Responses
200

Successful response.

application/json
heldbooleanRequired

True if renewed; false if the job is expired, stopping or terminal. Stop using an expired job rather than assuming it was revived.

post/{workspace}/video-jobs/v1/{jobId}/hold-preview
POST /{workspace}/video-jobs/v1/{jobId}/hold-preview HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
  "held": true
}

Watch annotated Workflow output

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

jobIdstring · min: 1 · max: 256Required

Job ID.

Pattern: ^[^/\\]+$
Body
outputstring · min: 1 · max: 256 · nullableOptional

Name of a Workflow image output, without a selector prefix. Null or omission uses the job's default selection.

Example: label_visualization_output
Responses
200

Successful response.

application/json
executionGenerationintegerOptional

Generation associated with this grant, when present on the job. Match it to the current job and request a fresh grant after execution changes.

whepUrlstring · uriRequired

Credentialed WHEP URL for annotated output. Use unchanged; do not log, persist or share it.

rtspsUrlstring · nullableRequired

Credentialed RTSPS URL for the same output, or null when the cell has no public RTSPS listener.

processorAccessTokenstringRequired

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.

post/{workspace}/video-jobs/v1/{jobId}/watch
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"
}

Download completed file results

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

jobIdstring · min: 1 · max: 256Required

Job ID.

Pattern: ^[^/\\]+$
Responses
200

Successful response.

application/json
get/{workspace}/video-jobs/v1/{jobId}/results
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"
  }
}

모델 평가

List model evaluations

get

Lists the model evaluations in a workspace, newest first. Filter by one of project, version, or model per request. Requires model-eval:read.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Query parameters
projectstringOptional

Project URL slug. An unknown slug returns an empty list.

Example: chess-pieces-fmhpz
versionstringOptional

Dataset version number. Alias: versionId.

Example: 4
modelstringOptional

Model ID, with or without the workspace prefix. Alias: modelId. An unknown ID returns an empty list.

Example: my-workspace/chess-pieces-fmhpz-4-rfdetr-small-t1
statusstring · enumOptional

Return only evaluations with this status.

Example: donePossible values:
limitinteger · min: 1 · max: 200Optional

Page size. Values above 200 are lowered to 200.

Default: 50
Responses
200

Successful response.

application/json
get/{workspace}/model-evals
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 model evaluations

get

Compare models on one Dataset Version. The operation includes models that have no evaluation. It is read-only and does not start evaluations.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Query parameters
projectstring · min: 1Required

Project URL slug.

Example: chess-pieces
versionstringRequired

Positive Dataset Version number.

Example: 131Pattern: ^[1-9][0-9]*$
frontierMetricstring · enumOptional

Metric used to calculate the Pareto frontier. The response lists supported choices in availableMetrics.

Example: mAP5095Possible values:
Responses
200

Successful response.

application/json
projectstringRequired

Project URL slug.

versionstringRequired

Dataset Version number.

frontierMetricundefined · enumRequired

Metric used to calculate onFrontier. Null when the Project type has no supported default metric.

Possible values:
get/{workspace}/model-evals/compare
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"
    }
  ]
}

Get a model evaluation

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

evaluationIdstringRequired

Model evaluation ID.

Example: huUF720inUcymARwqAGK
Responses
200

Successful response.

application/json
evalIdstringOptional

Model evaluation ID.

projectstring · nullableOptional

Project URL slug. null if the project was deleted.

versionIdstring · nullableOptional

Dataset version number.

modelIdstring · nullableOptional

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.

statusstring · enumOptional

pending while the model compiles for inference, running once the evaluation job starts, then done or failed.

Possible values:
createdAtstring · nullableOptional
get/{workspace}/model-evals/{evaluationId}
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
  }
}

Get mAP results

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

evaluationIdstringRequired

Model evaluation ID.

Example: huUF720inUcymARwqAGK
Responses
200

Successful response.

application/json
evalIdstringOptional

Model evaluation ID.

projectstring · nullableOptional

Project URL slug. null if the project was deleted.

versionIdstring · nullableOptional

Dataset version number.

modelIdstring · nullableOptional

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.

taskTypestring · enumOptional

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.

Possible values:
get/{workspace}/model-evals/{evaluationId}/map-results
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
          }
        }
      }
    }
  }
}

Get a confidence sweep

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

evaluationIdstringRequired

Model evaluation ID.

Example: huUF720inUcymARwqAGK
Responses
200

Successful response.

application/json
evalIdstringOptional

Model evaluation ID.

projectstring · nullableOptional

Project URL slug. null if the project was deleted.

versionIdstring · nullableOptional

Dataset version number.

modelIdstring · nullableOptional

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.

get/{workspace}/model-evals/{evaluationId}/confidence-sweep
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
          }
        }
      }
    }
  }
}

Get performance by class

get

Returns metrics for each class on one split. Requires model-eval:read.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

evaluationIdstringRequired

Model evaluation ID.

Example: huUF720inUcymARwqAGK
Query parameters
splitstring · enumOptional

Split to report. all is not accepted, because per-class metrics use a per-split threshold.

Default: testPossible values:
Responses
200

Successful response.

application/json
evalIdstringOptional

Model evaluation ID.

projectstring · nullableOptional

Project URL slug. null if the project was deleted.

versionIdstring · nullableOptional

Dataset version number.

modelIdstring · nullableOptional

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.

taskTypestringOptional

object-detection-like, semantic-segmentation, or action-recognition. Says which fields each class has.

splitstringOptional
iouThresholdnumber · nullableOptional

IoU threshold used, when the evaluation reports one.

get/{workspace}/model-evals/{evaluationId}/performance-by-class
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
    }
  ]
}

Get a confusion matrix

get

Returns the confusion matrix, built from the per-image results at one confidence threshold. Requires model-eval:read.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

evaluationIdstringRequired

Model evaluation ID.

Example: huUF720inUcymARwqAGK
Query parameters
splitstring · enumOptional

Split to count. all adds up every split.

Default: allPossible values:
confidenceinteger · max: 100Optional

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.

Example: 37
Responses
200

Successful response.

application/json
evalIdstringOptional

Model evaluation ID.

projectstring · nullableOptional

Project URL slug. null if the project was deleted.

versionIdstring · nullableOptional

Dataset version number.

modelIdstring · nullableOptional

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.

splitstringOptional

Split the matrix covers. all adds up train, valid, and test.

confidenceThresholdnumber · nullableOptional

Confidence threshold of the report, from 0 to 1.

classesstring[]Optional

Class names, in matrix order. The last entry is usually background.

get/{workspace}/model-evals/{evaluationId}/confusion-matrix
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
    ]
  ]
}

Get vector analysis

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

evaluationIdstringRequired

Model evaluation ID.

Example: huUF720inUcymARwqAGK
Query parameters
confidenceinteger · max: 100Optional

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.

Example: 37
Responses
200

Successful response.

application/json
evalIdstringOptional

Model evaluation ID.

projectstring · nullableOptional

Project URL slug. null if the project was deleted.

versionIdstring · nullableOptional

Dataset version number.

modelIdstring · nullableOptional

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.

confidenceThresholdnumber · nullableOptional

Confidence threshold of the report, from 0 to 1.

get/{workspace}/model-evals/{evaluationId}/vector-analysis
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"
      ]
    }
  ]
}

Get image predictions

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

evaluationIdstringRequired

Model evaluation ID.

Example: huUF720inUcymARwqAGK
Query parameters
splitstring · enumOptional

Split to return.

Default: allPossible values:
confidenceinteger · max: 100Optional

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.

Example: 37
imageNamestring · min: 1 · max: 1024Optional

Return only the records for this image name.

Example: abc.jpg
evalInputIdstring · min: 1 · max: 256Optional

Return only the record for this evaluated input. Use it when one image has several inputs (ex: tiles or crops).

includeGeometrybooleanOptional

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.

Default: false
limitinteger · min: 1 · max: 1000Optional

Page size. Values above 1000 are lowered to 1000.

Default: 200
offsetintegerOptional

Records to skip before the page starts.

Default: 0
Responses
200

Successful response.

application/json
evalIdstringOptional

Model evaluation ID.

projectstring · nullableOptional

Project URL slug. null if the project was deleted.

versionIdstring · nullableOptional

Dataset version number.

modelIdstring · nullableOptional

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.

splitstringOptional
confidenceThresholdnumber · nullableOptional

Confidence threshold of the report, from 0 to 1.

totalImagesintegerOptional

Records that match the filters, before paging.

offsetintegerOptional
limitintegerOptional
get/{workspace}/model-evals/{evaluationId}/image-predictions
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
        ]
      ]
    }
  ]
}

Get evaluation recommendations

get

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

evaluationIdstringRequired

Model evaluation ID.

Example: huUF720inUcymARwqAGK
Responses
200

Successful response.

application/json
evalIdstringOptional

Model evaluation ID.

projectstring · nullableOptional

Project URL slug. null if the project was deleted.

versionIdstring · nullableOptional

Dataset version number.

modelIdstring · nullableOptional

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.

generatedbooleanOptional

False when the evaluation has no recommendations yet. The other fields are then left out.

generatedAtstring · nullableOptional

When the recommendations were generated.

get/{workspace}/model-evals/{evaluationId}/recommendations
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
        }
      }
    ]
  }
}

결제

Get a billing usage report

post

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.

Authorizations
AuthorizationstringRequired

Roboflow API key or OAuth access token.

Path parameters
workspacestringRequired

Workspace URL slug.

Body
startAtstring · date-timeOptional

Start of the period, inclusive (ISO 8601). Defaults to 7 days ago.

Example: 2025-01-01T00:00:00.000Z
endAtstring · date-timeOptional

End of the period, exclusive (ISO 8601). Defaults to now.

Example: 2025-02-01T00:00:00.000Z
api_key_prefixesone ofOptional

Only usage billed to these API key prefixes: the first 5 characters of each key (ex: rf_ab for rf_abCdEfGhIjK). Exact match.

Example: ["rf_ab","rf_de"]
stringOptional
or
string[]Optional
featuresone ofOptional

Only these billing features (ex: train, serverless-inference-run).

Example: ["train","serverless-inference-run"]
stringOptional
or
string[]Optional
Responses
200

Successful response.

application/json

One row per API key prefix and feature, sorted by feature, then prefix.

api_key_prefixstringOptional

First 5 characters of the API key the usage was billed to.

featurestringOptional

Billing feature (ex: train, serverless-inference-run).

total_credits_usednumberOptional

Credits used.

usage_eventsintegerOptional

Individual usage events.

earliest_usagestring · date-timeOptional

First usage event in the period.

latest_usagestring · date-timeOptional

Last usage event in the period.

billing_entity_idstringOptional

ID of the folder or workspace the usage is attributed to.

billing_entity_namestringOptional

Name of that folder or workspace.

billing_entity_typestring · enumOptional

folder when the API key belongs to a billing folder, otherwise workspace.

Possible values:
post/{workspace}/billing-usage-report
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"
  }
]

마지막 업데이트

도움이 되었나요?