# Cosmos — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search a curated database of images, videos, links, notes, and products by content type, color, and sorting preferences, then browse results with pagination to find exactly what you need. Discover and organize collections of related visual content tailored to your search criteria.

**Category:** Other | **Website:** [cosmos.so/](https://cosmos.so/) | **Docs:** [parse.bot/marketplace/891e9419-e056-4b92-a3e2-18e90c09e99d/cosmos-so-api](https://parse.bot/marketplace/891e9419-e056-4b92-a3e2-18e90c09e99d/cosmos-so-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-cosmos-so-api-891e9419/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### search_category_images

Browse curated images within a specific Cosmos category. Returns elements from the category feed with image URL, caption, extracted tags (named entities from captions), author username, and source URL. Optionally filters results by keyword match against captions (client-side). Each page returns up to 40 elements; paginate via the next_page_cursor in each response.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | Yes | Category slug to browse. |
| `keyword` | string | No | Optional keyword to filter results by caption text match (case-insensitive). Omitted returns all category elements. |
| `page_cursor` | string | No | Pagination cursor from a previous response's next_page_cursor field. Omitted returns the first page. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-cosmos-so-api-891e9419/search_category_images \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","keyword":"<string>","page_cursor":"<string>"}'
```

### search_collections

Full-text search over Cosmos collections (curated groups of elements). Returns collections with cover image, owner info, element count, and follower count. Supports cursor-based pagination. Client-side sorting by POPULAR (followers descending), LARGEST (elements descending), or NAME (alphabetical) reorders the current page; RELEVANT keeps the server default.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page_cursor` | string | No | Pagination cursor from a previous response's next_page_cursor field. Omitted returns the first page. |
| `page_size` | integer | No | Number of results per page, between 1 and 100. |
| `query` | string | Yes | Search term to find collections (e.g. 'architecture', 'typography', 'fashion'). |
| `sort` | string | No | Sort order for results. Omitted defaults to relevance sorting. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-cosmos-so-api-891e9419/search_collections \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page_cursor":"<string>","page_size":"<integer>","query":"<string>","sort":"<string>"}'
```

### search_elements

Full-text search over Cosmos elements (images, videos, links, notes, products). Matches query against captions and metadata. Returns up to 40 results per page. Each element includes media URLs, captions, source attribution, and owner details. Paginate via the next_page_cursor returned in each response. Color filtering accepts a hex code; content_type and order restrict or reorder results server-side.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `color` | string | No | Filter results by color (hex color code without # prefix, e.g. 'FF0000' for red). Omitted returns all colors. |
| `content_type` | string | No | Filter by content type. Omitted returns all content types. |
| `order` | string | No | Sort order for results. Omitted defaults to relevance sorting. |
| `page_cursor` | string | No | Pagination cursor from a previous response's next_page_cursor field. Omitted returns the first page. |
| `query` | string | Yes | Search term to find elements (e.g. 'architecture', 'nature', 'minimalist design'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-cosmos-so-api-891e9419/search_elements \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"color":"<string>","content_type":"<string>","order":"<string>","page_cursor":"<string>","query":"<string>"}'
```