Cosmos APIcosmos.so ↗
Search the Cosmos curated database via API. Find images, videos, links, notes, and products by keyword, color, or content type. Browse collections with pagination.
What is the Cosmos API?
The Cosmos.so API provides 2 endpoints for searching a curated database of visual and multimedia elements. search_elements returns up to 40 results per page across images, videos, links, notes, and products — each with media URLs, captions, source attribution, and owner details. search_collections retrieves curated groups of elements with follower counts, element counts, and cover images, supporting page sizes up to 100.
curl -X POST 'https://api.parse.bot/scraper/518f0113-a227-49a8-95cf-31124444fa1e/search_elements' \
-H 'X-API-Key: $PARSE_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"order": "RELEVANT",
"query": "architecture",
"content_type": "IMAGE"
}'Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace cosmos-so-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""
Cosmos Image Search API - Parse SDK Example
Search for curated visual content and collections on Cosmos.
"""
from parse_apis.cosmos_image_search_api import Cosmos, ContentType, ElementOrder, CollectionSort
cosmos = Cosmos()
# Search for architecture images sorted by popularity
for element in cosmos.elements.search(query="architecture", content_type=ContentType.IMAGE, order=ElementOrder.POPULAR, limit=5):
print(element.id, element.caption, element.share_url)
# Search for collections about typography sorted by size
for collection in cosmos.collections.search(query="typography", sort=CollectionSort.LARGEST, limit=3):
print(collection.name, collection.number_of_elements, collection.followers_count)
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.
| Param | Type | Description |
|---|---|---|
| color | string | Filter results by color (hex color code without # prefix, e.g. 'FF0000' for red). Omitted returns all colors. |
| order | string | Sort order for results. Omitted defaults to relevance sorting. |
| queryrequired | string | Search term to find elements (e.g. 'architecture', 'nature', 'minimalist design'). |
| page_cursor | string | Pagination cursor from a previous response's next_page_cursor field. Omitted returns the first page. |
| content_type | string | Filter by content type. Omitted returns all content types. |
{
"type": "object",
"fields": {
"items": "array of element objects with id, type, created_at, share_url, owner, caption, source, media, and type-specific fields",
"total_count": "integer total number of matching results",
"next_page_cursor": "string cursor for fetching the next page, null if no more pages"
},
"sample": {
"data": {
"items": [
{
"id": 2019059012,
"type": "MediaElementTile",
"media": {
"url": "https://cdn.cosmos.so/c39f5bbd-3155-44f8-aadf-2ce88422d7c3",
"width": 1200,
"height": 1600,
"mediaId": "c39f5bbd-3155-44f8-aadf-2ce88422d7c3",
"blurHash": "00PjAI",
"__typename": "StaticImage",
"aiGenerated": false,
"notSafeForWorkStatus": "SAFE"
},
"owner": {
"username": "papillon",
"__typename": "UserPublicProfile",
"verifiedProfile": null,
"isVerifiedProfile": false
},
"source": {
"url": "https://baukobox.de/projekte/366",
"author": null,
"__typename": "ElementSource",
"isEditable": false,
"isPublicDomain": false
},
"caption": "The facade of the Bestseller Office Complex in Aarhus.",
"share_url": "https://www.cosmos.so/e/2019059012",
"created_at": "2024-09-27T16:02:40.934003Z",
"is_featured": false,
"multiple_media": []
}
],
"total_count": 500,
"next_page_cursor": "cursor://api_gateway/element_search?query=architecture&last=39&count=500"
},
"status": "success"
}
}About the Cosmos API
What the API Returns
The search_elements endpoint accepts a required query string and matches it against captions and metadata across all Cosmos element types. Each result object includes an id, type, created_at timestamp, share_url, owner details, caption, source attribution, and media URLs. Optional parameters let you narrow results: content_type filters to a specific element kind (image, video, link, note, or product), color accepts a hex code without the # prefix (e.g. FF0000) to filter by dominant color, and order controls sort direction. Pagination is cursor-based — the response includes a next_page_cursor string that you pass as page_cursor on the next request, or null when there are no further pages. The total_count field tells you how many total records matched.
Searching Collections
The search_collections endpoint searches Cosmos's curated collections — thematic groupings of elements maintained by users. Results include id, name, slug, cover image, owner, number_of_elements, and followers_count. You can control page size with page_size (1–100) and sort results using the sort parameter: POPULAR orders by followers descending, LARGEST orders by element count descending, and omitting sort defaults to relevance. Pagination works the same way as elements — pass next_page_cursor back as page_cursor on subsequent calls.
Coverage and Scope
Both endpoints cover publicly accessible Cosmos content. Element searches return type-specific fields alongside the common fields, so a product result may carry different metadata than an image result. Color filtering on search_elements is specific to visually dominant color and only applies when a hex value is provided; omitting the parameter returns results across all colors.
The Cosmos API is a managed, monitored endpoint for cosmos.so — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when cosmos.so changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official cosmos.so API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a mood board tool that queries
search_elementsby keyword andcolorhex to surface visually matching images. - Aggregate curated design collections by sorting
search_collectionsresults byPOPULARto surface trending topics. - Create a design research feed that paginates through
search_elementsresults for a niche query like 'brutalist typography'. - Power an internal asset discovery tool that filters
search_elementsbycontent_typeto return only videos or products. - Index Cosmos collections for a creative directory by extracting
name,slug,number_of_elements, andfollowers_count. - Identify top contributors by extracting
ownerdetails from high-follower collections returned bysearch_collections.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Cosmos.so have an official developer API?+
What does the `search_elements` endpoint return for each result?+
id, type, created_at, share_url, owner (with user details), caption, source (attribution metadata), and media (URLs for the associated file or embed). Type-specific fields may also be present depending on whether the element is an image, video, link, note, or product.How does pagination work across both endpoints?+
next_page_cursor string. Pass that value as page_cursor in your next request to retrieve the following page. When next_page_cursor is null, you have reached the last page. The total_count field in each response reports the full number of matching results.Can I retrieve the individual elements inside a specific collection?+
search_collections endpoint returns collection metadata — cover image, owner, element count, and follower count — but does not return the list of elements contained within a collection. You can fork this API on Parse and revise it to add an endpoint that fetches a collection's element contents by collection ID or slug.Is color filtering available when searching collections?+
color parameter is only available on search_elements, not on search_collections. Collection searches support keyword queries and sorting by popularity or size. You can fork this API on Parse and revise it to add color-based filtering to the collections search if that capability becomes relevant to your use case.