roasOS
API referenceDiscover

Search the ad library

Search ad creatives we have already indexed. Fast, cached, and read-only.

GET
/v1/discover/items

Search ad creatives we have already indexed. Fast, cached, and read-only.

Authorization

bearerAuth
AuthorizationBearer <token>

API key authentication. Use your API key as the bearer token: Authorization: Bearer roasos_sk_...

In: header

Query Parameters

view?string
Default"feed"

Value in

  • "feed"
  • "following"
  • "saved"
sources?array<>
Itemsitems <= 3
brand_ids?array<>
Itemsitems <= 100
media_types?array<>
Itemsitems <= 3
since?string
Formatdate-time
query?string
Lengthlength <= 500
sort?string
Default"newest"

Value in

  • "newest"
  • "oldest"
cursor?string

Opaque composite pagination cursor from the previous response. Do not parse or construct it.

limit?integer

Number of items to return

Range1 <= value <= 100
Default20

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/discover/items"
{  "data": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "source": "meta_ad",      "brand": {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "slug": "string",        "name": "string",        "handle": "string",        "avatar_url": "http://example.com"      },      "media": {        "aspect_ratio": 1,        "slides": [          {            "type": "image",            "thumbnail_url": "http://example.com",            "video_url": "http://example.com"          }        ]      },      "copy": "string",      "title": "string",      "description": "string",      "domain": "string",      "cta": "string",      "run_start_date": "string",      "run_end_date": "string",      "is_active_ad": true,      "post_date": "2019-08-24T14:15:22Z",      "engagement": {        "likes": 0,        "comments": 0,        "views": 0      },      "platform_link": "http://example.com",      "content_at": "2019-08-24T14:15:22Z",      "media_type": "image",      "vertical": "string",      "creative_type": "string",      "tags": [        "string"      ],      "ai_summary": "string",      "language": "string"    }  ],  "meta": {    "cursor": "string",    "has_more": true  }}

Refresh the intelligence documents

Recompile every document now from what this workspace already stores. The compiler runs no model, so a refresh is free, deterministic and repeatable: identical inputs write no new version, and `changed` says which documents actually moved. Free, and there is no quote. There is no schedule in this version — you refresh when you want it refreshed.

Get one ad

Get one cached ad creative by its ID.