> ## 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 # Sync an external post > Analytics. Changes your own setup; needs social:draft. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call. Fetch an account's latest external posts (published directly on the platform, not through AIsa) on demand. A newly published post is then retrievable within seconds instead of waiting for the background sync, which refreshes each account at most every ~90 minutes. Primary use case: verifying a submitted post. When a user publishes on the platform and immediately pastes the post URL into your app, call this with `accountId` plus `url` (or `postId`) to confirm the post exists and return its metadata. ### Behavior - Account access and connection state are checked before any platform call, including requests inside the debounce window. - Inactive accounts or accounts marked `needsReconnection` return `409` with code `ads_connection_required`. Stop scheduled retries for that account until it is reconnected, then read `GET /apis/v1/social/accounts` for its current account ID. - For connected accounts, we fetch the latest posts live from the platform, then match and return the submitted post. - Requests are debounced per account (~15s): if the account was synced inside that window, the live fetch is skipped. ### Account and platforms `accountId` is required, because a post URL or id alone cannot be resolved to an account. The account must be connected to AIsa (we use its token to read the platform). Supported for every platform with a listing API: Instagram, Facebook, TikTok, YouTube, X, Threads, Pinterest, Reddit, Bluesky, Google Business Profile, and LinkedIn organization accounts. ### Locating the post `url` accepts any format the platform uses, for example: - `instagram.com/p/…`, `instagram.com/reel/…` - `youtu.be/…`, `youtube.com/shorts/…` - `tiktok.com/@user/video/…`, `vm.tiktok.com` short links - `pinterest.com/pin/…` on any regional domain, and `pin.it` short links Pass `postId` (the platform media/video/pin id) as an alternative locator. ### LinkedIn personal profiles LinkedIn has no listing API for personal profiles, so a `url` is REQUIRED and imports that single post. Pass any LinkedIn post URL (`linkedin.com/posts/…`, `linkedin.com/feed/update/urn:li:activity:…`) or a `urn:li:share:…` / `urn:li:ugcPost:…` URN. It works for posts published outside AIsa and before the account was connected, at any age. The post must be authored by the connected member. Imported posts return full analytics (impressions, reach, reactions, comments, reshares, saves) and keep refreshing on the background analytics cycle. They carry no content/media, since LinkedIn does not expose them for personal profiles. `publishedAt` comes from the post id: - An activity URL (`linkedin.com/feed/update/urn:li:activity:…`) carries the publication time. - A `urn:li:share:…` / `urn:li:ugcPost:…` URN only carries the creation time, which is earlier for a post scheduled in another tool. Pass the activity URL for the exact publication date. Importing it again for a post already imported by its URN corrects `publishedAt` on the same record. Right after an import, the per-post `GET /apis/v1/social/analytics?postId=` read can show zeros for a few minutes while the metrics are ingested. This endpoint's response carries the fetched values immediately. ### TikTok Business accounts A `postId` or TikTok `url` that the listing has not stored is fetched from TikTok and imported as an external post, at any age, with its current metrics. ### Analytics delay Post-level analytics (reach, impressions) still carry the platform's own delay (e.g. ~24h on Instagram). This endpoint confirms the post exists and returns its metadata plus basic engagement (likes, comments), not delayed insights. 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/social/posts/sync-external * **Availability:** enabled * **Request URL template:** `https://api.aisa.one/apis/v1/social/posts/sync-external` * **Runtime facts:** 99acb5bddbedc8d3352e7c4fef86c3e6d8852c14772bcd18dbcf415237a642bd [Complete OpenAPI definition](https://aisa.one/docs/reference-contracts/aisa-social.json) Effective request and pricing declaration (including authentication and referenced schemas): ```json theme={null} { "operationId": "post_aisa_social_apis_v1_social_posts_sync_external", "method": "POST", "path": "/apis/v1/social/posts/sync-external", "servers": [ { "url": "https://api.aisa.one" } ], "parameters": [], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "example": { "accountId": "acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3" }, "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "postId": { "description": "The platform post/media/video id to locate, as an alternative to `url`. Optional.", "type": "string" }, "url": { "description": "The post URL to locate. Optional. Provide `url` or `postId` to return a specific post; omit both to refresh and return the account's recent posts.", "type": "string" } }, "required": [ "accountId" ], "type": "object" } } }, "required": true }, "x-aisa-status": "enabled", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "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-social.json POST /apis/v1/social/posts/sync-external openapi: 3.1.0 info: description: '' title: AIsa Social 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: 99acb5bddbedc8d3352e7c4fef86c3e6d8852c14772bcd18dbcf415237a642bd generator_version: '3' protocol_version: '1' schema_version: '1' composer_version: '27' response_pending: [] document_hash: sha256:7f9742cb1ea233c648dcb290fdfbf24e53a27dcf900ec1386f83a8ef2e6b1bf9 x-aisa-plans: builder: 1 display_plan: payg payg: 1 similarweb_payg: 1 team: 1 version: e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb x-aisa-provider: aisa-social x-aisa-catalogs: aisa-social: title: AIsa Social description: '' x-aisa-document: facts_hash: 99acb5bddbedc8d3352e7c4fef86c3e6d8852c14772bcd18dbcf415237a642bd 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/social/posts/sync-external: post: summary: Sync an external post description: >- Analytics. Changes your own setup; needs social:draft. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call. Fetch an account's latest external posts (published directly on the platform, not through AIsa) on demand. A newly published post is then retrievable within seconds instead of waiting for the background sync, which refreshes each account at most every ~90 minutes. Primary use case: verifying a submitted post. When a user publishes on the platform and immediately pastes the post URL into your app, call this with `accountId` plus `url` (or `postId`) to confirm the post exists and return its metadata. ### Behavior - Account access and connection state are checked before any platform call, including requests inside the debounce window. - Inactive accounts or accounts marked `needsReconnection` return `409` with code `ads_connection_required`. Stop scheduled retries for that account until it is reconnected, then read `GET /apis/v1/social/accounts` for its current account ID. - For connected accounts, we fetch the latest posts live from the platform, then match and return the submitted post. - Requests are debounced per account (~15s): if the account was synced inside that window, the live fetch is skipped. ### Account and platforms `accountId` is required, because a post URL or id alone cannot be resolved to an account. The account must be connected to AIsa (we use its token to read the platform). Supported for every platform with a listing API: Instagram, Facebook, TikTok, YouTube, X, Threads, Pinterest, Reddit, Bluesky, Google Business Profile, and LinkedIn organization accounts. ### Locating the post `url` accepts any format the platform uses, for example: - `instagram.com/p/…`, `instagram.com/reel/…` - `youtu.be/…`, `youtube.com/shorts/…` - `tiktok.com/@user/video/…`, `vm.tiktok.com` short links - `pinterest.com/pin/…` on any regional domain, and `pin.it` short links Pass `postId` (the platform media/video/pin id) as an alternative locator. ### LinkedIn personal profiles LinkedIn has no listing API for personal profiles, so a `url` is REQUIRED and imports that single post. Pass any LinkedIn post URL (`linkedin.com/posts/…`, `linkedin.com/feed/update/urn:li:activity:…`) or a `urn:li:share:…` / `urn:li:ugcPost:…` URN. It works for posts published outside AIsa and before the account was connected, at any age. The post must be authored by the connected member. Imported posts return full analytics (impressions, reach, reactions, comments, reshares, saves) and keep refreshing on the background analytics cycle. They carry no content/media, since LinkedIn does not expose them for personal profiles. `publishedAt` comes from the post id: - An activity URL (`linkedin.com/feed/update/urn:li:activity:…`) carries the publication time. - A `urn:li:share:…` / `urn:li:ugcPost:…` URN only carries the creation time, which is earlier for a post scheduled in another tool. Pass the activity URL for the exact publication date. Importing it again for a post already imported by its URN corrects `publishedAt` on the same record. Right after an import, the per-post `GET /apis/v1/social/analytics?postId=` read can show zeros for a few minutes while the metrics are ingested. This endpoint's response carries the fetched values immediately. ### TikTok Business accounts A `postId` or TikTok `url` that the listing has not stored is fetched from TikTok and imported as an external post, at any age, with its current metrics. ### Analytics delay Post-level analytics (reach, impressions) still carry the platform's own delay (e.g. ~24h on Instagram). This endpoint confirms the post exists and returns its metadata plus basic engagement (likes, comments), not delayed insights. 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_social_apis_v1_social_posts_sync_external parameters: [] requestBody: content: application/json: example: accountId: acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3 schema: properties: accountId: description: One of your social accounts (acc_...). pattern: ^acc_[0-9A-Za-z]{22}$ type: string postId: description: >- The platform post/media/video id to locate, as an alternative to `url`. Optional. type: string url: description: >- The post URL to locate. Optional. Provide `url` or `postId` to return a specific post; omit both to refresh and return the account's recent posts. type: string required: - accountId type: object required: true responses: '200': content: application/json: schema: properties: found: description: >- Present only when a locator (`url`/`postId`) was provided: whether the post was found. type: boolean post: description: >- The matched external post, or null when not found. Present only when a locator was provided. oneOf: - description: >- A post synced from a platform (published directly on the platform, not through AIsa). Returned by GET /apis/v1/social/posts?source=external and POST /apis/v1/social/posts/sync-external. Analytics are exposed separately via GET /apis/v1/social/analytics?source=external. properties: analytics: description: >- Engagement + insights for the post. `likes` and `comments` are available immediately after an on-demand sync (they come from the platform listing). `reach`, `impressions`, `views` depend on the platform's insights, which carry their own delay (e.g. ~24h on Instagram) and read 0 until the platform makes them available. properties: clicks: type: integer comments: type: integer engagementRate: description: >- Percentage, rounded to 2 decimals. Same definition as PostAnalytics.engagementRate: (likes + comments + shares + saves) / (impressions or reach or views) * 100, where the denominator is the first of the three that is non-zero. Clicks and follows are never counted. type: number impressions: type: integer lastUpdated: description: When these metrics were last refreshed format: date-time type: string likes: type: integer reach: type: integer saves: type: integer sends: type: integer shares: type: integer views: type: integer type: object content: description: Post caption / text type: string isAiGenerated: description: >- Instagram only: whether Instagram labeled the media as AI-generated. Absent when the platform did not report it. type: boolean isSharedToFeed: description: >- Instagram reels only: whether the reel is also shared to the main feed. Absent when the platform did not report it. type: boolean mediaAudioType: description: >- Instagram only: audio type of the media (MUSIC or ORIGINAL_SOUND). Absent when the platform did not report it. type: string mediaItems: description: Per-item media (for carousels / multi-media posts) items: type: object type: array mediaProductType: description: >- Instagram only: the platform media product type (e.g. FEED, REELS, STORY, AD). Absent when the platform did not report it. type: string mediaType: description: Media type (e.g. image, video, carousel) type: string platform: description: >- Platform the post belongs to (e.g. instagram, youtube, tiktok) type: string platformPostId: description: The platform's own post/media/video id type: string platformPostUrl: description: >- Canonical URL (permalink) of the post on the platform type: string publishedAt: description: When the post was published on the platform format: date-time type: string thumbnailUrl: description: Thumbnail URL type: string type: object - type: 'null' posts: description: >- The account's recent external posts. Present only when no locator was provided. items: description: >- A post synced from a platform (published directly on the platform, not through AIsa). Returned by GET /apis/v1/social/posts?source=external and POST /apis/v1/social/posts/sync-external. Analytics are exposed separately via GET /apis/v1/social/analytics?source=external. properties: analytics: description: >- Engagement + insights for the post. `likes` and `comments` are available immediately after an on-demand sync (they come from the platform listing). `reach`, `impressions`, `views` depend on the platform's insights, which carry their own delay (e.g. ~24h on Instagram) and read 0 until the platform makes them available. properties: clicks: type: integer comments: type: integer engagementRate: description: >- Percentage, rounded to 2 decimals. Same definition as PostAnalytics.engagementRate: (likes + comments + shares + saves) / (impressions or reach or views) * 100, where the denominator is the first of the three that is non-zero. Clicks and follows are never counted. type: number impressions: type: integer lastUpdated: description: When these metrics were last refreshed format: date-time type: string likes: type: integer reach: type: integer saves: type: integer sends: type: integer shares: type: integer views: type: integer type: object content: description: Post caption / text type: string isAiGenerated: description: >- Instagram only: whether Instagram labeled the media as AI-generated. Absent when the platform did not report it. type: boolean isSharedToFeed: description: >- Instagram reels only: whether the reel is also shared to the main feed. Absent when the platform did not report it. type: boolean mediaAudioType: description: >- Instagram only: audio type of the media (MUSIC or ORIGINAL_SOUND). Absent when the platform did not report it. type: string mediaItems: description: Per-item media (for carousels / multi-media posts) items: type: object type: array mediaProductType: description: >- Instagram only: the platform media product type (e.g. FEED, REELS, STORY, AD). Absent when the platform did not report it. type: string mediaType: description: Media type (e.g. image, video, carousel) type: string platform: description: >- Platform the post belongs to (e.g. instagram, youtube, tiktok) type: string platformPostId: description: The platform's own post/media/video id type: string platformPostUrl: description: >- Canonical URL (permalink) of the post on the platform type: string publishedAt: description: When the post was published on the platform format: date-time type: string thumbnailUrl: description: Thumbnail URL type: string type: object type: array synced: properties: postsFound: description: >- Posts returned by the platform listing during the on-demand sync type: integer postsSynced: description: Posts inserted or updated in AIsa type: integer skipped: description: >- True when the account was synced within the debounce window and no live fetch ran. type: boolean type: object type: object description: > Sync result. When `url` or `postId` is provided, returns the matched post (or `found: false`). When neither is provided, returns the account's freshly-synced recent posts. 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: enum: - never - after_delay - after_reconnect - reconcile_first - null 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. x-codeSamples: - lang: text label: Reference example source: >- # Fixed reference example. Playground inputs do not update this sample. curl --request POST \ --url https://api.aisa.one/apis/v1/social/posts/sync-external \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "accountId": "acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3" }' components: securitySchemes: bearerAuth: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.