> ## Documentation Index > Fetch the complete documentation index at: https://aisa.one/docs/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > - Base URLs: models `https://api.aisa.one/v1` (Gemini GenerateContent: `https://api.aisa.one/v1beta`); data APIs `https://api.aisa.one/apis/v1`. The `servers` of each operation in https://aisa.one/openapi.yaml is authoritative. > - Auth: `Authorization: Bearer $AISA_API_KEY`. Never print, log, or commit the key. > - MCP (preferred for agents): `https://mcp.aisa.one/mcp`, signed in with OAuth, so there is no key to paste. > - Agent Skill: `npx skills add AIsa-team/agent-skills --skill aisa`. Fallback with the AIsa CLI: `aisa skills install aisa`. > - Spending: docs, https://aisa.one/models, https://aisa.one/api, `/v1/models`, and MCP `search`, `list_categories`, `get_details`, `batch_quote`, and the `account` operation are free. Quote the exact calls before running them (MCP `batch_quote`, CLI `aisa quote --json`). If the quote reports `auto_execute_eligible: true`, run it unless the user set a tighter limit or asked only for a quote. Otherwise, tell the user in one message the planned calls, the quoted price, and a total USD budget for the task, then wait for approval. Direct HTTP calls follow the stricter rule at https://aisa.one/docs/get-started/cli.md#direct-http-fallback. Do not make paid calls to test availability. Full rule: https://aisa.one/llms.txt # Update a campaign > Ad Campaigns. Can spend money or change spend: needs the ads:spend scope and X-Aisa-Confirm: spend; without the header the request is refused with confirmation_required and nothing is sent. Changes a campaign's budget or bidding. Changes a campaign's settings, such as its name, budget, bidding or tracking URLs. Send at least one of `budget`, `bidStrategy`, `portfolioBidStrategyId`, `targetImpressionShare`, `manualCpc`, `networkSettings`, `trackingUrlTemplate`, `finalUrlSuffix`, `sharedBudgetId`, `name` or `platformSpecificData`. An unsupported field is always an error, never a silent drop. 当前未提供请求参考价格；请使用接口支持的报价功能确认费用。 最终费用以账户适用价格及实际结算为准。 ## 请求规范 * **方法与路径:** PUT /apis/v1/ads/campaigns/\{campaignId} * **可用状态:** enabled * **请求 URL 模板:** `https://api.aisa.one/apis/v1/ads/campaigns/{campaignId}` * **campaignId:** path; 必填 * **connectionId:** query; 必填 * **X-Aisa-Confirm:** header; 可选 * **Runtime 事实版本:** fe60122939c67dc98a3a6ac6b97bd5c326b526105150c8959304dd2160d4dd09 [完整 OpenAPI 定义](https://aisa.one/docs/reference-contracts/zh/aisa-ads.json) 有效请求与价格声明（包括认证和引用的 schema）： ```json theme={null} { "operationId": "put_aisa_ads_apis_v1_ads_campaigns_campaignid", "method": "PUT", "path": "/apis/v1/ads/campaigns/{campaignId}", "servers": [ { "url": "https://api.aisa.one" } ], "parameters": [ { "description": "Platform campaign ID", "in": "path", "name": "campaignId", "required": true, "schema": { "type": "string" } }, { "description": "The ads connection (adc_...) the request runs on: one of yours, from GET /apis/v1/ads/connections. On a request with a JSON body it may be sent as a top-level body member instead.", "in": "query", "name": "connectionId", "required": true, "schema": { "pattern": "^adc_[0-9A-Za-z]+$", "type": "string" } }, { "description": "Required with the value \"spend\" when the request can spend money or change spend. Without it the request is refused with 409 confirmation_required, which describes what would happen; nothing is sent to the ad platform.", "in": "header", "name": "X-Aisa-Confirm", "required": false, "schema": { "enum": [ "spend" ], "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "example": { "budget": { "amount": 8, "type": "daily" }, "connectionId": "adc_7f3k2m9q", "platform": "facebook" }, "schema": { "additionalProperties": true, "properties": { "allowSharedBudgetUpdate": { "default": false, "description": "Google only. Explicitly allow changing a shared campaign budget (flagged as shared by Google, or used by more than one campaign), affecting every campaign that uses it. Does not bypass an unknown sharing state.", "type": "boolean" }, "bidAmount": { "description": "Google only. Whole currency units (USD: 12 = $12.00). Max CPC for LOWEST_COST_WITH_BID_CAP, CPA target for COST_CAP; required for both.", "type": "number" }, "bidStrategy": { "description": "Meta + Google. Meta: the campaign default that ad sets inherit unless they override it. Google: the campaign's own bidding strategy.", "enum": [ "LOWEST_COST_WITHOUT_CAP", "LOWEST_COST_WITH_BID_CAP", "COST_CAP", "LOWEST_COST_WITH_MIN_ROAS" ], "type": "string" }, "budget": { "description": "Meta CBO, Google daily, or OpenAI Ads or Reddit Ads daily or lifetime campaign budget, in whole currency units.", "properties": { "amount": { "description": "Budget amount in the ad account's currency", "type": "number" }, "type": { "enum": [ "daily", "lifetime" ], "type": "string" } }, "required": [ "amount", "type" ], "type": "object" }, "connectionId": { "description": "The ads connection (adc_...), when not sent as the connectionId query parameter.", "pattern": "^adc_[0-9A-Za-z]+$", "type": "string" }, "finalUrlSuffix": { "description": "Google only. campaign.final_url_suffix; an empty string clears it.", "type": "string" }, "manualCpc": { "additionalProperties": false, "description": "Google Search and Display only. Manual CPC bidding. Enhanced CPC is not offered: Google no longer lets Search and Display campaigns enable it. Exclusive with every other strategy field.", "properties": { "maxCpc": { "description": "Max CPC of the ad groups, in the account's currency units: set on the ad group created with the campaign, and on every ad group of the campaign when an update switches it to Manual CPC. Google gives an ad group without one a 0.01 bid.", "exclusiveMinimum": 0, "type": "number" } }, "required": [ "maxCpc" ], "type": "object" }, "name": { "description": "Meta and Reddit. Rename the campaign.", "maxLength": 255, "type": "string" }, "networkSettings": { "additionalProperties": false, "description": "Google Search campaigns only. Which networks the campaign serves on besides Google Search.", "properties": { "displayNetwork": { "description": "campaign.network_settings.target_content_network (Search with Display expansion)", "type": "boolean" }, "searchPartners": { "description": "campaign.network_settings.target_search_network", "type": "boolean" } }, "type": "object" }, "platform": { "description": "Required: platform campaign IDs are not globally unique. Filled from the connection when omitted.", "enum": [ "facebook", "instagram", "tiktok", "linkedin", "pinterest", "google", "twitter", "openai", "reddit", "microsoft", "meta", "x" ], "type": "string" }, "platformSpecificData": { "description": "Meta only. Platform implied by the `platform` body param, same convention as POST /apis/v1/ads/create.", "properties": { "spendCap": { "description": "Campaign lifetime spend cap, in the ad account's currency (Meta `spend_cap`). Pass null to remove the cap; 0 is rejected by Meta.", "type": [ "number", "null" ] } }, "type": "object" }, "portfolioBidStrategyId": { "description": "Google only. Attach an existing portfolio bid strategy (numeric id from GET /apis/v1/ads/bid-strategies) instead of setting bidStrategy. Exclusive with bidStrategy.", "pattern": "^\\d+$", "type": "string" }, "roasAverageFloor": { "description": "Google only. Decimal ROAS multiplier (2.0 = 2.0x), required for LOWEST_COST_WITH_MIN_ROAS.", "type": "number" }, "sharedBudgetId": { "description": "Google only. Move the campaign onto this shared budget (id from GET /apis/v1/ads/shared-budgets), or null to move it back onto a budget of its own sized by `budget`.", "pattern": "^\\d+$", "type": [ "string", "null" ] }, "targetImpressionShare": { "additionalProperties": false, "description": "Google Search only. Target impression share bidding. Exclusive with bidStrategy, portfolioBidStrategyId and manualCpc; bidAmount is refused alongside it (the ceiling is maxCpc).", "properties": { "location": { "enum": [ "ANYWHERE_ON_PAGE", "TOP_OF_PAGE", "ABSOLUTE_TOP_OF_PAGE" ], "type": "string" }, "maxCpc": { "description": "Max CPC bid limit, in the account's currency units. Google requires it.", "exclusiveMinimum": 0, "type": "number" }, "percent": { "description": "Target share of impressions, in percent (65 = 65%). Sent to Google as location_fraction_micros (1% = 10,000).", "exclusiveMinimum": 0, "maximum": 100, "type": "number" } }, "required": [ "location", "maxCpc", "percent" ], "type": "object" }, "trackingUrlTemplate": { "description": "Google only. campaign.tracking_url_template; an empty string clears it.", "type": "string" } }, "type": "object" } } }, "required": true }, "x-aisa-status": "enabled", "x-aisa-pricing": { "description": "Ads operations are free. Ad spend is billed by the ad platform to the connected ad account, never by AIsa.", "kind": "no_customer_charge" }, "components": { "securitySchemes": { "bearerAuth": { "scheme": "bearer", "type": "http" } } } } ``` ## 费用与请求规则 当前未提供请求参考价格；请使用接口支持的报价功能确认费用。 最终费用以账户适用价格及实际结算为准。 公开参考值不是你的账户报价或最终扣费。对于支持 X-AISA-Cost-Mode: quote 的接口，执行前请针对完整请求获取免费报价；执行后通过响应费用元数据和 Usage Logs 核对结算费用。1 USD 等于 1,000,000 个整数 micro-USD。 ## OpenAPI ````yaml reference-contracts/zh/aisa-ads.json PUT /apis/v1/ads/campaigns/{campaignId} openapi: 3.1.0 info: description: '' title: AIsa Ads version: '1' x-aisa-capabilities: idempotency: Idempotency-Key max_price: X-AISA-Max-Price-USD quote: header: X-AISA-Cost-Mode value: quote x-aisa-configured-paths: [] x-aisa-document: facts_hash: fe60122939c67dc98a3a6ac6b97bd5c326b526105150c8959304dd2160d4dd09 generator_version: '3' protocol_version: '1' schema_version: '1' composer_version: '27' response_pending: [] document_hash: sha256:ba353f59e89e1ebabe0e301d8ef57d3cbfa6bb406a8c591ee9c3833d64b60520 x-aisa-plans: builder: 1 display_plan: payg payg: 1 similarweb_payg: 1 team: 1 version: e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb x-aisa-provider: aisa-ads x-aisa-catalogs: aisa-ads: title: AIsa Ads description: '' x-aisa-document: facts_hash: fe60122939c67dc98a3a6ac6b97bd5c326b526105150c8959304dd2160d4dd09 generator_version: '3' protocol_version: '1' schema_version: '1' x-aisa-plans: builder: 1 display_plan: payg payg: 1 similarweb_payg: 1 team: 1 version: e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb x-aisa-capabilities: idempotency: Idempotency-Key max_price: X-AISA-Max-Price-USD quote: header: X-AISA-Cost-Mode value: quote servers: - url: https://api.aisa.one security: - bearerAuth: [] paths: /apis/v1/ads/campaigns/{campaignId}: put: summary: Update a campaign description: >- Ad Campaigns. Can spend money or change spend: needs the ads:spend scope and X-Aisa-Confirm: spend; without the header the request is refused with confirmation_required and nothing is sent. Changes a campaign's budget or bidding. Changes a campaign's settings, such as its name, budget, bidding or tracking URLs. Send at least one of `budget`, `bidStrategy`, `portfolioBidStrategyId`, `targetImpressionShare`, `manualCpc`, `networkSettings`, `trackingUrlTemplate`, `finalUrlSuffix`, `sharedBudgetId`, `name` or `platformSpecificData`. An unsupported field is always an error, never a silent drop. 当前未提供请求参考价格；请使用接口支持的报价功能确认费用。 最终费用以账户适用价格及实际结算为准。 operationId: put_aisa_ads_apis_v1_ads_campaigns_campaignid parameters: - description: Platform campaign ID in: path name: campaignId required: true schema: type: string - description: >- The ads connection (adc_...) the request runs on: one of yours, from GET /apis/v1/ads/connections. On a request with a JSON body it may be sent as a top-level body member instead. in: query name: connectionId required: true schema: pattern: ^adc_[0-9A-Za-z]+$ type: string - description: >- Required with the value "spend" when the request can spend money or change spend. Without it the request is refused with 409 confirmation_required, which describes what would happen; nothing is sent to the ad platform. in: header name: X-Aisa-Confirm required: false schema: enum: - spend type: string requestBody: content: application/json: example: budget: amount: 8 type: daily connectionId: adc_7f3k2m9q platform: facebook schema: additionalProperties: true properties: allowSharedBudgetUpdate: default: false description: >- Google only. Explicitly allow changing a shared campaign budget (flagged as shared by Google, or used by more than one campaign), affecting every campaign that uses it. Does not bypass an unknown sharing state. type: boolean bidAmount: description: >- Google only. Whole currency units (USD: 12 = $12.00). Max CPC for LOWEST_COST_WITH_BID_CAP, CPA target for COST_CAP; required for both. type: number bidStrategy: description: >- Meta + Google. Meta: the campaign default that ad sets inherit unless they override it. Google: the campaign's own bidding strategy. enum: - LOWEST_COST_WITHOUT_CAP - LOWEST_COST_WITH_BID_CAP - COST_CAP - LOWEST_COST_WITH_MIN_ROAS type: string budget: description: >- Meta CBO, Google daily, or OpenAI Ads or Reddit Ads daily or lifetime campaign budget, in whole currency units. properties: amount: description: Budget amount in the ad account's currency type: number type: enum: - daily - lifetime type: string required: - amount - type type: object connectionId: description: >- The ads connection (adc_...), when not sent as the connectionId query parameter. pattern: ^adc_[0-9A-Za-z]+$ type: string finalUrlSuffix: description: >- Google only. campaign.final_url_suffix; an empty string clears it. type: string manualCpc: additionalProperties: false description: >- Google Search and Display only. Manual CPC bidding. Enhanced CPC is not offered: Google no longer lets Search and Display campaigns enable it. Exclusive with every other strategy field. properties: maxCpc: description: >- Max CPC of the ad groups, in the account's currency units: set on the ad group created with the campaign, and on every ad group of the campaign when an update switches it to Manual CPC. Google gives an ad group without one a 0.01 bid. exclusiveMinimum: 0 type: number required: - maxCpc type: object name: description: Meta and Reddit. Rename the campaign. maxLength: 255 type: string networkSettings: additionalProperties: false description: >- Google Search campaigns only. Which networks the campaign serves on besides Google Search. properties: displayNetwork: description: >- campaign.network_settings.target_content_network (Search with Display expansion) type: boolean searchPartners: description: campaign.network_settings.target_search_network type: boolean type: object platform: description: >- Required: platform campaign IDs are not globally unique. Filled from the connection when omitted. enum: - facebook - instagram - tiktok - linkedin - pinterest - google - twitter - openai - reddit - microsoft - meta - x type: string platformSpecificData: description: >- Meta only. Platform implied by the `platform` body param, same convention as POST /apis/v1/ads/create. properties: spendCap: description: >- Campaign lifetime spend cap, in the ad account's currency (Meta `spend_cap`). Pass null to remove the cap; 0 is rejected by Meta. type: - number - 'null' type: object portfolioBidStrategyId: description: >- Google only. Attach an existing portfolio bid strategy (numeric id from GET /apis/v1/ads/bid-strategies) instead of setting bidStrategy. Exclusive with bidStrategy. pattern: ^\d+$ type: string roasAverageFloor: description: >- Google only. Decimal ROAS multiplier (2.0 = 2.0x), required for LOWEST_COST_WITH_MIN_ROAS. type: number sharedBudgetId: description: >- Google only. Move the campaign onto this shared budget (id from GET /apis/v1/ads/shared-budgets), or null to move it back onto a budget of its own sized by `budget`. pattern: ^\d+$ type: - string - 'null' targetImpressionShare: additionalProperties: false description: >- Google Search only. Target impression share bidding. Exclusive with bidStrategy, portfolioBidStrategyId and manualCpc; bidAmount is refused alongside it (the ceiling is maxCpc). properties: location: enum: - ANYWHERE_ON_PAGE - TOP_OF_PAGE - ABSOLUTE_TOP_OF_PAGE type: string maxCpc: description: >- Max CPC bid limit, in the account's currency units. Google requires it. exclusiveMinimum: 0 type: number percent: description: >- Target share of impressions, in percent (65 = 65%). Sent to Google as location_fraction_micros (1% = 10,000). exclusiveMinimum: 0 maximum: 100 type: number required: - location - maxCpc - percent type: object trackingUrlTemplate: description: >- Google only. campaign.tracking_url_template; an empty string clears it. type: string type: object required: true responses: '200': content: application/json: schema: description: Echoes back only the fields you sent, plus `updated`. properties: bidAmount: type: number bidStrategy: description: >- Meta bid strategy. Same enum applies at campaign and ad-set level; ad-set value (when set) overrides campaign-level. Cross-field rules: `LOWEST_COST_WITHOUT_CAP` (default): auto-bid, forbids `bidAmount` and `roasAverageFloor`. enum: - LOWEST_COST_WITHOUT_CAP - LOWEST_COST_WITH_BID_CAP - COST_CAP - LOWEST_COST_WITH_MIN_ROAS type: string budget: description: >- Budget amount in the ad account's native currency (see the campaign's `currency` field for the code). properties: amount: type: number amountMicros: description: >- Google only. Exact decimal micros; DAILY uses amount_micros and CUSTOM_PERIOD uses total_amount_micros. pattern: ^\d+$ type: string deliveryMethod: description: >- Google only. campaign_budget.delivery_method, typically STANDARD, or null when unavailable. type: - string - 'null' explicitlyShared: description: >- Google only. True for a shared budget; null when unavailable. Shared writes require allowSharedBudgetUpdate=true; unknown sharing status cannot be overridden. type: - boolean - 'null' resourceName: description: >- Google only. campaign_budget.resource_name, or null when unavailable. type: - string - 'null' type: enum: - daily - lifetime type: string required: - amount - type type: object budgetLevel: enum: - campaign type: string finalUrlSuffix: type: string manualCpc: description: >- Google Search and Display only. Manual CPC bidding. Enhanced CPC is not offered: Google no longer lets Search and Display campaigns enable it. Exclusive with every other strategy field. properties: maxCpc: description: >- Max CPC of the ad groups, in the account's currency units: set on the ad group created with the campaign, and on every ad group of the campaign when an update switches it to Manual CPC. Google gives an ad group without one a 0.01 bid. exclusiveMinimum: 0 type: number required: - maxCpc type: object networkSettings: description: >- Google Search campaigns only. Which networks the campaign serves on besides Google Search. properties: displayNetwork: description: >- campaign.network_settings.target_content_network (Search with Display expansion) type: boolean searchPartners: description: campaign.network_settings.target_search_network type: boolean type: object platformSpecificData: type: object portfolioBidStrategyId: description: >- Google only. Echoed back, but NOT mirrored onto local Ad documents (no column for it yet). type: string roasAverageFloor: type: number sharedBudgetId: description: >- Google only. Echoed back when the campaign moved budgets; `budget` is then the budget it now uses. type: - string - 'null' targetImpressionShare: description: >- Google only. Target impression share bidding (Search campaigns only): Google sets bids so the ads show in `location` for `percent` of eligible impressions. properties: location: enum: - ANYWHERE_ON_PAGE - TOP_OF_PAGE - ABSOLUTE_TOP_OF_PAGE type: string maxCpc: description: >- Max CPC bid limit, in the account's currency units. Google requires it. exclusiveMinimum: 0 type: number percent: description: >- Target share of impressions, in percent (65 = 65%). Sent to Google as location_fraction_micros (1% = 10,000). exclusiveMinimum: 0 maximum: 100 type: number required: - location - maxCpc - percent type: object trackingUrlTemplate: type: string updated: description: Local Ad documents mirrored. 0 on the empty-campaign path. type: integer type: object description: Campaign updated default: content: application/json: schema: properties: error: properties: code: type: - string - 'null' details: additionalProperties: {} type: - object - 'null' message: type: - string - 'null' param: type: - string - 'null' retryHint: type: - string - 'null' retryable: type: - boolean - 'null' type: type: - string - 'null' type: - object - 'null' type: object description: Error. The code field is stable; see the error catalog. components: securitySchemes: bearerAuth: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.