{"openapi":"3.1.0","info":{"title":"Unsplash (BYOK) API","version":"0.1.0","description":"Unsplash (BYOK) lets an AI assistant read your own Unsplash data through the Unsplash API with a key you supply (application access key (Client ID)). Read-only: 9 tools (search_photos, search_collections, list_photos, get_photo, get_random_photos, get_user, list_user_photos, list_user_collections, get_photo_statistics). The BYOK key travels with each request, is used for that one call only and is...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-unsplash.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-unsplash/docs"},"termsOfService":"https://connectorbay.com/byok-unsplash/terms"},"servers":[{"url":"https://byok-unsplash.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-unsplash/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/search_photos":{"post":{"operationId":"search_photos","summary":"Search Unsplash photos by keywords, with optional color, orientation and ordering; returns size, color, description, ima","description":"Search Unsplash photos by keywords, with optional color, orientation and ordering; returns size, color, description, image URLs and the photographer. Free demo apps allow 50 calls per hour. Use for \"Find landscape photos of mountains at sunrise on Unsplash\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Search terms, for example 'mountain sunrise'.","maxLength":200,"title":"Query","type":"string"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Results per page (1 to 30).","title":"Per Page"},"order_by":{"anyOf":[{"enum":["relevant","latest"],"type":"string"},{"type":"null"}],"default":"relevant","description":"Order by relevant (default) or latest.","title":"Order By"},"color":{"anyOf":[{"enum":["black_and_white","black","white","yellow","orange","red","purple","magenta","green","teal","blue"],"type":"string"},{"type":"null"}],"default":null,"description":"Only photos of this dominant color.","title":"Color"},"orientation":{"anyOf":[{"enum":["landscape","portrait","squarish"],"type":"string"},{"type":"null"}],"default":null,"description":"Only photos with this orientation.","title":"Orientation"},"content_filter":{"anyOf":[{"enum":["low","high"],"type":"string"},{"type":"null"}],"default":"low","description":"Safe-content level: low (default) or high.","title":"Content Filter"},"collections":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated collection IDs to search within.","title":"Collections"}},"required":["query"],"title":"search_photosArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_collections":{"post":{"operationId":"search_collections","summary":"Search Unsplash collections by keywords; returns title, description, photo count and curator. Use for \"Find Unsplash col","description":"Search Unsplash collections by keywords; returns title, description, photo count and curator. Use for \"Find Unsplash collections about minimalism\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Search terms, for example 'minimal'.","maxLength":200,"title":"Query","type":"string"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Results per page (1 to 30).","title":"Per Page"}},"required":["query"],"title":"search_collectionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_photos":{"post":{"operationId":"list_photos","summary":"List photos from the Unsplash editorial feed, newest first, with size, color, description, image URLs and photographer. ","description":"List photos from the Unsplash editorial feed, newest first, with size, color, description, image URLs and photographer. Use for \"Show the latest Unsplash editorial photos\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Results per page (1 to 30).","title":"Per Page"},"order_by":{"anyOf":[{"enum":["latest","oldest","popular"],"type":"string"},{"type":"null"}],"default":"latest","description":"Order by latest (default), oldest or popular.","title":"Order By"}},"title":"list_photosArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_photo":{"post":{"operationId":"get_photo","summary":"Get one photo by ID with size, color, download count, description, tags, location, camera data, image URLs and the photo","description":"Get one photo by ID with size, color, download count, description, tags, location, camera data, image URLs and the photographer. Use for \"Show details of Unsplash photo Dwu85P9SOIk\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Photo ID, for example 'Dwu85P9SOIk'.","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"get_photoArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_random_photos":{"post":{"operationId":"get_random_photos","summary":"Get one or more random photos, optionally for a search term, topic, collection or photographer. Collections and topics c","description":"Get one or more random photos, optionally for a search term, topic, collection or photographer. Collections and topics cannot be combined with query. Use for \"Give me a random photo of the ocean from Unsplash\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Limit the photos to this search term.","title":"Query"},"collections":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated collection IDs.","title":"Collections"},"topics":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated topic IDs.","title":"Topics"},"username":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only photos of this photographer.","title":"Username"},"orientation":{"anyOf":[{"enum":["landscape","portrait","squarish"],"type":"string"},{"type":"null"}],"default":null,"description":"Only photos with this orientation.","title":"Orientation"},"content_filter":{"anyOf":[{"enum":["low","high"],"type":"string"},{"type":"null"}],"default":"low","description":"Safe-content level: low (default) or high.","title":"Content Filter"},"count":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"How many photos to return (1 to 30); with a count the answer is a list.","title":"Count"}},"title":"get_random_photosArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_user":{"post":{"operationId":"get_user","summary":"Get a photographer's public profile: name, bio, location, photo and collection counts, social handles and profile links.","description":"Get a photographer's public profile: name, bio, location, photo and collection counts, social handles and profile links. Use for \"Show the Unsplash profile of the user 'unsplash'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"username":{"description":"Unsplash username (the part after unsplash.com/@), for example 'unsplash'.","maxLength":200,"title":"Username","type":"string"}},"required":["username"],"title":"get_userArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_user_photos":{"post":{"operationId":"list_user_photos","summary":"List a photographer's photos with ordering and optional orientation. Use for \"Show the latest photos by the Unsplash use","description":"List a photographer's photos with ordering and optional orientation. Use for \"Show the latest photos by the Unsplash user 'unsplash'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"username":{"description":"Unsplash username (the part after unsplash.com/@), for example 'unsplash'.","maxLength":200,"title":"Username","type":"string"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Results per page (1 to 30).","title":"Per Page"},"order_by":{"anyOf":[{"enum":["latest","oldest","popular","views","downloads"],"type":"string"},{"type":"null"}],"default":"latest","description":"Order by latest (default), oldest, popular, views or downloads.","title":"Order By"},"orientation":{"anyOf":[{"enum":["landscape","portrait","squarish"],"type":"string"},{"type":"null"}],"default":null,"description":"Only photos with this orientation.","title":"Orientation"}},"required":["username"],"title":"list_user_photosArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_user_collections":{"post":{"operationId":"list_user_collections","summary":"List the public collections of a photographer with title, description and photo count. Use for \"What collections does th","description":"List the public collections of a photographer with title, description and photo count. Use for \"What collections does the Unsplash user 'unsplash' have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"username":{"description":"Unsplash username (the part after unsplash.com/@), for example 'unsplash'.","maxLength":200,"title":"Username","type":"string"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Results per page (1 to 30).","title":"Per Page"}},"required":["username"],"title":"list_user_collectionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_photo_statistics":{"post":{"operationId":"get_photo_statistics","summary":"Get a photo's download and view totals and history (daily values, last 30 days by default). Use for \"How many views and ","description":"Get a photo's download and view totals and history (daily values, last 30 days by default). Use for \"How many views and downloads did Unsplash photo Dwu85P9SOIk get\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Photo ID.","maxLength":200,"title":"Id","type":"string"},"quantity":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Number of daily data points (1 to 30).","title":"Quantity"}},"required":["id"],"title":"get_photo_statisticsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}