# Using the REST API

The Roboflow REST API is the authoritative interface to the platform - every feature ships here first, and the [Python SDK](/developer/python-sdk/using-the-python-sdk.md) and [CLI](/developer/command-line-interface/using-the-cli.md) both call it under the hood. Use the REST API directly when you're building a non-Python integration, calling from a webhook or browser, or working in an environment that can't install Python packages.

There are two base hosts to know about:

| Host                              | Used for                                                                                                                                                         |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `https://api.roboflow.com`        | Management - workspaces, projects, versions, training, workflows, datasets, vision events, trash.                                                                |
| `https://serverless.roboflow.com` | Hosted inference - running a trained model or workflow against an image or video. See [Run a Model on an Image](/developer/rest-api/run-a-model-on-an-image.md). |

[Dedicated Deployments](/developer/rest-api/dedicated-deployments.md) are managed at a third host (`https://roboflow.cloud`).

## Resource hierarchy

The Roboflow data model is hierarchical and the API URLs follow the hierarchy:

* `/:workspace` - list projects in a workspace, plus workspace metadata.
* `/:workspace/:project` - a project's metadata and version list.
* `/:workspace/:project/:version` - a specific dataset version, its model (if trained), and download URLs.
* `/:workspace/:project/:version/:format` - download a dataset in a specific [export format](https://roboflow.com/formats).
* `/:workspace/workflows/:workflow` - see [Manage Workflows](/developer/rest-api/manage-workflows.md).
* `/:workspace/groups` - project folders. See [Manage Project Folders](/developer/rest-api/manage-project-folders.md).
* `/:workspace/trash` - soft-deleted projects, versions, and workflows. See [Manage Trash](/developer/rest-api/manage-trash.md).

## Root endpoint

At the top level (`https://api.roboflow.com/`), you can verify your `api_key` is working. The response identifies the workspace your key belongs to:

```bash
curl "https://api.roboflow.com/?api_key=$ROBOFLOW_API_KEY"
```

```json
{
  "welcome": "Welcome to the Roboflow API.",
  "instructions": "You are successfully authenticated.",
  "docs": "https://docs.roboflow.com",
  "workspace": "my-workspace"
}
```

From there, drill into [List Workspaces and Projects](/developer/rest-api/list-workspaces-and-projects.md) to see what's in the workspace.

## Authentication and scopes

API keys are workspace-scoped. Pass the key as a query parameter (`?api_key=...`), in the request body for `POST` calls, or as a `Authorization: Bearer ...` header. See [Authenticate with the REST API](/developer/rest-api/authenticate-with-the-rest-api.md) for details and [Scoped API Keys](/developer/authentication/scoped-api-keys.md) for the per-resource scope reference.

## Errors

The API uses standard HTTP status codes and a JSON error body. See [Errors and Status Codes](/developer/errors-and-status-codes.md) for the cross-tool error reference.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.roboflow.com/developer/rest-api/using-the-rest-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.