Cosmos APIcosmos.so ↗
Search the Cosmos curated visual database via 3 endpoints. Filter elements by type, color, and keyword. Browse collections with follower and element counts.
What is the Cosmos API?
The Cosmos.so API exposes 3 endpoints for querying a curated database of visual content including images, videos, links, notes, and products. search_elements returns up to 40 results per page with media URLs, captions, source attribution, and owner details. search_collections surfaces curated groups with follower counts and cover images. search_category_images lets you browse named category feeds with extracted caption tags.
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 — bounded, re-runnable; every call capped."""
from parse_apis.Cosmos_Image_Search_API import Cosmos, Category, ContentType, ElementOrder, CollectionSort, ParseError
cosmos = Cosmos()
# Browse fashion category images
for img in cosmos.category_images.search(category=Category.FASHION, limit=3):
print(img.image_url, img.caption, img.tags)
# Filter architecture category by keyword
item = cosmos.category_images.search(category=Category.ARCHITECTURE, keyword="bridge", limit=1).first()
if item:
print(item.author, item.source_url, item.share_url)
# Search elements with content type filter
for element in cosmos.elements.search(query="minimalist design", content_type=ContentType.IMAGE, order=ElementOrder.POPULAR, limit=3):
print(element.id, element.caption, element.share_url)
# Search collections
try:
for coll in cosmos.collections.search(query="typography", sort=CollectionSort.LARGEST, limit=3):
print(coll.name, coll.number_of_elements, coll.followers_count)
except ParseError as e:
print(f"error: {e.code}")
print("exercised: category_images.search, elements.search, collections.search")
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 Covers
The Cosmos.so API gives programmatic access to a curated database of visual and multimedia elements organized into elements and collections. The three endpoints — search_elements, search_collections, and search_category_images — cover full-text search and category browsing. Each element returned by search_elements includes an id, type (image, video, link, note, or product), created_at timestamp, share_url, caption, source attribution, media URLs, and owner identity fields.
Filtering and Sorting
search_elements accepts a color parameter (hex code without the # prefix, e.g. FF0000) to narrow results by dominant color, a content_type filter to restrict to a single media type, and an order parameter for sort direction. Pagination is cursor-based: pass the next_page_cursor value from one response as page_cursor in the next request. search_collections supports a sort parameter with POPULAR (by followers descending), LARGEST (by element count descending), and a NEW option, plus a configurable page_size between 1 and 100.
Collections and Category Feeds
search_collections returns collection objects with name, slug, cover image, owner details, number_of_elements, and followers_count. search_category_images takes a category slug and an optional keyword string for caption-level filtering. Each result from that endpoint includes image_url, caption, a tags array of named entities extracted from the caption, author username, source_url, and share_url. The total_count field is present across all three endpoints, giving the full result set size before pagination.
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 visual mood-board tool by querying
search_elementsfor a theme keyword and displaying returnedmediaURLs withcaptiontext. - Identify trending visual topics by sorting
search_collectionsbyPOPULARand surfacing collections with the highestfollowers_count. - Create a color-palette-driven image browser using the
colorhex filter insearch_elementsto match brand guidelines. - Aggregate source attribution data by extracting the
sourcefield from element results for content provenance tracking. - Enumerate the content of a specific design category by paginating through
search_category_imageswith acategoryslug and scanning returnedtagsarrays. - Filter a category feed to a specific concept by passing a
keywordtosearch_category_imagesfor caption-level text matching. - Rank collections by size for a visual reference library by sorting
search_collectionswithLARGESTand readingnumber_of_elements.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. 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 `search_elements` return beyond the image URL?+
id, type, created_at, share_url, owner identity fields, caption, source attribution, and media URLs. Type-specific fields may also be present depending on whether the element is an image, video, link, note, or product.Can I retrieve the individual elements inside a collection by collection ID?+
name, slug, cover, owner, number_of_elements, and followers_count — but does not expose an endpoint to list the elements contained within a specific collection. You can fork this API on Parse and revise it to add that endpoint.How does pagination work across the three endpoints?+
search_elements and search_category_images both return a next_page_cursor string in each response. Pass that value as page_cursor in the next request to get the following page. A null value for next_page_cursor indicates no further pages. search_collections follows the same pattern and additionally accepts a page_size parameter (1–100) to control how many results are returned per call.Does the API expose user profile data or a user's personal boards?+
owner identity fields attached to elements and collections, but there is no dedicated endpoint for querying a specific user's profile or retrieving all boards belonging to a given account. You can fork this API on Parse and revise it to add a user-profile or user-collections endpoint.