{"openapi":"3.1.0","info":{"title":"Photo Scout","version":"0.1.0"},"paths":{"/v1/status":{"get":{"tags":["Photo Scout"],"summary":"Status","operationId":"status_photo_scout_v1_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/discover":{"post":{"tags":["Photo Scout"],"summary":"Discover","operationId":"discover_photo_scout_v1_discover_post","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExploreRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"402":{"description":"Payment required; use the public gateway payment challenge."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"Paid discovery: $2.00 per call via MPP; MCP uses x402 Base USDC. No private API key is issued to agents. Results include a token-protected report and signed order receipt.","x-payment-info":{"amount":"2.00","currency":"USD","protocols":["mpp","x402-mcp"]}}},"/v1/report/{job_id}":{"get":{"tags":["Photo Scout"],"summary":"Report","operationId":"report_photo_scout_v1_report__job_id__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"x-report-token","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Report-Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"ExploreRequest":{"properties":{"route":{"anyOf":[{"$ref":"#/components/schemas/RouteRequest"},{"type":"null"}]},"searchProgram":{"anyOf":[{"$ref":"#/components/schemas/SearchProgram"},{"type":"null"}]},"searchBranches":{"items":{"$ref":"#/components/schemas/SearchBranch"},"type":"array","maxItems":6,"title":"Searchbranches"},"query":{"type":"string","maxLength":1000,"title":"Query","default":""},"lat":{"type":"number","maximum":85,"minimum":-85,"title":"Lat"},"lon":{"type":"number","maximum":180,"minimum":-180,"title":"Lon"},"radius":{"type":"integer","maximum":20000,"minimum":100,"title":"Radius","default":1000},"limit":{"type":"integer","maximum":5,"minimum":1,"title":"Limit","description":"Legacy compatibility field; ignored. All verified matching results are returned.","default":3,"deprecated":true},"photoStyles":{"anyOf":[{"items":{"type":"string","enum":["nature","urban","vintage","iconic","artistic","waterside","minimal","adventure"]},"type":"array","maxItems":8,"minItems":1},{"type":"null"}],"title":"Photostyles"},"categories":{"anyOf":[{"items":{"type":"string","enum":["viewpoint","park","attraction","museum","artwork","historic","nature","recreation","cafe","restaurant","bar","shop"]},"type":"array","maxItems":8,"minItems":1},{"type":"null"}],"title":"Categories"},"poiQueries":{"items":{"type":"string","maxLength":200,"minLength":1},"type":"array","maxItems":4,"title":"Poiqueries"},"geographicCombination":{"type":"string","enum":["all","any"],"title":"Geographiccombination","default":"all"},"featureCombination":{"type":"string","enum":["all","any"],"title":"Featurecombination","default":"all"},"osmFeatures":{"items":{"$ref":"#/components/schemas/OSMFeatureQuery"},"type":"array","maxItems":6,"title":"Osmfeatures"},"geographicKinds":{"items":{"type":"string","enum":["lake","sea","river","peak","forest","waterside"]},"type":"array","maxItems":6,"title":"Geographickinds"},"requirements":{"items":{"$ref":"#/components/schemas/Requirement"},"type":"array","maxItems":16,"title":"Requirements"},"subjectRole":{"type":"string","enum":["scene","portrait-background","existing-subject"],"title":"Subjectrole","default":"scene"},"scoringIntent":{"type":"string","maxLength":1000,"title":"Scoringintent","default":""},"selectedPoiIds":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":50},{"type":"null"}],"title":"Selectedpoiids"},"poiCatalogToken":{"anyOf":[{"type":"string","maxLength":40000},{"type":"null"}],"title":"Poicatalogtoken"},"preferences":{"type":"string","maxLength":500,"title":"Preferences","default":"Scenic, distinctive public places for photography"}},"type":"object","required":["lat","lon"],"title":"ExploreRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"IntentRequest":{"properties":{"route":{"anyOf":[{"$ref":"#/components/schemas/RouteRequest"},{"type":"null"}]},"subjectRole":{"type":"string","enum":["scene","portrait-background","existing-subject"],"title":"Subjectrole","default":"scene"},"query":{"type":"string","maxLength":1000,"title":"Query","default":""},"lat":{"type":"number","maximum":85,"minimum":-85,"title":"Lat"},"lon":{"type":"number","maximum":180,"minimum":-180,"title":"Lon"},"radius":{"type":"integer","maximum":20000,"minimum":100,"title":"Radius","default":1000},"limit":{"type":"integer","maximum":5,"minimum":1,"title":"Limit","description":"Legacy compatibility field; ignored during interpretation and discovery.","default":3,"deprecated":true},"photoStyles":{"items":{"type":"string","enum":["nature","urban","vintage","iconic","artistic","waterside","minimal","adventure"]},"type":"array","maxItems":8,"title":"Photostyles"},"preferences":{"type":"string","maxLength":500,"title":"Preferences","default":""},"categories":{"anyOf":[{"items":{"type":"string","enum":["viewpoint","park","attraction","museum","artwork","historic","nature","recreation","cafe","restaurant","bar","shop"]},"type":"array"},{"type":"null"}],"title":"Categories"},"poiQueries":{"items":{"type":"string","maxLength":200,"minLength":1},"type":"array","maxItems":4,"title":"Poiqueries"},"geographicKinds":{"items":{"type":"string","enum":["lake","sea","river","peak","forest","waterside"]},"type":"array","maxItems":6,"title":"Geographickinds"},"osmFeatures":{"items":{"$ref":"#/components/schemas/OSMFeatureQuery"},"type":"array","maxItems":6,"title":"Osmfeatures"},"geographicCombination":{"type":"string","enum":["all","any"],"title":"Geographiccombination","default":"all"},"featureCombination":{"type":"string","enum":["all","any"],"title":"Featurecombination","default":"all"},"scoringIntent":{"type":"string","maxLength":1000,"title":"Scoringintent","default":""}},"type":"object","required":["lat","lon"],"title":"IntentRequest"},"NumericFilter":{"properties":{"key":{"type":"string","maxLength":80,"minLength":1,"pattern":"^[A-Za-z0-9_:.-]+$","title":"Key"},"minimum":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Minimum"},"maximum":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Maximum"}},"additionalProperties":false,"type":"object","required":["key"],"title":"NumericFilter"},"OSMFeatureQuery":{"properties":{"label":{"type":"string","maxLength":120,"minLength":1,"title":"Label"},"kind":{"type":"string","enum":["tagged","intersection"],"title":"Kind","default":"tagged"},"filters":{"items":{"$ref":"#/components/schemas/TagFilter"},"type":"array","maxItems":6,"title":"Filters"},"numericFilters":{"items":{"$ref":"#/components/schemas/NumericFilter"},"type":"array","maxItems":4,"title":"Numericfilters"},"proximityMeters":{"type":"integer","maximum":500,"minimum":0,"title":"Proximitymeters","default":150},"selectionHints":{"items":{"type":"string","enum":["large-footprint","small-footprint","more-storeys"]},"type":"array","maxItems":3,"title":"Selectionhints","description":"Soft candidate priorities only; never hard constraints. Building footprint/levels do not establish visual style or luxury."}},"additionalProperties":false,"type":"object","required":["label"],"title":"OSMFeatureQuery"},"Requirement":{"properties":{"expression":{"type":"string","maxLength":400,"minLength":1,"title":"Expression","description":"English expression preserving AND/OR/NOT grouping"},"strength":{"type":"string","enum":["required","preferred","forbidden"],"title":"Strength"},"route":{"type":"string","enum":["places","geography","features","visual"],"title":"Route"},"evidence":{"type":"string","enum":["visual","spatial","provider","combined"],"title":"Evidence","default":"visual"},"stepIds":{"items":{"type":"string"},"type":"array","maxItems":8,"title":"Stepids","description":"Retrieval steps implementing this condition; empty for shared visual requirements"}},"additionalProperties":false,"type":"object","required":["expression","strength","route","stepIds"],"title":"Requirement"},"RouteEndpoint":{"properties":{"query":{"anyOf":[{"type":"string","maxLength":200,"minLength":1},{"type":"null"}],"title":"Query"},"lat":{"anyOf":[{"type":"number","maximum":85,"minimum":-85},{"type":"null"}],"title":"Lat"},"lon":{"anyOf":[{"type":"number","maximum":180,"minimum":-180},{"type":"null"}],"title":"Lon"},"label":{"anyOf":[{"type":"string","maxLength":350},{"type":"null"}],"title":"Label"}},"additionalProperties":false,"type":"object","title":"RouteEndpoint"},"RouteRequest":{"properties":{"origin":{"anyOf":[{"$ref":"#/components/schemas/RouteEndpoint"},{"type":"null"}]},"destination":{"$ref":"#/components/schemas/RouteEndpoint"},"travelMode":{"type":"string","enum":["walk","drive"],"title":"Travelmode","default":"walk"},"corridorMeters":{"type":"integer","maximum":2000,"minimum":50,"title":"Corridormeters","description":"Maximum distance from the route, not the circle search radius.","default":50}},"additionalProperties":false,"type":"object","required":["destination"],"title":"RouteRequest"},"SearchBranch":{"properties":{"poiQueries":{"items":{"type":"string"},"type":"array","maxItems":4,"title":"Poiqueries"},"geographicKinds":{"items":{"type":"string","enum":["lake","sea","river","peak","forest","waterside"]},"type":"array","maxItems":6,"title":"Geographickinds"},"geographicCombination":{"type":"string","enum":["all","any"],"title":"Geographiccombination","default":"all"},"osmFeatures":{"items":{"$ref":"#/components/schemas/OSMFeatureQuery"},"type":"array","maxItems":6,"title":"Osmfeatures"},"featureCombination":{"type":"string","enum":["all","any"],"title":"Featurecombination","default":"all"},"visualIntent":{"type":"string","maxLength":1000,"title":"Visualintent","default":""}},"additionalProperties":false,"type":"object","title":"SearchBranch"},"SearchParameters":{"properties":{"lat":{"type":"number","maximum":85,"minimum":-85,"title":"Lat"},"lon":{"type":"number","maximum":180,"minimum":-180,"title":"Lon"},"radius":{"type":"integer","maximum":20000,"minimum":100,"title":"Radius","default":5000},"searchProgram":{"anyOf":[{"$ref":"#/components/schemas/SearchProgram"},{"type":"null"}]},"searchBranches":{"items":{"$ref":"#/components/schemas/SearchBranch"},"type":"array","maxItems":6,"title":"Searchbranches"},"poiQueries":{"items":{"type":"string"},"type":"array","maxItems":4,"title":"Poiqueries"},"geographicKinds":{"items":{"type":"string","enum":["lake","sea","river","peak","forest","waterside"]},"type":"array","maxItems":6,"title":"Geographickinds"},"geographicCombination":{"type":"string","enum":["all","any"],"title":"Geographiccombination","default":"all"},"featureCombination":{"type":"string","enum":["all","any"],"title":"Featurecombination","default":"all"},"osmFeatures":{"items":{"$ref":"#/components/schemas/OSMFeatureQuery"},"type":"array","maxItems":6,"title":"Osmfeatures"},"photoStyles":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":8},{"type":"null"}],"title":"Photostyles"},"categories":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":8},{"type":"null"}],"title":"Categories"},"requirements":{"items":{"$ref":"#/components/schemas/Requirement"},"type":"array","maxItems":16,"title":"Requirements"},"subjectRole":{"type":"string","enum":["scene","portrait-background","existing-subject"],"title":"Subjectrole","default":"scene"},"scoringIntent":{"type":"string","maxLength":1000,"title":"Scoringintent","default":""},"preferences":{"type":"string","maxLength":500,"title":"Preferences","default":""}},"additionalProperties":false,"type":"object","required":["lat","lon"],"title":"SearchParameters"},"SearchProgram":{"properties":{"steps":{"items":{"$ref":"#/components/schemas/SearchStep"},"type":"array","maxItems":24,"minItems":1,"title":"Steps"},"output":{"type":"string","maxLength":40,"minLength":1,"title":"Output"}},"additionalProperties":false,"type":"object","required":["steps","output"],"title":"SearchProgram"},"SearchStep":{"properties":{"id":{"type":"string","pattern":"^[a-zA-Z][a-zA-Z0-9_]{0,39}$","title":"Id"},"tool":{"type":"string","enum":["search_places","search_geography","search_features","sample_geography","sample_near_places","feature_points","filter_geography","filter_features","union","intersection","area_imagery","point_imagery","center_imagery","collect_images","score_images","rank_results"],"title":"Tool"},"inputs":{"items":{"type":"string"},"type":"array","maxItems":6,"title":"Inputs"},"queries":{"items":{"type":"string"},"type":"array","maxItems":4,"title":"Queries"},"geographicKinds":{"items":{"type":"string","enum":["lake","sea","river","peak","forest","waterside"]},"type":"array","maxItems":6,"title":"Geographickinds"},"osmFeatures":{"items":{"$ref":"#/components/schemas/OSMFeatureQuery"},"type":"array","maxItems":6,"title":"Osmfeatures"},"combination":{"type":"string","enum":["all","any"],"title":"Combination","default":"all"},"exclude":{"type":"boolean","title":"Exclude","default":false},"discoveryHints":{"type":"boolean","title":"Discoveryhints","default":false},"weights":{"items":{"type":"integer"},"type":"array","maxItems":6,"title":"Weights"},"visualIntent":{"type":"string","maxLength":1000,"title":"Visualintent","default":""},"radiusMeters":{"type":"integer","maximum":2000,"minimum":100,"title":"Radiusmeters","default":750}},"additionalProperties":false,"type":"object","required":["id","tool"],"title":"SearchStep"},"SearchTaskRequest":{"properties":{"route":{"anyOf":[{"$ref":"#/components/schemas/RouteRequest"},{"type":"null"}]},"searchProgram":{"anyOf":[{"$ref":"#/components/schemas/SearchProgram"},{"type":"null"}]},"searchBranches":{"items":{"$ref":"#/components/schemas/SearchBranch"},"type":"array","maxItems":6,"title":"Searchbranches"},"query":{"type":"string","maxLength":1000,"title":"Query","default":""},"lat":{"type":"number","maximum":85,"minimum":-85,"title":"Lat"},"lon":{"type":"number","maximum":180,"minimum":-180,"title":"Lon"},"radius":{"type":"integer","maximum":20000,"minimum":100,"title":"Radius","default":1000},"limit":{"type":"integer","maximum":5,"minimum":1,"title":"Limit","description":"Legacy compatibility field; ignored. All verified matching results are returned.","default":3,"deprecated":true},"photoStyles":{"anyOf":[{"items":{"type":"string","enum":["nature","urban","vintage","iconic","artistic","waterside","minimal","adventure"]},"type":"array","maxItems":8,"minItems":1},{"type":"null"}],"title":"Photostyles"},"categories":{"anyOf":[{"items":{"type":"string","enum":["viewpoint","park","attraction","museum","artwork","historic","nature","recreation","cafe","restaurant","bar","shop"]},"type":"array","maxItems":8,"minItems":1},{"type":"null"}],"title":"Categories"},"poiQueries":{"items":{"type":"string","maxLength":200,"minLength":1},"type":"array","maxItems":4,"title":"Poiqueries"},"geographicCombination":{"type":"string","enum":["all","any"],"title":"Geographiccombination","default":"all"},"featureCombination":{"type":"string","enum":["all","any"],"title":"Featurecombination","default":"all"},"osmFeatures":{"items":{"$ref":"#/components/schemas/OSMFeatureQuery"},"type":"array","maxItems":6,"title":"Osmfeatures"},"geographicKinds":{"items":{"type":"string","enum":["lake","sea","river","peak","forest","waterside"]},"type":"array","maxItems":6,"title":"Geographickinds"},"requirements":{"items":{"$ref":"#/components/schemas/Requirement"},"type":"array","maxItems":16,"title":"Requirements"},"subjectRole":{"type":"string","enum":["scene","portrait-background","existing-subject"],"title":"Subjectrole","default":"scene"},"scoringIntent":{"type":"string","maxLength":1000,"title":"Scoringintent","default":""},"selectedPoiIds":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":50},{"type":"null"}],"title":"Selectedpoiids"},"poiCatalogToken":{"anyOf":[{"type":"string","maxLength":40000},{"type":"null"}],"title":"Poicatalogtoken"},"preferences":{"type":"string","maxLength":500,"title":"Preferences","default":"Scenic, distinctive public places for photography"}},"type":"object","required":["lat","lon"],"title":"SearchTaskRequest"},"TagFilter":{"properties":{"key":{"type":"string","maxLength":80,"minLength":1,"pattern":"^[A-Za-z0-9_:.-]+$","title":"Key"},"value":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}],"title":"Value"},"required":{"type":"boolean","title":"Required","default":true}},"additionalProperties":false,"type":"object","required":["key"],"title":"TagFilter"},"ThumbnailRequest":{"properties":{"sourceUrls":{"items":{"type":"string"},"type":"array","maxItems":24,"title":"Sourceurls"}},"type":"object","required":["sourceUrls"],"title":"ThumbnailRequest"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"servers":[{"url":"https://photo-scout.aisoup.net/api"}]}