> ## 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 # Send conversion events > Conversions. Changes the ad account without starting or raising spend; audited. Sends conversion events, such as purchases or leads, from your server to an ad platform so it can attribute and optimize ads. Relays one or more events to the target ad platform's native Conversions API. The platform is inferred from the provided `connectionId`. Requires the Ads add-on. ### Supported platforms Meta (`metaads`) via Graph API A request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ. ## Request contract * **Method and path:** POST /apis/v1/ads/conversions * **Availability:** enabled * **Request URL template:** `https://api.aisa.one/apis/v1/ads/conversions` * **connectionId:** query; required * **Runtime facts:** fe60122939c67dc98a3a6ac6b97bd5c326b526105150c8959304dd2160d4dd09 [Complete OpenAPI definition](https://aisa.one/docs/reference-contracts/aisa-ads.json) Effective request and pricing declaration (including authentication and referenced schemas): ```json theme={null} { "operationId": "post_aisa_ads_apis_v1_ads_conversions", "method": "POST", "path": "/apis/v1/ads/conversions", "servers": [ { "url": "https://api.aisa.one" } ], "parameters": [ { "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" } } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "example": { "connectionId": "adc_7f3k2m9q", "destinationId": "1234567890", "events": [ { "eventId": "1234567890", "eventName": "example", "eventTime": 10, "user": { "city": "example", "clickIds": { "epik": "example", "fbc": "example" } } } ] }, "schema": { "additionalProperties": true, "properties": { "connectionId": { "description": "The ads connection (adc_...), when not sent as the connectionId query parameter.", "pattern": "^adc_[0-9A-Za-z]+$", "type": "string" }, "consent": { "description": "Batch-level user consent. Required by Google for EEA/UK events under the Feb 2026 restrictions.", "properties": { "adPersonalization": { "enum": [ "GRANTED", "DENIED" ], "type": "string" }, "adUserData": { "enum": [ "GRANTED", "DENIED" ], "type": "string" } }, "type": "object" }, "destinationId": { "description": "Platform destination identifier. For Meta, the pixel/dataset ID. For Google, the conversion action resource name. For LinkedIn, the conversion rule ID or full `urn:lla:llaPartnerConversion:{id}` URN. For OpenAI Ads, the pixel wire id.", "type": "string" }, "events": { "items": { "description": "A single conversion event to relay to the ad platform. Callers send plaintext.", "properties": { "actionSource": { "description": "Where the conversion happened. Used by Meta. Google also requires an event source internally; omitting this field sends OTHER to Google. Send an explicit value for accurate origin reporting.", "enum": [ "web", "app", "offline", "crm", "phone_call", "system_generated", "business_messaging" ], "type": "string" }, "currency": { "description": "ISO 4217 currency code.", "type": "string" }, "eventId": { "description": "Unique dedup key. Use the same eventId on pixel + CAPI to prevent double-counting. Mapped to: Meta: event_id. Google: transactionId. LinkedIn: eventId.", "type": "string" }, "eventName": { "description": "Standard event name (Purchase, Lead, CompleteRegistration, AddToCart, InitiateCheckout, AddPaymentInfo, Subscribe, StartTrial, ViewContent, Search, Contact, SubmitApplication, Schedule) or a custom string.", "type": "string" }, "eventTime": { "description": "When the conversion happened, in unix seconds.", "type": "integer" }, "items": { "description": "Item-level detail for ecommerce events.", "items": { "properties": { "category": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "price": { "type": "number" }, "quantity": { "type": "integer" } }, "type": "object" }, "type": "array" }, "messaging": { "description": "Meta only, read when `actionSource` is `business_messaging` (Conversions API for Business Messaging). `channel` is sent as the event's `messaging_channel` (`instagram_direct` goes out as `instagram`).", "properties": { "channel": { "enum": [ "whatsapp", "messenger", "instagram_direct" ], "type": "string" }, "ctwaClid": { "description": "WhatsApp only. Click-to-WhatsApp click id from the first inbound message referral, sent as `ctwa_clid`.", "type": "string" }, "instagramBusinessAccountId": { "description": "Instagram Direct only. Instagram professional account id (`instagram_business_account` on the Page), sent as `ig_account_id` next to `ig_sid`.", "type": "string" }, "instagramScopedUserId": { "description": "Instagram Direct only.", "type": "string" }, "pageId": { "description": "Messenger: Facebook Page id, sent as `page_id`.", "type": "string" }, "pageScopedUserId": { "description": "Messenger only.", "type": "string" }, "wabaId": { "description": "WhatsApp only. WhatsApp Business Account id, sent as `whatsapp_business_account_id`.", "type": "string" } }, "required": [ "channel" ], "type": "object" }, "platformData": { "additionalProperties": true, "description": "Escape hatch for platform-specific fields we haven't normalized. Use first-class fields (e.g. `user.leadId`) for anything that must reach `user_data`.", "type": "object" }, "sourceUrl": { "description": "URL where the conversion originated (used by Meta).", "format": "uri", "type": "string" }, "user": { "description": "User identity fields. More signals mean higher match rates.", "properties": { "city": { "description": "Meta advanced matching (ct). Plaintext city; normalized + SHA-256 hashed server-side. Meta only.", "type": "string" }, "clickIds": { "description": "Platform click identifiers captured from the originating ad click.", "properties": { "epik": { "description": "Pinterest click ID (the `epik` URL param or `_epik` cookie). Sent to Pinterest as `click_id`, not hashed.", "type": "string" }, "fbc": { "description": "Meta click ID (from fbclid URL param).", "type": "string" }, "fbp": { "description": "Meta browser ID (_fbp cookie).", "type": "string" }, "gbraid": { "description": "Google iOS 14.5+ app attribution ID.", "type": "string" }, "gclid": { "description": "Google click ID (from gclid URL param).", "type": "string" }, "li_fat_id": { "description": "LinkedIn first-party ad tracking click ID. Captured by parsing `li_fat_id` from landing-page URLs after the advertiser enables enhanced conversion tracking on the LinkedIn Insight Tag.", "type": "string" }, "rdt_cid": { "description": "Reddit click ID (the `rdt_cid` URL param Reddit adds to ad clicks). Sent to Reddit as `click_id`, not hashed.", "type": "string" }, "rdt_uuid": { "description": "Reddit Pixel browser id (the `_rdt_uuid` first-party cookie). Sent to Reddit as `user.uuid`, not hashed.", "type": "string" }, "wbraid": { "description": "Google iOS 14.5+ web-to-app attribution ID.", "type": "string" } }, "type": "object" }, "country": { "description": "ISO 3166-1 alpha-2 country code, e.g. 'us'.", "type": "string" }, "dob": { "description": "Meta advanced matching (db). YYYYMMDD; hashed server-side. Meta only.", "type": "string" }, "email": { "description": "Plaintext email. Hashed server-side.", "type": "string" }, "externalId": { "description": "Stable customer identifier (e.g. CRM user ID). Hashed server-side for Meta and Google. Sent as plaintext to LinkedIn (LinkedIn's Conversions API spec requires the raw value). Maximum effective list size on LinkedIn is 1.", "type": "string" }, "firstName": { "description": "Plaintext first name. Hashed server-side.", "type": "string" }, "gender": { "description": "Meta advanced matching (ge). 'f' or 'm'; hashed server-side. Meta only.", "type": "string" }, "ipAddress": { "description": "Client IP address. Sent plaintext.", "type": "string" }, "lastName": { "description": "Plaintext last name. Hashed server-side.", "type": "string" }, "leadId": { "description": "Meta lead ID from a Lead Ad submission, as a string. Required for Conversion Leads CRM events: send it with `actionSource: 'crm'` and `platformData: { event_source: 'crm', lead_event_source: '' }`.", "type": "string" }, "phone": { "description": "Phone number, ideally E.164. Hashed server-side.", "type": "string" }, "state": { "description": "Meta advanced matching (st). 2-letter ANSI for US; hashed server-side. Meta only.", "type": "string" }, "userAgent": { "description": "Client user-agent string. Sent plaintext.", "type": "string" }, "zip": { "description": "Meta advanced matching (zp). US uses first 5 digits; hashed server-side. Meta only.", "type": "string" } }, "type": "object" }, "value": { "description": "Conversion value in the specified currency.", "type": "number" } }, "required": [ "eventId", "eventName", "eventTime", "user" ], "type": "object" }, "minItems": 1, "type": "array" }, "testCode": { "description": "Test event code. Send it at the request root, never inside an event. A root-level `test_event_code` (Meta's own name) is accepted as an alias and must be a non-empty string; sending both with different values is a 400.", "type": "string" } }, "required": [ "destinationId", "events" ], "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" } } } } ``` ## Cost and request rules A request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ. Published reference values are not an account-specific quote or a settled charge. For endpoints supporting X-AISA-Cost-Mode: quote, obtain a free quote for your exact request before execution; reconcile the settled cost with response metadata and Usage Logs. USD amounts use 1,000,000 integer micro-USD per dollar. ## OpenAPI ````yaml reference-contracts/aisa-ads.json POST /apis/v1/ads/conversions 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/conversions: post: summary: Send conversion events description: >- Conversions. Changes the ad account without starting or raising spend; audited. Sends conversion events, such as purchases or leads, from your server to an ad platform so it can attribute and optimize ads. Relays one or more events to the target ad platform's native Conversions API. The platform is inferred from the provided `connectionId`. Requires the Ads add-on. ### Supported platforms Meta (`metaads`) via Graph API A request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ. operationId: post_aisa_ads_apis_v1_ads_conversions parameters: - 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 requestBody: content: application/json: example: connectionId: adc_7f3k2m9q destinationId: '1234567890' events: - eventId: '1234567890' eventName: example eventTime: 10 user: city: example clickIds: epik: example fbc: example schema: additionalProperties: true properties: connectionId: description: >- The ads connection (adc_...), when not sent as the connectionId query parameter. pattern: ^adc_[0-9A-Za-z]+$ type: string consent: description: >- Batch-level user consent. Required by Google for EEA/UK events under the Feb 2026 restrictions. properties: adPersonalization: enum: - GRANTED - DENIED type: string adUserData: enum: - GRANTED - DENIED type: string type: object destinationId: description: >- Platform destination identifier. For Meta, the pixel/dataset ID. For Google, the conversion action resource name. For LinkedIn, the conversion rule ID or full `urn:lla:llaPartnerConversion:{id}` URN. For OpenAI Ads, the pixel wire id. type: string events: items: description: >- A single conversion event to relay to the ad platform. Callers send plaintext. properties: actionSource: description: >- Where the conversion happened. Used by Meta. Google also requires an event source internally; omitting this field sends OTHER to Google. Send an explicit value for accurate origin reporting. enum: - web - app - offline - crm - phone_call - system_generated - business_messaging type: string currency: description: ISO 4217 currency code. type: string eventId: description: >- Unique dedup key. Use the same eventId on pixel + CAPI to prevent double-counting. Mapped to: Meta: event_id. Google: transactionId. LinkedIn: eventId. type: string eventName: description: >- Standard event name (Purchase, Lead, CompleteRegistration, AddToCart, InitiateCheckout, AddPaymentInfo, Subscribe, StartTrial, ViewContent, Search, Contact, SubmitApplication, Schedule) or a custom string. type: string eventTime: description: When the conversion happened, in unix seconds. type: integer items: description: Item-level detail for ecommerce events. items: properties: category: type: string id: type: string name: type: string price: type: number quantity: type: integer type: object type: array messaging: description: >- Meta only, read when `actionSource` is `business_messaging` (Conversions API for Business Messaging). `channel` is sent as the event's `messaging_channel` (`instagram_direct` goes out as `instagram`). properties: channel: enum: - whatsapp - messenger - instagram_direct type: string ctwaClid: description: >- WhatsApp only. Click-to-WhatsApp click id from the first inbound message referral, sent as `ctwa_clid`. type: string instagramBusinessAccountId: description: >- Instagram Direct only. Instagram professional account id (`instagram_business_account` on the Page), sent as `ig_account_id` next to `ig_sid`. type: string instagramScopedUserId: description: Instagram Direct only. type: string pageId: description: 'Messenger: Facebook Page id, sent as `page_id`.' type: string pageScopedUserId: description: Messenger only. type: string wabaId: description: >- WhatsApp only. WhatsApp Business Account id, sent as `whatsapp_business_account_id`. type: string required: - channel type: object platformData: additionalProperties: true description: >- Escape hatch for platform-specific fields we haven't normalized. Use first-class fields (e.g. `user.leadId`) for anything that must reach `user_data`. type: object sourceUrl: description: URL where the conversion originated (used by Meta). format: uri type: string user: description: >- User identity fields. More signals mean higher match rates. properties: city: description: >- Meta advanced matching (ct). Plaintext city; normalized + SHA-256 hashed server-side. Meta only. type: string clickIds: description: >- Platform click identifiers captured from the originating ad click. properties: epik: description: >- Pinterest click ID (the `epik` URL param or `_epik` cookie). Sent to Pinterest as `click_id`, not hashed. type: string fbc: description: Meta click ID (from fbclid URL param). type: string fbp: description: Meta browser ID (_fbp cookie). type: string gbraid: description: Google iOS 14.5+ app attribution ID. type: string gclid: description: Google click ID (from gclid URL param). type: string li_fat_id: description: >- LinkedIn first-party ad tracking click ID. Captured by parsing `li_fat_id` from landing-page URLs after the advertiser enables enhanced conversion tracking on the LinkedIn Insight Tag. type: string rdt_cid: description: >- Reddit click ID (the `rdt_cid` URL param Reddit adds to ad clicks). Sent to Reddit as `click_id`, not hashed. type: string rdt_uuid: description: >- Reddit Pixel browser id (the `_rdt_uuid` first-party cookie). Sent to Reddit as `user.uuid`, not hashed. type: string wbraid: description: Google iOS 14.5+ web-to-app attribution ID. type: string type: object country: description: ISO 3166-1 alpha-2 country code, e.g. 'us'. type: string dob: description: >- Meta advanced matching (db). YYYYMMDD; hashed server-side. Meta only. type: string email: description: Plaintext email. Hashed server-side. type: string externalId: description: >- Stable customer identifier (e.g. CRM user ID). Hashed server-side for Meta and Google. Sent as plaintext to LinkedIn (LinkedIn's Conversions API spec requires the raw value). Maximum effective list size on LinkedIn is 1. type: string firstName: description: Plaintext first name. Hashed server-side. type: string gender: description: >- Meta advanced matching (ge). 'f' or 'm'; hashed server-side. Meta only. type: string ipAddress: description: Client IP address. Sent plaintext. type: string lastName: description: Plaintext last name. Hashed server-side. type: string leadId: description: >- Meta lead ID from a Lead Ad submission, as a string. Required for Conversion Leads CRM events: send it with `actionSource: 'crm'` and `platformData: { event_source: 'crm', lead_event_source: '' }`. type: string phone: description: Phone number, ideally E.164. Hashed server-side. type: string state: description: >- Meta advanced matching (st). 2-letter ANSI for US; hashed server-side. Meta only. type: string userAgent: description: Client user-agent string. Sent plaintext. type: string zip: description: >- Meta advanced matching (zp). US uses first 5 digits; hashed server-side. Meta only. type: string type: object value: description: Conversion value in the specified currency. type: number required: - eventId - eventName - eventTime - user type: object minItems: 1 type: array testCode: description: >- Test event code. Send it at the request root, never inside an event. A root-level `test_event_code` (Meta's own name) is accepted as an alias and must be a non-empty string; sending both with different values is a 400. type: string required: - destinationId - events type: object required: true responses: '200': content: application/json: schema: properties: eventsFailed: description: Events rejected (see failures). type: integer eventsReceived: description: Events accepted by the platform. type: integer failures: items: properties: code: oneOf: - type: string - type: integer eventId: description: Echoes back the eventId of the failed event. type: string eventIndex: description: Index into the submitted events array. type: integer message: type: string platformError: additionalProperties: true description: >- Meta only. Meta's own error for the rejected chunk, with credentials redacted: `message`, `type`, `code`, `error_subcode`, `error_user_title`, `error_user_msg` and `fbtrace_id` when Meta sends them. type: object type: object type: array platform: enum: - metaads - googleads - linkedinads - tiktokads - openaiads - pinterestads - redditads type: string testCode: description: >- The test code sent to the platform, as received (from `testCode` or `test_event_code`). `null` when the request carried none, so the events were sent as production events. type: - string - 'null' traceId: description: >- Platform trace ID for debugging. fbtrace_id for Meta, requestId for Google. Absent for LinkedIn (LinkedIn's conversionEvents endpoint does not surface a trace ID), OpenAI Ads and Reddit (no trace ID surfaced). type: string type: object description: >- Events processed. Inspect `eventsFailed` and `failures[]` to detect partial failure. 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.