Roboflow Api Reference

For agents — source-of-truth: This skill is authored in `roboflow/computer-vision-skills` and shipped with the Roboflow plugin. If your client has loaded the plugin (you'll see roboflow:<name> skills in your available skills list), use those local skills — they're read fresh from disk every session. The same content served as MCP resources at roboflow://skills/<name>/... is a fallback for clients without the plugin and may lag this repo. Don't call `ReadMcpResourceTool` for `roboflow://skills/...` URIs when a local `roboflow:<name>` skill is available.

Tip: If you're connected to the Roboflow MCP server, prefer its tools (projects_*, versions_*, models_*, workflows_*, images_*, …) over raw REST calls — they handle auth, pagination, and typed responses for you. The REST patterns below stay relevant if you're not using MCP.

Roboflow API Reference — Overview

API Hosts

Use the inference-sdk Python package as the preferred client for all inference hosts. It handles auth, retries, and response parsing.

Authentication

API keys are workspace-scoped. Get yours from Workspace Settings > API Keys in the Roboflow dashboard (app.roboflow.com/{workspace}/settings/api). Personal API keys are at /settings/account → API Keys tab.

SDKs

Python inference-sdk Quick Start

from inference_sdk import InferenceHTTPClient

CLIENT = InferenceHTTPClient(
    api_url="https://serverless.roboflow.com",  # or dedicated URL, or localhost
    api_key="YOUR_KEY"
)
result = CLIENT.infer("image.jpg", model_id="your-project/1")

Python roboflow SDK Quick Start

import roboflow

rf = roboflow.Roboflow(api_key="YOUR_KEY")
project = rf.workspace("my-workspace").project("my-project")

# Upload
project.upload(image_path="image.jpg", split="train")

# Inference
model = project.version(1).model
result = model.predict("image.jpg", confidence=40).json()

Host Selection Guide

Rate Limits

• Serverless API: rate limits vary by plan
• File upload max: 20 MB

Related Pages

• roboflow://skills/api-reference/inference — inference URL patterns, request/response formats
• roboflow://skills/api-reference/rest-api — platform REST API endpoints (CRUD, upload, training)

Roboflow Inference API Reference

Source-of-truth note: This page ships with the Roboflow plugin. If your client has the plugin loaded, prefer the local skill (roboflow:api-reference) over fetching roboflow://skills/api-reference/inference via ReadMcpResourceTool — the MCP resources are a fallback for non-plugin clients and may lag the source repo.

Tip: If you're connected to the Roboflow MCP server, prefer models_infer (single-model) or workflow_specs_run / workflows_run (chained pipelines with annotated images) over raw HTTP calls — same operations, but auth is handled and responses are typed. The REST patterns below stay relevant if you're not using MCP.

Serverless Inference (Hosted API v2)

Single endpoint for all model types and Workflows. V2 is credit-billed by execution time (seconds); the older v1 hosted API was billed per inference count — v2 is the current default for all new projects.

POST https://serverless.roboflow.com/{dataset_id}/{version_id}
POST https://serverless.roboflow.com/{workspace_name}/workflows/{workflow_id}

Inference SDK (Recommended Client)

The inference-sdk Python package is the preferred way to call Roboflow models. It handles auth, retries, and response parsing.

pip install inference-sdk

from inference_sdk import InferenceHTTPClient

client = InferenceHTTPClient(
    api_url="https://serverless.roboflow.com",
    api_key="YOUR_KEY"
)
result = client.infer("image.jpg", model_id="my-project/1")

Works with local files, URLs, numpy arrays, and PIL images. Points at serverless by default; change api_url for dedicated deployments or local inference server.

Dedicated Deployments

Same API as serverless, but at your deployment URL:

POST https://<deployment-name>.roboflow.cloud/{projectId}/{versionNumber}

Request Format

Image Input (choose one)

Query Parameters

Visualization

The recommended approach for visualization is Workflows — use workflow_specs_run with a visualization block (Bounding Box, Label, Mask, etc.). This gives you full control over rendering and works reliably across all model types. See roboflow://skills/inference/workflows.

Response Shapes

Object Detection

{
  "predictions": [
    {
      "x": 189.5, "y": 100,
      "width": 163, "height": 186,
      "class": "helmet",
      "class_id": 0,
      "confidence": 0.544,
      "class_confidence": 0.544,
      "detection_id": "uuid"
    }
  ],
  "image": { "width": 2048, "height": 1371 }
}

(x, y) = center of bounding box. Corner points: x1 = x - width/2, y1 = y - height/2.

Classification (Single-Label)

{
  "predictions": [
    { "class": "real-image", "confidence": 0.7149 },
    { "class": "illustration", "confidence": 0.2851 }
  ],
  "top": "real-image",
  "confidence": 0.7149,
  "image": { "width": 210, "height": 113 },
  "prediction_type": "ClassificationModel"
}

Classification (Multi-Label)

{
  "predictions": {
    "dent": { "confidence": 0.5253 },
    "severe": { "confidence": 0.5804 }
  },
  "predicted_classes": ["dent", "severe"],
  "prediction_type": "ClassificationModel"
}

Instance Segmentation

Same as object detection, plus a points array per prediction:

{
  "predictions": [
    {
      "x": 179.2, "y": 247,
      "width": 231, "height": 147,
      "class": "A", "confidence": 0.98,
      "points": [
        { "x": 134, "y": 314 },
        { "x": 116, "y": 313 }
      ]
    }
  ]
}

Keypoint Detection

Same as object detection, plus a keypoints array per prediction:

{
  "predictions": [
    {
      "x": 189.5, "y": 100,
      "width": 163, "height": 186,
      "class": "helmet", "confidence": 0.544,
      "keypoints": [
        { "x": 189, "y": 20, "class": "top", "class_name": "top", "class_id": 0, "confidence": 0.91 },
        { "x": 188, "y": 180, "class": "bottom", "class_name": "bottom", "class_id": 1, "confidence": 0.93 }
      ]
    }
  ],
  "image": { "width": 2048, "height": 1371 }
}

Code Examples

Python (inference-sdk) — Recommended

from inference_sdk import InferenceHTTPClient

client = InferenceHTTPClient(
    api_url="https://serverless.roboflow.com",
    api_key="YOUR_KEY"
)

# Local image
result = client.infer("image.jpg", model_id="my-project/1")

# URL image
result = client.infer("https://example.com/photo.jpg", model_id="my-project/1")

curl — Base64

base64 image.jpg | curl -d @- \
  "https://serverless.roboflow.com/my-project/1?api_key=YOUR_KEY&confidence=50"

curl — Image URL

curl -X POST "https://serverless.roboflow.com/my-project/1?\
api_key=YOUR_KEY&image=https%3A%2F%2Fexample.com%2Fphoto.jpg"

Workflow Inference

curl -X POST "https://serverless.roboflow.com/my-workspace/workflows/my-workflow" \
  -H "Content-Type: application/json" \
  -d '{"api_key": "YOUR_KEY", "inputs": {"image": {"type": "url", "value": "https://example.com/photo.jpg"}}}'

Error Responses

Roboflow Platform REST API Reference

Source-of-truth note: This page ships with the Roboflow plugin. If your client has the plugin loaded, prefer the local skill (roboflow:api-reference) over fetching roboflow://skills/api-reference/rest-api via ReadMcpResourceTool — the MCP resources are a fallback for non-plugin clients and may lag the source repo.

Tip: If you're connected to the Roboflow MCP server, prefer its tools (projects_*, versions_*, images_*, annotations_save, models_train, …) over raw REST calls — they handle auth and typed responses for you. The REST patterns below stay relevant if you're not using MCP.

Base URL: https://api.roboflow.com

All endpoints require ?api_key=YOUR_KEY as a query parameter.

API keys are not available programmatically. Users can find theirs at Workspace Settings > API Keys in the Roboflow dashboard (app.roboflow.com/{workspace}/settings/api).

Projects

Create Project

curl -X POST "https://api.roboflow.com/my-workspace/projects?api_key=KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Project", "type": "object-detection", "annotation": "my-annotation-group"}'

Required body fields: name, type, annotation (annotation group identifier).

Project types: object-detection, single-label-classification, multi-label-classification, instance-segmentation, semantic-segmentation

Image Upload

Upload via Image URL

curl -X POST "https://api.roboflow.com/my-workspace/my-project/upload?\
api_key=KEY&\
name=photo.jpg&\
split=train&\
image=https%3A%2F%2Fexample.com%2Fphoto.jpg"

Upload via File (multipart)

curl -X POST "https://api.roboflow.com/my-workspace/my-project/upload?api_key=KEY" \
  -F "name=image.jpg" \
  -F "split=train" \
  -F "file=@image.jpg" \
  -F 'metadata={"camera_id":"cam001","temperature":72.5}'

Upload Parameters

Upload via Python SDK

import roboflow

rf = roboflow.Roboflow(api_key="KEY")
project = rf.workspace("my-workspace").project("my-project")

project.upload(
    image_path="image.jpg",
    split="train",
    metadata={"camera_id": "cam001", "temperature": 72.5}
)

Image limits: max 20 MB, max 16400x10900 px. Duplicate images are skipped.

Versions

Generate Version

Creates a new version with preprocessing and augmentation applied.

curl -X POST "https://api.roboflow.com/my-workspace/my-project/generate?api_key=KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "preprocessing": { "auto-orient": true, "resize": { "width": 640, "height": 640 } },
    "augmentation": { "flip": { "horizontal": true } }
  }'

Training

Start Training

curl -X POST "https://api.roboflow.com/my-workspace/my-project/1/train?api_key=KEY"

Training status is included in the version GET response (GET /{workspace}/{project}/{version}) under the version.train field. There is no separate training-status endpoint.

Models

The version response includes model performance metrics (map, precision, recall) when a trained model exists.

Workflows

Common Patterns

Full Pipeline: Upload, Version, Train

import roboflow

rf = roboflow.Roboflow(api_key="KEY")
project = rf.workspace("ws").project("proj")

# 1. Upload images
project.upload(image_path="img1.jpg", split="train")

# 2. Generate version
version = project.generate_version(
    preprocessing={"auto-orient": True, "resize": {"width": 640, "height": 640}},
    augmentation={"flip": {"horizontal": True}}
)

# 3. Train
version.train()

CLI Upload (bulk)

pip install roboflow
roboflow import -w my-workspace -p my-project /path/to/images/

Error Responses