Project Deploy API

Get, configure, and manage the deploy state of a Project, including model selection and Active Learning.

The Project Deploy API lets you read and configure a project's deployment state: which model is deployed, whether Active Learning is enabled, and how collected images are filtered and managed.

These endpoints live on the main API host at https://api.roboflow.com. All requests require an api_key passed as a query parameter or in the request body.

Get Project Deploy State

GET /:workspace/:project/deploy

Returns the project's deployment configuration, including the selected model, deployability status, workflow, and Active Learning state.

Required scope: project:read

curl "https://api.roboflow.com/my-workspace/my-project/deploy?api_key=$ROBOFLOW_API_KEY"

Response

{
  "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": {
    "kind": "pretrained",
    "modelId": "rfdetr-medium"
  },
  "deployability": {
    "status": "deployable",
    "reason": null,
    "modelWasConfigured": false,
    "selectedModelId": "rfdetr-medium",
    "selectionReason": null
  },
  "activeLearning": {
    "enabled": false,
    "collectionLimits": {},
    "filters": []
  },
  "baseWorkflowWasCreated": false
}

model is null when no model has been configured. deployability.status is "not_deployable" when the workflow cannot serve inference (for example, when no model is set and none can be auto-selected).

Update Deployed Model

POST /:workspace/:project/deploy/model

Set or change the model used by the project's deployment workflow.

Required scope: project:update

Body (JSON)

The model field accepts three shapes:

By model ID:

{
  "api_key": "YOUR_API_KEY",
  "model": {
    "type": "model_id",
    "modelId": "rfdetr-medium"
  }
}

SAM3 template (zero-shot segmentation):

{
  "api_key": "YOUR_API_KEY",
  "model": {
    "type": "sam3",
    "classes": ["cat", "dog"]
  }
}

CLIP template (zero-shot classification):

{
  "api_key": "YOUR_API_KEY",
  "model": {
    "type": "clip",
    "classes": ["cat", "dog"]
  }
}

curl -X POST "https://api.roboflow.com/my-workspace/my-project/deploy/model" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "'$ROBOFLOW_API_KEY'",
    "model": { "type": "model_id", "modelId": "rfdetr-medium" }
  }'

Response: Same shape as Get Project Deploy State, reflecting the updated model and deployability status.

Returns 400 if the model field is missing or does not match one of the accepted shapes.

Get Active Learning Configuration

GET /:workspace/:project/deploy/active-learning

Returns the project's Active Learning state: whether it is enabled, collection limits, and filters.

Required scope: project:read

curl "https://api.roboflow.com/my-workspace/my-project/deploy/active-learning?api_key=$ROBOFLOW_API_KEY"

Response

{
  "project": { ... },
  "workflow": { ... },
  "model": { ... },
  "deployability": { ... },
  "activeLearning": {
    "enabled": false,
    "collectionLimits": {},
    "filters": []
  }
}

Same shape as Get Project Deploy State except the baseWorkflowWasCreated field is omitted.

Enable Active Learning

POST /:workspace/:project/deploy/active-learning/enable

Enables Active Learning on the project. If no model is configured, the service attempts to auto-select one. Returns 400 if the workflow is not deployable (for example, no model can be selected).

Required scope: project:update

curl -X POST "https://api.roboflow.com/my-workspace/my-project/deploy/active-learning/enable" \
  -H "Content-Type: application/json" \
  -d '{ "api_key": "'$ROBOFLOW_API_KEY'" }'

Response: Same shape as Get Active Learning Configuration, with activeLearning.enabled set to true.

Disable Active Learning

POST /:workspace/:project/deploy/active-learning/disable

Disables Active Learning on the project.

Required scope: project:update

curl -X POST "https://api.roboflow.com/my-workspace/my-project/deploy/active-learning/disable" \
  -H "Content-Type: application/json" \
  -d '{ "api_key": "'$ROBOFLOW_API_KEY'" }'

Response: Same shape as Get Active Learning Configuration, with activeLearning.enabled set to false.

Update Active Learning Configuration

POST /:workspace/:project/deploy/active-learning/configuration

Updates collection limits and, optionally, filters for Active Learning.

Required scope: project:update

Body (JSON)

Name	Type	Description	Required
api_key	string	Workspace API key.
collectionLimits	object	Collection limits configuration (see below).
filters	array	Array of filter objects. Omit to leave existing filters unchanged.

Collection limits fields:

Required

Name	Type	Description	Required
dataPercentage	number	Percentage of inferences to collect (0-100).
minutelyUsageLimit	integer	Max images collected per minute (0 for unlimited).
hourlyUsageLimit	integer	Max images collected per hour.
dailyUsageLimit	integer	Max images collected per day.
labelingBatchesRecreationFrequency	string	How often new review batches are created: "never", "daily", "weekly", or "monthly".
usageQuotaName	string	Quota identifier (non-empty string).
imageCompressionLevel	integer	JPEG quality (1-100).
maxImageHeight	integer	Resize collected images to this max height.
maxImageWidth	integer	Resize collected images to this max width.
registrationTags	array	Tags to attach to collected images.
persistPredictions	boolean	Whether to store model predictions alongside collected images.

Filter types:

Each filter object has a type field. Two filter types are supported:

Class confidence filter - collects images where predictions for specific classes fall within a confidence range:

{
  "type": "classConfidence",
  "classFilterMode": "any",
  "classes": ["cat"],
  "confidenceLowerBound": 0.2,
  "confidenceUpperBound": 0.8
}

classFilterMode can be "any" (any class matches), "in" (only listed classes), or "out" (all classes except listed).

Detection size filter - collects images where detection bounding boxes fall within a size range:

{
  "type": "detectionSize",
  "sizeLowerPercentage": 5,
  "sizeUpperPercentage": 50
}

Example request:

curl -X POST "https://api.roboflow.com/my-workspace/my-project/deploy/active-learning/configuration" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "'$ROBOFLOW_API_KEY'",
    "collectionLimits": {
      "dataPercentage": 50,
      "minutelyUsageLimit": 10,
      "hourlyUsageLimit": 100,
      "dailyUsageLimit": 1000,
      "labelingBatchesRecreationFrequency": "daily",
      "usageQuotaName": "default"
    },
    "filters": [
      {
        "type": "classConfidence",
        "classFilterMode": "any",
        "classes": ["cat"],
        "confidenceLowerBound": 0.2,
        "confidenceUpperBound": 0.8
      }
    ]
  }'

Response: Same shape as Get Active Learning Configuration.

Returns 400 with validation details if collectionLimits or filters are malformed.

List Active Learning Images

GET /:workspace/:project/deploy/active-learning/images

Lists images in the Active Learning review queue with pagination, filtering, and sorting.

Required scope: project:read

Query parameters

Required

Name	Type	Description	Required
api_key	string	Workspace API key.
page	integer	Page number (default: 1).
pageSize	integer	Items per page.
search	string	Free text search.
reviewer	string	Filter by reviewer email, or "unassigned".
status	string	"all", "not_started", or "in_progress".
sortBy	string	"created", "images", or "progress".
sortDirection	string	"asc" or "desc".

curl "https://api.roboflow.com/my-workspace/my-project/deploy/active-learning/images?api_key=$ROBOFLOW_API_KEY&page=1&pageSize=20"

Response

{
  "activeLearningImages": {
    "totalImagesReadyForReview": 42,
    "reviewQueuePage": {
      "page": 1,
      "pageSize": 20,
      "totalItems": 42,
      "totalPages": 3,
      "items": [
        { "type": "batch", "id": "active_learning_2026-06-18" }
      ],
      "search": "",
      "status": "all",
      "sortBy": "created",
      "sortDirection": "desc",
      "reviewer": ""
    }
  }
}

Legacy Endpoints

The previous Active Learning endpoints at /:workspace/:project/active_learning (GET and POST) are deprecated. They now return Deprecation: true and Link headers pointing to the new deploy/active-learning namespace. Migrate to the endpoints documented above.