> ## 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 # Check account health > Accounts. Read only; needs social:read. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call. Returns detailed health info for a specific account including token status, permissions, and recommendations. A failing or stalled analytics sync (see `analyticsSync`) raises a healthy account to at least `warning`. ### Facebook, Instagram and Threads The token is also probed live. A probe Meta refuses with a dead-token error sets `tokenStatus.valid` to `false` and names Meta's code, subcode and fbtrace in `issues`. The exception: if an analytics sync succeeded with that token in the last six hours, the token stays `valid` and `issues` reports the probe as inconclusive, since Meta answers a transient 190 to live tokens now and then. Neither verdict disconnects the account. That happens only when a real operation fails, and `account.disconnected` is sent. ### WhatsApp The response also includes `platformConnection`, a live probe of the Meta link behind the channel (the same read as `GET /apis/v1/social/whatsapp/number-info`). The OAuth token can be perfectly valid while Meta refuses to serve the phone-number object (for example after a phone-side coexistence disconnect). So `tokenStatus` alone is not a liveness signal for WhatsApp. - When the Meta link is dead, `platformConnection.status` is `disconnected` and the overall `status` is `error`. - When Meta reports that the number's inbound message webhook does not reach AIsa, or subscribing the number's WhatsApp Business Account to AIsa's webhooks failed at connect, `platformConnection.inboundWebhookSubscribed` is `false`, an entry is added to `issues`, and the overall `status` is at least `warning`. - When `platformConnection.phoneStatus` is anything other than `CONNECTED`, an entry is added to `issues` and the overall `status` is at least `warning`; `BANNED` makes it `error`. `disconnectReason` stays null, since reconnecting does not lift a Meta status. ### Standalone ads connections (`googleads`, `redditads`, `microsoftads`) A connection that cannot serve requests until a fresh OAuth repairs it adds an entry to `issues`. It also adds a recommendation to call `GET /apis/v1/social/connect/{platform}/ads`, whose `authUrl` reconnects the same account. On `redditads` this is a connection authorized before AIsa needed a Reddit permission it now uses (for example `adsconversions`). Reddit refuses those requests until the user reconnects and allows every permission on Reddit's consent screen. 当前未提供请求参考价格；请使用接口支持的报价功能确认费用。 最终费用以账户适用价格及实际结算为准。 ## 请求规范 * **方法与路径:** GET /apis/v1/social/accounts/\{accountId}/health * **可用状态:** enabled * **请求 URL 模板:** `https://api.aisa.one/apis/v1/social/accounts/{accountId}/health` * **accountId:** path; 必填 * **Runtime 事实版本:** 99acb5bddbedc8d3352e7c4fef86c3e6d8852c14772bcd18dbcf415237a642bd [完整 OpenAPI 定义](https://aisa.one/docs/reference-contracts/zh/aisa-social.json) 有效请求与价格声明（包括认证和引用的 schema）： ```json theme={null} { "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_health", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/health", "servers": [ { "url": "https://api.aisa.one" } ], "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "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" } } } } ``` ## 费用与请求规则 当前未提供请求参考价格；请使用接口支持的报价功能确认费用。 最终费用以账户适用价格及实际结算为准。 公开参考值不是你的账户报价或最终扣费。对于支持 X-AISA-Cost-Mode: quote 的接口，执行前请针对完整请求获取免费报价；执行后通过响应费用元数据和 Usage Logs 核对结算费用。1 USD 等于 1,000,000 个整数 micro-USD。 ## OpenAPI ````yaml reference-contracts/zh/aisa-social.json GET /apis/v1/social/accounts/{accountId}/health 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/accounts/{accountId}/health: get: summary: Check account health description: >- Accounts. Read only; needs social:read. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call. Returns detailed health info for a specific account including token status, permissions, and recommendations. A failing or stalled analytics sync (see `analyticsSync`) raises a healthy account to at least `warning`. ### Facebook, Instagram and Threads The token is also probed live. A probe Meta refuses with a dead-token error sets `tokenStatus.valid` to `false` and names Meta's code, subcode and fbtrace in `issues`. The exception: if an analytics sync succeeded with that token in the last six hours, the token stays `valid` and `issues` reports the probe as inconclusive, since Meta answers a transient 190 to live tokens now and then. Neither verdict disconnects the account. That happens only when a real operation fails, and `account.disconnected` is sent. ### WhatsApp The response also includes `platformConnection`, a live probe of the Meta link behind the channel (the same read as `GET /apis/v1/social/whatsapp/number-info`). The OAuth token can be perfectly valid while Meta refuses to serve the phone-number object (for example after a phone-side coexistence disconnect). So `tokenStatus` alone is not a liveness signal for WhatsApp. - When the Meta link is dead, `platformConnection.status` is `disconnected` and the overall `status` is `error`. - When Meta reports that the number's inbound message webhook does not reach AIsa, or subscribing the number's WhatsApp Business Account to AIsa's webhooks failed at connect, `platformConnection.inboundWebhookSubscribed` is `false`, an entry is added to `issues`, and the overall `status` is at least `warning`. - When `platformConnection.phoneStatus` is anything other than `CONNECTED`, an entry is added to `issues` and the overall `status` is at least `warning`; `BANNED` makes it `error`. `disconnectReason` stays null, since reconnecting does not lift a Meta status. ### Standalone ads connections (`googleads`, `redditads`, `microsoftads`) A connection that cannot serve requests until a fresh OAuth repairs it adds an entry to `issues`. It also adds a recommendation to call `GET /apis/v1/social/connect/{platform}/ads`, whose `authUrl` reconnects the same account. On `redditads` this is a connection authorized before AIsa needed a Reddit permission it now uses (for example `adsconversions`). Reddit refuses those requests until the user reconnects and allows every permission on Reddit's consent screen. 当前未提供请求参考价格；请使用接口支持的报价功能确认费用。 最终费用以账户适用价格及实际结算为准。 operationId: get_aisa_social_apis_v1_social_accounts_accountid_health parameters: - description: One of your social accounts (acc_...). in: path name: accountId required: true schema: pattern: ^acc_[0-9A-Za-z]{22}$ type: string responses: '200': content: application/json: schema: properties: accountId: description: One of your social accounts (acc_...). pattern: ^acc_[0-9A-Za-z]{22}$ type: string analyticsSync: description: >- Absent on platforms without analytics sync. failing: several consecutive sync attempts failed. stalled: a sync was requested over 6 hours ago and never completed. never_synced: no sync has completed yet. Failing and stalled raise the account status to at least warning. properties: lastSyncedAt: description: >- Last successful sync. Null when never synced or the latest attempt failed. format: date-time type: - string - 'null' status: enum: - ok - failing - stalled - never_synced type: string type: object disconnectReason: description: >- Why the connection is broken or its token refresh is failing, from the most recent current cause. Null when the connection is healthy, including when the account is unhealthy for another reason (analytics, messaging restriction, missing analytics scopes, Meta phone status), or when no cause is stored. type: - string - 'null' disconnectionType: description: >- intentional: deliberately disconnected by the user or by AIsa (for example a plan downgrade), not a token failure. unintentional: token expired or revoked, or an auth failure. Null when disconnectReason is null. enum: - intentional - unintentional - null type: - string - 'null' displayName: type: string integrationLane: description: >- TikTok only. The TikTok integration the account is connected through: business (TikTok for Business, Accounts API) or developer (the original integration). Absent on other platforms. enum: - business - developer type: string issues: description: List of issues found items: type: string type: array messagingRestriction: description: >- Observed from Meta's own errors on our sends, not a live probe. It lags reality by one message in each direction. - **Facebook/Instagram:** error subcodes 2534122, 1893063, 2534029. Set on the first refused send, cleared when a later send succeeds. - **WhatsApp:** Cloud API error codes 131042 (payment or eligibility issue), 131031 (Business Account locked) and 368 (policy block). Set when a send or delivery status fails with one, cleared when a later message is delivered. After subcode 1893063 (Meta refusing the Page's messages), comment automation DMs are held and one is retried at `pausedUntil`: 30 minutes, doubling per refused retry up to 4 hours. Held DMs stay pending and are sent once Meta accepts again, within the 7-day private-reply window. properties: code: description: >- WhatsApp Cloud API error code. Null on Facebook and Instagram. type: - integer - 'null' firstSeenAt: format: date-time type: string lastSeenAt: format: date-time type: string message: type: - string - 'null' pausedUntil: description: >- When held automation DMs are next retried. Null when nothing is held. format: date-time type: - string - 'null' subcode: description: >- Meta error subcode (Facebook and Instagram). Null on WhatsApp. type: - integer - 'null' type: - object - 'null' ownerUserId: description: >- User id of the profile owner, not necessarily the team member who connected the account. type: string permissions: properties: analytics: items: properties: granted: type: boolean required: type: boolean scope: type: string type: object type: array canFetchAnalytics: type: boolean canPost: description: >- Whether the granted OAuth scopes allow posting. Scopes only: for WhatsApp, whether Meta lets the number send is `platformConnection.phoneStatus` and the overall `status`. type: boolean missingRequired: items: type: string type: array optional: items: properties: granted: type: boolean required: type: boolean scope: type: string type: object type: array posting: items: properties: granted: type: boolean required: type: boolean scope: type: string type: object type: array type: object platform: type: string platformConnection: description: >- WhatsApp accounts only. Live probe of the Meta link behind the channel, performed at request time (the same read as GET /apis/v1/social/whatsapp/number-info). properties: checkedAt: description: >- When this live probe ran (always the current request; never cached) format: date-time type: string inboundWebhookSubscribed: description: >- From the phone number's Meta health_status, overridden to `false` when subscribing the number's WhatsApp Business Account to AIsa's webhooks failed at connect. - `false`: Meta says AIsa is not subscribed to the message webhook for this number, or the subscribe failed when the number was connected, so inbound messages are not delivered, though the number is CONNECTED and can still send. - `false`, fix: re-subscribe (reconnect the number). If it stays `false`, the number is routed to a different WhatsApp Business Account (typically after linking it to a Facebook Page). - `true`: Meta reports no such problem. - `null`: Meta did not report it (read failed or no health_status); not evidence either way. type: - boolean - 'null' metaError: description: Set only when status is `disconnected` properties: code: description: Meta Graph error code (100) type: integer message: type: string subcode: description: Meta Graph error subcode (33) type: integer type: - object - 'null' phoneStatus: description: >- Meta's own `status` field from the phone-number node (for example CONNECTED), when the object was readable. Anything other than CONNECTED adds an issue and raises `status` (BANNED: error, others: warning). type: - string - 'null' status: description: >- `connected` = Meta served the channel object. `disconnected` = Meta refused to serve it (Graph error 100, subcode 33), which is how a phone-side coexistence disconnect surfaces. `unknown` = the live read failed for another reason (timeout, transient Meta error), not evidence either way. enum: - connected - disconnected - unknown type: string type: object push: description: >- Google and Microsoft only: state of the provider change-notification subscriptions behind `message.received` and `calendar.event.*`. `pending` means a granted area has no live subscription yet (retried every 6 hours), `failed` that renewals keep failing (reconnect the account). enum: - active - pending - failed - not_applicable type: string recommendations: description: Actionable recommendations to fix issues items: type: string type: array sendCap: description: >- Google and Microsoft only: today's outbound mail allowance for the mailbox. properties: limit: type: integer resetsAt: format: date-time type: string used: type: integer type: object status: description: Overall health status enum: - healthy - warning - error type: string tokenStatus: properties: expiresAt: format: date-time type: string expiresIn: description: Human-readable time until expiry type: string needsRefresh: description: Whether token expires within 24 hours type: boolean valid: description: Whether the token is valid type: boolean type: object unhealthySince: description: >- When the earliest current stored cause was recorded (the start of the outage); for an intentional disconnect, when it was disconnected. Null when the connection is healthy, including when the account is unhealthy for another reason (analytics, messaging restriction, missing analytics scopes, Meta phone status), or when unknown. format: date-time type: - string - 'null' username: type: string type: object description: Account health details 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. components: securitySchemes: bearerAuth: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.