# Inside Ads API

> API + MCP server to manage advertising campaigns, view statistics and read the
> user profile in Inside Ads (a Telegram ad exchange). Intended for AI agents that
> act on behalf of an authenticated user.

Two ways to integrate:
- MCP server (recommended for agent tool-use) — authenticated via OAuth 2.0 + PKCE.
- HTTP REST API — authenticated via `Authorization: token <apiKey>` + `userId` query param.

## MCP server (recommended)

- Endpoint (Streamable HTTP, JSON-RPC 2.0): https://api-partners.insideads.net/api/mcp
- Server card: https://api-partners.insideads.net/.well-known/mcp/server-card.json
- How to authenticate (register → authorize → token, OAuth 2.0 + PKCE): https://api-partners.insideads.net/auth.md
- OAuth metadata: https://api-partners.insideads.net/.well-known/oauth-authorization-server

## REST API

AI agents: authenticate with the OAuth access token from the flow above —
send `Authorization: Bearer <access_token>`. The userId is derived from the token,
so no manual apiKey and no `userId` query param are needed.

Manual auth (humans/scripts): header `Authorization: token <apiKey>`, plus `userId`
as a query parameter on every request. If the user has not provided credentials, ask for both:
- apiKey — in the app: Account → Settings.
- userId — the user's Telegram user ID (visible in Telegram).

- [Cookbook with ready-to-use curl recipes](https://api-partners.insideads.net/public/api.md): create an ad, generate content, set budget, change statuses, read statistics, important gotchas.
- [OpenAPI V1 (JSON)](https://api-partners.insideads.net/public/openapi.json): full list of methods and parameters.
- [OpenAPI V2, AI-optimized (JSON)](https://api-partners.insideads.net/v2/openapi.json).

## Machine-readable discovery

- API catalog (RFC 9727): https://api-partners.insideads.net/.well-known/api-catalog

## Base URL

https://api-partners.insideads.net