# 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 for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/cosmos/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## 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/credits/cosmos/search-category-images \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/cosmos/search-collections \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/cosmos/search-elements \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"color":"<string>","content_type":"<string>","order":"<string>","page_cursor":"<string>","query":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://paywithlocus.com/agent/index.md): every Locus agent page.