> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/developer/rest-api/universe-api.md).

# Universe API

[`Roboflow Universe`](https://universe.roboflow.com/) provides the following endpoints:

* [Search public datasets](#search-universe-datasets)

### Search Universe datasets

## GET /universe/search

> Search publicly available datasets on Roboflow Universe. Supports inline filter syntax in the query string (e.g. \`images>100\`, \`dog+stars>=5\`, \`class:cat\`, \`model:yolov8\`, \`object detection\`).

```json
{"openapi":"3.0.3","info":{"title":"Roboflow Universe API","version":"1.0.0"},"servers":[{"url":"https://api.roboflow.com"}],"security":[{"ApiKeyQuery":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyQuery":{"type":"apiKey","in":"query","name":"api_key"},"BearerAuth":{"type":"http","scheme":"bearer"}}},"paths":{"/universe/search":{"get":{"description":"Search publicly available datasets on Roboflow Universe. Supports inline filter syntax in the query string (e.g. `images>100`, `dog+stars>=5`, `class:cat`, `model:yolov8`, `object detection`).","parameters":[{"schema":{"type":"string"},"name":"q","in":"query","required":true},{"schema":{"type":"integer"},"name":"page","in":"query"}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"429":{"description":"Too Many Requests"},"502":{"description":"Bad Gateway"}}}}}}
```

#### Search by image

To rank datasets by visual similarity, send a `POST` to the same `/universe/search` path with a JSON body containing a base64-encoded query image. The `image` field is required, and you can pass an optional `q` text query to refine the results and a `page` number.

```bash
curl -X POST "https://api.roboflow.com/universe/search?api_key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "image": "<base64-encoded image>", "q": "class:person", "page": 1 }'
```

The `image` value accepts a bare base64 string or a data URL (ex: `data:image/png;base64,...`). It must be at most 4MB of base64 and 67 megapixels.

Responses include a `query_type` field describing how the search ran: `text`, `image`, or `image+text`. For an image-only search, `query` is `null`.

#### Thumbnail fields

Each result in the response includes two thumbnail fields:

| Field                 | Type             | Description                                                                                   |
| --------------------- | ---------------- | --------------------------------------------------------------------------------------------- |
| `thumbnail`           | `string \| null` | URL to the project's thumbnail image. `null` when the project has no icon set.                |
| `annotationThumbnail` | `string \| null` | URL to a sample annotated image from the project. `null` when annotation data is unavailable. |

Example result snippet:

```json
{
  "name": "Cars",
  "url": "https://universe.roboflow.com/growth-plan/cars-8q9vz",
  "thumbnail": "https://source.roboflow.com/.../thumb.jpg",
  "annotationThumbnail": "https://source.roboflow.com/.../annotation-cars.png"
}
```