---
title: "Search media library"
method: GET
path: "/api/businesses/{business_id}/library/search"
tags: ["library"]
---

# Search media library

`GET /api/businesses/{business_id}/library/search`

## Request

- Base URL: `https://api.mymarky.ai`
- URL: `https://api.mymarky.ai/api/businesses/{business_id}/library/search`
- Auth: HTTP bearer

Search a business's MEDIA library by meaning, returning the best matches first.

This is a semantic (vector) search over each image's alt-text, so it finds
relevant images even when the query words don't appear literally. Use it to
pick media for a post; for a plain reverse-chronological list use `list_library`.

By default it returns the business's own, unused, full-size photos: it hides
photos posted recently, AI-generated images, and images under 600px on the
long side. If nothing passes those filters it returns the best matches
without the recency and size filters, and each item's `last_used_at` shows
it was posted before. `unused_count` says how many unused photos the whole
library holds.

Results are a single ranked page (most relevant first), so `next` is always
null — raise `limit` to get more.

Errors:
    400 invalid_value: The business_id is not a valid UUID.
    401 authentication_required: API key or token is missing, invalid, or revoked.
    403 permission_denied: Your plan does not include API access, or this business is not in your org.
    404 resource_not_found: No business with that ID exists.
    429 rate_limit_exceeded: You sent too many requests this minute.

## Path parameters

- `business_id` string, required: A UUID identifier.

## Query parameters

- `query` string, required: What to look for, in plain words (e.g. 'sunset beach', 'team photo').
- `limit` integer: Max results (1-50)
- `include_recently_used` boolean: Also return photos posted recently. Leave false unless the user asked to reuse a photo.
- `include_generated` boolean: Also return AI-generated images and rendered designs. Leave false when you want the business's own photos.

## Headers

- `Marky-Version` '2026-04-08' | '2026-07-17' | '2026-08-02' | '2026-08-04' | '2026-08-06'

## Response `200`

Successful Response

- MediaSearchPage: The search results plus how many unused photos the library holds. Keeps the standard Page shape (`items` + `next`) and only ADDS `unused_count`, the same way QueuedPostsPage adds `summary`.
  - `items` MediaSearchHit[], required: This page of results.
    - `id` string, required: Media ID
    - `business_id` string, required: Business this media belongs to
    - `alt_text` string, nullable: Alt text description
    - `original_url` string, nullable: Media URL
    - `type` string, nullable: Media type: image, video, or audio
    - `width` integer, nullable: Width in pixels
    - `height` integer, nullable: Height in pixels
    - `source` string, nullable: Media origin (e.g. upload, unsplash)
    - `created_at` string, required: When the media was uploaded
    - `last_used_at` string, nullable: When this media was last put on a post of this business (deleted posts don't count). Null means it has never been posted.
    - `low_res` boolean: True when the longest side is under 1080px, so it may look soft on Instagram or Facebook. False when the size is unknown.
  - `next` string, nullable: Opaque cursor for the next page; null when there are no more. Pass it back verbatim as ?cursor=. Do not construct or decode it.
  - `unused_count` integer, required: How many photos in the whole library the default search would offer: not posted recently, not AI-generated, and at least 600px on the long side. 0 means every usable photo was posted recently, so the results are repeats (check each item's last_used_at).

## Other responses

- `400`: Bad request — the input was malformed or otherwise invalid.
- `401`: Authentication failed — the API key is missing or invalid.
- `403`: Forbidden — the key is valid but may not access this resource.
- `404`: Not found — no resource matches the id in the path.
- `422`: Validation error — one or more fields failed validation.
- `429`: Rate limited — retry after the window resets (see Retry-After).
- `500`: Server error — something failed on our side; retry or quote X-Request-Id.

---

[API](https://skmtc.dev/mymarky/apis/marky-public-api.md) · [All operations](https://skmtc.dev/mymarky/apis/marky-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mymarky/apis/marky-public-api/revisions/25aeacae455c?raw)