Discovery API in AI Agent

Overview

Discovery API is the AI Agent's live line to your connected data sources. It talks to a platform's API directly, using the credentials of a connection you already have in Improvado, and returns the answer in chat — right now, without loading anything into a warehouse first.

That means you can ask about the current state of an ad account and get today's numbers, not yesterday's extract. And because the same channel works in both directions, you can also make changes — pause a campaign, adjust a budget, fix a name — with an explicit confirmation before each one.

What you can do with it

Read	Write
Pull live metrics — today's spend, current delivery, real-time pacing	Pause or enable campaigns, ad sets and ads
Inspect account structure — campaigns, ad groups, creatives, settings	Change budgets and bids
Explore what an API exposes before you build an extraction	Rename entities to match your naming convention
Validate extracted data against what the platform's own UI shows	Create campaigns, ad sets and ads from a brief
List existing audiences, their sizes and freshness	Create and refresh custom audiences and suppression lists

The write surface differs per platform — what can be created, changed or only read is a property of the vendor's own API. Ask the Agent what's possible for a specific source and it will tell you from Improvado's curated guide for that platform.

How to use the Discovery API feature

Prerequisites

• An active connection for the data source you want to work with
• Access to the AI Agent

Guide

1. 1Open the AI Agent chat and describe what you want in plain language — “show me all active Facebook campaigns with spend over $500 yesterday”, or “I want to explore Ad Labels for Facebook Ads”.
2. 2Pick the API version, if the platform offers several.
3. 3Pick which of your existing connections to use. The Agent never chooses an account for you.
4. 4The Agent resolves the right endpoint and parameters from Improvado's curated API guide for that source, sends the request with the selected credentials, and shows you the response.
5. 5Keep going — refine filters, follow a relationship into another entity, or ask for the same figures a different way.
6. 6Each request produces a document capturing the parameters, headers and configuration used. Keep it for auditing, troubleshooting or as a reference when you build the same thing again.

When it writes rather than reads

Any change to your accounts is confirmed first. The Agent states the entity, the account, the exact field, and the old and new value, and waits — one confirmation covers one operation. Beyond that, a few rules apply by default:

• Anything the Agent creates starts paused, so you review before it spends.
• Pausing is preferred over deleting. Deletion is irreversible and breaks reporting continuity.
• Changes are made one at a time and read back, so what you see reported is what the platform actually stored.

Discovery API, Extract & Load, or a Custom Pipeline?

These three cover different jobs, and picking the right one first saves the most time:

You want to…	Use
See or change something in a platform right now, once	Discovery API in chat
Load a large dataset on a schedule for reporting and dashboards	Extract & Load
Repeat a multi-step process — read, decide, act, report — on a schedule	Custom Pipelines
Get alerted when a metric in a connected source drifts	Discovery API governance rules

They build on each other. The normal route to a production workflow is: prototype the request in chat with Discovery API, confirm it returns exactly what you expect, then ask the Agent to turn it into a Custom Pipeline. The pipeline reuses the same connection and the same request shape, so a request that worked in chat works on a schedule.

Discovery API is deliberately not a bulk-loading tool. For large historical datasets, use Extract & Load — it handles volume, schema and scheduling properly.

Use cases

Live account review

A media buyer wants the current state of an account without waiting for an extraction to run.

Scenario: mid-flight check on a campaign that launched this morning. Nothing has been loaded into the warehouse yet, and yesterday's extract doesn't answer the question.

Goal: pull today's delivery and spend straight from the platform, compare against plan, and decide whether to intervene.

Direct API discovery

A marketing analyst wants to explore what data an API exposes before committing to an extraction.

Scenario: starting from scratch, no sample data available. They want to browse and test the API to learn what fields and entities are accessible — campaign settings, spend, targeting.

Goal:

1. 1Discover available endpoints and data models
2. 2Explore fields and relationships between entities
3. 3Preview sample data from each endpoint
4. 4Identify useful fields for reporting or analysis

Data sample (CSV, JSON, screenshot) to API endpoint mapping

An analyst has a data sample and wants to find which API endpoints can reproduce it.

Scenario: they have reporting data from a platform like Reddit Ads, joined across entities (Campaign, Ad Group), but don't know which endpoints produced it. They want to rebuild the dataset via the API.

Goal: analyze the sample to identify the relevant endpoints for each field, detect the necessary joins between entities, and recommend a sequence of API calls that reconstructs it.

Data discrepancy troubleshooting

An analyst notices a mismatch between platform UI metrics and API-extracted data.

Scenario: the numbers in the ad platform's UI disagree with those in the warehouse. The cause may be granularity differences, missing dimensions, unsupported campaign types, or filter mismatches.

Goal: pinpoint the root cause, compare UI and API data structures and filters, identify excluded data, and validate that the extraction logic matches what the UI shows.

Everyday account operations

A campaign manager wants to act on what they just found, without leaving the conversation.

Scenario: three ad sets are overspending, one campaign name breaks the naming convention, and a budget needs raising before the weekend.

Goal: make each change from chat with an explicit confirmation, and get back the before/after values as a record of what was done. If it turns out to be a recurring need, the same operations become a Custom Pipeline.

Supported sources

Discovery API works with any connected source in Improvado's connector catalog. For a growing set of platforms, Improvado additionally maintains curated API guides — endpoint contracts, required parameters, mandatory headers, pagination, versioning and the platform-specific gotchas — generated from the vendor's own specification and validated against Improvado's ingestion code.

When a source has a curated guide, the Agent works from it instead of searching the web, which means the right endpoint and API version on the first attempt. Sources with curated guides currently include Google Ads, Meta, TikTok Ads, LinkedIn Ads, Microsoft Advertising, Amazon Marketing Cloud, Salesforce, HubSpot, Shopify, Google Sheets, Mixpanel, PostHog, Matomo, Notion, Jira, Slack, Snowflake, Redshift and more — the list grows continuously. Ask the Agent whether the source you care about is covered.

For sources without a curated guide, the Agent resolves the current API version from the vendor's official documentation before making a request. It never guesses a version or invents a URL.

Technical details

The Discovery API feature is built on several components:

• Curated API guides: Improvado's own per-source endpoint documentation, used before anything else to shape a correct request.
• Documentation vector search: API documentation retrieval and versioning for sources not yet covered by a curated guide.
• Credentials manager: resolves the credentials of the connection you selected. The Agent never sees the raw credentials.
• API request sender: performs the actual request and returns the response.

Related articles