canonical: https://jentic.com/apis/opteo.dev/opteo # Opteo API Jentic publishes the only available OpenAPI specification for Opteo API, keeping it validated and agent-ready. Opteo is a Google Ads optimisation platform that surfaces improvement suggestions, performance goals, and budget controls for paid-search accounts. The API exposes endpoints for managing customer accounts, configuring budgets and performance modes, setting goals, and retrieving active and completed improvement suggestions. Authentication is a bearer token issued by Opteo to each agency or in-house team. ## For AI agents Configure Opteo customer budgets, performance goals, and modes, and retrieve Google Ads improvement suggestions through 12 REST endpoints. ## Scope Does not handle Google Ads writes, billing, or campaign creation - use for Opteo customer configuration and improvement retrieval only. ## Capabilities - List Opteo customer accounts linked to the calling agency - Read or update the monthly budget for a Google Ads customer - Configure the performance mode that drives Opteo's optimisation behaviour - Set or read performance goals such as target CPA or ROAS - Retrieve the active improvement suggestions Opteo has surfaced for an account - Look up the history of improvements that were already implemented or dismissed ## Use cases ### Agency-wide budget syncing PPC agencies running many client accounts can keep Opteo budgets in step with the source of truth in their finance system. A scheduled agent calls GET /customers to enumerate accounts and POST `/customers/{customerId}/budget` to push the latest monthly budget figures, so Opteo's optimisation guardrails always reflect what each client has actually approved. Example prompt: GET /customers, then for each customerId POST `/customers/{customerId}/budget` with the monthly_budget value pulled from the finance system. ### Goal-driven optimisation When an account changes objective from cost-per-acquisition to return-on-ad-spend, the responsible analyst can update the Opteo performance goals via POST `/customers/{customerId}/performance-goals` so subsequent improvement suggestions align with the new target. The matching GET endpoint lets an agent read back the configuration before pushing further changes. Example prompt: POST `/customers/{customerId}/performance-goals` with target_roas=4 and primary_metric=conversion_value to switch the account to ROAS-led optimisation. ### Surfacing improvement suggestions PPC managers reviewing their book can pull the queue of unaddressed Opteo suggestions across every account by calling GET `/customers/{customerId}/improvements` per account, then sort them by impact in their own dashboard. The `/improvements/completed` endpoint provides the matching record of decisions taken, which is useful for monthly reviews with clients. Example prompt: Iterate over GET `/customers/{customerId}/improvements` for each managed account and surface the top three by estimated impact. ### AI agent for paid search Through Jentic, a paid-search assistant agent can answer 'what should I do this week' by calling GET `/customers/{customerId}/improvements` and summarising the top suggestions in plain language, with an option to drill into linking state via GET `/customers/{customerId}/linking.` The Opteo bearer token sits in your Jentic One instance, so the agent never handles the secret. Example prompt: Search Jentic for 'list opteo improvements for a customer', execute GET `/customers/{customerId}/improvements`, and present the top suggestions to the user. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/customers` | List managed customer accounts | | GET | `/customers/{customerId}/budget` | Get a customer's monthly budget | | POST | `/customers/{customerId}/budget` | Update a customer's monthly budget | | POST | `/customers/{customerId}/performance-goals` | Update performance goals | | GET | `/customers/{customerId}/improvements` | Get active improvements | | GET | `/customers/{customerId}/improvements/completed` | Get completed improvements | ## Key resources - **Customers** — Linked Google Ads customer accounts - **Budget** — Monthly budget configuration per customer - **Performance Mode** — Optimisation behaviour mode for an account - **Performance Goals** — Targets such as CPA or ROAS used by Opteo - **Improvements** — Active and completed Google Ads improvement suggestions ## Why Jentic - **Setup:** Wiring the Opteo API by hand means sending its bearer token on every call and keeping the customer budget, performance-goal, and improvement routes straight yourself. Through Jentic you install once, import the Opteo API from the API Directory, store the token once, and your agent calls it. - **Permission scoping:** Opteo puts the customer id in the URL path (`/customers/{customerId}/...`), so a rule can pin your agent to one customer account: it can read that account's improvements and nothing else. You choose the operations it may call, so writes like setting a budget or a performance goal are not included unless you add them. - **Credential handling:** Your Opteo bearer token is stored once, encrypted, by your own Jentic One instance and injected as the Authorization header at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'list opteo customer accounts' or 'get opteo improvements', and Jentic returns the matching operation under /customers with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Optmyzr** — PPC optimisation platform with suggestions, alerts, and workouts - **WhatConverts** — Lead-tracking platform that ties paid-search clicks to qualified outcomes - **Mixpanel** — Product analytics platform used to validate paid traffic conversion impact ## FAQ ### Why is there no official OpenAPI spec for Opteo API? Opteo does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Opteo API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Opteo API use? Opteo uses an HTTP bearer token issued by the Opteo team. Through Jentic the token is stored encrypted in the vault and supplied as Authorization at execution time, so an agent never sees or stores the credential itself. ### Can I push changes back to Google Ads through this API? No. Opteo's API exposes Opteo's own configuration (budgets, performance goals, improvements) - it does not act as a write path into Google Ads. Changes you accept inside Opteo are applied to Google Ads through Opteo's own connection, not through this API. ### What are the rate limits for the Opteo API? The spec does not document fixed rate limits; these are governed by Opteo's commercial agreement with the calling agency. Treat 429 responses with backoff and ask the Opteo account team for ceilings before running large batch syncs. ### How do I retrieve active improvements for a customer through Jentic? Search Jentic for 'list opteo improvements for a customer', load GET `/customers/{customerId}/improvements`, and execute it with the customer ID. The vaulted bearer token is supplied automatically. ### Can I update the budget for many customers in one call? Not directly. POST `/customers/{customerId}/budget` operates on a single customer. Agencies typically iterate the call across the customers returned by GET /customers, which is straightforward to chain in a Jentic agent. ### Can I limit what my agent is allowed to do with the Opteo API? Yes. Because Opteo puts the customer id in the URL path (`/customers/{customerId}/...`), a rule in your self-hosted Jentic One instance can pin the agent to a single customer account, so it reads that account's improvements and touches nothing else. You decide which operations the agent may call, so read routes like GET `/customers/{customerId}/improvements` can be allowed while writes such as POST `/customers/{customerId}/budget` or POST `/customers/{customerId}/performance-goals` stay off unless you add them. Your own rules govern which endpoints and credentials the agent may use, so it can never reach an operation you have not granted.