{"openapi":"3.1.0","info":{"title":"Topsort (BYOK) API","version":"0.1.0","description":"Topsort (BYOK) lets an AI assistant read your own Topsort data through the Topsort API with a key you supply (Topsort Advanced API key (Settings, API Integration)). Read-only: 12 tools (list_campaigns, get_campaign, list_campaign_bids, list_campaign_products, get_campaign_report, get_campaign_daily_report, get_marketplace_report, get_marketplace_daily_report, get_vendor_report,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-topsort.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-topsort/docs"},"termsOfService":"https://connectorbay.com/byok-topsort/terms"},"servers":[{"url":"https://byok-topsort.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-topsort/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/list_campaigns":{"post":{"operationId":"list_campaigns","summary":"List the ad campaigns of the marketplace or of one vendor with budget, dates, status, ad format, charge type and bid cou","description":"List the ad campaigns of the marketplace or of one vendor with budget, dates, status, ad format, charge type and bid counts; filter by vendor, activity or external id. Use for \"Which Topsort campaigns are active and what budgets do they have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"vendor_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only campaigns of this vendor id (omit for all vendors).","title":"Vendor Id"},"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"Only active (true) or inactive (false) campaigns.","title":"Is Active"},"external_campaign_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only the campaign with this id from your own system.","title":"External Campaign Id"},"order_by":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"One clause such as created_at:asc (also start_date, end_date, name, campaign_id).","title":"Order By"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Rows to skip (default 0).","title":"Offset"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Rows per page (1 to 100, default 100).","title":"Limit"}},"title":"list_campaignsArguments","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_campaign":{"post":{"operationId":"get_campaign","summary":"Get one campaign with budget, dates, status, ad format, charge type, targeting and bid count. Use for \"What are the sett","description":"Get one campaign with budget, dates, status, ad format, charge type, targeting and bid count. Use for \"What are the settings of Topsort campaign camp_123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"campaign_id":{"description":"Campaign id (the campaignId from list_campaigns).","maxLength":200,"title":"Campaign Id","type":"string"}},"required":["campaign_id"],"title":"get_campaignArguments","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_campaign_bids":{"post":{"operationId":"list_campaign_bids","summary":"List the bids of a campaign with amount, target product or category, state and ad format properties. Use for \"What are t","description":"List the bids of a campaign with amount, target product or category, state and ad format properties. Use for \"What are the bids on Topsort campaign camp_123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"campaign_id":{"description":"Campaign id (the campaignId from list_campaigns).","maxLength":200,"title":"Campaign Id","type":"string"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Rows to skip (default 0).","title":"Offset"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Rows per page (1 to 100, default 100).","title":"Limit"}},"required":["campaign_id"],"title":"list_campaign_bidsArguments","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_campaign_products":{"post":{"operationId":"list_campaign_products","summary":"List the products of a banner or sponsored brand campaign and whether each is active. Use for \"Which products are in Top","description":"List the products of a banner or sponsored brand campaign and whether each is active. Use for \"Which products are in Topsort campaign camp_123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"campaign_id":{"description":"Campaign id (the campaignId from list_campaigns).","maxLength":200,"title":"Campaign Id","type":"string"},"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"Only active (true) or inactive (false) products.","title":"Is Active"}},"required":["campaign_id"],"title":"list_campaign_productsArguments","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_campaign_report":{"post":{"operationId":"get_campaign_report","summary":"Get a campaign's impressions, clicks, ad spend, purchases and auction win rate for a date range. Use for \"How did Topsor","description":"Get a campaign's impressions, clicks, ad spend, purchases and auction win rate for a date range. Use for \"How did Topsort campaign camp_123 perform this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"campaign_id":{"description":"Campaign id (the campaignId from list_campaigns).","maxLength":200,"title":"Campaign Id","type":"string"},"start_date":{"description":"First day, YYYY-MM-DD.","maxLength":10,"title":"Start Date","type":"string"},"end_date":{"description":"Last day, YYYY-MM-DD.","maxLength":10,"title":"End Date","type":"string"}},"required":["campaign_id","start_date","end_date"],"title":"get_campaign_reportArguments","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_campaign_daily_report":{"post":{"operationId":"get_campaign_daily_report","summary":"Get a campaign's daily impressions, clicks, ad spend and purchases for a date range; paged. Use for \"What was the daily ","description":"Get a campaign's daily impressions, clicks, ad spend and purchases for a date range; paged. Use for \"What was the daily spend of Topsort campaign camp_123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"campaign_id":{"description":"Campaign id (the campaignId from list_campaigns).","maxLength":200,"title":"Campaign Id","type":"string"},"start_date":{"description":"First day, YYYY-MM-DD.","maxLength":10,"title":"Start Date","type":"string"},"end_date":{"description":"Last day, YYYY-MM-DD.","maxLength":10,"title":"End Date","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Days per page (1 to 100, default 100).","title":"Limit"},"next_page":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's nextPage.","title":"Next Page"}},"required":["campaign_id","start_date","end_date"],"title":"get_campaign_daily_reportArguments","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_marketplace_report":{"post":{"operationId":"get_marketplace_report","summary":"Get the whole marketplace's impressions, clicks, ad spend and purchases for a date range. Use for \"How much did Topsort ","description":"Get the whole marketplace's impressions, clicks, ad spend and purchases for a date range. Use for \"How much did Topsort ads earn across the marketplace this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_date":{"description":"First day, YYYY-MM-DD.","maxLength":10,"title":"Start Date","type":"string"},"end_date":{"description":"Last day, YYYY-MM-DD.","maxLength":10,"title":"End Date","type":"string"}},"required":["start_date","end_date"],"title":"get_marketplace_reportArguments","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_marketplace_daily_report":{"post":{"operationId":"get_marketplace_daily_report","summary":"Get the marketplace's daily impressions, clicks, ad spend and purchases for a date range; paged. Use for \"What were the ","description":"Get the marketplace's daily impressions, clicks, ad spend and purchases for a date range; paged. Use for \"What were the daily Topsort ad totals this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_date":{"description":"First day, YYYY-MM-DD.","maxLength":10,"title":"Start Date","type":"string"},"end_date":{"description":"Last day, YYYY-MM-DD.","maxLength":10,"title":"End Date","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Days per page (1 to 100, default 100).","title":"Limit"},"next_page":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's nextPage.","title":"Next Page"}},"required":["start_date","end_date"],"title":"get_marketplace_daily_reportArguments","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_vendor_report":{"post":{"operationId":"get_vendor_report","summary":"Get one vendor's impressions, clicks, ad spend, purchases and auction win rate for a date range. Use for \"How did vendor","description":"Get one vendor's impressions, clicks, ad spend, purchases and auction win rate for a date range. Use for \"How did vendor vendor_9 do on Topsort this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"vendor_id":{"description":"Vendor id (the id from list_catalog_vendors).","maxLength":200,"title":"Vendor Id","type":"string"},"start_date":{"description":"First day, YYYY-MM-DD.","maxLength":10,"title":"Start Date","type":"string"},"end_date":{"description":"Last day, YYYY-MM-DD.","maxLength":10,"title":"End Date","type":"string"}},"required":["vendor_id","start_date","end_date"],"title":"get_vendor_reportArguments","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_catalog_vendors":{"post":{"operationId":"list_catalog_vendors","summary":"List the vendors (sellers or brands) in the marketplace catalog with name and role. Use for \"Which vendors are in my Top","description":"List the vendors (sellers or brands) in the marketplace catalog with name and role. Use for \"Which vendors are in my Topsort catalog\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"global_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only the vendor with this global vendor id.","title":"Global Id"},"next_page":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's nextPage.","title":"Next Page"}},"title":"list_catalog_vendorsArguments","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_banner_slots":{"post":{"operationId":"list_banner_slots","summary":"List the banner slots of a page position (landing, category_search, category or search) with page, dimensions and status","description":"List the banner slots of a page position (landing, category_search, category or search) with page, dimensions and status. Use for \"Which banner slots can run Topsort ads on search pages\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"position":{"description":"Slot position.","enum":["landing","category_search","category","search"],"title":"Position","type":"string"},"page_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only slots of this page id.","title":"Page Id"},"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Match on page url, page name or slot id.","title":"Search"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Rows per page (1 to 50, default 25).","title":"Limit"},"next_page":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's nextPage.","title":"Next Page"}},"required":["position"],"title":"list_banner_slotsArguments","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_placements":{"post":{"operationId":"list_placements","summary":"List the banner placements (templates with size limits for logo, title and products) with name and template. Use for \"Wh","description":"List the banner placements (templates with size limits for logo, title and products) with name and template. Use for \"Which banner placements are set up in Topsort\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Match on name, external placement id or template name.","title":"Search"},"json_template_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only placements of this template id.","title":"Json Template Id"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Rows per page (1 to 50, default 25).","title":"Limit"},"next_page":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's nextPage.","title":"Next Page"}},"title":"list_placementsArguments","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}}}}