{ "components": { "securitySchemes": { "bearerAuth": { "scheme": "bearer", "type": "http" } } }, "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.0, "display_plan": "payg", "payg": 1.0, "similarweb_payg": 1.0, "team": 1.0, "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.0, "display_plan": "payg", "payg": 1.0, "similarweb_payg": 1.0, "team": 1.0, "version": "e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb" }, "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "header": "X-AISA-Cost-Mode", "value": "quote" } } } } }, "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "openapi": "3.1.0", "security": [ { "bearerAuth": [] } ], "servers": [ { "url": "https://api.aisa.one" } ], "paths": { "/apis/v1/social/account-groups": { "get": { "description": "Account Groups. 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.\n\nReturns all account groups visible to the authenticated user. Groups can\ncontain accounts from multiple profiles. For API keys scoped to specific\nprofiles, only groups whose accounts all live in allowed profiles are\nreturned.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_account_groups", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "groups": { "items": { "properties": { "_id": { "type": "string" }, "accountIds": { "description": "Your social accounts (acc_...).", "items": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "type": "array" }, "name": { "type": "string" }, "profileId": { "description": "One of your profiles (prf_...).", "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Groups" }, "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." } }, "summary": "List groups", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.account_groups.list_account_groups@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "6f130524dc1413d155c7c528accf58e79a4fa7dfa3e8fccf27eda0b0e4f267ee" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_account_groups", "method": "GET", "path": "/apis/v1/social/account-groups" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_account_groups" }, "post": { "description": "Account Groups. 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.\n\nCreates a new account group with a name and a list of account IDs.\nAccounts can belong to different profiles; the caller must have access to\nevery account's profile. Group names must be unique per user.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_account_groups", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "accountIds": [ "acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3", "acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3" ], "name": "Marketing Accounts" }, "schema": { "properties": { "accountIds": { "description": "Your social accounts (acc_...).", "items": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "type": "array" }, "name": { "type": "string" }, "profileId": { "description": "One of your profiles (prf_...).", "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" } }, "required": [ "accountIds", "name" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "group": { "properties": { "_id": { "type": "string" }, "accountIds": { "description": "Your social accounts (acc_...).", "items": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "type": "array" }, "name": { "type": "string" } }, "type": "object" }, "message": { "type": "string" } }, "type": "object" } } }, "description": "Created" }, "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." } }, "summary": "Create group", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.account_groups.create_account_group@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "10d115869801efe29328c1ee20de480bae6067f05a5e9fc4ab175b191b73c811" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_account_groups", "method": "POST", "path": "/apis/v1/social/account-groups" }, "x-codeSamples": [ { "lang": "text", "label": "Reference example", "source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/social/account-groups \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"accountIds\": [\n \"acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3\",\n \"acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3\"\n ],\n \"name\": \"Marketing Accounts\"\n}'" } ], "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_account_groups" } }, "/apis/v1/social/account-groups/{groupId}": { "delete": { "description": "Account Groups. 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.\n\nPermanently deletes an account group. The accounts themselves are not affected.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "delete_aisa_social_apis_v1_social_account_groups_groupid", "parameters": [ { "in": "path", "name": "groupId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } }, "description": "Deleted" }, "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." } }, "summary": "Delete group", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.account_groups.delete_account_group@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "971950fc4dff2c5fb4f2d74747427a1f9cbbf8870f5d3c94ed260e3e46e5a6f4" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "delete_aisa_social_apis_v1_social_account_groups_groupid", "method": "DELETE", "path": "/apis/v1/social/account-groups/{groupId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/delete_aisa_social_apis_v1_social_account_groups_groupid" }, "put": { "description": "Account Groups. 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.\n\nUpdates the name or account list of an existing group. You can rename the group, change its accounts, or both.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "put_aisa_social_apis_v1_social_account_groups_groupid", "parameters": [ { "in": "path", "name": "groupId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "accountIds": [ "acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3", "acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3", "acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3" ], "name": "Updated Marketing Accounts" }, "schema": { "properties": { "accountIds": { "description": "Your social accounts (acc_...).", "items": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "type": "array" }, "name": { "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "group": { "type": "object" }, "message": { "type": "string" } }, "type": "object" } } }, "description": "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": { "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." } }, "summary": "Update group", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.account_groups.update_account_group@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "919f6ed90320352332a117362133f2bdb1c4de570350a0b0d6126b442037dbbc" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "put_aisa_social_apis_v1_social_account_groups_groupid", "method": "PUT", "path": "/apis/v1/social/account-groups/{groupId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/put_aisa_social_apis_v1_social_account_groups_groupid" } }, "/apis/v1/social/accounts": { "get": { "description": "\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts", "parameters": [ { "description": "A prf_ id.", "in": "query", "name": "profileId", "required": false, "schema": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Filter by platform.", "in": "query", "name": "platform", "required": false, "schema": { "enum": [ "tiktok", "instagram", "twitter", "youtube", "facebook", "linkedin", "pinterest", "threads", "reddit", "googlebusiness", "googleanalytics", "bluesky", "telegram", "slack", "snapchat", "hubspot", "microsoft", "x" ], "type": "string" } }, { "description": "Page size, default 20.", "in": "query", "name": "limit", "required": false, "schema": { "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque cursor from the previous page's nextCursor.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "avatarUrl": { "type": [ "string", "null" ] }, "connectedAt": { "format": "date-time", "type": [ "string", "null" ] }, "displayName": { "type": [ "string", "null" ] }, "followersCount": { "type": [ "integer", "null" ] }, "id": { "type": [ "string", "null" ] }, "platform": { "enum": [ "tiktok", "instagram", "twitter", "youtube", "facebook", "linkedin", "pinterest", "threads", "reddit", "googlebusiness", "googleanalytics", "bluesky", "telegram", "slack", "snapchat", "hubspot", "microsoft", null ], "type": [ "string", "null" ] }, "platformAccountId": { "type": [ "string", "null" ] }, "profileId": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "syncedAt": { "format": "date-time", "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "nextCursor": { "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Success" }, "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." } }, "summary": "List connected accounts", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.accounts.list@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "This operation does not settle a customer usage charge.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "496bfc4fa43135bbda4f5e51672bda1febe141ab04bf9331d9ed0fab3588a069" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts", "method": "GET", "path": "/apis/v1/social/accounts" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts" } }, "/apis/v1/social/accounts/follower-stats": { "get": { "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. Without profileId or accountId it reads your default profile.\n\nReturns follower count history and growth metrics for connected accounts.\nRequires analytics add-on subscription. Follower counts are refreshed once per day.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_follower_stats", "parameters": [ { "description": "Your social accounts (acc_...). Comma-separated.", "in": "query", "name": "accountIds", "required": false, "schema": { "description": "Comma-separated.", "type": "string" } }, { "description": "One of your profiles (prf_...). Defaults to your default profile when neither profileId nor accountId is sent.", "in": "query", "name": "profileId", "required": false, "schema": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Start date in YYYY-MM-DD format (defaults to 30 days ago)", "in": "query", "name": "fromDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "End date in YYYY-MM-DD format (defaults to today)", "in": "query", "name": "toDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Data aggregation level", "in": "query", "name": "granularity", "required": false, "schema": { "default": "daily", "enum": [ "daily", "weekly", "monthly" ], "type": "string" } }, { "description": "Accounts per page, ordered by account id. Send it to page through accounts; the response then carries `pagination.nextCursor`. Without limit or cursor every matching account is returned.", "in": "query", "name": "limit", "required": false, "schema": { "maximum": 25, "minimum": 1, "type": "integer" } }, { "description": "Opaque cursor from a previous response's `pagination.nextCursor`; returns the next page of `limit` accounts (25 when limit is omitted). A cursor we cannot parse returns 400.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "accounts": { "items": { "properties": { "_id": { "type": "string" }, "accountStats": { "description": "Platform-specific account stats from the latest daily snapshot.\nFields vary by platform. Only present if metadata has been captured.", "properties": { "boardCount": { "description": "Total boards (Pinterest)", "type": "number" }, "followingCount": { "description": "Number of accounts being followed", "type": "number" }, "likesCount": { "description": "Total likes received (TikTok)", "type": "number" }, "listedCount": { "description": "Lists the user appears on (X)", "type": "number" }, "mediaCount": { "description": "Total media posts (Instagram)", "type": "number" }, "monthlyViews": { "description": "Monthly profile views (Pinterest)", "type": "number" }, "pinCount": { "description": "Total pins (Pinterest)", "type": "number" }, "postsCount": { "description": "Total posts (Bluesky)", "type": "number" }, "totalViews": { "description": "Total channel views (YouTube)", "type": "number" }, "tweetCount": { "description": "Total tweets (X)", "type": "number" }, "videoCount": { "description": "Total videos (YouTube, TikTok)", "type": "number" } }, "type": "object" }, "currentFollowers": { "description": "Current follower count", "type": "number" }, "dataPoints": { "description": "Number of historical snapshots", "type": "number" }, "displayName": { "type": "string" }, "enabled": { "description": "Whether the user explicitly activated this account. false means the account was created as a side effect (e.g., a posting account auto-created when the user connected ads first).\n\n- GET /apis/v1/social/accounts still returns such accounts unless `excludeHidden=true` is passed.\n- They cannot be posted to (`ACCOUNT_NOT_ENABLED_FOR_POSTING`) and are not billed as connected accounts.\n- On an ads account (`metaads`, `googleads`, ...) the value does not hide the connection: ads accounts are listed whatever their `enabled` value and keep working for ads.", "type": "boolean" }, "followersCount": { "description": "Follower count (only included if user has analytics add-on)", "type": "number" }, "followersLastUpdated": { "description": "Last time follower count was updated (only included if user has analytics add-on)", "format": "date-time", "type": "string" }, "growth": { "description": "Follower change over period", "type": "number" }, "growthPercentage": { "description": "Percentage growth", "type": "number" }, "isActive": { "type": "boolean" }, "lastUpdated": { "format": "date-time", "type": "string" }, "metadata": { "description": "Platform-specific metadata. Fields vary by platform.\n\n**WhatsApp accounts:**\n\n- qualityRating: phone number quality rating from Meta (GREEN, YELLOW, RED, or UNKNOWN).\n- nameStatus: display name review status (APPROVED, PENDING_REVIEW, DECLINED, or NONE). A declined or pending name does not by itself block sending; sendability is reported separately via health_status (can_send_message).\n- messagingLimitTier: maximum unique business-initiated conversations per 24h rolling window (TIER_250, TIER_1K, TIER_10K, TIER_100K, or TIER_UNLIMITED). Scales automatically as quality rating improves.\n- verifiedName: Meta-verified business display name.\n- displayPhoneNumber: formatted phone number (e.g., \"+1 555-123-4567\").\n- wabaId: WhatsApp Business Account ID.\n- phoneNumberId: Meta phone number ID.\n\n**Meta ads business-login accounts:**\n\n- tokenType: system-user.\n- businessId: the owning Business Manager ID when there is one owner; null for multiple owners.\n- businessIds: owning Business Manager IDs discovered from granted ad accounts.\n- grantedAdAccountIds: ad-account IDs granted to the token.\n- adAccountBusinesses: map from ad-account ID to its owning business ID or null.\n- availablePages: granted Page IDs and names. No Page tokens are exposed.\n- selectedPageId: the Page selected for creatives and lead forms, or null.\n- scopedAdAccountIds: existing sync scope preserved on reconnect.\n\nNon-expiring tokens have no tokenExpiresAt field. Parent posting reconnects do not replace this token.\n\n**LinkedIn accounts:** profileData carries profile details refreshed on each daily snapshot.\n\n- profileData.bio: the member's headline (personal accounts) or the organization description (organization accounts). null when not set.\n- profileData.extraData.vanityName: the member's profile slug, the /in/{vanityName} segment of profileUrl. Personal accounts only; an organization's slug is in metadata.organizationInfo.vanityName.\n\n**Instagram accounts:**\n\n- loginMethod: \"facebook_login\" when connected through Facebook Login; absent for Instagram Login. On facebook_login accounts, comment reads leave hidden comments out entirely instead of returning them with isHidden true.\n- instagramScopedId: the Instagram professional account id (`17841...`). On Instagram Login accounts it is the same whichever app connected the account, while platformUserId is app-scoped. Facebook Login accounts hold this id as platformUserId.\n\n**X (Twitter) accounts:**\n\n- profileData.extraData.isPremium: whether X reports a paid subscription (Basic, Premium, Premium+, or a blue verified badge), which raises the post length limit from 280 to 25,000 characters. Read live at connect and reconnect, refreshed by the daily follower snapshot.\n- Because X intermittently reports no subscription for subscribed accounts, a cancellation is stored on the fourth consecutive daily snapshot reporting it (about four days). Accounts connected before the extraData layout carry the flag at profileData.isPremium.", "type": "object" }, "needsReconnection": { "description": "The platform definitively reported the stored OAuth token as dead.\nWhile true, GET /apis/v1/social/connect/{platform}/ads returns a\nfresh authUrl (implicit force=true) instead of alreadyConnected,\nso re-running the connect flow recovers the account. Cleared\nautomatically when the account is re-authorized.", "type": "boolean" }, "parentAccountId": { "description": "Reference to the parent posting social account. Set for ads accounts that share\nor derive from a posting account's OAuth token. null for standalone ads (Google Ads)\nand all posting accounts. Meta ads business-login accounts also have no parent.", "type": [ "string", "null" ] }, "platform": { "enum": [ "tiktok", "instagram", "facebook", "youtube", "linkedin", "twitter", "threads", "pinterest", "reddit", "bluesky", "googlebusiness", "telegram", "snapchat", "discord", "slack", "whatsapp", "shopify", "wordpress", "wix", "linkedinads", "metaads", "pinterestads", "tiktokads", "xads", "googleads", "openaiads", "redditads", "sms", "phone", "rcs", "whopads", "google", "microsoft", "hubspot", "webflow", "googleanalytics", "imessage", "tiktokshop", "microsoftads" ], "type": "string" }, "platformUserId": { "description": "The account's id on its platform, as the platform reports it to AIsa. Stable across reconnects, so use it to match an account against your own records.\n\n- **Instagram Login accounts:** the app-scoped user id (the professional account id is in `metadata.instagramScopedId`).\n- **Instagram via Facebook Login:** the professional account id (`17841...`).\n- **TikTok:** the open_id of AIsa's TikTok app, which differs from the open_id any other app sees for the same user.\n\nEither value can be passed back as `expectedPlatformUserId` on GET /apis/v1/social/connect/{platform}.", "type": "string" }, "profileId": { "description": "One of your profiles (prf_...).", "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" }, "profilePicture": { "description": "URL to the account's profile picture on the platform. May be null if the platform does not provide one.", "type": [ "string", "null" ] }, "profileUrl": { "description": "Full profile URL for the connected account on its platform.", "type": "string" }, "rateLimitedUntil": { "description": "End of the account's publishing cooldown. Compare it with the current time: a value in the past means the cooldown has ended (the field is cleared on the next successful publish); null means no cooldown since the last successful publish.\n\n**When it starts.** A post to the account fails with `errorCategory` `user_abuse` (spam, abuse or rate-limit errors), or 10 or more posts to it fail within an hour with `user_content`, `platform_error`, `platform_rate_limit` or `unknown`.\n\n**How long.** It doubles with each start inside a 24-hour window that opens at the first one (10, 20, 40, 80 minutes and so on, capped at 24 hours).\n\nOn a YouTube account with a recorded successful upload, it instead runs until 24 hours after that upload, or 1 hour when that upload is older than 24 hours.\n\n**Effect.** While it is in the future, POST /apis/v1/social/posts (drafts excepted) and POST /apis/v1/social/posts/{postId}/retry return 429 for this account. When it starts, this account's pending targets on posts scheduled before the cooldown ends are failed.", "format": "date-time", "type": [ "string", "null" ] }, "scopeAreas": { "description": "Accounts connected through your own OAuth app: the permission areas the connect requested. Null on accounts connected through AIsa's app.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "tiktokAccountType": { "description": "TikTok accounts only. The account type TikTok reported when the account was connected.\n\n- `personal`: cannot use TikTok direct messages through the API (TikTok limits Business Messaging to Business Accounts). Skip the inbox for them and tell the user to switch to a Business Account in the TikTok app, then reconnect.\n- `business`: the prerequisite, not a guarantee. Messaging also needs the messaging scopes granted and TikTok's regional availability.\n- `unknown`: accounts connected before this was captured, or whose grant left out the account-type scope.", "enum": [ "business", "personal", "unknown" ], "type": "string" }, "username": { "type": "string" } }, "required": [ "_id", "isActive", "platform", "profileId" ], "type": "object" }, "type": "array" }, "dateRange": { "properties": { "from": { "format": "date-time", "type": "string" }, "to": { "format": "date-time", "type": "string" } }, "type": "object" }, "granularity": { "type": "string" }, "pagination": { "properties": { "limit": { "type": "integer" }, "nextCursor": { "description": "Opaque cursor for the next page; pass it back as `cursor`. Null on the last page.", "type": [ "string", "null" ] } }, "required": [ "limit", "nextCursor" ], "type": "object" }, "stats": { "additionalProperties": { "items": { "properties": { "date": { "format": "date", "type": "string" }, "followers": { "type": "number" } }, "type": "object" }, "type": "array" }, "type": "object" } }, "type": "object" } } }, "description": "Follower stats" }, "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." } }, "summary": "Get follower stats", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.accounts.get_follower_stats@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "059f33ac1759594cb283d99391f0b3c6899be560721ad6ee1a802cb9e445360b" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_follower_stats", "method": "GET", "path": "/apis/v1/social/accounts/follower-stats" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_follower_stats" } }, "/apis/v1/social/accounts/health": { "get": { "description": "\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_health", "parameters": [ { "description": "A prf_ id.", "in": "query", "name": "profileId", "required": false, "schema": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "accountId": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "checkedAt": { "format": "date-time", "type": [ "string", "null" ] }, "issues": { "items": { "properties": { "code": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "needsReconnect": { "type": [ "boolean", "null" ] }, "platform": { "enum": [ "tiktok", "instagram", "twitter", "youtube", "facebook", "linkedin", "pinterest", "threads", "reddit", "googlebusiness", "googleanalytics", "bluesky", "telegram", "slack", "snapchat", "hubspot", "microsoft", null ], "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "nextCursor": { "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Success" }, "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." } }, "summary": "Check account health", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.accounts.health@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "This operation does not settle a customer usage charge.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "42c2f0cd043a144bf6dceff39de01b4013a21fe5b5bf1b6a38c9f3ab511e29db" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_health", "method": "GET", "path": "/apis/v1/social/accounts/health" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_health" } }, "/apis/v1/social/accounts/{accountId}": { "delete": { "description": "\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "delete_aisa_social_apis_v1_social_accounts_accountid", "parameters": [ { "in": "path", "name": "accountId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "avatarUrl": { "type": [ "string", "null" ] }, "connectedAt": { "format": "date-time", "type": [ "string", "null" ] }, "displayName": { "type": [ "string", "null" ] }, "followersCount": { "type": [ "integer", "null" ] }, "id": { "type": [ "string", "null" ] }, "platform": { "enum": [ "tiktok", "instagram", "twitter", "youtube", "facebook", "linkedin", "pinterest", "threads", "reddit", "googlebusiness", "googleanalytics", "bluesky", "telegram", "slack", "snapchat", "hubspot", "microsoft", null ], "type": [ "string", "null" ] }, "platformAccountId": { "type": [ "string", "null" ] }, "profileId": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "syncedAt": { "format": "date-time", "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Success" }, "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." } }, "summary": "Disconnect an account", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.accounts.disconnect@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "This operation does not settle a customer usage charge.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "15890bdf962653ac7fbe9d69422309621a7a4f969b1c38e8ccf2b1e7a61bb60c" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "delete_aisa_social_apis_v1_social_accounts_accountid", "method": "DELETE", "path": "/apis/v1/social/accounts/{accountId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/delete_aisa_social_apis_v1_social_accounts_accountid" }, "put": { "description": "Accounts. 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. xCapabilities is not accepted: turns on X background reads, which X bills per call.\n\nUpdates a connected account's display name or username override.\n\n### X capabilities\n\nFor X accounts on usage-based billing, also accepts an `xCapabilities` object to toggle background API operations that incur X API pass-through costs.\n\n- Both fields are opt-in (default `false`).\n- When off, no analytics syncs or DM polling are performed for that account, and no API call is metered for those operations.\n- Publishing and deleting posts are always available regardless of these toggles.\n- Setting `xCapabilities` on a non-X account returns 400.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "put_aisa_social_apis_v1_social_accounts_accountid", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "displayName": "Acme Corporation Official" }, "schema": { "properties": { "displayName": { "type": "string" }, "username": { "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "displayName": { "type": "string" }, "message": { "type": "string" }, "username": { "type": "string" }, "xCapabilities": { "description": "Echo of the resulting `xCapabilities` state, returned only\nwhen the request body included an `xCapabilities` object.", "properties": { "analytics": { "type": "boolean" }, "inbox": { "type": "boolean" } }, "type": "object" } }, "type": "object" } } }, "description": "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": { "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." } }, "summary": "Update account", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.accounts.update_account@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "52f0e54e3bd788b9b1a17ea73900a704531d6fc8eb398235daf49db073832079" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "put_aisa_social_apis_v1_social_accounts_accountid", "method": "PUT", "path": "/apis/v1/social/accounts/{accountId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/put_aisa_social_apis_v1_social_accounts_accountid" } }, "/apis/v1/social/accounts/{accountId}/blogs": { "get": { "description": "Blogs. 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.\n\nLists blogs on the connected account. Supported on Shopify (`shopify`), WordPress (`wordpress`), Wix (`wix`) and Webflow (`webflow`).\n\n### By platform\n\n- Shopify: returns its store blogs with cursor pagination.\n- WordPress or Wix: the account represents one site and always returns exactly that one blog with `nextCursor: null`.\n- Webflow: returns each CMS collection that has a rich text field (its blog id is the collection id), with `nextCursor: null`.\n\n### Pagination\n\n`limit` is 1-50 (default 20). Treat `nextCursor` as opaque; pass it unchanged on the next request.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_blogs", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Page size (1-50).", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 50, "minimum": 1, "type": "integer" } }, { "description": "Opaque cursor from a previous response. Omit for the first page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "blogs": { "items": { "description": "A blog container on the connected platform. All content lives on the platform; AIsa proxies it and stores nothing.", "properties": { "handle": { "description": "URL slug on Shopify and Webflow (the collection slug); site hostname on WordPress and Wix.", "type": "string" }, "id": { "description": "Platform-native blog id. Shopify uses a numeric blog id. WordPress.com uses the numeric site id; self-hosted WordPress and Wix use `1`, scoped to the connected account. Webflow uses the CMS collection id.", "type": "string" }, "platform": { "enum": [ "shopify", "wordpress", "wix", "webflow" ], "type": "string" }, "title": { "type": "string" } }, "type": "object" }, "type": "array" }, "nextCursor": { "description": "Cursor for the next page; null when there are no more pages.", "type": [ "string", "null" ] }, "platform": { "enum": [ "shopify", "wordpress", "wix", "webflow" ], "type": "string" } }, "type": "object" } } }, "description": "Blogs listed" }, "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." } }, "summary": "List blogs", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.blogs.list_blogs@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "07fb73b5be9162619ad22184e357414d0d3a8949e0243bc41aa8b0c132b47d37" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_blogs", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/blogs" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_blogs" }, "post": { "description": "Blogs. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nCreates a blog on the connected store. The platform generates the URL\n`handle` from the title when omitted.\n\nSupported on Shopify (platform `shopify`). A WordPress or Wix\nconnection is its existing site, so both return 405 for blog creation.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_accounts_accountid_blogs", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "title": "example" }, "schema": { "properties": { "handle": { "description": "URL slug. Generated from the title when omitted.", "minLength": 1, "type": "string" }, "title": { "minLength": 1, "type": "string" } }, "required": [ "title" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "blog": { "description": "A blog container on the connected platform. All content lives on the platform; AIsa proxies it and stores nothing.", "properties": { "handle": { "description": "URL slug on Shopify and Webflow (the collection slug); site hostname on WordPress and Wix.", "type": "string" }, "id": { "description": "Platform-native blog id. Shopify uses a numeric blog id. WordPress.com uses the numeric site id; self-hosted WordPress and Wix use `1`, scoped to the connected account. Webflow uses the CMS collection id.", "type": "string" }, "platform": { "enum": [ "shopify", "wordpress", "wix", "webflow" ], "type": "string" }, "title": { "type": "string" } }, "type": "object" }, "platform": { "enum": [ "shopify" ], "type": "string" } }, "type": "object" } } }, "description": "Blog created" }, "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." } }, "summary": "Create a blog", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.blogs.create_blog@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "983d84b15e6cd783c28133aeaacd4c19a5ff3d23fb0cbc3633e914c7dbeb4b63" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_accounts_accountid_blogs", "method": "POST", "path": "/apis/v1/social/accounts/{accountId}/blogs" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_accounts_accountid_blogs" } }, "/apis/v1/social/accounts/{accountId}/blogs/{blogId}": { "delete": { "description": "Blogs. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nDeletes the blog AND every article in it. The delete happens on the\nplatform and is permanent; AIsa stores nothing to restore it from.\n\nSupported on Shopify (platform `shopify`). Disconnect a WordPress or\nWix account instead of deleting its site; both return 405 here.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "delete_aisa_social_apis_v1_social_accounts_accoun_710a82", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Platform-native blog id. Shopify blog ids are numeric; other values return 400.", "in": "path", "name": "blogId", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } } ], "responses": { "204": { "content": { "application/json": { "schema": { "description": "An empty object or a success flag.", "properties": { "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Blog deleted (no content)." }, "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." } }, "summary": "Delete a blog", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.blogs.delete_blog@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "74159940857ea7b88c536769aa4b7420404d88a2e994da0ec9582d569bfd10e9" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "delete_aisa_social_apis_v1_social_accounts_accoun_710a82", "method": "DELETE", "path": "/apis/v1/social/accounts/{accountId}/blogs/{blogId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/delete_aisa_social_apis_v1_social_accounts_accoun_710a82" }, "get": { "description": "Blogs. 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.\n\nFetches a single blog. Use the platform-native `blogId` returned by\n`GET /apis/v1/social/accounts/{accountId}/blogs`: a Shopify numeric blog id, the\nWordPress.com numeric site id, or `1` for a self-hosted WordPress or a\nWix site. That `1` is scoped to its connected account.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_710a82", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Platform-native blog/site id returned by the list operation.", "in": "path", "name": "blogId", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "blog": { "description": "A blog container on the connected platform. All content lives on the platform; AIsa proxies it and stores nothing.", "properties": { "handle": { "description": "URL slug on Shopify and Webflow (the collection slug); site hostname on WordPress and Wix.", "type": "string" }, "id": { "description": "Platform-native blog id. Shopify uses a numeric blog id. WordPress.com uses the numeric site id; self-hosted WordPress and Wix use `1`, scoped to the connected account. Webflow uses the CMS collection id.", "type": "string" }, "platform": { "enum": [ "shopify", "wordpress", "wix", "webflow" ], "type": "string" }, "title": { "type": "string" } }, "type": "object" }, "platform": { "enum": [ "shopify", "wordpress", "wix", "webflow" ], "type": "string" } }, "type": "object" } } }, "description": "Blog fetched" }, "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." } }, "summary": "Get a blog", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.blogs.get_blog@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "07cd88282c6e8b6e7606f778e68f62ae08a182cc95ba891230cd1a1e18ad470d" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_710a82", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/blogs/{blogId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_710a82" }, "patch": { "description": "Blogs. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nPartial-updates a blog. Send any subset of `title` and `handle`; at\nleast one field is required (an empty body returns 400).\n\nSupported on Shopify (platform `shopify`). WordPress and Wix site\nsettings are not writable through this API, so both return 405.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "patch_aisa_social_apis_v1_social_accounts_account_710a82", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Platform-native blog id. Shopify blog ids are numeric; other values return 400.", "in": "path", "name": "blogId", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "description": "At least one field is required.", "properties": { "handle": { "description": "URL slug. Changing it changes the blog URL on the store.", "minLength": 1, "type": "string" }, "title": { "minLength": 1, "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "blog": { "description": "A blog container on the connected platform. All content lives on the platform; AIsa proxies it and stores nothing.", "properties": { "handle": { "description": "URL slug on Shopify and Webflow (the collection slug); site hostname on WordPress and Wix.", "type": "string" }, "id": { "description": "Platform-native blog id. Shopify uses a numeric blog id. WordPress.com uses the numeric site id; self-hosted WordPress and Wix use `1`, scoped to the connected account. Webflow uses the CMS collection id.", "type": "string" }, "platform": { "enum": [ "shopify", "wordpress", "wix", "webflow" ], "type": "string" }, "title": { "type": "string" } }, "type": "object" }, "platform": { "enum": [ "shopify" ], "type": "string" } }, "type": "object" } } }, "description": "Blog 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": { "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." } }, "summary": "Update a blog", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.blogs.update_blog@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "29e650239bf9de0a6b88685460a3fa2ada6f316b383242c09950c06e21f131ed" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "patch_aisa_social_apis_v1_social_accounts_account_710a82", "method": "PATCH", "path": "/apis/v1/social/accounts/{accountId}/blogs/{blogId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/patch_aisa_social_apis_v1_social_accounts_account_710a82" } }, "/apis/v1/social/accounts/{accountId}/blogs/{blogId}/articles": { "get": { "description": "Blogs. 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.\n\nLists the articles of a blog. Supported on Shopify (`shopify`), WordPress (`wordpress`), Wix (`wix`) and Webflow (`webflow`).\n\n### Pagination\n\nCursor-paginated: pass `limit` (1-50, default 20) and the `cursor` from a previous response's `nextCursor`. `nextCursor` is null when there are no more pages. Treat cursors as opaque and pass them unchanged.\n\n### Platform differences\n\n- WordPress and Wix results include `status`, and include `publishDate` only for scheduled (`future`) posts.\n- Wix lists return `bodyHtml: null`; get the article for its body.\n- Webflow results report `status` as `publish` or `draft` only.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_9e8439", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Platform-native blog/site id returned by the list operation.", "in": "path", "name": "blogId", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Page size (1-50).", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 50, "minimum": 1, "type": "integer" } }, { "description": "Opaque cursor from a previous response. Omit for the first page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "articles": { "items": { "description": "An article inside a blog on the connected platform.", "properties": { "author": { "description": "Shopify author display name, numeric WordPress user id serialized as a string, or Wix site member id. Wix posts without one are attributed to the site's default author.", "type": [ "string", "null" ] }, "blogId": { "description": "Platform-native id of the blog the article belongs to.", "type": "string" }, "bodyHtml": { "description": "Article body as HTML. Wix stores rich content, converted from and to HTML; Wix lists return null (get the article for its body).", "type": [ "string", "null" ] }, "createdAt": { "description": "Creation time when the platform exposes one. WordPress returns null because its core date is the editable publication date.", "format": "date-time", "type": [ "string", "null" ] }, "excerpt": { "description": "Short summary shown in blog listings.", "type": [ "string", "null" ] }, "handle": { "description": "URL slug of the article.", "type": "string" }, "id": { "description": "Platform-native article/post id: numeric on Shopify and WordPress, a GUID on Wix, a hex item id on Webflow.", "type": "string" }, "image": { "description": "Featured image.", "properties": { "altText": { "type": [ "string", "null" ] }, "url": { "type": "string" } }, "type": [ "object", "null" ] }, "isPublished": { "description": "False while the article is a draft or its publish date is still in the future.", "type": "boolean" }, "platform": { "enum": [ "shopify", "wordpress", "wix", "webflow" ], "type": "string" }, "publishDate": { "description": "WordPress and Wix. Scheduled publication time in UTC when status is `future`; null for other statuses and omitted for Shopify.", "format": "date-time", "type": [ "string", "null" ] }, "publishedAt": { "description": "Publication time. On WordPress this is present only when status is `publish`; null for drafts, pending/private posts, and scheduled posts.", "format": "date-time", "type": [ "string", "null" ] }, "status": { "description": "WordPress and Wix. Post status (`future` = scheduled, `pending` = in review on Wix); omitted for Shopify.", "enum": [ "publish", "future", "draft", "pending", "private" ], "type": "string" }, "tags": { "description": "Tag names. On WordPress and Wix, missing tag names are created and matching is case-insensitive.", "items": { "type": "string" }, "type": "array" }, "title": { "type": "string" }, "updatedAt": { "description": "Last modification time. WordPress returns modified_gmt as UTC.", "format": "date-time", "type": [ "string", "null" ] }, "url": { "description": "WordPress and Wix. Public URL of the article while it is published; null for drafts and scheduled posts, and on a Wix site that is not published yet.", "type": [ "string", "null" ] } }, "type": "object" }, "type": "array" }, "nextCursor": { "description": "Cursor for the next page; null when there are no more pages.", "type": [ "string", "null" ] }, "platform": { "enum": [ "shopify", "wordpress", "wix", "webflow" ], "type": "string" } }, "type": "object" } } }, "description": "Articles listed" }, "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." } }, "summary": "List blog articles", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.blogs.list_blog_articles@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "7fa330d2136ea86fceaa8af9acc0fb3b11c9d44c7d9599783c760bbc92d03c3c" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_9e8439", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/blogs/{blogId}/articles" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_9e8439" }, "post": { "description": "Blogs. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nCreates an article on the blog. Supported on Shopify (`shopify`), WordPress (`wordpress`), Wix (`wix`) and Webflow (`webflow`).\n\n### Publishing behavior\n\n- WordPress, Wix and Webflow default to a draft when both publishing fields are omitted.\n- `isPublished: false` keeps the article as a draft and takes priority over a future `publishDate`.\n- A future `publishDate` schedules publication natively on the platform. The platform publishes it at that time with no AIsa queue involved.\n- `isPublished: true` publishes immediately when there is no future `publishDate`.\n- WordPress native scheduling depends on the site's scheduler/WP-Cron.\n\n### SEO\n\n`seo.title` / `seo.description` map to:\n\n- Shopify: the global `title_tag` and `description_tag` metafields (the fields Shopify themes read for the page title and meta description).\n- Wix: the post's SEO title and meta description.\n\nWordPress and Webflow reject `seo`; SEO plugin and custom-field writes are not supported.\n\n### Webflow\n\nWebflow has no scheduling API: a future `publishDate` returns 400 unless `isPublished: false` keeps a draft.\n\nFields map to the collection's own fields by type and slug:\n\n- The body goes to its rich text field.\n- `excerpt` goes to a summary field.\n- `image` goes to an image field.\n- `tags` and `author` go to tag and author reference fields.\n\nSending a field the collection does not have returns 400, as does a collection that requires a field the Blogs API cannot fill.\n\n### Wix\n\nWix stores rich content. `bodyHtml` is converted on write (each top-level HTML element must fit 30,000 characters), and images in the body are imported into the site's Media Manager.\n\n### Idempotency\n\nSend an Idempotency-Key header to make retries safe. A retry with the same key and body replays the original 201 instead of creating a second article. A retry while the first request is still running returns 409; retry after a short backoff.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_accounts_accounti_9e8439", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Platform-native blog/site id returned by the list operation.", "in": "path", "name": "blogId", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Passed to the channel: a retry with the same key within 24 hours returns the first result instead of acting twice. AIsa never retries a write for you.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 191, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "title": "example" }, "schema": { "properties": { "author": { "description": "Shopify author display name, numeric WordPress user id serialized as a string, or Wix site member id. Assigning another WordPress user may require elevated capability. Wix posts without one go to the site's default author.", "type": "string" }, "bodyHtml": { "description": "Article body as HTML.", "type": "string" }, "excerpt": { "description": "Short summary shown in blog listings.", "type": "string" }, "fieldData": { "additionalProperties": true, "description": "Webflow only (other platforms answer 400). The collection's own fields that the Blogs API does not map, keyed by field slug, in Webflow's value format (a Reference is an item id, an Image is { url, alt }).\n\nRequired by collections with required fields of their own: a create that leaves one empty answers 400 listing them. A slug the API already fills (name, slug, body, summary, image, tags, author, date) or one the collection lacks answers 400.", "type": "object" }, "handle": { "description": "URL slug. Generated from the title when omitted.", "type": "string" }, "image": { "description": "Featured image from a public URL. WordPress downloads it into the media library and Wix imports it into the Media Manager; JPEG, PNG, GIF and WebP are accepted up to 10 MB.", "properties": { "altText": { "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "url" ], "type": "object" }, "isPublished": { "description": "Set false for a draft or true to publish. On WordPress and Wix false takes priority over a future publishDate; omission with no date defaults to draft.", "type": "boolean" }, "publishDate": { "description": "ISO 8601 datetime with offset (or Z). A future date schedules publication natively on the platform.", "format": "date-time", "type": "string" }, "seo": { "description": "Shopify and Wix. Search-engine overrides: Shopify global title_tag and description_tag metafields, Wix post SEO title and meta description. WordPress rejects this field.", "properties": { "description": { "type": "string" }, "title": { "type": "string" } }, "type": "object" }, "tags": { "description": "Tag names. WordPress and Wix resolve existing names case-insensitively and create missing tags (Wix allows up to 30).", "items": { "minLength": 1, "type": "string" }, "maxItems": 100, "type": "array" }, "title": { "minLength": 1, "type": "string" } }, "required": [ "title" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "article": { "description": "An article inside a blog on the connected platform.", "properties": { "author": { "description": "Shopify author display name, numeric WordPress user id serialized as a string, or Wix site member id. Wix posts without one are attributed to the site's default author.", "type": [ "string", "null" ] }, "blogId": { "description": "Platform-native id of the blog the article belongs to.", "type": "string" }, "bodyHtml": { "description": "Article body as HTML. Wix stores rich content, converted from and to HTML; Wix lists return null (get the article for its body).", "type": [ "string", "null" ] }, "createdAt": { "description": "Creation time when the platform exposes one. WordPress returns null because its core date is the editable publication date.", "format": "date-time", "type": [ "string", "null" ] }, "excerpt": { "description": "Short summary shown in blog listings.", "type": [ "string", "null" ] }, "handle": { "description": "URL slug of the article.", "type": "string" }, "id": { "description": "Platform-native article/post id: numeric on Shopify and WordPress, a GUID on Wix, a hex item id on Webflow.", "type": "string" }, "image": { "description": "Featured image.", "properties": { "altText": { "type": [ "string", "null" ] }, "url": { "type": "string" } }, "type": [ "object", "null" ] }, "isPublished": { "description": "False while the article is a draft or its publish date is still in the future.", "type": "boolean" }, "platform": { "enum": [ "shopify", "wordpress", "wix", "webflow" ], "type": "string" }, "publishDate": { "description": "WordPress and Wix. Scheduled publication time in UTC when status is `future`; null for other statuses and omitted for Shopify.", "format": "date-time", "type": [ "string", "null" ] }, "publishedAt": { "description": "Publication time. On WordPress this is present only when status is `publish`; null for drafts, pending/private posts, and scheduled posts.", "format": "date-time", "type": [ "string", "null" ] }, "status": { "description": "WordPress and Wix. Post status (`future` = scheduled, `pending` = in review on Wix); omitted for Shopify.", "enum": [ "publish", "future", "draft", "pending", "private" ], "type": "string" }, "tags": { "description": "Tag names. On WordPress and Wix, missing tag names are created and matching is case-insensitive.", "items": { "type": "string" }, "type": "array" }, "title": { "type": "string" }, "updatedAt": { "description": "Last modification time. WordPress returns modified_gmt as UTC.", "format": "date-time", "type": [ "string", "null" ] }, "url": { "description": "WordPress and Wix. Public URL of the article while it is published; null for drafts and scheduled posts, and on a Wix site that is not published yet.", "type": [ "string", "null" ] } }, "type": "object" }, "platform": { "enum": [ "shopify", "wordpress", "wix", "webflow" ], "type": "string" } }, "type": "object" } } }, "description": "Article created" }, "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." } }, "summary": "Create a blog article", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.blogs.create_blog_article@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "d0df57cfb50caf3356308cefee3e06639b76d2c7c915c579518862fe1c0975ee" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_accounts_accounti_9e8439", "method": "POST", "path": "/apis/v1/social/accounts/{accountId}/blogs/{blogId}/articles" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_accounts_accounti_9e8439" } }, "/apis/v1/social/accounts/{accountId}/blogs/{blogId}/articles/{articleId}": { "delete": { "description": "Blogs. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nDeletes the article. The delete happens on the platform and is permanent; AIsa stores nothing to restore it from.\n\nSupported on Shopify (`shopify`), WordPress (`wordpress`), Wix (`wix`) and Webflow (`webflow`).\n\n### Platform behavior\n\n- WordPress: the post is force-deleted, while uploaded attachments and tags remain in the site's media library and taxonomy.\n- Webflow: the item is unpublished from the live site, then deleted from the collection.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "delete_aisa_social_apis_v1_social_accounts_accoun_1bfa6c", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Platform-native blog/site id returned by the list operation.", "in": "path", "name": "blogId", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Platform-native article id: numeric on Shopify and WordPress, a GUID on Wix, a 24-character hex item id on Webflow. Other formats return 400.", "in": "path", "name": "articleId", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } } ], "responses": { "204": { "content": { "application/json": { "schema": { "description": "An empty object or a success flag.", "properties": { "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Article deleted (no content)." }, "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." } }, "summary": "Delete a blog article", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.blogs.delete_blog_article@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "ed1862f4c01a0d52e7bdefce9aea355d9384ffde046a9670c1767f2420f53578" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "delete_aisa_social_apis_v1_social_accounts_accoun_1bfa6c", "method": "DELETE", "path": "/apis/v1/social/accounts/{accountId}/blogs/{blogId}/articles/{articleId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/delete_aisa_social_apis_v1_social_accounts_accoun_1bfa6c" }, "get": { "description": "Blogs. 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.\n\nFetches a single article. An article addressed through a blog it does\nnot belong to is a 404 (code blog_article_not_found).\n\nSupported on Shopify (`shopify`), WordPress (`wordpress`), Wix (`wix`) and Webflow (`webflow`). WordPress\nreturns its native `status`; `publishedAt` is present only for a\npublished post and `publishDate` only for a scheduled post.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_1bfa6c", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Platform-native blog/site id returned by the list operation.", "in": "path", "name": "blogId", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Platform-native article id: numeric on Shopify and WordPress, a GUID on Wix, a 24-character hex item id on Webflow. Other formats return 400.", "in": "path", "name": "articleId", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "article": { "description": "An article inside a blog on the connected platform.", "properties": { "author": { "description": "Shopify author display name, numeric WordPress user id serialized as a string, or Wix site member id. Wix posts without one are attributed to the site's default author.", "type": [ "string", "null" ] }, "blogId": { "description": "Platform-native id of the blog the article belongs to.", "type": "string" }, "bodyHtml": { "description": "Article body as HTML. Wix stores rich content, converted from and to HTML; Wix lists return null (get the article for its body).", "type": [ "string", "null" ] }, "createdAt": { "description": "Creation time when the platform exposes one. WordPress returns null because its core date is the editable publication date.", "format": "date-time", "type": [ "string", "null" ] }, "excerpt": { "description": "Short summary shown in blog listings.", "type": [ "string", "null" ] }, "handle": { "description": "URL slug of the article.", "type": "string" }, "id": { "description": "Platform-native article/post id: numeric on Shopify and WordPress, a GUID on Wix, a hex item id on Webflow.", "type": "string" }, "image": { "description": "Featured image.", "properties": { "altText": { "type": [ "string", "null" ] }, "url": { "type": "string" } }, "type": [ "object", "null" ] }, "isPublished": { "description": "False while the article is a draft or its publish date is still in the future.", "type": "boolean" }, "platform": { "enum": [ "shopify", "wordpress", "wix", "webflow" ], "type": "string" }, "publishDate": { "description": "WordPress and Wix. Scheduled publication time in UTC when status is `future`; null for other statuses and omitted for Shopify.", "format": "date-time", "type": [ "string", "null" ] }, "publishedAt": { "description": "Publication time. On WordPress this is present only when status is `publish`; null for drafts, pending/private posts, and scheduled posts.", "format": "date-time", "type": [ "string", "null" ] }, "status": { "description": "WordPress and Wix. Post status (`future` = scheduled, `pending` = in review on Wix); omitted for Shopify.", "enum": [ "publish", "future", "draft", "pending", "private" ], "type": "string" }, "tags": { "description": "Tag names. On WordPress and Wix, missing tag names are created and matching is case-insensitive.", "items": { "type": "string" }, "type": "array" }, "title": { "type": "string" }, "updatedAt": { "description": "Last modification time. WordPress returns modified_gmt as UTC.", "format": "date-time", "type": [ "string", "null" ] }, "url": { "description": "WordPress and Wix. Public URL of the article while it is published; null for drafts and scheduled posts, and on a Wix site that is not published yet.", "type": [ "string", "null" ] } }, "type": "object" }, "platform": { "enum": [ "shopify", "wordpress", "wix", "webflow" ], "type": "string" } }, "type": "object" } } }, "description": "Article fetched" }, "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." } }, "summary": "Get a blog article", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.blogs.get_blog_article@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "ead6151f9c61290f23b706935805796e128c4c95dbf97427a08806f29c93bfc5" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_1bfa6c", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/blogs/{blogId}/articles/{articleId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_1bfa6c" }, "patch": { "description": "Blogs. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nPartial-updates an article. Supported on Shopify (`shopify`), WordPress (`wordpress`), Wix (`wix`) and Webflow (`webflow`).\n\nSend any subset of the create fields: `title`, `bodyHtml`, `handle`, `tags`, `author`, `excerpt`, `image`, `seo`, `isPublished`, `publishDate`. At least one field is required (an empty body returns 400).\n\n### Publishing\n\n`isPublished` and `publishDate` behave as on create:\n\n- `isPublished: false` unpublishes back to a draft.\n- A future `publishDate` schedules publication natively on the platform.\n- Omitting both fields preserves the current WordPress or Wix status.\n\nOmitting `image` preserves the current featured image; removal is not supported.\n\n### Platform limits\n\n- **WordPress**: rejects `seo` and does not support SEO-plugin/custom-field, category, or custom-post-type writes.\n- **Webflow**: an edit to a published item goes live immediately, `isPublished: false` unpublishes it, and a future `publishDate` returns 400.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "patch_aisa_social_apis_v1_social_accounts_account_1bfa6c", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Platform-native blog/site id returned by the list operation.", "in": "path", "name": "blogId", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } }, { "description": "Platform-native article id: numeric on Shopify and WordPress, a GUID on Wix, a 24-character hex item id on Webflow. Other formats return 400.", "in": "path", "name": "articleId", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{1,64}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "description": "At least one field is required.", "properties": { "author": { "description": "Shopify author display name, numeric WordPress user id serialized as a string, or Wix site member id. Assigning another WordPress user may require elevated capability. Wix posts without one go to the site's default author.", "type": "string" }, "bodyHtml": { "description": "Article body as HTML.", "type": "string" }, "excerpt": { "description": "Short summary shown in blog listings.", "type": "string" }, "fieldData": { "additionalProperties": true, "description": "Webflow only (other platforms answer 400). The collection's own fields that the Blogs API does not map, keyed by field slug, in Webflow's value format (a Reference is an item id, an Image is { url, alt }).\n\n- Required by collections with required fields of their own. A create that leaves one empty answers 400 listing them.\n- A slug the API already fills (name, slug, body, summary, image, tags, author, date) or one the collection lacks answers 400.", "type": "object" }, "handle": { "description": "URL slug of the article.", "type": "string" }, "image": { "description": "Featured image from a public URL. WordPress downloads it into the media library and Wix imports it into the Media Manager; JPEG, PNG, GIF and WebP are accepted up to 10 MB. Omit to preserve it; null removal is not supported.", "properties": { "altText": { "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "url" ], "type": "object" }, "isPublished": { "description": "Set false to move to draft or true to publish. On WordPress and Wix false takes priority over a future publishDate; omission preserves status unless publishDate is sent (edits to a published Wix post go live).", "type": "boolean" }, "publishDate": { "description": "ISO 8601 datetime with offset (or Z). A future date schedules publication natively on the platform.", "format": "date-time", "type": "string" }, "seo": { "description": "Shopify and Wix. Search-engine overrides: Shopify global title_tag and description_tag metafields, Wix post SEO title and meta description. WordPress rejects this field.", "properties": { "description": { "type": "string" }, "title": { "type": "string" } }, "type": "object" }, "tags": { "description": "Replaces the full tag-name list. WordPress and Wix resolve existing names case-insensitively and create missing tags (Wix allows up to 30).", "items": { "minLength": 1, "type": "string" }, "maxItems": 100, "type": "array" }, "title": { "minLength": 1, "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "article": { "description": "An article inside a blog on the connected platform.", "properties": { "author": { "description": "Shopify author display name, numeric WordPress user id serialized as a string, or Wix site member id. Wix posts without one are attributed to the site's default author.", "type": [ "string", "null" ] }, "blogId": { "description": "Platform-native id of the blog the article belongs to.", "type": "string" }, "bodyHtml": { "description": "Article body as HTML. Wix stores rich content, converted from and to HTML; Wix lists return null (get the article for its body).", "type": [ "string", "null" ] }, "createdAt": { "description": "Creation time when the platform exposes one. WordPress returns null because its core date is the editable publication date.", "format": "date-time", "type": [ "string", "null" ] }, "excerpt": { "description": "Short summary shown in blog listings.", "type": [ "string", "null" ] }, "handle": { "description": "URL slug of the article.", "type": "string" }, "id": { "description": "Platform-native article/post id: numeric on Shopify and WordPress, a GUID on Wix, a hex item id on Webflow.", "type": "string" }, "image": { "description": "Featured image.", "properties": { "altText": { "type": [ "string", "null" ] }, "url": { "type": "string" } }, "type": [ "object", "null" ] }, "isPublished": { "description": "False while the article is a draft or its publish date is still in the future.", "type": "boolean" }, "platform": { "enum": [ "shopify", "wordpress", "wix", "webflow" ], "type": "string" }, "publishDate": { "description": "WordPress and Wix. Scheduled publication time in UTC when status is `future`; null for other statuses and omitted for Shopify.", "format": "date-time", "type": [ "string", "null" ] }, "publishedAt": { "description": "Publication time. On WordPress this is present only when status is `publish`; null for drafts, pending/private posts, and scheduled posts.", "format": "date-time", "type": [ "string", "null" ] }, "status": { "description": "WordPress and Wix. Post status (`future` = scheduled, `pending` = in review on Wix); omitted for Shopify.", "enum": [ "publish", "future", "draft", "pending", "private" ], "type": "string" }, "tags": { "description": "Tag names. On WordPress and Wix, missing tag names are created and matching is case-insensitive.", "items": { "type": "string" }, "type": "array" }, "title": { "type": "string" }, "updatedAt": { "description": "Last modification time. WordPress returns modified_gmt as UTC.", "format": "date-time", "type": [ "string", "null" ] }, "url": { "description": "WordPress and Wix. Public URL of the article while it is published; null for drafts and scheduled posts, and on a Wix site that is not published yet.", "type": [ "string", "null" ] } }, "type": "object" }, "platform": { "enum": [ "shopify", "wordpress", "wix", "webflow" ], "type": "string" } }, "type": "object" } } }, "description": "Article 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": { "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." } }, "summary": "Update a blog article", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.blogs.update_blog_article@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "8789558e48cd54ef36d7d49babc1faff9037fb04581411b6ce1ae253932443ff" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "patch_aisa_social_apis_v1_social_accounts_account_1bfa6c", "method": "PATCH", "path": "/apis/v1/social/accounts/{accountId}/blogs/{blogId}/articles/{articleId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/patch_aisa_social_apis_v1_social_accounts_account_1bfa6c" } }, "/apis/v1/social/accounts/{accountId}/bluesky-settings": { "get": { "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.\n\nReturns the account's default post languages (defaultLangs), applied at publish time whenever a post's platformSpecificData.langs is absent. Null when no default is set.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_7d2f8f", "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": { "defaultLangs": { "items": { "type": "string" }, "type": [ "array", "null" ] } }, "type": "object" } } }, "description": "Bluesky account settings" }, "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." } }, "summary": "Get Bluesky account settings", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.accounts.get_bluesky_settings@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "7a9f8179522de578357c223bf932851b6bfe68777c5447bbe9e6041d715e217b" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_7d2f8f", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/bluesky-settings" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_7d2f8f" }, "patch": { "description": "Accounts. 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.\n\nSet or clear the account's default post languages. 1-3 BCP-47 codes (e.g. \"pt\", \"en-US\"), the same validation as per-post langs; explicit null clears the default. Per-post platformSpecificData.langs always overrides this default. Applies to posts published after the change; already-published posts cannot be retagged (Bluesky has no post edit).\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "patch_aisa_social_apis_v1_social_accounts_account_7d2f8f", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "defaultLangs": [ "example" ] }, "schema": { "properties": { "defaultLangs": { "items": { "type": "string" }, "maxItems": 3, "minItems": 1, "type": [ "array", "null" ] } }, "required": [ "defaultLangs" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "An empty object or a success flag.", "properties": { "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Updated settings" }, "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." } }, "summary": "Update Bluesky account settings", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.accounts.update_bluesky_settings@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "b06d0adec79c5d725c2ee5b282a62762a58f54c30d719d0966594a357c6b85f7" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "patch_aisa_social_apis_v1_social_accounts_account_7d2f8f", "method": "PATCH", "path": "/apis/v1/social/accounts/{accountId}/bluesky-settings" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/patch_aisa_social_apis_v1_social_accounts_account_7d2f8f" } }, "/apis/v1/social/accounts/{accountId}/business-partners": { "delete": { "description": "Accounts. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nRemoves every task the partner business portfolio held on the Page.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "delete_aisa_social_apis_v1_social_accounts_accoun_31b011", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Meta business portfolio id of the partner (numeric string).", "in": "query", "name": "businessId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "businessId": { "type": "string" }, "pageId": { "type": "string" }, "revoked": { "type": "boolean" } }, "type": "object" } } }, "description": "Access revoked" }, "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." } }, "summary": "Revoke a partner business from the Page", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.accounts.revoke_business_partner@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "76eea89645775ff2abc38b97f4a7e618a29b2a6f9c7ddf843078c36a3ea5a3cf" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "delete_aisa_social_apis_v1_social_accounts_accoun_31b011", "method": "DELETE", "path": "/apis/v1/social/accounts/{accountId}/business-partners" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/delete_aisa_social_apis_v1_social_accounts_accoun_31b011" }, "get": { "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.\n\nThe business portfolios (Meta Business Managers) that may act on the Facebook Page\nbehind this account, plus the Page's owning portfolio and linked Instagram\nprofessional account. Works on Facebook accounts and on Instagram accounts connected\nthrough Facebook Login.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_31b011", "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": { "page": { "properties": { "business": { "description": "Business portfolio that owns the Page; null when the Page is outside any portfolio.", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "type": [ "object", "null" ] }, "id": { "description": "Facebook Page id.", "type": "string" }, "instagramBusinessAccount": { "description": "Instagram professional account linked to the Page; null when none is linked.", "properties": { "id": { "type": "string" }, "username": { "type": "string" } }, "type": [ "object", "null" ] }, "name": { "type": "string" } }, "type": "object" }, "partners": { "items": { "properties": { "businessId": { "type": "string" }, "name": { "type": "string" }, "permittedTasks": { "description": "Tasks the partner holds, in the bare spelling the grant takes (ADVERTISE, ANALYZE, MANAGE, ...). Meta reads them back with a PROFILE_PLUS_ prefix, which is stripped here; partners granted in Business Settings may hold tasks beyond the six the grant accepts, such as MANAGE_LEADS or REVENUE.", "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Page ownership and partners" }, "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." } }, "summary": "List partner businesses of the Page", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.accounts.list_business_partners@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "1aacafda6808ff87256cfa1e6f96e82a25a31c4b7d1949ddaf6ce48ba9c6c6ba" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_31b011", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/business-partners" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_31b011" }, "post": { "description": "Accounts. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nGrants a partner business portfolio tasks on the Facebook Page behind this account.\n\nWith `ADVERTISE`, the partner can run ads for the Page from ad accounts in its own portfolio. This is how an integrator advertises for an end user without touching the end user's ad accounts.\n\n### Responses\n\n- `422`: the Page is outside any business portfolio. Meta only lets a user token share a Page that a portfolio owns, so claim it into one at business.facebook.com first.\n- `200` with `alreadyShared: true` and the tasks the partner currently holds: the portfolio already has access. Meta refuses a second grant instead of replacing its tasks.\n\nTo change a partner's tasks, revoke and grant again.\n\n### After the grant\n\nThe partner assigns its own people to the Page with `POST /apis/v1/ads/page-users`; Meta does not assign partner admins automatically.\n\nThe Instagram professional account linked to the Page is returned in `page` so the partner can reference it. Meta exposes no API to share Instagram accounts; that is done in Business Settings.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_accounts_accounti_31b011", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "businessId": "1234567890123", "permittedTasks": [ "ADVERTISE", "ANALYZE" ] }, "schema": { "properties": { "businessId": { "description": "Meta business portfolio id of the partner (numeric string).", "type": "string" }, "permittedTasks": { "description": "Tasks granted on the Page, Meta's permitted_tasks vocabulary. Defaults to ADVERTISE and ANALYZE. The bare names are what Business Settings shows; the PROFILE_PLUS_ names are the New Pages Experience tasks and the only way to grant FACEBOOK_ACCESS or REVENUE. Granting MANAGE also yields MANAGE_LEADS.", "items": { "enum": [ "MANAGE", "CREATE_CONTENT", "MODERATE", "MESSAGING", "ADVERTISE", "ANALYZE", "MODERATE_COMMUNITY", "MANAGE_JOBS", "PAGES_MESSAGING", "PAGES_MESSAGING_SUBSCRIPTIONS", "READ_PAGE_MAILBOXES", "VIEW_MONETIZATION_INSIGHTS", "MANAGE_LEADS", "CASHIER_ROLE", "GLOBAL_STRUCTURE_MANAGEMENT", "PROFILE_PLUS_FULL_CONTROL", "PROFILE_PLUS_MANAGE", "PROFILE_PLUS_FACEBOOK_ACCESS", "PROFILE_PLUS_CREATE_CONTENT", "PROFILE_PLUS_MODERATE", "PROFILE_PLUS_MODERATE_DELEGATE_COMMUNITY", "PROFILE_PLUS_MESSAGING", "PROFILE_PLUS_ADVERTISE", "PROFILE_PLUS_ANALYZE", "PROFILE_PLUS_REVENUE", "PROFILE_PLUS_MANAGE_LEADS", "PROFILE_PLUS_CREATIVE_MANAGEMENT", "PROFILE_PLUS_CREATOR_MANAGEMENT", "PROFILE_PLUS_GLOBAL_STRUCTURE_MANAGEMENT" ], "type": "string" }, "type": "array" } }, "required": [ "businessId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "alreadyShared": { "description": "Always true on this response.", "type": "boolean" }, "page": { "properties": { "business": { "description": "Business portfolio that owns the Page; null when the Page is outside any portfolio.", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "type": [ "object", "null" ] }, "id": { "description": "Facebook Page id.", "type": "string" }, "instagramBusinessAccount": { "description": "Instagram professional account linked to the Page; null when none is linked.", "properties": { "id": { "type": "string" }, "username": { "type": "string" } }, "type": [ "object", "null" ] }, "name": { "type": "string" } }, "type": "object" }, "partner": { "properties": { "businessId": { "type": "string" }, "permittedTasks": { "description": "Tasks the partner currently holds.", "items": { "type": "string" }, "type": "array" } }, "type": "object" } }, "type": "object" } } }, "description": "The portfolio already had access; nothing changed" }, "201": { "content": { "application/json": { "schema": { "properties": { "page": { "properties": { "business": { "description": "Business portfolio that owns the Page; null when the Page is outside any portfolio.", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "type": [ "object", "null" ] }, "id": { "description": "Facebook Page id.", "type": "string" }, "instagramBusinessAccount": { "description": "Instagram professional account linked to the Page; null when none is linked.", "properties": { "id": { "type": "string" }, "username": { "type": "string" } }, "type": [ "object", "null" ] }, "name": { "type": "string" } }, "type": "object" }, "partner": { "properties": { "businessId": { "type": "string" }, "permittedTasks": { "items": { "type": "string" }, "type": "array" } }, "type": "object" } }, "type": "object" } } }, "description": "Page shared" }, "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." } }, "summary": "Share the Page with a partner business", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.accounts.grant_business_partner@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "c7bae46968302d4ad1546bd5693cac96b3f18cc70b831e0589cbe8ee326a0345" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_accounts_accounti_31b011", "method": "POST", "path": "/apis/v1/social/accounts/{accountId}/business-partners" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_accounts_accounti_31b011" } }, "/apis/v1/social/accounts/{accountId}/discord-channels": { "get": { "description": "Discord. 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.\n\nReturns the text, announcement, and forum channels in the connected Discord guild. Use this to discover available channels when switching the connected channel via PATCH /apis/v1/social/accounts/{accountId}/discord-settings.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_797ef0", "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": { "channels": { "items": { "properties": { "id": { "description": "Channel snowflake ID", "type": "string" }, "name": { "description": "Channel name", "type": "string" }, "type": { "description": "Channel type: 0 (text), 5 (announcement), 15 (forum)", "type": "integer" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Channel list" }, "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." } }, "summary": "List Discord guild channels", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.discord.get_discord_channels@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "c5cc3983484c6d93656b4b58b0a479476cb8b651a511f7ed108f17d6e13cd7b6" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_797ef0", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/discord-channels" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_797ef0" } }, "/apis/v1/social/accounts/{accountId}/discord-settings": { "get": { "description": "Discord. 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.\n\nReturns the current Discord account settings including webhook identity (display name and avatar), connected channel, and guild information.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_7917f3", "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": { "account": { "properties": { "_id": { "type": "string" }, "channelId": { "description": "Connected channel snowflake ID", "type": "string" }, "channelName": { "description": "Channel name", "type": "string" }, "channelType": { "description": "Channel type (0 = text, 5 = announcement, 15 = forum)", "type": "string" }, "displayName": { "description": "Guild - #channel display name", "type": "string" }, "guildId": { "description": "Guild (server) snowflake ID", "type": "string" }, "platform": { "type": "string" }, "profilePicture": { "description": "Guild icon URL", "type": "string" }, "username": { "description": "Channel name", "type": "string" }, "webhookAvatarUrl": { "description": "Custom webhook avatar URL (null = default bot avatar)", "type": [ "string", "null" ] }, "webhookUsername": { "description": "Custom webhook display name (null = default \"AIsa\")", "type": [ "string", "null" ] } }, "type": "object" } }, "type": "object" } } }, "description": "Discord account settings" }, "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." } }, "summary": "Get Discord account settings", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.discord.get_discord_settings@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "6b4edb93b66335b2be713f3bc924b823dc50d06176437399738bb05812626e03" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_7917f3", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/discord-settings" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_7917f3" }, "patch": { "description": "Discord. 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.\n\nUpdate Discord account settings. Supports two operations (can be combined):\n\n1. **Webhook identity** - Set the default display name and avatar that appear as the message author on every post. These are account-level defaults; individual posts can override them via platformSpecificData.webhookUsername / webhookAvatarUrl.\n\n2. **Switch channel** - Move the connection to a different channel in the same guild. A new webhook is automatically created in the target channel.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "patch_aisa_social_apis_v1_social_accounts_account_7917f3", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "webhookAvatarUrl": "https://example.com/logo.png", "webhookUsername": "My Brand" }, "schema": { "properties": { "channelId": { "description": "Switch to a different channel in the same guild. Must be a text (0), announcement (5), or forum (15) channel.", "type": "string" }, "webhookAvatarUrl": { "description": "Custom avatar URL. Empty string resets to default bot avatar. AIsa upload URLs (temp/) are copied to permanent storage; an expired one returns 400.", "type": "string" }, "webhookUsername": { "description": "Custom display name for the webhook (1-80 chars). Empty string resets to default (\"AIsa\"). Cannot contain \"clyde\" or \"discord\".", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "account": { "properties": { "_id": { "type": "string" }, "channelId": { "type": "string" }, "channelName": { "type": "string" }, "channelType": { "type": "string" }, "displayName": { "type": "string" }, "guildId": { "type": "string" }, "platform": { "type": "string" }, "profilePicture": { "type": "string" }, "username": { "type": "string" }, "webhookAvatarUrl": { "type": [ "string", "null" ] }, "webhookUsername": { "type": [ "string", "null" ] } }, "type": "object" }, "message": { "type": "string" } }, "type": "object" } } }, "description": "Settings 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": { "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." } }, "summary": "Update Discord settings", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.discord.update_discord_settings@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "316c8d552552d8207e3c4fe58d0e817b44806d33becf20c2bf7ccb849282fbf6" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "patch_aisa_social_apis_v1_social_accounts_account_7917f3", "method": "PATCH", "path": "/apis/v1/social/accounts/{accountId}/discord-settings" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/patch_aisa_social_apis_v1_social_accounts_account_7917f3" } }, "/apis/v1/social/accounts/{accountId}/facebook-page": { "get": { "description": "Account settings. 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.\n\nReturns all Facebook Pages the connected account has access to, including the currently selected Page and the Instagram professional account linked to each Page.\n\nWorks on `facebook` accounts and on `metaads` accounts (classic and Facebook Login for Business connections).\n\n- Business-login `metaads` connection: `selectedPageId` is the default Page ads run as, and every listed Page can be passed as `pageId` on POST /apis/v1/ads/create.\n- Classic `metaads` connection: there is no default Page, so `selectedPageId` is null.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_3eff32", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "When true, bypasses the page cache and fetches fresh pages from Meta. Rate-limited server-side to 1 refresh per 60s. Pages no longer accessible to the connected account will be removed from the list on refresh.", "in": "query", "name": "refresh", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "cached": { "description": "false when this response was just read from Meta (cold cache or a refresh that ran), true when served from the stored list (including a debounced refresh or an empty Meta answer)", "type": "boolean" }, "pages": { "items": { "properties": { "category": { "type": "string" }, "fan_count": { "type": "integer" }, "id": { "type": "string" }, "instagramAccount": { "description": "The Instagram professional account linked to the Page (Meta instagram_business_account), or null when none is linked or the list was served from a cache stored before this field existed (pass refresh=true to re-read it).", "properties": { "id": { "description": "Instagram professional account id, usable as instagramAccountId on POST /apis/v1/ads/create", "type": "string" }, "username": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "name": { "type": "string" }, "username": { "type": "string" } }, "type": "object" }, "type": "array" }, "selectedPageId": { "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Pages list" }, "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." } }, "summary": "List Facebook pages", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.account_settings.get_facebook_pages@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "6e2bc4aa55fc9c402c539cfa397013f6c39b8010a595aa954037d6937ff17d8d" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_3eff32", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/facebook-page" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_3eff32" }, "put": { "description": "Account settings. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nSwitch which Facebook Page is active for a connected account.\n\n- `facebook` account: changes the Page posts publish to.\n- Facebook Login for Business `metaads` connection: changes the default Page ads run as (and the Page whose leads are ingested).\n- Classic `metaads` connection: has no default Page and answers 400. Pass `pageId` per ad on POST /apis/v1/ads/create instead.\n\nThe Page must be in the list returned by GET (use refresh=true to pick up newly granted Pages).\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "put_aisa_social_apis_v1_social_accounts_accountid_3eff32", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "selectedPageId": "123456789012345" }, "schema": { "properties": { "selectedPageId": { "type": "string" } }, "required": [ "selectedPageId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "selectedPage": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Page 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": { "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." } }, "summary": "Update Facebook page", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.account_settings.update_facebook_page@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "a4b29aca3534dd56a3006dca77a292d1c34a2dcc36b6a1e2a0234d4b1e42a595" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "put_aisa_social_apis_v1_social_accounts_accountid_3eff32", "method": "PUT", "path": "/apis/v1/social/accounts/{accountId}/facebook-page" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/put_aisa_social_apis_v1_social_accounts_accountid_3eff32" } }, "/apis/v1/social/accounts/{accountId}/facebook-post-reactions": { "get": { "description": "Analytics. 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.\n\nReturns the reaction breakdown for a Facebook Page post: a count per reaction type\nplus the overall total.\n\nThe whole breakdown is fetched in a single Graph call. The post analytics\nendpoint reports only an aggregate reaction count (surfaced there as `likes`), so use\nthis endpoint when you need per-type counts.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_53ed18", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "The Facebook post ID", "in": "query", "name": "postId", "required": true, "schema": { "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" }, "breakdown": { "description": "Count per reaction type. A type with no reactions returns 0.", "properties": { "angry": { "type": "integer" }, "care": { "type": "integer" }, "haha": { "type": "integer" }, "like": { "type": "integer" }, "love": { "type": "integer" }, "sad": { "type": "integer" }, "wow": { "type": "integer" } }, "type": "object" }, "lastUpdated": { "format": "date-time", "type": "string" }, "platform": { "type": "string" }, "postId": { "type": "string" }, "total": { "description": "Total reactions across all types", "type": "integer" }, "username": { "type": "string" } }, "type": "object" } } }, "description": "Reaction breakdown for the post" }, "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." } }, "summary": "Get Facebook post reactions", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.get_facebook_post_reactions@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "91e7189da6e2a9ed86b333d7aac35a6a7bec9f6c237e40ec2195403b88545e1c" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_53ed18", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/facebook-post-reactions" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_53ed18" } }, "/apis/v1/social/accounts/{accountId}/facebook-tagged-posts": { "get": { "description": "Analytics. 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.\n\nReturns the public posts where other people or Pages tagged the connected\nFacebook Page, as Meta returns them from the Page's `tagged` edge.\n\nCursor-paginated: pass `nextCursor` from the previous response as\n`cursor` to read the next page. `nextCursor` is null when there are no\nmore pages. Meta does not say whether a page is the last one, so the\nfinal page can come back empty with `nextCursor` null.\n\nWorks for `facebook` accounts with a Page selected. Meta needs the\n`pages_read_user_content` permission on the connection: a connection\nmade without it gets Meta's refusal back as `platform_api_error`, and\nreconnecting the account grants it.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_b38d3e", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Page size.", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 50, "minimum": 1, "type": "integer" } }, { "description": "The `nextCursor` of the previous page.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 1000, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "createdTime": { "description": "Publication time as Meta returns it (ISO 8601).", "type": [ "string", "null" ] }, "from": { "description": "Null when Meta does not return the author, which is common for posts by people.", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ], "type": [ "object", "null" ] }, "id": { "description": "Facebook post ID of the post that tags the Page.", "type": "string" }, "message": { "type": [ "string", "null" ] }, "permalinkUrl": { "description": "Public Facebook URL of the post.", "type": [ "string", "null" ] }, "pictureUrl": { "description": "Full-size picture attached to the post.", "type": [ "string", "null" ] }, "taggedTime": { "description": "When the Page was tagged in the post (ISO 8601).", "type": [ "string", "null" ] } }, "required": [ "createdTime", "from", "id", "message", "permalinkUrl", "pictureUrl", "taggedTime" ], "type": "object" }, "type": "array" }, "nextCursor": { "description": "Pass as `cursor` to read the next page. Null when there are no more pages.", "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "type": "object" } } }, "description": "One page of posts the Page is tagged in" }, "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." } }, "summary": "List the posts a Facebook Page is tagged in", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.list_facebook_tagged_posts@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "fc314a9fe6941812968d1b5e9d41168aaac620859ee8844739511f30136ae11e" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_b38d3e", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/facebook-tagged-posts" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_b38d3e" } }, "/apis/v1/social/accounts/{accountId}/facebook-visitor-posts": { "get": { "description": "Analytics. 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.\n\nReturns the posts other people published on the connected Facebook Page, newest first. A Page without visitor posts returns an empty `data` array.\n\n### What is returned\n\nAIsa reads the Page feed (Graph `/{page-id}/feed`, which works on New Pages Experience Pages, unlike the deprecated `visitor_posts` edge). It drops:\n\n- the posts the Page published itself\n- the posts other people published on their own timeline that only tag the Page\n\n### Pagination\n\nCursor-paginated: pass `nextCursor` from the previous response as `cursor` to read the next page.\n\n`limit` sets how many feed entries are scanned, so a page can hold fewer posts than `limit`, or none, while `nextCursor` is not null. `nextCursor` is null when there are no more pages, and the final page can come back empty.\n\n### Requirements\n\nWorks on `facebook` accounts with a Page selected. Meta requires the `pages_read_user_content` permission, which AIsa requests with the comments scope. An account connected without it receives Meta's refusal as `platform_api_error`.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_71edb5", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Number of Page feed entries to scan. The Page's own posts are dropped from them.", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The `nextCursor` of the previous page.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 4096, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "createdTime": { "description": "Creation time as Meta returns it (ISO 8601).", "type": [ "string", "null" ] }, "from": { "description": "The person or Page that published the post. Null when Meta omits the author.", "properties": { "id": { "description": "App-scoped ID of the author.", "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ], "type": [ "object", "null" ] }, "id": { "description": "Facebook post ID (`{pageId}_{postId}`).", "type": "string" }, "media": { "description": "Media of the first attachment, in the same shape as Facebook Page posts. Null when the post has no attachment.", "properties": { "mediaItems": { "items": { "properties": { "thumbnail": { "description": "Poster frame of a video.", "type": "string" }, "type": { "enum": [ "image", "video" ], "type": "string" }, "url": { "description": "Temporary CDN URL.", "type": "string" } }, "required": [ "type", "url" ], "type": "object" }, "type": "array" }, "mediaType": { "enum": [ "image", "video", "carousel", "text" ], "type": "string" }, "thumbnailUrl": { "description": "Temporary CDN URL of the cover image. Empty when there is none.", "type": "string" } }, "required": [ "mediaItems", "mediaType", "thumbnailUrl" ], "type": [ "object", "null" ] }, "message": { "description": "Text of the post. Null for media-only posts.", "type": [ "string", "null" ] }, "permalinkUrl": { "description": "Public Facebook URL of the post.", "type": [ "string", "null" ] } }, "required": [ "createdTime", "from", "id", "media", "message", "permalinkUrl" ], "type": "object" }, "type": "array" }, "nextCursor": { "description": "Pass as `cursor` to read the next page. Null when there are no more pages.", "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "type": "object" } } }, "description": "One page of visitor 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." } }, "summary": "List visitor posts on a Facebook Page", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.list_facebook_visitor_posts@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "7e95065dc071f874cf7c63558f02f6e7558bb8f857e4afbe448aa061ff6142ab" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_71edb5", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/facebook-visitor-posts" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_71edb5" } }, "/apis/v1/social/accounts/{accountId}/follow-status/{userId}": { "get": { "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.\n\nResolves the follow relationship between an Instagram user and the connected account, plus their public profile counters.\n\n`userId` is the Instagram-scoped id (IGSID) Meta gives you on a webhook: `sender.id` on `message.received`, `comment.author.id` on `comment.received`.\n\n### When it cannot be resolved\n\n**Meta only answers for people who have MESSAGED the account.** Commenting grants no consent, so a commenter who has never DMed you is unresolvable. That is a platform rule, not a limitation of this endpoint.\n\nWhen it cannot be resolved the response is still `200` with `isFollower: null` and an `unavailableReason`, because \"unknown\" is a normal state to branch on:\n\n- `consent_required`: the user has never messaged this account.\n- `dm_access_disabled`: the account owner turned off Instagram Direct API access.\n- `not_messageable`: the id is not a messaging-scoped id.\n- `error`: a transient Graph API failure.\n\n### Gating comment automations\n\nTo gate a comment automation on this, use the automation's `audience` rules instead of calling this per comment. They run the same lookup only on comments that actually match a keyword, and can ask the commenter to confirm with one tap.\n\n### Caching\n\nAnswers are cached briefly per (account, user). Pass `refresh=true` right after asking someone to follow, so a follow from a moment ago is visible.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_8a8acc", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Instagram-scoped user id (IGSID) from a webhook payload", "in": "path", "name": "userId", "required": true, "schema": { "type": "string" } }, { "description": "Bypass the cache and re-query Meta", "in": "query", "name": "refresh", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "followerCount": { "type": [ "integer", "null" ] }, "isFollowedByAccount": { "description": "This account follows the user.", "type": [ "boolean", "null" ] }, "isFollower": { "description": "The user follows this account. Null = unknown, never \"no\".", "type": [ "boolean", "null" ] }, "isVerified": { "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] }, "unavailableReason": { "description": "Why the follow relationship could not be resolved. Null when it was.", "enum": [ "consent_required", "dm_access_disabled", "not_messageable", "error", null ], "type": [ "string", "null" ] }, "userId": { "type": "string" }, "username": { "type": [ "string", "null" ] } }, "required": [ "accountId", "isFollower", "userId" ], "type": "object" } } }, "description": "Follow status (fields are null when Meta would not resolve it)" }, "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." } }, "summary": "Check whether an Instagram user follows the account", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.accounts.get_instagram_follow_status@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "4218fc682e8568f80e26889773c0c60d50f9ad7c6a0a7e58e188f0c35e6b7648" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_8a8acc", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/follow-status/{userId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_8a8acc" } }, "/apis/v1/social/accounts/{accountId}/gmb-attribute-metadata": { "get": { "description": "Google Business. 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.\n\nReturns metadata about which Google Business Profile attributes are available for\na location or business category. Use this endpoint to discover valid attribute names,\nvalue types, and allowed enum values before reading or writing via gmb-attributes.\n\nTwo mutually exclusive query modes:\n\n**Location mode**: pass `locationId` (or rely on the account's stored `selectedLocationId`).\nGoogle returns attributes valid for that specific location.\n\n**Category mode**: pass `categoryName` (must start with `categories/`) and `regionCode`.\nGoogle returns attributes valid for that category across the given region.\n`languageCode` is optional in category mode.\n\nBoth modes support `pageSize` and `pageToken` for pagination.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_2d8a3e", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Google Business Profile location ID (e.g. \"6257659026299438786\"). If omitted, uses the account's stored selectedLocationId. Mutually exclusive with categoryName.", "in": "query", "name": "locationId", "required": false, "schema": { "type": "string" } }, { "description": "Category resource name, must start with \"categories/\" (e.g. \"categories/gcid:plumber\"). Required together with regionCode. Mutually exclusive with locationId.", "in": "query", "name": "categoryName", "required": false, "schema": { "type": "string" } }, { "description": "BCP-47 region code (e.g. \"US\", \"ES\"). Required when categoryName is provided.", "in": "query", "name": "regionCode", "required": false, "schema": { "type": "string" } }, { "description": "BCP-47 language code for display names (e.g. \"en\", \"es\"). Optional when categoryName is provided. Omitted from the Google call when not supplied.", "in": "query", "name": "languageCode", "required": false, "schema": { "type": "string" } }, { "description": "Maximum number of attribute metadata items to return. Google defaults to 200.", "in": "query", "name": "pageSize", "required": false, "schema": { "maximum": 200, "minimum": 1, "type": "integer" } }, { "description": "Pagination token from a previous response's nextPageToken field.", "in": "query", "name": "pageToken", "required": false, "schema": { "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" }, "attributeMetadata": { "items": { "properties": { "deprecated": { "description": "True if this attribute should no longer be used.", "type": "boolean" }, "displayName": { "description": "Localized human-readable attribute name.", "type": "string" }, "groupDisplayName": { "description": "Display name of the attribute group.", "type": "string" }, "parent": { "description": "Resource name of the attribute (e.g. \"attributes/has_delivery\").", "type": "string" }, "repeatable": { "description": "True if multiple values can be set simultaneously.", "type": "boolean" }, "valueMetadata": { "description": "Possible enum values (for ENUM / REPEATED_ENUM types).", "items": { "properties": { "displayName": { "type": "string" }, "value": { "type": "string" } }, "type": "object" }, "type": "array" }, "valueType": { "description": "Value type (e.g. BOOL, ENUM, URL, REPEATED_ENUM).", "type": "string" } }, "type": "object" }, "type": "array" }, "locationId": { "description": "Only present in location mode.", "type": "string" }, "nextPageToken": { "description": "Present when additional pages of results are available.", "type": "string" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Attribute metadata fetched successfully" }, "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." } }, "summary": "Get attribute metadata", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.google_business.get_gmb_attribute_metadata@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "9b91c072348687416df578c91112bab1fcd37ad95384944188166953f103331f" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_2d8a3e", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/gmb-attribute-metadata" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_2d8a3e" } }, "/apis/v1/social/accounts/{accountId}/gmb-attributes": { "get": { "description": "Google Business. 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.\n\nReturns Google Business Profile location attributes (amenities, services, accessibility, payment types). Available attributes vary by business category.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_b29347", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.", "in": "query", "name": "locationId", "required": false, "schema": { "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" }, "attributes": { "items": { "properties": { "name": { "description": "Attribute identifier (e.g. has_delivery)", "type": "string" }, "repeatedEnumValue": { "properties": { "setValues": { "items": { "type": "string" }, "type": "array" }, "unsetValues": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "valueType": { "description": "Value type (BOOL, ENUM, URL, REPEATED_ENUM)", "type": "string" }, "values": { "items": {}, "type": "array" } }, "type": "object" }, "type": "array" }, "locationId": { "type": "string" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Attributes fetched successfully" }, "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." } }, "summary": "Get attributes", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.google_business.get_google_business_attributes@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "753de2bb296abb4b77721cedd6b9ad51734301f263e35dd0564b88a2c591e8b5" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_b29347", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/gmb-attributes" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_b29347" }, "put": { "description": "Google Business. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nUpdates location attributes (amenities, services, etc.).\n\nThe attributeMask specifies which attributes to update (comma-separated).\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "put_aisa_social_apis_v1_social_accounts_accountid_b29347", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.", "in": "query", "name": "locationId", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "attributeMask": "has_delivery,has_takeout,has_outdoor_seating", "attributes": [ { "name": "has_delivery", "values": [ true ] }, { "name": "has_takeout", "values": [ true ] }, { "name": "has_outdoor_seating", "values": [ false ] } ] }, "schema": { "properties": { "attributeMask": { "description": "Comma-separated attribute names to update (e.g. 'has_delivery,has_takeout')", "minLength": 1, "type": "string" }, "attributes": { "items": { "properties": { "name": { "minLength": 1, "type": "string" }, "repeatedEnumValue": { "properties": { "setValues": { "items": { "type": "string" }, "type": "array" }, "unsetValues": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "uriValues": { "items": { "properties": { "uri": { "format": "uri", "type": "string" } }, "required": [ "uri" ], "type": "object" }, "type": "array" }, "valueType": { "enum": [ "ATTRIBUTE_VALUE_TYPE_UNSPECIFIED", "BOOL", "ENUM", "URL", "REPEATED_ENUM" ], "type": "string" }, "values": { "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "items": {}, "type": "array" }, { "type": "object" } ] }, "type": "array" } }, "required": [ "name" ], "type": "object" }, "type": "array" } }, "required": [ "attributeMask", "attributes" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "attributes": { "items": { "type": "object" }, "type": "array" }, "locationId": { "type": "string" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Attributes updated successfully" }, "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." } }, "summary": "Update attributes", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.google_business.update_google_business_attributes@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "254a43cc4dc6eb347eca53b1498b10730ff7c534bd51a7eefb29c48a10d60fa0" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "put_aisa_social_apis_v1_social_accounts_accountid_b29347", "method": "PUT", "path": "/apis/v1/social/accounts/{accountId}/gmb-attributes" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/put_aisa_social_apis_v1_social_accounts_accountid_b29347" } }, "/apis/v1/social/accounts/{accountId}/gmb-food-menus": { "get": { "description": "Google Business. 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.\n\nReturns food menus for a Google Business Profile location including sections, items, pricing, and dietary info. Only for locations with food menu support.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_63ad1c", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.", "in": "query", "name": "locationId", "required": false, "schema": { "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" }, "locationId": { "type": "string" }, "menus": { "items": { "properties": { "cuisines": { "description": "Cuisine types (e.g. AMERICAN, ITALIAN, JAPANESE)", "items": { "type": "string" }, "type": "array" }, "labels": { "items": { "properties": { "description": { "description": "Optional description", "type": "string" }, "displayName": { "description": "Display name of the item/section/menu", "type": "string" }, "languageCode": { "description": "BCP-47 language code (e.g. en, es)", "type": "string" } }, "required": [ "displayName" ], "type": "object" }, "minItems": 1, "type": "array" }, "sections": { "items": { "properties": { "items": { "items": { "properties": { "attributes": { "properties": { "allergen": { "type": "array" }, "dietaryRestriction": { "type": "array" }, "mediaKeys": { "type": "array" }, "preparationMethods": { "type": "array" }, "price": { "type": "object" }, "servesNumPeople": { "type": "integer" }, "spiciness": { "type": "string" } }, "type": "object" }, "labels": { "items": { "type": "object" }, "minItems": 1, "type": "array" }, "options": { "description": "Item variants/options (e.g. sizes, preparations)", "items": { "type": "object" }, "type": "array" } }, "required": [ "labels" ], "type": "object" }, "type": "array" }, "labels": { "items": { "properties": { "description": { "description": "Optional description", "type": "string" }, "displayName": { "description": "Display name of the item/section/menu", "type": "string" }, "languageCode": { "description": "BCP-47 language code (e.g. en, es)", "type": "string" } }, "required": [ "displayName" ], "type": "object" }, "minItems": 1, "type": "array" } }, "required": [ "labels" ], "type": "object" }, "type": "array" }, "sourceUrl": { "description": "URL of the original menu source", "format": "uri", "type": "string" } }, "required": [ "labels" ], "type": "object" }, "type": "array" }, "name": { "description": "Resource name of the food menus", "type": "string" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Food menus fetched successfully" }, "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." } }, "summary": "Get food menus", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.google_business.get_google_business_food_menus@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "173e2a4898f08f9e381c89ef551cdea74a6336340505e0c5bab7bd8912c74cc9" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_63ad1c", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/gmb-food-menus" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_63ad1c" }, "put": { "description": "Google Business. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nUpdates food menus for a Google Business Profile location. Send the full menus array. Use updateMask for partial updates.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "put_aisa_social_apis_v1_social_accounts_accountid_63ad1c", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.", "in": "query", "name": "locationId", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "menus": [ { "labels": [ { "displayName": "Dinner Menu", "languageCode": "en" } ], "sections": [ { "items": [ { "attributes": { "allergen": [ "FISH" ], "price": { "currencyCode": "USD", "units": "24" } }, "labels": [ { "description": "With seasonal vegetables", "displayName": "Grilled Salmon" } ] } ], "labels": [ { "displayName": "Mains" } ] } ] } ], "updateMask": "menus" }, "schema": { "properties": { "menus": { "description": "Array of food menus to set", "items": { "properties": { "cuisines": { "description": "Cuisine types (e.g. AMERICAN, ITALIAN, JAPANESE)", "items": { "type": "string" }, "type": "array" }, "labels": { "items": { "properties": { "description": { "description": "Optional description", "type": "string" }, "displayName": { "description": "Display name of the item/section/menu", "type": "string" }, "languageCode": { "description": "BCP-47 language code (e.g. en, es)", "type": "string" } }, "required": [ "displayName" ], "type": "object" }, "minItems": 1, "type": "array" }, "sections": { "items": { "properties": { "items": { "items": { "properties": { "attributes": { "properties": { "allergen": { "type": "array" }, "dietaryRestriction": { "type": "array" }, "mediaKeys": { "type": "array" }, "preparationMethods": { "type": "array" }, "price": { "type": "object" }, "servesNumPeople": { "type": "integer" }, "spiciness": { "type": "string" } }, "type": "object" }, "labels": { "items": { "type": "object" }, "minItems": 1, "type": "array" }, "options": { "description": "Item variants/options (e.g. sizes, preparations)", "items": { "type": "object" }, "type": "array" } }, "required": [ "labels" ], "type": "object" }, "type": "array" }, "labels": { "items": { "properties": { "description": { "description": "Optional description", "type": "string" }, "displayName": { "description": "Display name of the item/section/menu", "type": "string" }, "languageCode": { "description": "BCP-47 language code (e.g. en, es)", "type": "string" } }, "required": [ "displayName" ], "type": "object" }, "minItems": 1, "type": "array" } }, "required": [ "labels" ], "type": "object" }, "type": "array" }, "sourceUrl": { "description": "URL of the original menu source", "format": "uri", "type": "string" } }, "required": [ "labels" ], "type": "object" }, "type": "array" }, "updateMask": { "description": "Field mask for partial updates (e.g. \"menus\")", "type": "string" } }, "required": [ "menus" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "locationId": { "type": "string" }, "menus": { "items": { "properties": { "cuisines": { "description": "Cuisine types (e.g. AMERICAN, ITALIAN, JAPANESE)", "items": { "type": "string" }, "type": "array" }, "labels": { "items": { "properties": { "description": { "description": "Optional description", "type": "string" }, "displayName": { "description": "Display name of the item/section/menu", "type": "string" }, "languageCode": { "description": "BCP-47 language code (e.g. en, es)", "type": "string" } }, "required": [ "displayName" ], "type": "object" }, "minItems": 1, "type": "array" }, "sections": { "items": { "properties": { "items": { "items": { "properties": { "attributes": { "properties": { "allergen": { "type": "array" }, "dietaryRestriction": { "type": "array" }, "mediaKeys": { "type": "array" }, "preparationMethods": { "type": "array" }, "price": { "type": "object" }, "servesNumPeople": { "type": "integer" }, "spiciness": { "type": "string" } }, "type": "object" }, "labels": { "items": { "type": "object" }, "minItems": 1, "type": "array" }, "options": { "description": "Item variants/options (e.g. sizes, preparations)", "items": { "type": "object" }, "type": "array" } }, "required": [ "labels" ], "type": "object" }, "type": "array" }, "labels": { "items": { "properties": { "description": { "description": "Optional description", "type": "string" }, "displayName": { "description": "Display name of the item/section/menu", "type": "string" }, "languageCode": { "description": "BCP-47 language code (e.g. en, es)", "type": "string" } }, "required": [ "displayName" ], "type": "object" }, "minItems": 1, "type": "array" } }, "required": [ "labels" ], "type": "object" }, "type": "array" }, "sourceUrl": { "description": "URL of the original menu source", "format": "uri", "type": "string" } }, "required": [ "labels" ], "type": "object" }, "type": "array" }, "name": { "type": "string" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Food menus updated successfully" }, "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." } }, "summary": "Update food menus", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.google_business.update_google_business_food_menus@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "d558bab607d7d4dcace59a8dba3f75553859af37cc75c728e8e3d987def26dc4" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "put_aisa_social_apis_v1_social_accounts_accountid_63ad1c", "method": "PUT", "path": "/apis/v1/social/accounts/{accountId}/gmb-food-menus" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/put_aisa_social_apis_v1_social_accounts_accountid_63ad1c" } }, "/apis/v1/social/accounts/{accountId}/gmb-location-details": { "get": { "description": "Google Business. 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.\n\nReturns detailed Google Business Profile location info (hours, description, phone, website, categories, services). Use readMask to request specific fields.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_7d035a", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.", "in": "query", "name": "locationId", "required": false, "schema": { "type": "string" } }, { "description": "Comma-separated fields to return. Available: name, title, phoneNumbers, categories, storefrontAddress, websiteUri, regularHours, specialHours, serviceArea, serviceItems, profile, openInfo, metadata, moreHours.\n\n`title` and `metadata` are always included in the response so the `location` summary block can be populated, even if you omit them here.\n\n`location` is a derived response field, not a Google readMask value: passing it returns 400.", "in": "query", "name": "readMask", "required": false, "schema": { "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" }, "categories": { "description": "Business categories (returned when readMask includes 'categories')", "properties": { "additionalCategories": { "items": { "properties": { "displayName": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" }, "primaryCategory": { "properties": { "displayName": { "description": "Human-readable category name", "type": "string" }, "name": { "description": "Category resource name", "type": "string" } }, "type": "object" } }, "type": "object" }, "location": { "description": "Compact public-facing summary derived from Google's `metadata`. Useful\nfor surfacing the \"leave a review\" URL (e.g. behind a QR code) without\nparsing the raw block. Always populated regardless of readMask.\nFor unverified or new locations Google omits placeId/reviewUrl/mapsUri,\nso those return as null and `isVerified` is false.", "properties": { "isVerified": { "description": "True when the location has Voice of Merchant (verified + live on Google)", "type": "boolean" }, "mapsUri": { "description": "Public Google Maps URL for this location", "type": [ "string", "null" ] }, "name": { "description": "Business name as set in Google Business Profile", "type": [ "string", "null" ] }, "placeId": { "description": "Google Maps Place ID for this location", "type": [ "string", "null" ] }, "reviewUrl": { "description": "Public \"write a review\" URL Google generates for this place", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "locationId": { "type": "string" }, "phoneNumbers": { "properties": { "additionalPhones": { "items": { "type": "string" }, "type": "array" }, "primaryPhone": { "type": "string" } }, "type": "object" }, "profile": { "properties": { "description": { "description": "Business description", "type": "string" } }, "type": "object" }, "regularHours": { "properties": { "periods": { "items": { "properties": { "closeDay": { "type": "string" }, "closeTime": { "type": "string" }, "openDay": { "enum": [ "MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", "SUNDAY" ], "type": "string" }, "openTime": { "description": "Opening time in HH:MM format", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "serviceItems": { "description": "Services offered (returned when readMask includes 'serviceItems')", "items": { "properties": { "freeFormServiceItem": { "properties": { "category": { "type": "string" }, "label": { "properties": { "displayName": { "type": "string" }, "languageCode": { "type": "string" } }, "type": "object" } }, "type": "object" }, "price": { "properties": { "currencyCode": { "type": "string" }, "nanos": { "type": "integer" }, "units": { "type": "string" } }, "type": "object" }, "structuredServiceItem": { "properties": { "description": { "type": "string" }, "serviceTypeId": { "type": "string" } }, "type": "object" } }, "type": "object" }, "type": "array" }, "specialHours": { "properties": { "specialHourPeriods": { "items": { "properties": { "closeTime": { "type": "string" }, "closed": { "type": "boolean" }, "endDate": { "properties": { "day": { "type": "integer" }, "month": { "type": "integer" }, "year": { "type": "integer" } }, "type": "object" }, "openTime": { "type": "string" }, "startDate": { "properties": { "day": { "type": "integer" }, "month": { "type": "integer" }, "year": { "type": "integer" } }, "type": "object" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "success": { "type": "boolean" }, "title": { "description": "Business name", "type": "string" }, "websiteUri": { "type": "string" } }, "type": "object" } } }, "description": "Location details fetched successfully" }, "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." } }, "summary": "Get location details", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.google_business.get_google_business_location_details@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "91ac98383bdaca7648fc6245fa36df9211ae56f2dbb1ed910adfa24d47592241" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_7d035a", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/gmb-location-details" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_7d035a" }, "put": { "description": "Google Business. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nUpdates Google Business Profile location details. The updateMask field is required and specifies which fields to update.\nThis endpoint proxies Google's Business Information API locations.patch, so any valid updateMask field is supported.\nCommon fields: regularHours, specialHours, profile.description, websiteUri, phoneNumbers, categories, serviceItems.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "put_aisa_social_apis_v1_social_accounts_accountid_7d035a", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.", "in": "query", "name": "locationId", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "regularHours": { "periods": [ { "closeDay": "MONDAY", "closeTime": "17:00", "openDay": "MONDAY", "openTime": "09:00" }, { "closeDay": "SATURDAY", "closeTime": "14:00", "openDay": "SATURDAY", "openTime": "10:00" } ] }, "specialHours": { "specialHourPeriods": [ { "closed": true, "startDate": { "day": 25, "month": 12, "year": 2026 } }, { "closeTime": "15:00", "openTime": "09:00", "startDate": { "day": 31, "month": 12, "year": 2026 } } ] }, "updateMask": "regularHours,specialHours" }, "schema": { "additionalProperties": true, "properties": { "adWordsLocationExtensions": { "description": "Alternate phone shown in Google Ads location extensions. Use updateMask='adWordsLocationExtensions'.", "properties": { "adPhone": { "type": "string" } }, "type": "object" }, "categories": { "description": "Primary and additional business categories. Use updateMask='categories' to update.", "properties": { "additionalCategories": { "items": { "properties": { "name": { "description": "Category resource name (e.g. 'categories/gcid:dry_cleaner')", "type": "string" } }, "type": "object" }, "type": "array" }, "primaryCategory": { "properties": { "name": { "description": "Category resource name (e.g. 'categories/gcid:laundromat'). Use Google's Categories API to look up valid IDs.", "type": "string" } }, "type": "object" } }, "type": "object" }, "labels": { "description": "Free-form, internal-only labels for grouping (1-255 characters each). Use updateMask='labels'.", "items": { "type": "string" }, "type": "array" }, "latlng": { "description": "Precise coordinates. Use updateMask='latlng'. Google restricts latlng writes to approved clients, so this update may be silently ignored or rejected.", "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" } }, "type": "object" }, "moreHours": { "description": "Additional hours for specific services (delivery, drive-through, etc.). Use updateMask='moreHours'.", "items": { "properties": { "hoursTypeId": { "description": "Hours type from Google's catalog (e.g. 'DELIVERY', 'DRIVE_THROUGH')", "type": "string" }, "periods": { "items": { "properties": { "closeDay": { "type": "string" }, "closeTime": { "type": "string" }, "openDay": { "type": "string" }, "openTime": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" }, "openInfo": { "description": "Open/closed status of the location. Use updateMask='openInfo'.", "properties": { "openingDate": { "properties": { "day": { "type": "integer" }, "month": { "type": "integer" }, "year": { "type": "integer" } }, "type": "object" }, "status": { "enum": [ "OPEN", "CLOSED_PERMANENTLY", "CLOSED_TEMPORARILY" ], "type": "string" } }, "type": "object" }, "phoneNumbers": { "properties": { "additionalPhones": { "items": { "type": "string" }, "type": "array" }, "primaryPhone": { "type": "string" } }, "type": "object" }, "profile": { "properties": { "description": { "type": "string" } }, "type": "object" }, "regularHours": { "properties": { "periods": { "items": { "properties": { "closeDay": { "type": "string" }, "closeTime": { "type": "string" }, "openDay": { "type": "string" }, "openTime": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "serviceArea": { "description": "Areas the business serves. Use updateMask='serviceArea'. Full replacement: send every place you want to keep.", "properties": { "businessType": { "enum": [ "CUSTOMER_LOCATION_ONLY", "CUSTOMER_AND_BUSINESS_LOCATION" ], "type": "string" }, "places": { "properties": { "placeInfos": { "items": { "properties": { "placeId": { "description": "Google Place ID for the area", "type": "string" }, "placeName": { "description": "Localized area name (e.g. 'Sao Paulo, SP, Brasil')", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "regionCode": { "description": "Immutable. CLDR region code of the country the business is based in (e.g. 'BR')", "type": "string" } }, "type": "object" }, "serviceItems": { "description": "Services offered by the business. Use updateMask='serviceItems' to update.", "items": { "properties": { "freeFormServiceItem": { "description": "A custom service not in Google's catalog", "properties": { "category": { "description": "Category resource name this service belongs to (e.g. 'categories/gcid:laundromat')", "type": "string" }, "label": { "properties": { "displayName": { "description": "Service name as displayed to users", "type": "string" }, "languageCode": { "description": "Language code (e.g. 'en')", "type": "string" } }, "type": "object" } }, "type": "object" }, "price": { "description": "Optional price for the service", "properties": { "currencyCode": { "description": "ISO 4217 currency code (e.g. 'USD')", "type": "string" }, "nanos": { "description": "Nano units (10^-9) of the amount", "type": "integer" }, "units": { "description": "Whole units of the amount", "type": "string" } }, "type": "object" }, "structuredServiceItem": { "description": "A predefined service from Google's service type catalog", "properties": { "description": { "description": "Optional description of the service", "type": "string" }, "serviceTypeId": { "description": "Service type ID from Google's catalog (e.g. 'job_type_id:plumbing_drain_repair')", "type": "string" } }, "type": "object" } }, "type": "object" }, "type": "array" }, "specialHours": { "properties": { "specialHourPeriods": { "items": { "properties": { "closeTime": { "type": "string" }, "closed": { "type": "boolean" }, "endDate": { "properties": { "day": { "type": "integer" }, "month": { "type": "integer" }, "year": { "type": "integer" } }, "type": "object" }, "openTime": { "type": "string" }, "startDate": { "properties": { "day": { "type": "integer" }, "month": { "type": "integer" }, "year": { "type": "integer" } }, "type": "object" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "storeCode": { "description": "External store identifier, unique within the account. Use updateMask='storeCode'.", "type": "string" }, "storefrontAddress": { "description": "Postal address of the storefront. Use updateMask='storefrontAddress'. Omit for service-area-only businesses.", "properties": { "addressLines": { "items": { "type": "string" }, "type": "array" }, "administrativeArea": { "description": "State or province", "type": "string" }, "languageCode": { "type": "string" }, "locality": { "description": "City", "type": "string" }, "postalCode": { "type": "string" }, "regionCode": { "description": "ISO 3166-1 alpha-2 country code (e.g. 'BR')", "type": "string" } }, "type": "object" }, "title": { "description": "Business name. Use updateMask='title'.", "type": "string" }, "updateMask": { "description": "Required. Comma-separated fields to update (e.g. 'regularHours', 'specialHours', 'profile.description', 'categories', 'serviceItems'). Any valid Google Business Information API updateMask field is supported.", "type": "string" }, "websiteUri": { "type": "string" } }, "required": [ "updateMask" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "locationId": { "type": "string" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Location updated successfully" }, "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." } }, "summary": "Update location details", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.google_business.update_google_business_location_details@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "ce6778b40c79ef2cd4faa4a04be08b849944aed433c798e9af35665bb18ffc22" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "put_aisa_social_apis_v1_social_accounts_accountid_7d035a", "method": "PUT", "path": "/apis/v1/social/accounts/{accountId}/gmb-location-details" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/put_aisa_social_apis_v1_social_accounts_accountid_7d035a" } }, "/apis/v1/social/accounts/{accountId}/gmb-locations": { "get": { "description": "Account settings. 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.\n\nReturns Google Business Profile locations the connected account can access, plus the currently selected location.\n\nThe list is bounded (see hasMore). For accounts that own many locations:\n\n- use the search or filter query params to find a specific one instead of loading them all;\n- or raise limit to enumerate an account with more than 100 locations.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_7ded08", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Free-text search on the business name, applied server-side by Google. Use for accounts with many locations.", "in": "query", "name": "search", "required": false, "schema": { "type": "string" } }, { "description": "Raw Google Business Information API filter expression (advanced; takes precedence over search), e.g. storeCode=\"LH279411\".", "in": "query", "name": "filter", "required": false, "schema": { "type": "string" } }, { "description": "Max locations to return (default 100, max 500). Raise it to enumerate an account with more than 100 locations; for accounts with thousands, use search/filter instead.", "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 500, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "cached": { "type": "boolean" }, "hasMore": { "description": "True when more locations exist than were returned (use search to narrow down).", "type": "boolean" }, "locations": { "items": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "accountName": { "type": "string" }, "address": { "type": "string" }, "category": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "storeCode": { "type": "string" }, "websiteUrl": { "type": "string" } }, "type": "object" }, "type": "array" }, "selectedLocationId": { "type": "string" } }, "type": "object" } } }, "description": "Locations list" }, "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." } }, "summary": "List Google Business Profile locations", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.account_settings.get_gmb_locations@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "4acf833545f2bc27152e536f926c37a8de405a4586ede9e9bfaf2fda7503aaec" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_7ded08", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/gmb-locations" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_7ded08" }, "put": { "description": "Account settings. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nSwitch which Google Business Profile location is active for a connected account.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "put_aisa_social_apis_v1_social_accounts_accountid_7ded08", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "googleAccountId": "accounts/123456789", "selectedLocationId": "12345678901234567890" }, "schema": { "properties": { "googleAccountId": { "description": "Optional but recommended. The Google Business Profile Account resource name (\"accounts/123\") that owns the new location (from GET gmb-locations).\n\nWhen provided, the location is resolved directly instead of by enumerating the account, which is required for accounts with many locations.\n\nNamed `googleAccountId` to disambiguate from the path `accountId` (the AIsa account). The legacy field name `accountId` is still accepted for backwards compatibility.", "minLength": 1, "type": "string" }, "selectedLocationId": { "minLength": 1, "type": "string" } }, "required": [ "selectedLocationId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "selectedLocation": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Location 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": { "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." } }, "summary": "Update Google Business Profile location", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.account_settings.update_gmb_location@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "c495c8526e02c3f5ea158465989a7264382bc83db4298c81ce2c5f63baa201ed" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "put_aisa_social_apis_v1_social_accounts_accountid_7ded08", "method": "PUT", "path": "/apis/v1/social/accounts/{accountId}/gmb-locations" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/put_aisa_social_apis_v1_social_accounts_accountid_7ded08" } }, "/apis/v1/social/accounts/{accountId}/gmb-locations/assign": { "post": { "description": "Account settings. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nConnect a Google Business Profile location onto a DIFFERENT profile by reusing the OAuth grant from an already-connected Google Business Profile account, with no browser and no re-authorization.\n\nBuilt for agencies whose single Google account has manager access to many client locations and who run one profile per client:\n\n1. Connect one location the normal way (browser OAuth).\n2. Bulk-assign the rest onto each client's profile via this endpoint.\n\n### Parameters\n\n- The path `accountId` is a SOURCE connected Google Business Profile account (the token holder).\n- The body `profileId` is the TARGET profile, which may already hold other locations.\n\nAssigning a location the target profile already holds refreshes that account.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_accounts_accounti_eef110", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "googleAccountId": "accounts/123456789", "profileId": "prf_2Bn8Wq5Td1Yh7Kc3Mz9Lp4", "selectedLocationId": "locations/12345678901234567890" }, "schema": { "properties": { "googleAccountId": { "description": "Optional but recommended. The Google Business Profile Account resource name (\"accounts/123\") that owns the location (from GET gmb-locations). When provided the location is resolved directly instead of by enumerating the account, required for accounts with many locations.", "type": "string" }, "profileId": { "description": "One of your profiles (prf_...).", "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" }, "selectedLocationId": { "description": "The Google Business Profile location ID to assign (e.g. \"locations/123\").", "type": "string" } }, "required": [ "profileId", "selectedLocationId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "account": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "displayName": { "type": "string" }, "isActive": { "type": "boolean" }, "platform": { "type": "string" }, "selectedLocationId": { "description": "Bare Google Business Profile location id (digits only). Combine with the Google Business Profile account id as accounts/{gbpAccountId}/locations/{selectedLocationId} to form the location resource names that gmb-reviews/batch expects in locationNames.", "type": "string" }, "selectedLocationName": { "description": "Human-readable location display name (e.g. \"Snap Fitness Dianella\"), NOT a resource name. Do not use it to build API paths.", "type": "string" }, "username": { "type": "string" } }, "type": "object" }, "message": { "type": "string" } }, "type": "object" } } }, "description": "Location assigned to the target profile" }, "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." } }, "summary": "Assign Google Business Profile location to another profile", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.account_settings.assign_google_business_location@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "ef0f952b4774f4bab757de04a5e9c573b20b746343c1d91231cb678cfcd20b2c" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_accounts_accounti_eef110", "method": "POST", "path": "/apis/v1/social/accounts/{accountId}/gmb-locations/assign" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_accounts_accounti_eef110" } }, "/apis/v1/social/accounts/{accountId}/gmb-media": { "delete": { "description": "Google Business. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nDeletes a photo or media item from a Google Business Profile location.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "delete_aisa_social_apis_v1_social_accounts_accoun_aa8387", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.", "in": "query", "name": "locationId", "required": false, "schema": { "type": "string" } }, { "description": "The media item ID to delete", "in": "query", "name": "mediaId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "type": "boolean" }, "mediaId": { "type": "string" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Media deleted successfully" }, "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." } }, "summary": "Delete photo", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.google_business.delete_google_business_media@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "87d92b0fa4e0be4ee0154c6ecd2ce2c0693cb051486bcb54f5f33e924ecebb6c" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "delete_aisa_social_apis_v1_social_accounts_accoun_aa8387", "method": "DELETE", "path": "/apis/v1/social/accounts/{accountId}/gmb-media" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/delete_aisa_social_apis_v1_social_accounts_accoun_aa8387" }, "get": { "description": "Google Business. 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.\n\nLists media items (photos) for a Google Business Profile location.\nReturns photo URLs, descriptions, categories, and metadata.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_aa8387", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.", "in": "query", "name": "locationId", "required": false, "schema": { "type": "string" } }, { "description": "Number of items to return (max 100)", "in": "query", "name": "pageSize", "required": false, "schema": { "default": 100, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Pagination token from previous response", "in": "query", "name": "pageToken", "required": false, "schema": { "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" }, "locationId": { "type": "string" }, "mediaItems": { "items": { "properties": { "createTime": { "format": "date-time", "type": "string" }, "description": { "type": "string" }, "googleUrl": { "description": "Google-hosted URL", "type": "string" }, "locationAssociation": { "properties": { "category": { "type": "string" } }, "type": "object" }, "mediaFormat": { "enum": [ "PHOTO", "VIDEO" ], "type": "string" }, "name": { "description": "Resource name", "type": "string" }, "sourceUrl": { "type": "string" }, "thumbnailUrl": { "type": "string" } }, "type": "object" }, "type": "array" }, "nextPageToken": { "type": "string" }, "success": { "type": "boolean" }, "totalMediaItemsCount": { "type": "integer" } }, "type": "object" } } }, "description": "Media items fetched successfully" }, "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." } }, "summary": "List media", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.google_business.list_google_business_media@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "4da102c2e98b2419e3b8c382039c57e10ac801dbbcfa559feb94761264bff782" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_aa8387", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/gmb-media" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_aa8387" }, "post": { "description": "Google Business. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nCreates a media item (photo) for a location from a publicly accessible URL.\n\nCategories determine where the photo appears: CATEGORY_UNSPECIFIED, COVER, PROFILE, LOGO, EXTERIOR, INTERIOR, PRODUCT, FOOD_AND_DRINK, MENU, COMMON_AREA, ROOMS, TEAMS, AT_WORK, ADDITIONAL.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_accounts_accounti_aa8387", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.", "in": "query", "name": "locationId", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "category": "INTERIOR", "description": "Dining area with outdoor seating", "sourceUrl": "https://example.com/photos/restaurant-interior.jpg" }, "schema": { "properties": { "category": { "description": "Where the photo appears on the listing", "enum": [ "CATEGORY_UNSPECIFIED", "COVER", "PROFILE", "LOGO", "EXTERIOR", "INTERIOR", "PRODUCT", "FOOD_AND_DRINK", "MENU", "COMMON_AREA", "ROOMS", "TEAMS", "AT_WORK", "ADDITIONAL" ], "type": "string" }, "description": { "description": "Photo description", "minLength": 1, "type": "string" }, "mediaFormat": { "default": "PHOTO", "enum": [ "PHOTO", "VIDEO" ], "type": "string" }, "sourceUrl": { "description": "Publicly accessible image URL", "format": "uri", "type": "string" } }, "required": [ "sourceUrl" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "googleUrl": { "type": "string" }, "mediaFormat": { "type": "string" }, "name": { "type": "string" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Media created successfully" }, "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." } }, "summary": "Upload photo", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.google_business.create_google_business_media@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "6f917eb56ccf93a1fc4cc6599c48db7ba674d78b7b996b8cee1a936a24ab7c14" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_accounts_accounti_aa8387", "method": "POST", "path": "/apis/v1/social/accounts/{accountId}/gmb-media" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_accounts_accounti_aa8387" } }, "/apis/v1/social/accounts/{accountId}/gmb-place-actions": { "delete": { "description": "Google Business. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nDeletes a place action link (e.g. booking or ordering URL) from a Google Business Profile location.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "delete_aisa_social_apis_v1_social_accounts_accoun_badf32", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.", "in": "query", "name": "locationId", "required": false, "schema": { "type": "string" } }, { "description": "The resource name of the place action link (e.g. locations/123/placeActionLinks/456)", "in": "query", "name": "name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "type": "boolean" }, "name": { "type": "string" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Place action deleted successfully" }, "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." } }, "summary": "Delete action link", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.google_business.delete_google_business_place_action@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "d5fdde4be3da7324e59ecf84163c496cc3269732d568a162fd04aa48054b55b8" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "delete_aisa_social_apis_v1_social_accounts_accoun_badf32", "method": "DELETE", "path": "/apis/v1/social/accounts/{accountId}/gmb-place-actions" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/delete_aisa_social_apis_v1_social_accounts_accoun_badf32" }, "get": { "description": "Google Business. 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.\n\nLists place action links for a Google Business Profile location.\n\nPlace actions are the booking, ordering, and reservation buttons that appear on your listing.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_badf32", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.", "in": "query", "name": "locationId", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "pageSize", "required": false, "schema": { "default": 100, "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "pageToken", "required": false, "schema": { "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" }, "locationId": { "type": "string" }, "nextPageToken": { "type": "string" }, "placeActionLinks": { "items": { "properties": { "createTime": { "format": "date-time", "type": "string" }, "name": { "description": "Resource name", "type": "string" }, "placeActionType": { "type": "string" }, "updateTime": { "format": "date-time", "type": "string" }, "uri": { "description": "Action URL", "type": "string" } }, "type": "object" }, "type": "array" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Place actions fetched successfully" }, "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." } }, "summary": "List action links", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.google_business.list_google_business_place_actions@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "b7d920611617a2eeb7117ae317d529e574da5e08790c412db2a87ef1a21a3106" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_badf32", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/gmb-place-actions" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_badf32" }, "patch": { "description": "Google Business. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nUpdates a place action link (change URL or action type).\nOnly the fields included in the request body will be updated.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "patch_aisa_social_apis_v1_social_accounts_account_badf32", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Override which location to target. If omitted, uses the account's selected location.", "in": "query", "name": "locationId", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "name": "locations/123/placeActionLinks/456", "uri": "https://order.doordash.com/joespizza" }, "schema": { "properties": { "name": { "description": "Resource name of the place action link (e.g. locations/123/placeActionLinks/456)", "type": "string" }, "placeActionType": { "description": "New action type", "enum": [ "APPOINTMENT", "ONLINE_APPOINTMENT", "DINING_RESERVATION", "FOOD_ORDERING", "FOOD_DELIVERY", "FOOD_TAKEOUT", "SHOP_ONLINE" ], "type": "string" }, "uri": { "description": "New action URL. At least one of uri or placeActionType is required (enforced server-side; not modeled as anyOf because required-only anyOf branches break SDK generators).", "format": "uri", "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "name": { "type": "string" }, "placeActionType": { "type": "string" }, "success": { "type": "boolean" }, "uri": { "type": "string" } }, "type": "object" } } }, "description": "Place action updated successfully" }, "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." } }, "summary": "Update action link", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.google_business.update_google_business_place_action@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "915a3c7239631bdbc1189195328f54f93221ff62ec6149a7eb3addcff82d4f11" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "patch_aisa_social_apis_v1_social_accounts_account_badf32", "method": "PATCH", "path": "/apis/v1/social/accounts/{accountId}/gmb-place-actions" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/patch_aisa_social_apis_v1_social_accounts_account_badf32" }, "post": { "description": "Google Business. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nCreates a place action link for a location.\n\nAvailable action types: APPOINTMENT, ONLINE_APPOINTMENT, DINING_RESERVATION, FOOD_ORDERING, FOOD_DELIVERY, FOOD_TAKEOUT, SHOP_ONLINE.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_accounts_accounti_badf32", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.", "in": "query", "name": "locationId", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "placeActionType": "FOOD_ORDERING", "uri": "https://order.ubereats.com/joespizza" }, "schema": { "properties": { "placeActionType": { "description": "Type of action", "enum": [ "APPOINTMENT", "ONLINE_APPOINTMENT", "DINING_RESERVATION", "FOOD_ORDERING", "FOOD_DELIVERY", "FOOD_TAKEOUT", "SHOP_ONLINE" ], "type": "string" }, "uri": { "description": "The action URL", "format": "uri", "type": "string" } }, "required": [ "placeActionType", "uri" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "name": { "description": "Resource name of the created link", "type": "string" }, "placeActionType": { "type": "string" }, "success": { "type": "boolean" }, "uri": { "type": "string" } }, "type": "object" } } }, "description": "Place action created successfully" }, "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." } }, "summary": "Create action link", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.google_business.create_google_business_place_action@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "a71bc3b4077186861110fca875f772f61f20c7b903e1ea8381f6c5322ad8fa22" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_accounts_accounti_badf32", "method": "POST", "path": "/apis/v1/social/accounts/{accountId}/gmb-place-actions" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_accounts_accounti_badf32" } }, "/apis/v1/social/accounts/{accountId}/gmb-reviews": { "get": { "description": "Google Business. 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.\n\nReturns reviews for a Google Business Profile account including ratings, comments, and owner replies. Use nextPageToken for pagination.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_cf07fe", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.", "in": "query", "name": "locationId", "required": false, "schema": { "type": "string" } }, { "description": "Number of reviews to fetch per page (max 50)", "in": "query", "name": "pageSize", "required": false, "schema": { "default": 50, "maximum": 50, "minimum": 1, "type": "integer" } }, { "description": "Pagination token from previous response", "in": "query", "name": "pageToken", "required": false, "schema": { "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" }, "averageRating": { "description": "Overall average rating", "type": "number" }, "locationId": { "type": "string" }, "nextPageToken": { "description": "Token for next page", "type": [ "string", "null" ] }, "reviews": { "items": { "description": "A Google Business Profile review, as returned by every gmb-reviews read endpoint.", "properties": { "comment": { "description": "Review text", "type": "string" }, "createTime": { "format": "date-time", "type": "string" }, "id": { "description": "Review ID", "type": "string" }, "name": { "description": "Full resource name", "type": "string" }, "photoCount": { "description": "Number of photos attached to the review (photos only, videos are not counted)", "type": "integer" }, "photos": { "description": "Photos attached to the review by the reviewer", "items": { "properties": { "url": { "format": "uri", "type": "string" } }, "type": "object" }, "type": "array" }, "rating": { "description": "Numeric star rating (0 when Google sends no rating)", "maximum": 5, "minimum": 0, "type": "integer" }, "reviewReply": { "properties": { "comment": { "description": "Business owner reply", "type": "string" }, "updateTime": { "format": "date-time", "type": "string" } }, "type": [ "object", "null" ] }, "reviewer": { "properties": { "displayName": { "type": "string" }, "isAnonymous": { "type": "boolean" }, "profilePhotoUrl": { "type": [ "string", "null" ] } }, "type": "object" }, "starRating": { "description": "Google's string rating", "enum": [ "ONE", "TWO", "THREE", "FOUR", "FIVE" ], "type": "string" }, "updateTime": { "format": "date-time", "type": "string" } }, "type": "object" }, "type": "array" }, "success": { "type": "boolean" }, "totalReviewCount": { "description": "Total number of reviews", "type": "integer" } }, "type": "object" } } }, "description": "Reviews fetched successfully" }, "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." } }, "summary": "Get reviews", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.google_business.get_google_business_reviews@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "69610bb02ce0377ff4d4adc2b797fde1270275c7ff17be2130d3717a823bfa3e" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_cf07fe", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/gmb-reviews" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_cf07fe" } }, "/apis/v1/social/accounts/{accountId}/gmb-reviews/batch": { "post": { "description": "Google Business. 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.\n\nFetches reviews across multiple locations in a single request. More efficient than calling GET /gmb-reviews per location for multi-location businesses.\n\n### Response\n\nReturns a flat locationReviews array (not grouped by location). Each item carries:\n\n- `name`: the location resource name it belongs to.\n- `review`: the review object, whose identity is `review.reviewId`.\n\n### Ordering\n\nReviews are requested from Google ordered by `orderBy` (default `updateTime desc`, newest first). Callers polling for recent reviews can stop paginating once they cross their date window.\n\n### Aggregate metrics\n\nThis endpoint does not return aggregate metrics (averageRating / totalReviewCount). For those, use the single-location GET /gmb-reviews endpoint.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_accounts_accounti_a99a2c", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "locationNames": [ "accounts/123/locations/456", "accounts/123/locations/789" ], "pageSize": 50 }, "schema": { "properties": { "locationNames": { "description": "Array of full location resource names (e.g. ['accounts/123/locations/456']). Max 50 per request (Google's batchGetReviews cap); chunk larger sets into multiple requests.", "items": { "pattern": "^accounts/[^/]+/locations/[^/]+$", "type": "string" }, "maxItems": 50, "minItems": 1, "type": "array" }, "orderBy": { "default": "updateTime desc", "description": "Sort order requested from Google. Defaults to 'updateTime desc' (newest first), which allows early-stopping pagination once results cross your date window.", "enum": [ "updateTime desc", "rating", "rating desc" ], "type": "string" }, "pageSize": { "default": 50, "description": "Number of reviews per page (max 50)", "maximum": 50, "minimum": 1, "type": "integer" }, "pageToken": { "description": "Pagination token from previous response", "minLength": 1, "type": "string" } }, "required": [ "locationNames" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "locationReviews": { "items": { "properties": { "name": { "description": "LOCATION resource name the review belongs to (accounts/{accountId}/locations/{locationId}) - NOT the review resource name. Use it to attribute the review to a location; the review identity is review.reviewId (full review resource name at review.name).", "type": "string" }, "review": { "description": "The review object: reviewId (the review's identity), name (full review resource name, accounts/*/locations/*/reviews/*), starRating, comment, reviewer, createTime, updateTime, reviewReply, and reviewMediaItems (review photos/videos; photo items carry thumbnailUrl, video items carry videoUrl)", "type": "object" } }, "type": "object" }, "type": "array" }, "nextPageToken": { "type": "string" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Batch reviews fetched successfully" }, "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." } }, "summary": "Batch get reviews", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.google_business.batch_get_google_business_reviews@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "3c3481b72b4cff0ca85c3d71b07c35316809d59b56e3c3e70c124d7f9b820f57" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_accounts_accounti_a99a2c", "method": "POST", "path": "/apis/v1/social/accounts/{accountId}/gmb-reviews/batch" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_accounts_accounti_a99a2c" } }, "/apis/v1/social/accounts/{accountId}/gmb-reviews/{reviewId}": { "get": { "description": "Google Business. 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.\n\nReturns one Google Business Profile review, in the same shape as the entries of GET /apis/v1/social/accounts/{accountId}/gmb-reviews.\n\nThe review is read from the account's selected location unless locationId overrides it. Google returns 404 for a review id that belongs to another location.\n\nRead the review before replying if a human may have answered it already: replies are overwritten in place and Google keeps no history.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_de45eb", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "The review ID portion (e.g. \"AIe9_BGx1234567890\"), not the full resource name", "in": "path", "name": "reviewId", "required": true, "schema": { "type": "string" } }, { "description": "Override which location to read the review from. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.", "in": "query", "name": "locationId", "required": false, "schema": { "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" }, "locationId": { "type": "string" }, "review": { "description": "A Google Business Profile review, as returned by every gmb-reviews read endpoint.", "properties": { "comment": { "description": "Review text", "type": "string" }, "createTime": { "format": "date-time", "type": "string" }, "id": { "description": "Review ID", "type": "string" }, "name": { "description": "Full resource name", "type": "string" }, "photoCount": { "description": "Number of photos attached to the review (photos only, videos are not counted)", "type": "integer" }, "photos": { "description": "Photos attached to the review by the reviewer", "items": { "properties": { "url": { "format": "uri", "type": "string" } }, "type": "object" }, "type": "array" }, "rating": { "description": "Numeric star rating (0 when Google sends no rating)", "maximum": 5, "minimum": 0, "type": "integer" }, "reviewReply": { "properties": { "comment": { "description": "Business owner reply", "type": "string" }, "updateTime": { "format": "date-time", "type": "string" } }, "type": [ "object", "null" ] }, "reviewer": { "properties": { "displayName": { "type": "string" }, "isAnonymous": { "type": "boolean" }, "profilePhotoUrl": { "type": [ "string", "null" ] } }, "type": "object" }, "starRating": { "description": "Google's string rating", "enum": [ "ONE", "TWO", "THREE", "FOUR", "FIVE" ], "type": "string" }, "updateTime": { "format": "date-time", "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Review fetched successfully" }, "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." } }, "summary": "Get a review", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.google_business.get_google_business_review@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "4623b3f217cb6010bf44752c5a9559cbf2b18dc7f9bf393d3c8698b066ad9f38" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_de45eb", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/gmb-reviews/{reviewId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_de45eb" } }, "/apis/v1/social/accounts/{accountId}/gmb-reviews/{reviewId}/reply": { "delete": { "description": "Google Business. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nRemoves the business owner reply from a Google Business Profile review. The review itself remains.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "delete_aisa_social_apis_v1_social_accounts_accoun_9b4cb2", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "The review ID portion (e.g. \"AIe9_BGx1234567890\"), not the full resource name", "in": "path", "name": "reviewId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "platform": { "type": "string" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Reply deleted successfully" }, "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." } }, "summary": "Delete a review reply", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.google_business.delete_google_business_review_reply@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "6a94de7cf8578e93b3270858008784031c568b33041b912aefd41680e232ad67" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "delete_aisa_social_apis_v1_social_accounts_accoun_9b4cb2", "method": "DELETE", "path": "/apis/v1/social/accounts/{accountId}/gmb-reviews/{reviewId}/reply" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/delete_aisa_social_apis_v1_social_accounts_accoun_9b4cb2" }, "post": { "description": "Google Business. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nPosts (or updates) the business owner reply to a Google Business Profile review.\n\nThe reply is associated with the account's currently selected location (set via /apis/v1/social/accounts/{accountId}/gmb-locations).\n\n### Overwrites\n\nCalling this endpoint a second time on the same review overwrites the previous reply (PUT semantics on Google's side).\n\nGoogle keeps no history, so an automated retry silently replaces a reply someone edited by hand in the Google Business Profile UI. Read the review before retrying if a human may have answered it.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_accounts_accounti_9b4cb2", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "The review ID portion (e.g. \"AIe9_BGx1234567890\"), not the full resource name", "in": "path", "name": "reviewId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "comment": "Thank you for your kind words, we really appreciate it!" }, "schema": { "properties": { "comment": { "description": "The reply text to post on the review. Must be non-empty.", "minLength": 1, "type": "string" } }, "required": [ "comment" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "platform": { "type": "string" }, "reviewId": { "type": "string" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Reply posted successfully" }, "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." } }, "summary": "Reply to a review", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.google_business.reply_to_google_business_review@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "4357874eda21ab67fd0d522512c70b150e7f0bea46257d0856787ca7689c8777" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_accounts_accounti_9b4cb2", "method": "POST", "path": "/apis/v1/social/accounts/{accountId}/gmb-reviews/{reviewId}/reply" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_accounts_accounti_9b4cb2" } }, "/apis/v1/social/accounts/{accountId}/gmb-services": { "get": { "description": "Google Business. 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.\n\nGets the services offered by a Google Business Profile location.\nReturns an array of service items (structured or free-form with optional price).\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_a7f18f", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Override which location to query. If omitted, uses the account's selected location.", "in": "query", "name": "locationId", "required": false, "schema": { "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" }, "locationId": { "type": "string" }, "services": { "items": { "properties": { "freeFormServiceItem": { "properties": { "category": { "type": "string" }, "label": { "properties": { "description": { "type": "string" }, "displayName": { "type": "string" } }, "type": "object" } }, "type": "object" }, "price": { "properties": { "currencyCode": { "type": "string" }, "nanos": { "type": "integer" }, "units": { "type": "string" } }, "type": "object" }, "structuredServiceItem": { "properties": { "description": { "type": "string" }, "serviceTypeId": { "type": "string" } }, "type": "object" } }, "type": "object" }, "type": "array" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Services fetched successfully" }, "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." } }, "summary": "Get services", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.google_business.get_google_business_services@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "04c595c9340f0216814a6c02463b4109337ad78c5fcaa96282126312c02b99dd" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_a7f18f", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/gmb-services" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_a7f18f" }, "put": { "description": "Google Business. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nReplaces the entire service list for a location.\nGoogle's API requires full replacement; individual item updates are not supported.\nEach service can be structured (using a predefined serviceTypeId) or free-form (custom label).\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "put_aisa_social_apis_v1_social_accounts_accountid_a7f18f", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Override which location to target. If omitted, uses the account's selected location.", "in": "query", "name": "locationId", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "serviceItems": [ { "freeFormServiceItem": { "category": "categories/gcid:plumber", "label": { "description": "Emergency and scheduled pipe repair", "displayName": "Pipe Repair" } }, "price": { "currencyCode": "USD", "units": "150" } } ] }, "schema": { "properties": { "serviceItems": { "items": { "properties": { "freeFormServiceItem": { "properties": { "category": { "minLength": 1, "type": "string" }, "label": { "properties": { "description": { "type": "string" }, "displayName": { "minLength": 1, "type": "string" }, "languageCode": { "type": "string" } }, "required": [ "displayName" ], "type": "object" } }, "required": [ "category", "label" ], "type": "object" }, "price": { "properties": { "currencyCode": { "minLength": 1, "type": "string" }, "nanos": { "type": "integer" }, "units": { "minLength": 1, "type": "string" } }, "type": "object" }, "structuredServiceItem": { "description": "Exactly one of structuredServiceItem or freeFormServiceItem is required per item (enforced server-side; not modeled as oneOf because required-only oneOf branches break SDK generators).", "properties": { "description": { "type": "string" }, "serviceTypeId": { "minLength": 1, "type": "string" } }, "required": [ "serviceTypeId" ], "type": "object" } }, "type": "object" }, "type": "array" } }, "required": [ "serviceItems" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "services": { "items": { "type": "object" }, "type": "array" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Services updated successfully" }, "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." } }, "summary": "Replace services", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.google_business.update_google_business_services@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "4d9043231896affeb7e794c22ad00b16c72bc60718bc7955f1d35d26b58ba11e" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "put_aisa_social_apis_v1_social_accounts_accountid_a7f18f", "method": "PUT", "path": "/apis/v1/social/accounts/{accountId}/gmb-services" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/put_aisa_social_apis_v1_social_accounts_accountid_a7f18f" } }, "/apis/v1/social/accounts/{accountId}/gmb-verifications": { "get": { "description": "Google Business. 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.\n\nReturns the location's Voice of Merchant state plus its verification history. `voiceOfMerchantState.hasVoiceOfMerchant` tells you whether the listing is verified and published; when it is false, `verify` reports whether a verification is already pending. Each entry in `verifications` has a `state` of PENDING, COMPLETED, or FAILED.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_3006c1", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.", "in": "query", "name": "locationId", "required": false, "schema": { "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" }, "locationId": { "type": "string" }, "success": { "type": "boolean" }, "verifications": { "description": "Verification history, newest first. Empty when none exist.", "items": { "properties": { "createTime": { "format": "date-time", "type": "string" }, "method": { "description": "Method used (omitted on some entries).", "enum": [ "ADDRESS", "EMAIL", "PHONE_CALL", "SMS", "AUTO", "VETTED_PARTNER" ], "type": "string" }, "name": { "description": "Resource name, e.g. \"locations/123/verifications/0T1776879124712\". The last segment is the verificationId.", "type": "string" }, "state": { "enum": [ "PENDING", "COMPLETED", "FAILED" ], "type": "string" } }, "type": "object" }, "type": "array" }, "voiceOfMerchantState": { "description": "Raw Voice of Merchant state from Google.", "properties": { "hasBusinessAuthority": { "description": "True when the authenticated user has owner/manager authority over the listing.", "type": "boolean" }, "hasVoiceOfMerchant": { "description": "True when the listing is verified and published (eligible to surface reviews, edits, etc.).", "type": "boolean" }, "verify": { "description": "Present when verification is the path to Voice of Merchant.", "properties": { "hasPendingVerification": { "description": "True when a verification is already in progress.", "type": "boolean" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } }, "description": "Verification state fetched successfully" }, "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." } }, "summary": "Get verification state", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.google_business.get_google_business_verifications@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "279c2ec62a10f37f603efdae1f351be88787e381738630387a49b14c763207c2" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_3006c1", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/gmb-verifications" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_3006c1" }, "post": { "description": "Google Business. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nStarts a verification for the location. This is a mutating action: depending on `method`, Google mails a postcard, places a call, or sends an SMS/email to the business. Submit the resulting code with POST /gmb-verifications/{verificationId}/complete. Use POST /gmb-verifications/options first to discover which methods are eligible.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_accounts_accounti_3006c1", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Override which location to target. If omitted, uses the account's selected location.", "in": "query", "name": "locationId", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "languageCode": "en-US", "method": "SMS", "phoneNumber": "+14155550123" }, "schema": { "properties": { "context": { "description": "ServiceBusinessContext (e.g. service address). Required for service-area businesses.", "type": "object" }, "emailAddress": { "description": "For EMAIL.", "type": "string" }, "languageCode": { "type": "string" }, "mailerContact": { "description": "For ADDRESS (postcard) verification.", "type": "object" }, "method": { "description": "The verification method. Selects which method-specific field below is required.", "enum": [ "ADDRESS", "EMAIL", "PHONE_CALL", "SMS", "AUTO", "VETTED_PARTNER" ], "type": "string" }, "phoneNumber": { "description": "For PHONE_CALL / SMS.", "type": "string" } }, "required": [ "method" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "locationId": { "type": "string" }, "success": { "type": "boolean" }, "verification": { "properties": { "createTime": { "format": "date-time", "type": "string" }, "method": { "enum": [ "ADDRESS", "EMAIL", "PHONE_CALL", "SMS", "AUTO", "VETTED_PARTNER" ], "type": "string" }, "name": { "type": "string" }, "state": { "enum": [ "PENDING", "COMPLETED", "FAILED" ], "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Verification started" }, "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." } }, "summary": "Start a verification", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.google_business.start_google_business_verification@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "5d64e72e530464e7ec36373c23ae8996959e2c73fe4563d337046c40943dbd82" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_accounts_accounti_3006c1", "method": "POST", "path": "/apis/v1/social/accounts/{accountId}/gmb-verifications" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_accounts_accounti_3006c1" } }, "/apis/v1/social/accounts/{accountId}/gmb-verifications/options": { "post": { "description": "Google Business. 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.\n\nReports the verification methods Google currently offers for the location. Non-mutating (nothing is sent to the business). `languageCode` is required; service-area (\"CUSTOMER_LOCATION_ONLY\") businesses also require `context.address`, otherwise Google returns 400.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_accounts_accounti_85bc88", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Override which location to query. If omitted, uses the account's selected location.", "in": "query", "name": "locationId", "required": false, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "languageCode": "en-US" }, "schema": { "properties": { "context": { "description": "ServiceBusinessContext. Required for service-area businesses (must include the service address).", "type": "object" }, "languageCode": { "type": "string" } }, "required": [ "languageCode" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "locationId": { "type": "string" }, "options": { "items": { "properties": { "phoneNumber": { "description": "Present for PHONE_CALL / SMS.", "type": "string" }, "verificationMethod": { "enum": [ "ADDRESS", "EMAIL", "PHONE_CALL", "SMS", "AUTO", "VETTED_PARTNER" ], "type": "string" } }, "type": "object" }, "type": "array" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Verification options fetched" }, "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." } }, "summary": "Fetch verification options", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.google_business.fetch_google_business_verification_options@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "e81690d9ec10cc03f0d0812f3bc486739148709b3a30b23e8bccd945430794ca" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_accounts_accounti_85bc88", "method": "POST", "path": "/apis/v1/social/accounts/{accountId}/gmb-verifications/options" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_accounts_accounti_85bc88" } }, "/apis/v1/social/accounts/{accountId}/gmb-verifications/{verificationId}/complete": { "post": { "description": "Google Business. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nCompletes a PENDING verification by submitting the PIN/code Google sent the business (postcard code, SMS PIN, etc.). On success the verification moves to COMPLETED.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_accounts_accounti_8651fa", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "The last segment of a verification `name` from GET /gmb-verifications.", "in": "path", "name": "verificationId", "required": true, "schema": { "type": "string" } }, { "description": "Override which location to target. If omitted, uses the account's selected location.", "in": "query", "name": "locationId", "required": false, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "pin": "123456" }, "schema": { "properties": { "pin": { "description": "The code Google sent to the business.", "type": "string" } }, "required": [ "pin" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "locationId": { "type": "string" }, "success": { "type": "boolean" }, "verification": { "properties": { "createTime": { "format": "date-time", "type": "string" }, "method": { "enum": [ "ADDRESS", "EMAIL", "PHONE_CALL", "SMS", "AUTO", "VETTED_PARTNER" ], "type": "string" }, "name": { "type": "string" }, "state": { "enum": [ "PENDING", "COMPLETED", "FAILED" ], "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Verification completed" }, "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." } }, "summary": "Complete a verification", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.google_business.complete_google_business_verification@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "55aefb2869387c8b9ba560ced9cd8db33e36fcc8cb925b13f7ead92a0fc1e606" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_accounts_accounti_8651fa", "method": "POST", "path": "/apis/v1/social/accounts/{accountId}/gmb-verifications/{verificationId}/complete" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_accounts_accounti_8651fa" } }, "/apis/v1/social/accounts/{accountId}/health": { "get": { "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.\n\nReturns detailed health info for a specific account including token status, permissions, and recommendations.\n\nA failing or stalled analytics sync (see `analyticsSync`) raises a healthy account to at least `warning`.\n\n### Facebook, Instagram and Threads\n\nThe 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`.\n\nThe 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.\n\nNeither verdict disconnects the account. That happens only when a real operation fails, and `account.disconnected` is sent.\n\n### WhatsApp\n\nThe 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`).\n\nThe 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.\n\n- When the Meta link is dead, `platformConnection.status` is `disconnected` and the overall `status` is `error`.\n- 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`.\n- 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.\n\n### Standalone ads connections (`googleads`, `redditads`, `microsoftads`)\n\nA 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.\n\nOn `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.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "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.\n\n- **Facebook/Instagram:** error subcodes 2534122, 1893063, 2534029. Set on the first refused send, cleared when a later send succeeds.\n- **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.\n\nAfter 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.\n\n- `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.\n- `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).\n- `true`: Meta reports no such problem.\n- `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." } }, "summary": "Check account health", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.accounts.get_account_health@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "4192a16c38875faf9df76a77a53ad6593a4204a9db86c3cf17374eb49955bf35" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_health", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/health" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_health" } }, "/apis/v1/social/accounts/{accountId}/hubspot-settings": { "get": { "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.\n\nRead a connected HubSpot portal and what AIsa syncs to it.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_764712", "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": { "account": { "properties": { "_id": { "description": "AIsa account ID of the HubSpot connection.", "type": "string" }, "hubDomain": { "description": "HubSpot portal domain, when HubSpot reports one.", "type": [ "string", "null" ] }, "hubId": { "description": "HubSpot portal (hub) ID.", "type": "string" }, "logMessages": { "description": "Whether AIsa logs inbox messages on HubSpot contact timelines.", "type": "boolean" }, "platform": { "enum": [ "hubspot" ], "type": "string" }, "reportDeals": { "description": "Whether AIsa sends closed-won deals as Purchase events to the profile's event destinations.", "type": "boolean" }, "scopes": { "description": "OAuth scopes the portal granted.", "items": { "type": "string" }, "type": "array" }, "syncContacts": { "description": "Whether AIsa creates HubSpot contacts for inbox contacts that match none.", "type": "boolean" } }, "required": [ "_id", "hubDomain", "hubId", "logMessages", "platform", "reportDeals", "scopes", "syncContacts" ], "type": "object" } }, "type": "object" } } }, "description": "HubSpot settings" }, "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." } }, "summary": "Get HubSpot account settings", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.accounts.get_hub_spot_settings@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "781d4967a6f4ab538a176973f6dd8698f2b5a0c91c2fb56c28e56199f9d648ab" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_764712", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/hubspot-settings" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_764712" }, "patch": { "description": "Accounts. 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.\n\nTurn contact sync, message logging or deal reporting on or off for a connected HubSpot portal. Send at least one field; omitted fields keep their value. Settings survive reconnecting the same portal.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "patch_aisa_social_apis_v1_social_accounts_account_764712", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "properties": { "logMessages": { "description": "Log inbound and outbound inbox messages on the contact's HubSpot timeline.", "type": "boolean" }, "reportDeals": { "description": "Send each deal that becomes closed won as a Purchase to the profile's event destinations, about once an hour. Requires the portal to have granted `crm.objects.deals.read`; otherwise 400. Deals closed before it was turned on are not sent.", "type": "boolean" }, "syncContacts": { "description": "Create a HubSpot contact for an inbox contact that matches none by email or phone. A match is linked as it is and never updated.", "type": "boolean" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "account": { "properties": { "_id": { "description": "AIsa account ID of the HubSpot connection.", "type": "string" }, "hubDomain": { "description": "HubSpot portal domain, when HubSpot reports one.", "type": [ "string", "null" ] }, "hubId": { "description": "HubSpot portal (hub) ID.", "type": "string" }, "logMessages": { "description": "Whether AIsa logs inbox messages on HubSpot contact timelines.", "type": "boolean" }, "platform": { "enum": [ "hubspot" ], "type": "string" }, "reportDeals": { "description": "Whether AIsa sends closed-won deals as Purchase events to the profile's event destinations.", "type": "boolean" }, "scopes": { "description": "OAuth scopes the portal granted.", "items": { "type": "string" }, "type": "array" }, "syncContacts": { "description": "Whether AIsa creates HubSpot contacts for inbox contacts that match none.", "type": "boolean" } }, "required": [ "_id", "hubDomain", "hubId", "logMessages", "platform", "reportDeals", "scopes", "syncContacts" ], "type": "object" }, "message": { "type": "string" } }, "type": "object" } } }, "description": "Updated settings" }, "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." } }, "summary": "Update HubSpot account settings", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.accounts.update_hub_spot_settings@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "9e83c6f5bf342fa4442f65aee54f4cfacf435e54c5a4a309fffe663e3e90140b" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "patch_aisa_social_apis_v1_social_accounts_account_764712", "method": "PATCH", "path": "/apis/v1/social/accounts/{accountId}/hubspot-settings" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/patch_aisa_social_apis_v1_social_accounts_account_764712" } }, "/apis/v1/social/accounts/{accountId}/instagram/audio": { "get": { "description": "Instagram. 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.\n\nSearch Instagram's audio catalog (licensed music or original sounds),\nor list what is currently trending by omitting `q`. Returns up to ~30\nassets; Meta exposes no pagination on this edge.\n\nPass the returned `audioId` as\n`platformSpecificData.audioConfiguration.audioId` when creating a Reel\nto publish it with that track.\n\nRequires an Instagram account connected via **Facebook Login**. Meta\nhosts this catalog on graph.facebook.com only, so accounts connected\nwith classic Instagram Login receive a 400\n(`instagram_audio_requires_facebook_login`) and must be reconnected\nchoosing the Facebook option.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_d96147", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Catalog to search: licensed music or original sounds from Reels.", "in": "query", "name": "audioType", "required": true, "schema": { "enum": [ "music", "original_sound" ], "type": "string" } }, { "description": "Search keywords. Omit to get the current trending list.", "in": "query", "name": "q", "required": false, "schema": { "maxLength": 200, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "audio": { "items": { "description": "One asset from the Instagram audio catalog. Licensed music carries artist/artwork fields; original sounds carry creator fields instead, so most fields are nullable.", "properties": { "audioId": { "description": "Audio asset ID. Pass it as platformSpecificData.audioConfiguration.audioId when creating a Reel.", "type": "string" }, "audioType": { "description": "Catalog type of the asset.", "enum": [ "music", "original_sound", null ], "type": [ "string", "null" ] }, "coverArtworkThumbnailUrl": { "description": "Cover artwork thumbnail (licensed music only).", "type": [ "string", "null" ] }, "displayArtist": { "description": "Artist name (licensed music only).", "type": [ "string", "null" ] }, "downloadUrl": { "description": "Temporary preview URL. Meta expires it after roughly 1.5 days; re-fetch the asset to refresh it.", "type": [ "string", "null" ] }, "durationInMs": { "description": "Asset duration in milliseconds.", "type": [ "integer", "null" ] }, "igUsername": { "description": "Creator username (original sounds only).", "type": [ "string", "null" ] }, "isAdsEligible": { "description": "Whether the asset is eligible for ads use.", "type": [ "boolean", "null" ] }, "onPlatformAudioPreviewLink": { "description": "Instagram web link to preview the audio.", "type": [ "string", "null" ] }, "profilePictureUrl": { "description": "Creator profile picture (original sounds only).", "type": [ "string", "null" ] }, "title": { "description": "Track or sound title.", "type": [ "string", "null" ] } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Matching audio assets (may be empty)" }, "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." } }, "summary": "Search Instagram audio", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.instagram.search_instagram_audio@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "baa7d66550139b4505ccc012af5c1d8989ddd171a5971a45ff103cf395227834" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_d96147", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/instagram/audio" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_d96147" } }, "/apis/v1/social/accounts/{accountId}/instagram/audio/{audioId}": { "get": { "description": "Instagram. 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.\n\nFetch one audio asset's metadata by ID. Use it to re-validate a stored\n`audioId` before a scheduled Reel publishes, or to refresh the preview\n`downloadUrl` (Meta expires preview URLs after roughly 1.5 days).\n\nSame connection requirement as the search endpoint: Facebook-Login\nInstagram accounts only.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_e8190f", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Instagram audio asset ID", "in": "path", "name": "audioId", "required": true, "schema": { "pattern": "^\\d{1,30}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "audio": { "description": "One asset from the Instagram audio catalog. Licensed music carries artist/artwork fields; original sounds carry creator fields instead, so most fields are nullable.", "properties": { "audioId": { "description": "Audio asset ID. Pass it as platformSpecificData.audioConfiguration.audioId when creating a Reel.", "type": "string" }, "audioType": { "description": "Catalog type of the asset.", "enum": [ "music", "original_sound", null ], "type": [ "string", "null" ] }, "coverArtworkThumbnailUrl": { "description": "Cover artwork thumbnail (licensed music only).", "type": [ "string", "null" ] }, "displayArtist": { "description": "Artist name (licensed music only).", "type": [ "string", "null" ] }, "downloadUrl": { "description": "Temporary preview URL. Meta expires it after roughly 1.5 days; re-fetch the asset to refresh it.", "type": [ "string", "null" ] }, "durationInMs": { "description": "Asset duration in milliseconds.", "type": [ "integer", "null" ] }, "igUsername": { "description": "Creator username (original sounds only).", "type": [ "string", "null" ] }, "isAdsEligible": { "description": "Whether the asset is eligible for ads use.", "type": [ "boolean", "null" ] }, "onPlatformAudioPreviewLink": { "description": "Instagram web link to preview the audio.", "type": [ "string", "null" ] }, "profilePictureUrl": { "description": "Creator profile picture (original sounds only).", "type": [ "string", "null" ] }, "title": { "description": "Track or sound title.", "type": [ "string", "null" ] } }, "type": "object" } }, "type": "object" } } }, "description": "The audio asset" }, "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." } }, "summary": "Get Instagram audio metadata", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.instagram.get_instagram_audio@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "569d43040a4f85288e3d7ef7827b7ed3f2f3326d5924ab539d79f77bd1df68d4" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_e8190f", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/instagram/audio/{audioId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_e8190f" } }, "/apis/v1/social/accounts/{accountId}/instagram/business-discovery": { "get": { "description": "Instagram. 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.\n\nReturns the public profile and most recent media of any Instagram\nBusiness or Creator account, looked up by username through one of your\nconnected Instagram accounts. Useful for competitor and market research.\nPersonal accounts and private accounts cannot be looked up.\n\nRequires an Instagram account connected via **Facebook Login**. Meta\nserves business discovery on graph.facebook.com only, so accounts\nconnected with classic Instagram Login receive a 400\n(`instagram_business_discovery_requires_facebook_login`) and must be\nreconnected choosing the Facebook option. Any one such account can look\nup any public Business or Creator handle.\n\n`likeCount` is null when the owner hides like counts.\n\nMedia URLs are temporary, and fields Meta does not return come back as null, never omitted.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_2b1a7f", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Instagram handle to look up, with or without the leading @. Case-insensitive.", "in": "query", "name": "username", "required": true, "schema": { "maxLength": 31, "type": "string" } }, { "description": "How many of the most recent media to return.", "in": "query", "name": "limit", "required": false, "schema": { "default": 12, "maximum": 25, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "media": { "description": "Most recent media first, up to `limit`.", "items": { "properties": { "caption": { "type": [ "string", "null" ] }, "children": { "description": "Carousel slides in order. Null unless mediaType is CAROUSEL_ALBUM.", "items": { "properties": { "id": { "type": "string" }, "mediaType": { "type": [ "string", "null" ] }, "mediaUrl": { "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] } }, "required": [ "id", "mediaType", "mediaUrl", "thumbnailUrl" ], "type": "object" }, "type": [ "array", "null" ] }, "commentsCount": { "type": [ "integer", "null" ] }, "id": { "type": "string" }, "likeCount": { "description": "Null when the owner hides like counts", "type": [ "integer", "null" ] }, "mediaProductType": { "description": "FEED or REELS", "type": [ "string", "null" ] }, "mediaType": { "description": "IMAGE, VIDEO or CAROUSEL_ALBUM", "type": [ "string", "null" ] }, "mediaUrl": { "description": "Temporary CDN URL that expires; download the file rather than storing the link. Null on videos whose audio is licensed music, use thumbnailUrl for the cover.", "type": [ "string", "null" ] }, "permalink": { "type": [ "string", "null" ] }, "thumbnailUrl": { "description": "Video cover frame, VIDEO only. Temporary CDN URL.", "type": [ "string", "null" ] }, "timestamp": { "format": "date-time", "type": [ "string", "null" ] }, "viewCount": { "description": "Reels only. Null on images and carousels.", "type": [ "integer", "null" ] } }, "required": [ "caption", "children", "commentsCount", "id", "likeCount", "mediaProductType", "mediaType", "mediaUrl", "permalink", "thumbnailUrl", "timestamp", "viewCount" ], "type": "object" }, "type": "array" }, "profile": { "properties": { "biography": { "type": [ "string", "null" ] }, "followersCount": { "type": [ "integer", "null" ] }, "followsCount": { "type": [ "integer", "null" ] }, "id": { "description": "Instagram user ID of the looked-up account", "type": "string" }, "mediaCount": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "profilePictureUrl": { "description": "Temporary CDN URL; download it rather than storing the link.", "type": [ "string", "null" ] }, "username": { "type": "string" }, "website": { "type": [ "string", "null" ] } }, "required": [ "id", "username" ], "type": "object" } }, "required": [ "media", "profile" ], "type": "object" } } }, "description": "Public profile and recent media" }, "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." } }, "summary": "Look up a public Instagram Business account", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.instagram.get_instagram_business_discovery@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "1fc59b375145ea4b4c7c8e671668988835638909437c989db2392ab3b698da7f" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_2b1a7f", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/instagram/business-discovery" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_2b1a7f" } }, "/apis/v1/social/accounts/{accountId}/instagram/live-media": { "get": { "description": "Instagram. 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.\n\nReturns the live videos the connected Instagram account is broadcasting right now.\n\nMeta only returns broadcasts in progress at the time of the request, so the list is empty when nothing is live (a 200, not an error).\n\nPair the returned `id` with comments flagged as live (the live_comments webhook field) or with a `live_comment` comment automation.\n\n### Requires Facebook Login\n\nThe Instagram account must be connected via **Facebook Login**. Meta documents the live_media edge on graph.facebook.com only.\n\nAccounts connected with classic Instagram Login receive a 400 (`instagram_live_media_requires_facebook_login`) and must be reconnected choosing the Facebook option.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_d39605", "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": { "data": { "items": { "properties": { "id": { "description": "Instagram media ID of the live broadcast.", "type": "string" }, "mediaProductType": { "description": "LIVE for a live video.", "type": [ "string", "null" ] }, "mediaType": { "description": "BROADCAST for a live video.", "type": [ "string", "null" ] }, "timestamp": { "description": "Creation time of the broadcast media as Meta returns it (ISO 8601).", "type": [ "string", "null" ] }, "username": { "description": "Instagram handle of the broadcasting account.", "type": [ "string", "null" ] } }, "required": [ "id", "mediaProductType", "mediaType", "timestamp", "username" ], "type": "object" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "Live broadcasts in progress" }, "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." } }, "summary": "List the live broadcasts of an Instagram account", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.instagram.list_instagram_live_media@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "a7a3bfcc383cf77b629f96817cdbbe2dd101717abf64b9b9de0200748aeb96af" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_d39605", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/instagram/live-media" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_d39605" } }, "/apis/v1/social/accounts/{accountId}/instagram/media/{mediaId}/collaborators": { "get": { "description": "Instagram. 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.\n\nReturns the accounts invited as collaborators on one of the connected\naccount's own posts (feed image, Reel or carousel), with whether each\ninvitation was accepted or is still pending. Use it to check who\naccepted a collab post after publishing it.\n\nRequires an Instagram account connected via **Facebook Login**. Meta\nserves this edge on graph.facebook.com only, so accounts connected with\nclassic Instagram Login receive a 400\n(`instagram_collaborators_require_facebook_login`) and must be\nreconnected choosing the Facebook option.\n\nMeta returns at most 5 collaborators and only those who allow\ncollaborator tagging. A post without collaborators returns an empty list.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_3a824b", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Instagram media ID of a post published by this account (digits only, e.g. the platformPostId of a published post).", "in": "path", "name": "mediaId", "required": true, "schema": { "pattern": "^[0-9]+$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "id": { "description": "App-scoped ID of the collaborator's Instagram account.", "type": "string" }, "inviteStatus": { "description": "accepted or pending. Any other value Meta adds later is passed through in lowercase.", "type": [ "string", "null" ] }, "username": { "description": "Instagram handle of the collaborator.", "type": [ "string", "null" ] } }, "required": [ "id", "inviteStatus", "username" ], "type": "object" }, "maxItems": 5, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "Collaborators of the post" }, "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." } }, "summary": "List the collaborators of an Instagram post", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.instagram.list_instagram_media_collaborators@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "09f2acd6455a3efc5802b8fcc3235c53c7a0f4dd7b5eb54019aa7749ba57d175" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_3a824b", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/instagram/media/{mediaId}/collaborators" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_3a824b" } }, "/apis/v1/social/accounts/{accountId}/instagram/mentions/comments/{commentId}": { "get": { "description": "Instagram. 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.\n\nReturns a comment in which another Instagram user @mentioned the connected account, with the post it was left on.\n\nMeta sends the comment ID in its mention notification and offers no list of mentions, so this reads one mention by ID. Meta answers an error when comments are disabled on that post.\n\n### Requires Facebook Login\n\nThe Instagram account must be connected via **Facebook Login**. Meta serves mentions on graph.facebook.com only.\n\nAccounts connected with classic Instagram Login receive a 400 (`instagram_mentions_require_facebook_login`) and must be reconnected choosing the Facebook option.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_636880", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Instagram comment ID of the comment that mentions the account (digits only).", "in": "path", "name": "commentId", "required": true, "schema": { "maxLength": 32, "pattern": "^[0-9]+$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "id": { "description": "Instagram comment ID of the comment that mentions the account.", "type": "string" }, "likeCount": { "type": [ "integer", "null" ] }, "media": { "description": "The post the comment was left on.", "properties": { "id": { "description": "Instagram media ID of the post.", "type": "string" } }, "required": [ "id" ], "type": [ "object", "null" ] }, "text": { "type": [ "string", "null" ] }, "timestamp": { "description": "Creation time as Meta returns it (ISO 8601).", "type": [ "string", "null" ] } }, "required": [ "id", "likeCount", "media", "text", "timestamp" ], "type": "object" } } }, "description": "Get a comment that mentions an Instagram account" }, "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." } }, "summary": "Get a comment that mentions an Instagram account", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.instagram.get_instagram_mentioned_comment@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "01bb440ac10f1cf8cafd3e91925db580665442b4197002641ca0be9859ec48d7" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_636880", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/instagram/mentions/comments/{commentId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_636880" } }, "/apis/v1/social/accounts/{accountId}/instagram/mentions/media/{mediaId}": { "get": { "description": "Instagram. 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.\n\nReturns a post in which another Instagram user @mentioned the\nconnected account in the caption. Meta sends the media ID in its\nmention notification and offers no list of mentions, so this reads one\nmention by ID. Mentions in Stories are not supported by Meta.\n\nRequires an Instagram account connected via **Facebook Login**. Meta\nserves mentions on graph.facebook.com only, so accounts connected with\nclassic Instagram Login receive a 400\n(`instagram_mentions_require_facebook_login`) and must be reconnected\nchoosing the Facebook option.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_5765da", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Instagram media ID of the post that mentions the account (digits only).", "in": "path", "name": "mediaId", "required": true, "schema": { "maxLength": 32, "pattern": "^[0-9]+$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "caption": { "type": [ "string", "null" ] }, "commentsCount": { "type": [ "integer", "null" ] }, "id": { "description": "Instagram media ID of the post whose caption mentions the account.", "type": "string" }, "likeCount": { "description": "Null when the owner hides like counts.", "type": [ "integer", "null" ] }, "mediaType": { "description": "IMAGE, VIDEO or CAROUSEL_ALBUM.", "type": [ "string", "null" ] }, "mediaUrl": { "description": "Temporary CDN URL. Meta omits it for videos with copyrighted or licensed audio and reels whose owner disabled downloads.", "type": [ "string", "null" ] }, "timestamp": { "description": "Publication time as Meta returns it (ISO 8601).", "type": [ "string", "null" ] }, "username": { "description": "Instagram handle of the account that posted the media and mentioned yours.", "type": [ "string", "null" ] } }, "required": [ "caption", "commentsCount", "id", "likeCount", "mediaType", "mediaUrl", "timestamp", "username" ], "type": "object" } } }, "description": "Get a post that mentions an Instagram account in its caption" }, "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." } }, "summary": "Get a post that mentions an Instagram account in its caption", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.instagram.get_instagram_mentioned_media@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "1c2e2ce50338e846745473e31604709e15a0ba198429cdb42262240a592897e2" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_5765da", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/instagram/mentions/media/{mediaId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_5765da" } }, "/apis/v1/social/accounts/{accountId}/instagram/publishing-limit": { "get": { "description": "Instagram. 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.\n\nReturns the account's remaining content-publishing quota for Instagram's rolling\n24-hour window, so you can pace publishing and warn before the cap is reached.\n\n`quotaUsage` counts containers published since the start of the window.\nAlways compare against the returned `quotaTotal` rather than hardcoding a number:\nMeta's prose documentation and the live API disagree on the value, and the live\nvalue is authoritative.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_bbc84a", "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": { "quotaDurationSeconds": { "description": "Length of the rolling window in seconds", "type": "integer" }, "quotaTotal": { "description": "Maximum containers publishable per window", "type": "integer" }, "quotaUsage": { "description": "Containers published so far in the current window", "type": "integer" } }, "type": "object" } } }, "description": "Remaining publishing quota for the rolling window" }, "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." } }, "summary": "Get Instagram publishing limit", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.instagram.get_instagram_publishing_limit@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "3cdc826cfcb3f4aa1f2e08b598c76bb6c97e210b12d981dca8d3beebf7d04b70" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_bbc84a", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/instagram/publishing-limit" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_bbc84a" } }, "/apis/v1/social/accounts/{accountId}/instagram/stories": { "get": { "description": "Instagram. 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.\n\nReturns the IG Business/Creator account's currently-active stories.\nMeta keeps stories live for 24h; expired stories are not returned.\n\nLimitations propagated from Meta (these are NOT bugs):\n- 24h window only\n- Live videos excluded\n- Reshared stories not returned\n- `mediaUrl` may be null if Meta flagged the story for copyright\n- `caption`, `likeCount`, `commentsCount` do not apply to story media\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_f867cc", "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": { "data": { "items": { "properties": { "id": { "description": "Instagram media ID of the story.", "type": "string" }, "mediaProductType": { "description": "Always 'STORY' for this endpoint.", "type": [ "string", "null" ] }, "mediaType": { "description": "IMAGE / VIDEO / CAROUSEL_ALBUM", "type": [ "string", "null" ] }, "mediaUrl": { "description": "Direct media URL. Null if Meta flagged the story for copyright. URL expires when the story expires.", "type": [ "string", "null" ] }, "permalink": { "description": "Public Instagram permalink to the story (only viewable while live).", "type": [ "string", "null" ] }, "thumbnailUrl": { "description": "Thumbnail URL for video stories.", "type": [ "string", "null" ] }, "timestamp": { "description": "When the story was posted.", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": "object" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "Active stories" }, "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." } }, "summary": "List active Instagram stories", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.instagram.list_instagram_stories@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "a2ebf51f13a46a9a7aa9a41a3b9435d74563a6fbaf89bc5e7baac19938411de9" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_f867cc", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/instagram/stories" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_f867cc" } }, "/apis/v1/social/accounts/{accountId}/instagram/stories/{storyId}/insights": { "get": { "description": "Instagram. 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.\n\nReturns metrics for a single story. The `source` field discriminates between three states:\n\n- `live`: fetched from Meta in real time (story is still active)\n- `cached`: fetched from a persisted `story_insights` webhook payload (story has expired but we received its final-state metrics from Meta)\n- `unavailable`: story has expired and Meta sent no `story_insights` webhook for it\n\nMeta sends that webhook most reliably for accounts connected with Facebook Login or with their linked Facebook Page connected. So read insights while the story is live if you need final numbers.\n\nMeta can report an expired story as an empty successful result rather than an error. So an expired story resolves to `cached` or `unavailable` even though the upstream request itself succeeded.\n\n### Field semantics\n\nField semantics follow Meta's API.\n\n- Counts below 5 may be returned as 0 due to Meta's privacy floor on small audiences.\n- The `navigation` field is the sum of `tapsForward + tapsBack + exits + swipesForward`.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_efb0e8", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "The Instagram media ID of the story.", "in": "path", "name": "storyId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "metrics": { "properties": { "exits": { "description": "Closed Stories interface entirely.", "type": "integer" }, "follows": { "type": "integer" }, "navigation": { "description": "Total nav actions (tapsForward + tapsBack + exits + swipesForward).", "type": "integer" }, "profileVisits": { "type": "integer" }, "reach": { "description": "Unique accounts that saw the story.", "type": "integer" }, "replies": { "description": "DMs sent in reply to the story.", "type": "integer" }, "reposts": { "type": "integer" }, "shares": { "type": "integer" }, "swipesForward": { "description": "Swiped left to next account's story.", "type": "integer" }, "tapsBack": { "description": "Tapped left to previous slide.", "type": "integer" }, "tapsForward": { "description": "Tapped right to next slide of SAME story.", "type": "integer" }, "totalInteractions": { "type": "integer" }, "views": { "description": "Total story plays. Replaces deprecated 'impressions' for media created after 2024-07-02.", "type": "integer" } }, "required": [ "exits", "follows", "navigation", "profileVisits", "reach", "replies", "reposts", "shares", "swipesForward", "tapsBack", "tapsForward", "totalInteractions", "views" ], "type": "object" }, "source": { "enum": [ "live", "cached", "unavailable" ], "type": "string" } }, "required": [ "metrics", "source" ], "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "Story insights" }, "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." } }, "summary": "Get Instagram story insights", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.instagram.get_instagram_story_insights@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "40364c9469b7a5ffa90da69ed17f053f9de1bc3a57d1ff5270523970f3edec56" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_efb0e8", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/instagram/stories/{storyId}/insights" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_efb0e8" } }, "/apis/v1/social/accounts/{accountId}/instagram/tags": { "get": { "description": "Instagram. 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.\n\nReturns the media where other Instagram users photo-tagged the connected\naccount, newest first. Private media is never returned.\n\nCursor-paginated: pass `nextCursor` from the previous response as\n`cursor` to read the next page. `nextCursor` is null when there are no\nmore pages. Meta does not say whether a page is the last one, so the\nfinal page can come back empty with `nextCursor` null.\n\nRequires an Instagram account connected via **Facebook Login**. Meta\ndoes not give Instagram Login access to tagging, so accounts connected\nwith classic Instagram Login receive a 400\n(`instagram_tagged_media_requires_facebook_login`) and must be\nreconnected choosing the Facebook option.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_634b4a", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Page size.", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 50, "minimum": 1, "type": "integer" } }, { "description": "The `nextCursor` of the previous page.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 1000, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "caption": { "type": [ "string", "null" ] }, "commentsCount": { "type": [ "integer", "null" ] }, "id": { "description": "Instagram media ID of the post the account is tagged in.", "type": "string" }, "likeCount": { "description": "Null when the owner hides like counts.", "type": [ "integer", "null" ] }, "mediaProductType": { "description": "FEED or REELS.", "type": [ "string", "null" ] }, "mediaType": { "description": "IMAGE, VIDEO or CAROUSEL_ALBUM.", "type": [ "string", "null" ] }, "mediaUrl": { "description": "Temporary CDN URL. Meta omits it for videos with copyrighted audio, flagged videos and reels whose owner disabled downloads.", "type": [ "string", "null" ] }, "permalink": { "description": "Public Instagram URL of the post.", "type": [ "string", "null" ] }, "thumbnailUrl": { "description": "Cover image of a video or reel.", "type": [ "string", "null" ] }, "timestamp": { "description": "Publication time as Meta returns it (ISO 8601).", "type": [ "string", "null" ] }, "username": { "description": "Instagram handle of the account that posted the media and tagged yours.", "type": [ "string", "null" ] } }, "required": [ "caption", "commentsCount", "id", "likeCount", "mediaProductType", "mediaType", "mediaUrl", "permalink", "thumbnailUrl", "timestamp", "username" ], "type": "object" }, "type": "array" }, "nextCursor": { "description": "Pass as `cursor` to read the next page. Null when there are no more pages.", "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "type": "object" } } }, "description": "One page of tagged media" }, "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." } }, "summary": "List the posts an Instagram account is tagged in", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.instagram.list_instagram_tagged_media@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "83797e5745011d2d1d611d44bd137d8ed5a9e8c313d60b11315fa5f3f3a18d40" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_634b4a", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/instagram/tags" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_634b4a" } }, "/apis/v1/social/accounts/{accountId}/linkedin-aggregate-analytics": { "get": { "description": "Analytics. 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.\n\nReturns aggregate analytics across all posts for a LinkedIn personal account. Requires r_member_postAnalytics scope.\n\nCovers every post authored by the member, whether or not it was published through AIsa (LinkedIn aggregates by member, not by post). Org accounts should use /apis/v1/social/analytics instead.\n\nSaves (POST_SAVE) and sends (POST_SEND) are available for personal accounts. Organization pages always return 0 for these two metrics because LinkedIn does not expose them on the organization analytics endpoint.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_ac2eba", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "TOTAL (default, lifetime totals) or DAILY (time series). MEMBERS_REACHED not available with DAILY.", "in": "query", "name": "aggregation", "required": false, "schema": { "default": "TOTAL", "enum": [ "TOTAL", "DAILY" ], "type": "string" } }, { "description": "Start date (YYYY-MM-DD). If omitted, returns lifetime analytics.", "in": "query", "name": "fromDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "End date (YYYY-MM-DD, exclusive). Defaults to today if omitted.", "in": "query", "name": "toDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Alias of fromDate, kept for existing callers", "in": "query", "name": "startDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Alias of toDate, kept for existing callers", "in": "query", "name": "endDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Comma-separated metrics: IMPRESSION, MEMBERS_REACHED, REACTION, COMMENT, RESHARE, POST_SAVE, POST_SEND. Omit for all.", "in": "query", "name": "metrics", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "description": "Response for TOTAL aggregation (lifetime totals)", "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "accountType": { "type": "string" }, "aggregation": { "enum": [ "TOTAL" ], "type": "string" }, "analytics": { "properties": { "comments": { "description": "Total comments across all posts", "type": "integer" }, "engagementRate": { "description": "Overall engagement rate, as a percentage rounded to 2 decimals: (reactions + comments + shares + saves + sends) / impressions * 100.\n\nClicks are not counted and there is no fallback denominator, so this is 0 whenever impressions is 0. NOT the same formula as PostAnalytics.engagementRate on GET /apis/v1/social/analytics.", "type": "number" }, "impressions": { "description": "Total impressions across all posts", "type": "integer" }, "reach": { "description": "Unique members reached across all posts", "type": "integer" }, "reactions": { "description": "Total reactions across all posts", "type": "integer" }, "saves": { "description": "Total times posts were saved (personal accounts only)", "type": "integer" }, "sends": { "description": "Total times posts were sent via LinkedIn messaging (personal accounts only)", "type": "integer" }, "shares": { "description": "Total reshares across all posts", "type": "integer" } }, "type": "object" }, "dateRange": { "properties": { "endDate": { "format": "date", "type": "string" }, "startDate": { "format": "date", "type": "string" } }, "type": [ "object", "null" ] }, "lastUpdated": { "format": "date-time", "type": "string" }, "note": { "type": "string" }, "platform": { "type": "string" }, "username": { "type": "string" } }, "type": "object" }, { "description": "Response for DAILY aggregation (time series breakdown)", "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "accountType": { "type": "string" }, "aggregation": { "enum": [ "DAILY" ], "type": "string" }, "analytics": { "description": "Daily breakdown of each metric as date/count pairs. Reach not available with DAILY aggregation.", "properties": { "comments": { "items": { "properties": { "count": { "type": "integer" }, "date": { "format": "date", "type": "string" } }, "type": "object" }, "type": "array" }, "impressions": { "items": { "properties": { "count": { "type": "integer" }, "date": { "format": "date", "type": "string" } }, "type": "object" }, "type": "array" }, "reactions": { "items": { "properties": { "count": { "type": "integer" }, "date": { "format": "date", "type": "string" } }, "type": "object" }, "type": "array" }, "saves": { "description": "Daily saves (personal accounts only)", "items": { "properties": { "count": { "type": "integer" }, "date": { "format": "date", "type": "string" } }, "type": "object" }, "type": "array" }, "sends": { "description": "Daily sends via LinkedIn messaging (personal accounts only)", "items": { "properties": { "count": { "type": "integer" }, "date": { "format": "date", "type": "string" } }, "type": "object" }, "type": "array" }, "shares": { "items": { "properties": { "count": { "type": "integer" }, "date": { "format": "date", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "dateRange": { "properties": { "endDate": { "format": "date", "type": "string" }, "startDate": { "format": "date", "type": "string" } }, "type": [ "object", "null" ] }, "lastUpdated": { "format": "date-time", "type": "string" }, "note": { "type": "string" }, "platform": { "type": "string" }, "skippedMetrics": { "description": "Metrics that were skipped due to API limitations", "items": { "type": "string" }, "type": "array" }, "username": { "type": "string" } }, "type": "object" } ] } } }, "description": "Aggregate analytics data" }, "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." } }, "summary": "Get LinkedIn aggregate stats", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.get_linked_in_aggregate_analytics@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "86c95fca131cea450b1373305722d7cb5faaa1606a03e146802672f727fa44ad" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_ac2eba", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/linkedin-aggregate-analytics" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_ac2eba" } }, "/apis/v1/social/accounts/{accountId}/linkedin-mentions": { "get": { "description": "LinkedIn Mentions. 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.\n\nConverts a LinkedIn profile or company URL to a URN for @mentions in posts.\n\nYou usually do not need this endpoint. Put the profile or company URL inside `@[...]` in the post `content` (for example `@[https://www.linkedin.com/in/vincentjong]`) and the post resolves it for you, using LinkedIn's own name.\n\nUse this endpoint to preview what a URL resolves to, or to get ready-made `@Name` markup, which still works in `content` and is published exactly as written.\n\n### Example\n\n1. Resolve: GET /apis/v1/social/accounts/{id}/linkedin-mentions?url=linkedin.com/in/vincentjong\n2. Returns: mentionFormat: \"@Vincent Jong\"\n3. Use in post content: \"Great talk with @Vincent Jong today!\"\n\nImportant: the mentions array field in POST /apis/v1/social/posts is stored for reference only and does NOT trigger @mentions on LinkedIn. Write the mention in the content text.\n\n### Requirements\n\n- Resolving a profile URL to a person mention requires the LinkedIn account to be admin of at least one organization: both endpoints that resolve a profile URL to a member URN take an organization you administer.\n- A resolved person mention publishes from any account. Organization mentions (e.g. @Microsoft) have no such requirement.\n- Person mentions DO work when published from personal profiles (the URN only needs to be valid). The limitation is only in the resolution step (URL to URN), not in publishing.\n\n### Why a profile can 404\n\nThe two resolution endpoints are not scoped alike:\n\n- peopleTypeahead?q=organizationFollowers only returns that organization's followers.\n- vanityUrl?q=vanityUrlAsOrganization does not, and its resolvable set is opaque.\n\nA 404 here does not mean the person is unknown to you or unknown to LinkedIn: a live public profile can 404 with no reason given.\n\n### Display name\n\ndisplayName is deprecated and ignored in practice: the endpoint reads the person's real name from LinkedIn itself. LinkedIn renders a person mention as a link only when the mention text is the person's first name, last name or full name (case-sensitive).\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_477d29", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "LinkedIn profile URL, company URL, or vanity name.", "in": "query", "name": "url", "required": true, "schema": { "type": "string" } }, { "description": "Deprecated: omit it. When omitted, the real name is read from LinkedIn. Ignored for org mentions, which always use the organization's LinkedIn name.\n\nWhen sent for a person, it overrides the mention text, and LinkedIn renders the mention only if it is exactly the person's first name, last name or full name (case-sensitive).", "in": "query", "name": "displayName", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "displayName": { "description": "Display name (provided, from API, or derived from vanity URL)", "type": "string" }, "mentionFormat": { "description": "Ready-to-use mention format for post content", "type": "string" }, "type": { "description": "The type of entity (person or organization)", "enum": [ "person", "organization" ], "type": "string" }, "urn": { "description": "The LinkedIn URN (person or organization)", "type": "string" }, "vanityName": { "description": "The vanity name/slug (only for organization mentions)", "type": "string" }, "warning": { "description": "Only present for person mentions when displayName was not provided and the real name could not be resolved from LinkedIn", "type": "string" } }, "type": "object" } } }, "description": "URN resolved successfully" }, "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." } }, "summary": "Resolve LinkedIn mention", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.linkedin_mentions.get_linked_in_mentions@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "e32d0351a93e6ae1e9664df80a0a38d3f581748f5d65ae07353981462376010f" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_477d29", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/linkedin-mentions" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_477d29" } }, "/apis/v1/social/accounts/{accountId}/linkedin-organization": { "put": { "description": "Account settings. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nSwitch a LinkedIn account between personal profile and organization (company page) posting.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "put_aisa_social_apis_v1_social_accounts_accountid_c83c9e", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "accountType": "organization", "selectedOrganization": { "id": "12345678", "name": "Acme Corporation", "urn": "urn:li:organization:12345678", "vanityName": "acme-corp" } }, "schema": { "properties": { "accountType": { "enum": [ "personal", "organization" ], "type": "string" }, "selectedOrganization": { "type": "object" } }, "required": [ "accountType" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "accountName": { "type": "string" }, "accountType": { "enum": [ "personal", "organization" ], "type": "string" }, "message": { "type": "string" } }, "type": "object" } } }, "description": "Account 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": { "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." } }, "summary": "Switch LinkedIn account type", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.account_settings.update_linked_in_organization@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "0e897254b00a4c88b192d049704db4c31bd1a66dae79079938028d0b1f205530" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "put_aisa_social_apis_v1_social_accounts_accountid_c83c9e", "method": "PUT", "path": "/apis/v1/social/accounts/{accountId}/linkedin-organization" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/put_aisa_social_apis_v1_social_accounts_accountid_c83c9e" } }, "/apis/v1/social/accounts/{accountId}/linkedin-organizations": { "get": { "description": "Account settings. 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.\n\nReturns LinkedIn organizations (company pages) the connected account has admin access to.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_ff7a11", "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": { "organizations": { "items": { "properties": { "id": { "type": "string" }, "localizedName": { "type": "string" }, "name": { "type": "string" }, "vanityName": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Organizations list" }, "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." } }, "summary": "List LinkedIn orgs", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.account_settings.get_linked_in_organizations@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "9250fc1141d8df240b76f9db58a94a84f18988289c747a3c8ed40989a752b0e2" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_ff7a11", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/linkedin-organizations" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_ff7a11" } }, "/apis/v1/social/accounts/{accountId}/linkedin-post-analytics": { "get": { "description": "Analytics. 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.\n\nReturns analytics for a specific LinkedIn post by URN. Works for both personal and organization accounts. Saves and sends are only populated for personal accounts (LinkedIn does not expose these metrics on the organization analytics endpoint).\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_8a5549", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "The LinkedIn post URN", "in": "query", "name": "urn", "required": true, "schema": { "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" }, "accountType": { "enum": [ "personal", "organization" ], "type": "string" }, "analytics": { "properties": { "clicks": { "description": "Clicks on the post (organization accounts only)", "type": "integer" }, "comments": { "description": "Comments on the post", "type": "integer" }, "engagementRate": { "description": "Engagement rate, as a percentage rounded to 2 decimals: (likes + comments + shares + clicks + saves + sends) / impressions * 100.\n\nUnlike PostAnalytics.engagementRate on GET /apis/v1/social/analytics, this one DOES count clicks and has no fallback denominator, so it is 0 whenever impressions is 0.\n\nFor organization accounts the value is the rate LinkedIn returns, not one computed here.", "type": "number" }, "impressions": { "description": "Times the post was shown", "type": "integer" }, "likes": { "description": "Reactions on the post", "type": "integer" }, "reach": { "description": "Unique members who saw the post", "type": "integer" }, "saves": { "description": "Times the post was saved (personal accounts only; 0 for organization accounts)", "type": "integer" }, "sends": { "description": "Times the post was sent via LinkedIn messaging (personal accounts only; 0 for organization accounts)", "type": "integer" }, "shares": { "description": "Reshares of the post", "type": "integer" }, "views": { "description": "Video views (video posts only)", "type": "integer" } }, "type": "object" }, "lastUpdated": { "format": "date-time", "type": "string" }, "platform": { "type": "string" }, "postUrn": { "type": "string" }, "username": { "type": "string" } }, "type": "object" } } }, "description": "Post analytics data" }, "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." } }, "summary": "Get LinkedIn post stats", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.get_linked_in_post_analytics@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "a012a0bc9cd0a2169be936c8c707ad3b4e722d6e02cabbd900a5880ba0806f09" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_8a5549", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/linkedin-post-analytics" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_8a5549" } }, "/apis/v1/social/accounts/{accountId}/linkedin-post-reactions": { "get": { "description": "Analytics. 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.\n\nReturns individual reactions for a specific LinkedIn post, including reactor profiles\n(name, headline/job title, profile picture, profile URL, reaction type).\nOnly works for organization/company page accounts. LinkedIn restricts reaction\ndata for personal profiles (r_member_social_feed is a closed permission).\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_b907d7", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "The LinkedIn post URN", "in": "query", "name": "urn", "required": true, "schema": { "pattern": "^urn:li:(share|ugcPost|activity):[0-9]+$", "type": "string" } }, { "description": "Maximum number of reactions to return per page", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Offset-based pagination start index", "in": "query", "name": "cursor", "required": false, "schema": { "default": 0, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "accountType": { "type": "string" }, "lastUpdated": { "format": "date-time", "type": "string" }, "pagination": { "properties": { "cursor": { "description": "Offset for next page", "type": "string" }, "hasMore": { "type": "boolean" }, "total": { "description": "Total number of reactions (when available)", "type": "integer" } }, "type": "object" }, "platform": { "type": "string" }, "postUrn": { "type": "string" }, "reactions": { "items": { "properties": { "from": { "properties": { "headline": { "description": "Reactor's headline/job title", "type": "string" }, "name": { "description": "Reactor's display name", "type": "string" }, "profilePicture": { "description": "Profile picture URL", "type": "string" }, "profileUrl": { "description": "Direct link to LinkedIn profile", "type": "string" }, "urn": { "description": "LinkedIn person or organization URN", "type": "string" }, "username": { "description": "LinkedIn vanity name", "type": "string" } }, "type": "object" }, "reactedAt": { "format": "date-time", "type": "string" }, "reactionLabel": { "description": "User-friendly label (Like, Celebrate, Love, Insightful, Support, Funny)", "type": "string" }, "reactionType": { "description": "LinkedIn reaction enum (LIKE, PRAISE, EMPATHY, INTEREST, APPRECIATION, ENTERTAINMENT)", "type": "string" } }, "type": "object" }, "type": "array" }, "username": { "type": "string" } }, "type": "object" } } }, "description": "Reactions with reactor profiles" }, "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." } }, "summary": "Get LinkedIn post reactions", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.get_linked_in_post_reactions@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "8b8f2543ba7b952f87de1a169556fccc41e3f458762f463e5b173d7a2901c33e" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_b907d7", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/linkedin-post-reactions" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_b907d7" } }, "/apis/v1/social/accounts/{accountId}/pinterest-boards": { "get": { "description": "Account settings. 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.\n\nReturns the boards available for a connected Pinterest account. Use this to get a board ID when creating a Pinterest post.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_8d2b9a", "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": { "boards": { "items": { "properties": { "description": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "privacy": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Boards list" }, "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." } }, "summary": "List Pinterest boards", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.account_settings.get_pinterest_boards@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "5daa8c89d7e153e6fadc282cc6d4e81a53b0ba6e8ac38ddfb27a1a921c03a4f6" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_8d2b9a", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/pinterest-boards" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_8d2b9a" }, "post": { "description": "Account settings. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nCreates a new board on the connected Pinterest account. The returned board ID can be used immediately as `platformSpecificData.boardId` when creating a Pinterest post.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_accounts_accounti_8d2b9a", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "description": "My favorite summer recipes", "name": "Summer Recipes", "privacy": "PUBLIC" }, "schema": { "properties": { "description": { "description": "Board description", "type": "string" }, "name": { "description": "Name of the board", "type": "string" }, "privacy": { "default": "PUBLIC", "description": "Board privacy setting", "enum": [ "PUBLIC", "PROTECTED", "SECRET" ], "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "board": { "properties": { "description": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "privacy": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Board created" }, "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." } }, "summary": "Create Pinterest board", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.account_settings.create_pinterest_board@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "22ee6207398a1d11fb663b282e632eb8ca1027955c7d10a566cb8fec30acdb15" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_accounts_accounti_8d2b9a", "method": "POST", "path": "/apis/v1/social/accounts/{accountId}/pinterest-boards" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_accounts_accounti_8d2b9a" }, "put": { "description": "Account settings. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nSets the default board used when publishing pins for this account.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "put_aisa_social_apis_v1_social_accounts_accountid_8d2b9a", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "defaultBoardId": "123456789012345678", "defaultBoardName": "Marketing Ideas" }, "schema": { "properties": { "defaultBoardId": { "type": "string" }, "defaultBoardName": { "type": "string" } }, "required": [ "defaultBoardId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "account": { "properties": { "_id": { "type": "string" }, "displayName": { "type": "string" }, "enabled": { "description": "Whether the user explicitly activated this account. false means the account was created as a side effect (e.g., a posting account auto-created when the user connected ads first).\n\n- GET /apis/v1/social/accounts still returns such accounts unless `excludeHidden=true` is passed.\n- They cannot be posted to (`ACCOUNT_NOT_ENABLED_FOR_POSTING`) and are not billed as connected accounts.\n- On an ads account (`metaads`, `googleads`, ...) the value does not hide the connection: ads accounts are listed whatever their `enabled` value and keep working for ads.", "type": "boolean" }, "followersCount": { "description": "Follower count (only included if user has analytics add-on)", "type": "number" }, "followersLastUpdated": { "description": "Last time follower count was updated (only included if user has analytics add-on)", "format": "date-time", "type": "string" }, "isActive": { "type": "boolean" }, "metadata": { "description": "Platform-specific metadata. Fields vary by platform.\n\n**WhatsApp accounts:**\n\n- qualityRating: phone number quality rating from Meta (GREEN, YELLOW, RED, or UNKNOWN).\n- nameStatus: display name review status (APPROVED, PENDING_REVIEW, DECLINED, or NONE). A declined or pending name does not by itself block sending; sendability is reported separately via health_status (can_send_message).\n- messagingLimitTier: maximum unique business-initiated conversations per 24h rolling window (TIER_250, TIER_1K, TIER_10K, TIER_100K, or TIER_UNLIMITED). Scales automatically as quality rating improves.\n- verifiedName: Meta-verified business display name.\n- displayPhoneNumber: formatted phone number (e.g., \"+1 555-123-4567\").\n- wabaId: WhatsApp Business Account ID.\n- phoneNumberId: Meta phone number ID.\n\n**Meta ads business-login accounts:**\n\n- tokenType: system-user.\n- businessId: the owning Business Manager ID when there is one owner; null for multiple owners.\n- businessIds: owning Business Manager IDs discovered from granted ad accounts.\n- grantedAdAccountIds: ad-account IDs granted to the token.\n- adAccountBusinesses: map from ad-account ID to its owning business ID or null.\n- availablePages: granted Page IDs and names. No Page tokens are exposed.\n- selectedPageId: the Page selected for creatives and lead forms, or null.\n- scopedAdAccountIds: existing sync scope preserved on reconnect.\n\nNon-expiring tokens have no tokenExpiresAt field. Parent posting reconnects do not replace this token.\n\n**LinkedIn accounts:** profileData carries profile details refreshed on each daily snapshot.\n\n- profileData.bio: the member's headline (personal accounts) or the organization description (organization accounts). null when not set.\n- profileData.extraData.vanityName: the member's profile slug, the /in/{vanityName} segment of profileUrl. Personal accounts only; an organization's slug is in metadata.organizationInfo.vanityName.\n\n**Instagram accounts:**\n\n- loginMethod: \"facebook_login\" when connected through Facebook Login; absent for Instagram Login. On facebook_login accounts, comment reads leave hidden comments out entirely instead of returning them with isHidden true.\n- instagramScopedId: the Instagram professional account id (`17841...`). On Instagram Login accounts it is the same whichever app connected the account, while platformUserId is app-scoped. Facebook Login accounts hold this id as platformUserId.\n\n**X (Twitter) accounts:**\n\n- profileData.extraData.isPremium: whether X reports a paid subscription (Basic, Premium, Premium+, or a blue verified badge), which raises the post length limit from 280 to 25,000 characters. Read live at connect and reconnect, refreshed by the daily follower snapshot.\n- Because X intermittently reports no subscription for subscribed accounts, a cancellation is stored on the fourth consecutive daily snapshot reporting it (about four days). Accounts connected before the extraData layout carry the flag at profileData.isPremium.", "type": "object" }, "needsReconnection": { "description": "The platform definitively reported the stored OAuth token as dead.\nWhile true, GET /apis/v1/social/connect/{platform}/ads returns a\nfresh authUrl (implicit force=true) instead of alreadyConnected,\nso re-running the connect flow recovers the account. Cleared\nautomatically when the account is re-authorized.", "type": "boolean" }, "parentAccountId": { "description": "Reference to the parent posting social account. Set for ads accounts that share\nor derive from a posting account's OAuth token. null for standalone ads (Google Ads)\nand all posting accounts. Meta ads business-login accounts also have no parent.", "type": [ "string", "null" ] }, "platform": { "enum": [ "tiktok", "instagram", "facebook", "youtube", "linkedin", "twitter", "threads", "pinterest", "reddit", "bluesky", "googlebusiness", "telegram", "snapchat", "discord", "slack", "whatsapp", "shopify", "wordpress", "wix", "linkedinads", "metaads", "pinterestads", "tiktokads", "xads", "googleads", "openaiads", "redditads", "sms", "phone", "rcs", "whopads", "google", "microsoft", "hubspot", "webflow", "googleanalytics", "imessage", "tiktokshop", "microsoftads" ], "type": "string" }, "platformUserId": { "description": "The account's id on its platform, as the platform reports it to AIsa. Stable across reconnects, so use it to match an account against your own records.\n\n- **Instagram Login accounts:** the app-scoped user id (the professional account id is in `metadata.instagramScopedId`).\n- **Instagram via Facebook Login:** the professional account id (`17841...`).\n- **TikTok:** the open_id of AIsa's TikTok app, which differs from the open_id any other app sees for the same user.\n\nEither value can be passed back as `expectedPlatformUserId` on GET /apis/v1/social/connect/{platform}.", "type": "string" }, "profileId": { "description": "One of your profiles (prf_...).", "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" }, "profilePicture": { "description": "URL to the account's profile picture on the platform. May be null if the platform does not provide one.", "type": [ "string", "null" ] }, "profileUrl": { "description": "Full profile URL for the connected account on its platform.", "type": "string" }, "rateLimitedUntil": { "description": "End of the account's publishing cooldown. Compare it with the current time: a value in the past means the cooldown has ended (the field is cleared on the next successful publish); null means no cooldown since the last successful publish.\n\n**When it starts.** A post to the account fails with `errorCategory` `user_abuse` (spam, abuse or rate-limit errors), or 10 or more posts to it fail within an hour with `user_content`, `platform_error`, `platform_rate_limit` or `unknown`.\n\n**How long.** It doubles with each start inside a 24-hour window that opens at the first one (10, 20, 40, 80 minutes and so on, capped at 24 hours).\n\nOn a YouTube account with a recorded successful upload, it instead runs until 24 hours after that upload, or 1 hour when that upload is older than 24 hours.\n\n**Effect.** While it is in the future, POST /apis/v1/social/posts (drafts excepted) and POST /apis/v1/social/posts/{postId}/retry return 429 for this account. When it starts, this account's pending targets on posts scheduled before the cooldown ends are failed.", "format": "date-time", "type": [ "string", "null" ] }, "scopeAreas": { "description": "Accounts connected through your own OAuth app: the permission areas the connect requested. Null on accounts connected through AIsa's app.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "tiktokAccountType": { "description": "TikTok accounts only. The account type TikTok reported when the account was connected.\n\n- `personal`: cannot use TikTok direct messages through the API (TikTok limits Business Messaging to Business Accounts). Skip the inbox for them and tell the user to switch to a Business Account in the TikTok app, then reconnect.\n- `business`: the prerequisite, not a guarantee. Messaging also needs the messaging scopes granted and TikTok's regional availability.\n- `unknown`: accounts connected before this was captured, or whose grant left out the account-type scope.", "enum": [ "business", "personal", "unknown" ], "type": "string" }, "username": { "type": "string" } }, "required": [ "_id", "isActive", "platform", "profileId" ], "type": "object" }, "message": { "type": "string" } }, "type": "object" } } }, "description": "Default board set" }, "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." } }, "summary": "Set default Pinterest board", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.account_settings.update_pinterest_boards@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "63b3c98135c108271b2355f740076533a675189aa71a585be9747992016331dc" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "put_aisa_social_apis_v1_social_accounts_accountid_8d2b9a", "method": "PUT", "path": "/apis/v1/social/accounts/{accountId}/pinterest-boards" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/put_aisa_social_apis_v1_social_accounts_accountid_8d2b9a" } }, "/apis/v1/social/accounts/{accountId}/posts": { "get": { "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.\n\nReturns the 25 most recent posts that exist on the platform for a connected account, read live from the platform API. This covers everything on the account, including posts that were never created through AIsa.\n\nUse it to obtain the platform's own post id, which the analytics endpoints take as input. On YouTube the returned `id` is the video ID that `GET /apis/v1/social/analytics/youtube/daily-views`, `/video-retention` and `/demographics` expect as `videoId`, so this endpoint is what backs a video picker in your own UI.\n\n### Platform-specific fields\n\nNot every field applies to every platform. Absent fields are omitted from the response.\n\n- `reactionCount`: Facebook and LinkedIn.\n- `shareCount`: platform dependent.\n- `cid`: the Bluesky content id needed to reply.\n- `subreddit`: Reddit only.\n- `title`, `description`, `link`, `boardId` and `boardOwnerUsername`: Pinterest only (the native Pin values; `message` keeps title and description joined).\n\n### Expired tokens\n\nThe account's token is refreshed before the call when it has expired. When the refresh cannot recover it, the response is a 401 with code `TOKEN_EXPIRED` and the account has to be reconnected.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_posts", "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": { "lastUpdated": { "format": "date-time", "type": "string" }, "posts": { "items": { "properties": { "boardId": { "description": "Pinterest only: id of the board holding the Pin", "type": "string" }, "boardOwnerUsername": { "description": "Pinterest only: username of the board owner", "type": "string" }, "cid": { "description": "Bluesky content id, required to reply to the post", "type": "string" }, "commentCount": { "type": "integer" }, "createdTime": { "format": "date-time", "type": "string" }, "description": { "description": "Pinterest only: full native Pin description (Pinterest caps it at 800 characters)", "type": "string" }, "id": { "description": "The platform's own post id (the video ID on YouTube)", "type": "string" }, "likeCount": { "type": "integer" }, "link": { "description": "Pinterest only: destination URL of the Pin, not the Pin page (see permalink)", "type": "string" }, "mediaType": { "type": "string" }, "message": { "description": "Caption or title, empty string when the post has no text", "type": "string" }, "permalink": { "description": "Public URL of the post on the platform", "type": "string" }, "picture": { "description": "Thumbnail or media URL", "type": "string" }, "platform": { "type": "string" }, "reactionCount": { "description": "Facebook and LinkedIn only", "type": "integer" }, "shareCount": { "type": "integer" }, "subreddit": { "description": "Reddit only", "type": "string" }, "title": { "description": "Pinterest only: native Pin title", "type": "string" } }, "type": "object" }, "type": "array" }, "status": { "enum": [ "success" ], "type": "string" } }, "type": "object" } } }, "description": "Posts list" }, "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." } }, "summary": "List posts published on the platform", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.accounts.get_account_posts@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "1c72c8d4b2af475ea2695a5ac82f1c324d44d829782ef978f9cb5739a11b691f" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_posts", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/posts" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_posts" } }, "/apis/v1/social/accounts/{accountId}/reddit-flairs": { "get": { "description": "Account settings. 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.\n\nTemporarily unavailable: Reddit has blocked third-party apps from its API, so this endpoint returns 503 `PLATFORM_DISABLED` until Reddit restores access. Reddit Ads is not affected.\n\nReturns available post flairs for a subreddit. Some subreddits require a flair when posting.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_4ea533", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Subreddit name (without \"r/\" prefix) to fetch flairs for", "in": "query", "name": "subreddit", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "flairs": { "items": { "properties": { "backgroundColor": { "description": "Background hex color (e.g. '#ff4500')", "type": "string" }, "id": { "description": "Flair ID to pass as flairId in platformSpecificData", "type": "string" }, "text": { "description": "Flair display text", "type": "string" }, "textColor": { "description": "Text color: 'dark' or 'light'", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Flairs list" }, "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." } }, "summary": "List subreddit flairs", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.account_settings.get_reddit_flairs@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "5249f898df0c57a023d6977ad3606eb0410af25ce4f3d91597d6dbe88f81f018" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_4ea533", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/reddit-flairs" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_4ea533" }, "post": { "description": "Account settings. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nTemporarily unavailable: Reddit has blocked third-party apps from its API, so this endpoint returns 503 `PLATFORM_DISABLED` until Reddit restores access. Reddit Ads is not affected.\n\nApplies a flair to a post the connected account already published. Use the GET on this\npath to list the available `flairTemplateId` values for the subreddit.\n\nFlair can also be set at submit time by passing `flairId` in `platformSpecificData`\nwhen creating the post. This endpoint is for changing it afterwards.\n\nThe subreddit must allow users to select their own post flair. Setting flair on\nanother user's post requires moderator permissions, which AIsa does not request.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_accounts_accounti_4ea533", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "flairTemplateId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "postId": "t3_abc123", "subreddit": "webdev" }, "schema": { "properties": { "flairTemplateId": { "description": "Flair template id from the GET on this path", "minLength": 1, "type": "string" }, "postId": { "description": "Reddit post id, with or without the t3_ prefix", "minLength": 1, "type": "string" }, "subreddit": { "description": "Subreddit name (without the \"r/\" prefix)", "minLength": 1, "type": "string" }, "text": { "description": "Optional override text, only for editable flair templates", "type": "string" } }, "required": [ "flairTemplateId", "postId", "subreddit" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Flair applied" }, "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." } }, "summary": "Set Reddit post flair", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.account_settings.set_reddit_post_flair@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "72c9a93669cb7a9050fc5c0eb425b89cf14793c59b46532dc46e6b1e1cc1003a" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_accounts_accounti_4ea533", "method": "POST", "path": "/apis/v1/social/accounts/{accountId}/reddit-flairs" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_accounts_accounti_4ea533" } }, "/apis/v1/social/accounts/{accountId}/reddit-subreddits": { "get": { "description": "Account settings. 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.\n\nTemporarily unavailable: Reddit has blocked third-party apps from its API, so this endpoint returns 503 `PLATFORM_DISABLED` until Reddit restores access. Reddit Ads is not affected.\n\nReturns the subreddits the connected Reddit account can post to. Use this to get a subreddit name when creating a Reddit post.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_fd4a31", "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": { "defaultSubreddit": { "description": "Currently set default subreddit for posting", "type": "string" }, "subreddits": { "items": { "properties": { "id": { "description": "Reddit subreddit ID", "type": "string" }, "name": { "description": "Subreddit name without r/ prefix", "type": "string" }, "over18": { "description": "Whether the subreddit is NSFW", "type": "boolean" }, "title": { "description": "Subreddit title", "type": "string" }, "url": { "description": "Subreddit URL path", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Subreddits list" }, "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." } }, "summary": "List Reddit subreddits", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.account_settings.get_reddit_subreddits@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "109e895f37f2ebbd26676c391720d2ff08be97bebedd6bed1a53ba846ed50633" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_fd4a31", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/reddit-subreddits" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_fd4a31" }, "put": { "description": "Account settings. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nTemporarily unavailable: Reddit has blocked third-party apps from its API, so this endpoint returns 503 `PLATFORM_DISABLED` until Reddit restores access. Reddit Ads is not affected.\n\nSets the default subreddit used when publishing posts for this Reddit account.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "put_aisa_social_apis_v1_social_accounts_accountid_fd4a31", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "defaultSubreddit": "marketing" }, "schema": { "properties": { "defaultSubreddit": { "minLength": 1, "type": "string" } }, "required": [ "defaultSubreddit" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Default subreddit set" }, "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." } }, "summary": "Set default subreddit", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.account_settings.update_reddit_subreddits@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "e8df91c2aec48d70301016834104125c8678095343aadcaf831ba2fe5a4fdce0" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "put_aisa_social_apis_v1_social_accounts_accountid_fd4a31", "method": "PUT", "path": "/apis/v1/social/accounts/{accountId}/reddit-subreddits" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/put_aisa_social_apis_v1_social_accounts_accountid_fd4a31" } }, "/apis/v1/social/accounts/{accountId}/reddit-subreddits/{subreddit}/rules": { "get": { "description": "Account settings. 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.\n\nTemporarily unavailable: Reddit has blocked third-party apps from its API, so this endpoint returns 503 `PLATFORM_DISABLED` until Reddit restores access. Reddit Ads is not affected.\n\nReturns a subreddit's posting rules plus Reddit's site-wide rules, so you can check\nthem before submitting and avoid a removal.\n\nUse this alongside `GET /apis/v1/social/tools/validate/subreddit`, which only confirms that a\nsubreddit exists and reports its basic posting settings.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_b399e6", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Subreddit name (without the \"r/\" prefix)", "in": "path", "name": "subreddit", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "rules": { "items": { "properties": { "createdUtc": { "description": "Unix timestamp when the rule was created", "type": "number" }, "description": { "description": "Full rule text", "type": "string" }, "kind": { "description": "Scope of the rule: 'link', 'comment', or 'all'", "type": "string" }, "priority": { "description": "Display order of the rule", "type": "integer" }, "shortName": { "description": "Short rule title shown in the subreddit sidebar", "type": "string" }, "violationReason": { "description": "Reason shown to a user when the rule is enforced", "type": "string" } }, "type": "object" }, "type": "array" }, "siteRules": { "description": "Reddit's site-wide content policy rules", "items": { "type": "string" }, "type": "array" } }, "type": "object" } } }, "description": "Subreddit and site rules" }, "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." } }, "summary": "Get subreddit rules", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.account_settings.get_subreddit_rules@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "79921b987d8d5bb2fb81bd3077ce2edbd5d749beedbfd2a63dcf6f09f4f3c780" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_b399e6", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/reddit-subreddits/{subreddit}/rules" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_b399e6" } }, "/apis/v1/social/accounts/{accountId}/reddit-vote": { "post": { "description": "Account settings. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nTemporarily unavailable: Reddit has blocked third-party apps from its API, so this endpoint returns 503 `PLATFORM_DISABLED` until Reddit restores access. Reddit Ads is not affected.\n\nCast, change, or clear the connected account's vote on a Reddit post or comment.\n\n### Reddit requires that votes be cast by humans\n\nReddit's API terms permit a client to proxy a human's action one-for-one, and prohibit a bot from deciding how to vote or from amplifying a human's vote.\n\nCall this endpoint only in direct response to an explicit action by the account owner. Automated or agent-decided voting is vote manipulation and puts API access at risk.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_accounts_accounti_87c5f5", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "direction": 1, "thingId": "t3_abc123" }, "schema": { "properties": { "direction": { "description": "1 to upvote, -1 to downvote, 0 to clear an existing vote", "enum": [ 1, 0, -1 ], "type": "integer" }, "thingId": { "description": "Reddit fullname of the target. Prefix \"t3_\" for a post and \"t1_\" for a comment. A bare id with no prefix is treated as a post (\"t3_\").", "type": "string" } }, "required": [ "direction", "thingId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Vote registered" }, "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." } }, "summary": "Vote on a Reddit post or comment", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.account_settings.vote_reddit_thing@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "b3eea59efc2785729e7a1bade0854ca0939f768f9cefdb4dc96d5d77d31a6bca" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_accounts_accounti_87c5f5", "method": "POST", "path": "/apis/v1/social/accounts/{accountId}/reddit-vote" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_accounts_accounti_87c5f5" } }, "/apis/v1/social/accounts/{accountId}/slack-members": { "get": { "description": "Slack. 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.\n\nMembers of the connected Slack workspace that can receive a direct message, for populating a recipient picker. Bots, deactivated members and Slackbot are excluded. Start a DM by passing a member id as `participantId` to POST /apis/v1/social/inbox/conversations.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_e4f002", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Case-insensitive filter over display name and handle.", "in": "query", "name": "query", "required": false, "schema": { "maxLength": 100, "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 2000, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "members": { "items": { "properties": { "id": { "description": "Slack member id (pass as participantId to start a DM).", "type": "string" }, "name": { "description": "Display name", "type": "string" }, "picture": { "description": "Avatar URL", "type": [ "string", "null" ] }, "username": { "description": "Slack handle", "type": [ "string", "null" ] } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Workspace members" }, "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." } }, "summary": "List Slack workspace members", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.slack.list_slack_members@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "d403f777bceb6b2d4a508b0a6281c65395f128a225118c369f587793ebff3019" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_e4f002", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/slack-members" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_e4f002" } }, "/apis/v1/social/accounts/{accountId}/slack-settings": { "get": { "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.\n\nReturns the connected Slack channel details and the default message identity (name and avatar shown as the author on every post, with Slack's APP badge). The identity applies to messages only; the app's own Slack profile is global and cannot be changed per workspace.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_33e3eb", "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": { "account": { "properties": { "_id": { "type": "string" }, "channelId": { "type": [ "string", "null" ] }, "channelName": { "type": [ "string", "null" ] }, "channelType": { "description": "public or private", "type": [ "string", "null" ] }, "defaultIconUrl": { "type": [ "string", "null" ] }, "defaultUsername": { "type": [ "string", "null" ] }, "displayName": { "type": [ "string", "null" ] }, "platform": { "type": "string" }, "teamName": { "type": [ "string", "null" ] } }, "type": "object" } }, "type": "object" } } }, "description": "Slack account settings" }, "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." } }, "summary": "Get Slack account settings", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.accounts.get_slack_settings@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "3ba7aa66b6af9da0b03446f364095f94248eb8fe4b3af5351402940d0faf8f9e" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_33e3eb", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/slack-settings" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_33e3eb" }, "patch": { "description": "Accounts. 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.\n\nSet or clear the default message identity for this channel. Empty string clears a field; per-post platformSpecificData.username/iconUrl still override these defaults.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "patch_aisa_social_apis_v1_social_accounts_account_33e3eb", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "properties": { "applyToWorkspace": { "default": false, "description": "Applies the name and icon to every connected channel of this Slack workspace owned by the same owner, on the same Slack app, in profiles the caller can access. Channels connected later inherit the identity from a channel of that workspace.", "type": "boolean" }, "defaultIconUrl": { "description": "Author avatar image URL. Empty string clears it.", "type": "string" }, "defaultUsername": { "description": "Author name shown on posts. Empty string clears it.", "maxLength": 80, "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "An empty object or a success flag.", "properties": { "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Updated settings" }, "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." } }, "summary": "Update Slack account settings", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.accounts.update_slack_settings@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "eaebba39aaee459ebcc60b55e62e13bc408291c602409913bc26d1e8ee98615c" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "patch_aisa_social_apis_v1_social_accounts_account_33e3eb", "method": "PATCH", "path": "/apis/v1/social/accounts/{accountId}/slack-settings" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/patch_aisa_social_apis_v1_social_accounts_account_33e3eb" } }, "/apis/v1/social/accounts/{accountId}/tiktok/commercial-music": { "get": { "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.\n\nReturns the 100 currently trending tracks of TikTok's Commercial Music Library for a TikTok account connected through the TikTok for Business app.\n\nThe list is not paged; countryCode selects the country chart.\n\n### Using a track in a post\n\nSend a track's clip.id as tiktokSettings.musicSoundInfo.musicSoundId when creating a post. Fall back to id only when the track has no clip.\n\nBoth publish, but with the full-track id TikTok has shown viewers \"This song is not available in your country\" on the sound page (observed from Germany, 2026-10-06). The clip id gave a working sound page for the same track.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_9867af", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Two-letter ISO 3166-1 country code of the chart to read (for example ES). Defaults to TikTok's global chart.", "in": "query", "name": "countryCode", "required": false, "schema": { "maxLength": 2, "minLength": 2, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "tracks": { "items": { "properties": { "artist": { "type": "string" }, "clip": { "description": "The trending excerpt of the track, when TikTok provides one. Send clip.id as musicSoundId: it publishes and its sound page opens for viewers, unlike the full-track id (observed from Germany, 2026-10-06).", "properties": { "durationSec": { "type": "integer" }, "id": { "type": "string" }, "previewUrl": { "type": "string" } }, "type": "object" }, "commercialMusicId": { "description": "TikTok's commercial_music_id, for reference only", "type": "string" }, "durationSec": { "type": "integer" }, "genres": { "items": { "type": "string" }, "type": "array" }, "id": { "description": "The full track's song clip id. Accepted as musicSoundId, but prefer clip.id: posts published with this id have shown viewers a sound page saying the song is not available in their country (observed from Germany). TikTok rejects the commercial music id itself at publish time.", "type": "string" }, "name": { "type": "string" }, "previewUrl": { "description": "Preview audio of the full track", "type": "string" }, "rank": { "description": "Position in the trending chart, 1 first", "type": "integer" }, "thumbnailUrl": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "The trending tracks, rank 1 first" }, "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." } }, "summary": "List trending commercial music", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.accounts.list_tik_tok_commercial_music@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "4ae86089ba785ed3513fec16c1c98eb482d192ad518e3402800cc742854d9490" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_9867af", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/tiktok/commercial-music" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_9867af" } }, "/apis/v1/social/accounts/{accountId}/tiktok/creator-info": { "get": { "description": "Required before posting to TikTok: privacyLevel must be one of privacyLevelOptions.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_a5c302", "parameters": [ { "description": "Options differ for video and photo posts.", "in": "query", "name": "mediaType", "required": true, "schema": { "enum": [ "video", "photo" ], "type": "string" } }, { "in": "path", "name": "accountId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "accountId": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "canPostMore": { "type": [ "boolean", "null" ] }, "commentDisabled": { "type": [ "boolean", "null" ] }, "commercialContentTypes": { "items": { "properties": { "label": { "type": [ "string", "null" ] }, "requires": { "items": { "type": [ "string", "null" ] }, "type": [ "array", "null" ] }, "value": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "duetDisabled": { "type": [ "boolean", "null" ] }, "fetchedAt": { "format": "date-time", "type": [ "string", "null" ] }, "maxVideoDurationSeconds": { "type": [ "integer", "null" ] }, "mediaType": { "type": [ "string", "null" ] }, "privacyLevelOptions": { "items": { "type": [ "string", "null" ] }, "type": [ "array", "null" ] }, "stitchDisabled": { "type": [ "boolean", "null" ] } }, "type": "object" } } }, "description": "Success" }, "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." } }, "summary": "Get TikTok creator info", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.accounts.tiktok_creator_info@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "This operation does not settle a customer usage charge.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "beaffa10694389661c416fa6420063f12595d2455c0bf03011ec6a9168ed3678" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_a5c302", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/tiktok/creator-info" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_a5c302" } }, "/apis/v1/social/accounts/{accountId}/tiktok/locations": { "get": { "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.\n\nSearches the location tags a TikTok account connected through the TikTok for Business app can attach to a video post.\n\nSend a result's id and name as tiktokSettings.locationId and locationName when creating a post.\n\nTikTok answers the 20 closest matches and fills the list with fuzzy matches when nothing matches, so an unrelated result does not mean the place is missing.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_86a4b4", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Place name to search, for example a city, a venue or an address", "in": "query", "name": "query", "required": true, "schema": { "maxLength": 100, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "locations": { "items": { "properties": { "address": { "description": "Address or region TikTok shows for the place, for disambiguation", "type": "string" }, "id": { "description": "The value to send as locationId", "type": "string" }, "name": { "description": "The value to send as locationName", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "The closest location tags, best match first" }, "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." } }, "summary": "Search TikTok location tags", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.accounts.search_tik_tok_locations@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "2d22722848eb479c8ae144d282b23b0173e406bd8cbef92abe98c902b5ce9ed1" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_86a4b4", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/tiktok/locations" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_86a4b4" } }, "/apis/v1/social/accounts/{accountId}/webhook-subscription": { "get": { "description": "Account settings. 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.\n\nReturns the webhook fields AIsa's app is subscribed to on the connected Page, read live from Meta.\nUse it to confirm `leadgen` is present: a Page missing it keeps delivering every other event while\nlead ads stop arriving, with nothing to indicate it.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_0edb79", "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": { "appSubscribed": { "description": "False when the Page carries no subscription for our app at all.", "type": "boolean" }, "leadgen": { "description": "Whether lead ads submitted on this Page reach AIsa in real time.", "type": "boolean" }, "pageId": { "type": "string" }, "subscribedFields": { "items": { "type": "string" }, "type": "array" }, "warning": { "description": "Present only when leadgen is missing.", "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "The Page's current subscription" }, "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." } }, "summary": "Read a Facebook Page's webhook subscription", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.account_settings.get_page_webhook_subscription@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "7a59fcf5ecef3714aa78ac166b9f1411315e90bb92f4b876a0181509469ec86a" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_0edb79", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/webhook-subscription" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_0edb79" }, "post": { "description": "Account settings. 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.\n\nRe-sends the full field set to Meta and returns the subscription read back afterwards.\nMeta only honours the field set sent at subscribe time, so a Page connected before a field\nexisted stays without it until this runs. The response reflects what Meta actually granted,\nnot what was requested.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_accounts_accounti_0edb79", "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": { "appSubscribed": { "type": "boolean" }, "leadgen": { "type": "boolean" }, "pageId": { "type": "string" }, "resubscribed": { "type": "boolean" }, "subscribedFields": { "items": { "type": "string" }, "type": "array" }, "warning": { "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "The subscription after re-subscribing" }, "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." } }, "summary": "Re-subscribe a Facebook Page to AIsa's webhooks", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.account_settings.resync_page_webhook_subscription@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "60642c6a7f0fea5dc174cbbb7fb48af98b14091dd267eaf4a73f5f4b30d48fec" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_accounts_accounti_0edb79", "method": "POST", "path": "/apis/v1/social/accounts/{accountId}/webhook-subscription" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_accounts_accounti_0edb79" } }, "/apis/v1/social/accounts/{accountId}/youtube-captions": { "get": { "description": "Account settings. 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.\n\nReturns the caption track YouTube already holds for one of the connected channel's own videos, as plain text plus timed cues. Use it instead of downloading and transcribing the video yourself.\n\nAuto-generated (ASR) tracks are included: YouTube serves them to the channel owner, which is what the connected account is. Uploaded tracks win over auto-generated ones when both exist for a language.\n\n### Caching\n\nWe store the transcript on first read and serve it from there afterwards, so you do not need to cache it yourself. A cached read costs no YouTube quota and does not call YouTube at all.\n\n- `source` tells you which happened: `youtube` on the first read, `cache` after.\n- Pass `refresh=true` only when the captions actually changed on YouTube, since that re-downloads.\n\n### Notes\n\n- Only videos owned by this connected channel. Anything else returns 404.\n- `contentDetails.caption` in YouTube's own API reads `false` on videos that DO have a serving auto-generated track, so it is not a usable availability signal. Call this endpoint and handle the 404.\n- YouTube generates auto-captions only for videos with recognisable speech, and can take a few hours after upload to publish them.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_74e10b", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "The YouTube video id (the `platformPostId` on a synced external post).", "in": "query", "name": "videoId", "required": true, "schema": { "type": "string" } }, { "description": "BCP-47 language tag as YouTube labels the track. `en` also matches an `en-GB` track. Omit to take the best available track.", "in": "query", "name": "language", "required": false, "schema": { "type": "string" } }, { "description": "`json` returns timed `cues`; `srt` returns the raw SubRip body instead. `text` is present either way.", "in": "query", "name": "format", "required": false, "schema": { "default": "json", "enum": [ "json", "srt" ], "type": "string" } }, { "description": "Re-download from YouTube instead of serving the stored copy. Spends 200 quota units.", "in": "query", "name": "refresh", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "availableTracks": { "description": "Every track on the video, so you can re-request another language. On a cached read this is the listing as it stood when we downloaded, so a language added to the video since then appears only after a `refresh=true` or when you request that language directly.", "items": { "properties": { "language": { "type": "string" }, "name": { "description": "The track's display name. Empty for auto-generated tracks.", "type": "string" }, "trackId": { "type": "string" }, "trackKind": { "enum": [ "asr", "standard" ], "type": "string" } }, "type": "object" }, "type": "array" }, "cues": { "description": "Timed cues. Present when format is json. Auto-generated cues overlap in time by design (captions roll), so `start` can precede the previous cue's `end`.", "items": { "properties": { "end": { "type": "number" }, "start": { "description": "Seconds from the start of the video.", "type": "number" }, "text": { "type": "string" } }, "type": "object" }, "type": "array" }, "fetchedAt": { "description": "When the stored copy was downloaded from YouTube.", "format": "date-time", "type": "string" }, "language": { "description": "The language of the returned track.", "type": "string" }, "source": { "description": "`cache` when served from our stored copy, `youtube` when this call spent the quota units.", "enum": [ "cache", "youtube" ], "type": "string" }, "srt": { "description": "Raw SubRip body. Present when format is srt.", "type": "string" }, "text": { "description": "The whole transcript as one paragraph, no timings.", "type": "string" }, "trackId": { "description": "YouTube's own caption track id.", "type": "string" }, "trackKind": { "description": "`asr` is YouTube's auto-generated track; `standard` was uploaded by the channel.", "enum": [ "asr", "standard" ], "type": "string" }, "videoId": { "type": "string" } }, "type": "object" } } }, "description": "The transcript." }, "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." } }, "summary": "Get a YouTube video transcript", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.account_settings.get_youtube_captions@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "04cd17aa122807c5919b51b827562a79f537f4e8b78ff59b9a1d1875e1fe85b6" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_74e10b", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/youtube-captions" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_74e10b" } }, "/apis/v1/social/accounts/{accountId}/youtube-playlists": { "get": { "description": "Account settings. 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.\n\nReturns the playlists available for a connected YouTube account. Use this to get a playlist ID when creating a YouTube post with the playlistId field.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_accounts_accountid_0a9694", "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": { "defaultPlaylistId": { "type": [ "string", "null" ] }, "playlists": { "items": { "properties": { "description": { "type": "string" }, "id": { "type": "string" }, "itemCount": { "type": "integer" }, "privacy": { "enum": [ "public", "private", "unlisted" ], "type": "string" }, "thumbnailUrl": { "type": "string" }, "title": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Playlists list" }, "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." } }, "summary": "List YouTube playlists", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.account_settings.get_youtube_playlists@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "24bcf3eaa647de53dcf58e66f423ea6aafe3afeda72b00b6472c08ae9a21625e" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_accounts_accountid_0a9694", "method": "GET", "path": "/apis/v1/social/accounts/{accountId}/youtube-playlists" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_accounts_accountid_0a9694" }, "post": { "description": "Account settings. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nCreates an empty playlist on the connected YouTube channel. Requires a title; privacy defaults to private.\n\nReturns the same playlist shape as the list endpoint. Pass the returned playlist.id as platformSpecificData.playlistId when publishing a video. Does not change the account's default playlist.\n\n### Requirements and cost\n\n- Requires the youtube or youtube.force-ssl OAuth scope.\n- Costs 50 YouTube quota units.\n\n### Retries\n\nThis operation is not idempotent and is not automatically retried. Repeating a request can create another playlist, including after a timeout. List playlists before retrying an ambiguous failure.\n\n### Official series\n\nOfficial series settings are not exposed by YouTube's public API and must be enabled manually in YouTube's desktop playlist settings.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_accounts_accounti_0a9694", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "description": "Step-by-step video tutorials", "privacy": "private", "title": "Tutorials" }, "schema": { "properties": { "description": { "description": "Optional playlist description.", "type": "string" }, "privacy": { "default": "private", "enum": [ "private", "public", "unlisted" ], "type": "string" }, "title": { "description": "Playlist title. Leading and trailing whitespace is removed.", "minLength": 1, "type": "string" } }, "required": [ "title" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "playlist": { "properties": { "description": { "type": "string" }, "id": { "type": "string" }, "itemCount": { "type": "integer" }, "privacy": { "enum": [ "private", "public", "unlisted" ], "type": "string" }, "thumbnailUrl": { "type": "string" }, "title": { "type": "string" } }, "required": [ "description", "id", "itemCount", "privacy", "thumbnailUrl", "title" ], "type": "object" } }, "required": [ "playlist" ], "type": "object" } } }, "description": "Playlist created" }, "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." } }, "summary": "Create YouTube playlist", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.account_settings.create_youtube_playlist@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "66900e148ac335e2eb03877c21292a0555785d79ec99cfb579ea1186a1aab3cd" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_accounts_accounti_0a9694", "method": "POST", "path": "/apis/v1/social/accounts/{accountId}/youtube-playlists" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_accounts_accounti_0a9694" }, "put": { "description": "Account settings. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nSets the default playlist used when publishing videos for this account. When a post does not specify a playlistId, the default playlist is not automatically used (it is stored for client-side convenience).\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "put_aisa_social_apis_v1_social_accounts_accountid_0a9694", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "path", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "defaultPlaylistId": "PLxxxxxxxxxxxxx", "defaultPlaylistName": "Tutorials" }, "schema": { "properties": { "defaultPlaylistId": { "minLength": 1, "type": "string" }, "defaultPlaylistName": { "type": "string" } }, "required": [ "defaultPlaylistId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Default playlist set" }, "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." } }, "summary": "Set default YouTube playlist", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.account_settings.update_youtube_default_playlist@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "82b90144c1531a66ce59ab8237d1401357a65c1c6eb8e666cf5c940998961ee0" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "put_aisa_social_apis_v1_social_accounts_accountid_0a9694", "method": "PUT", "path": "/apis/v1/social/accounts/{accountId}/youtube-playlists" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/put_aisa_social_apis_v1_social_accounts_accountid_0a9694" } }, "/apis/v1/social/analytics": { "get": { "description": "Returns 202 while every platform is still syncing. Some TikTok metrics arrive 24 to 48 hours after publishing.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics", "parameters": [ { "description": "A pst_ id.", "in": "query", "name": "postId", "required": true, "schema": { "pattern": "^pst_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "platforms": { "items": { "properties": { "accountId": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "metrics": { "additionalProperties": { "type": [ "integer", "null" ] }, "type": [ "object", "null" ] }, "platform": { "enum": [ "tiktok", "instagram", "twitter", "youtube", "facebook", "linkedin", "pinterest", "threads", "reddit", "googlebusiness", "googleanalytics", "bluesky", "telegram", "slack", "snapchat", "hubspot", "microsoft", null ], "type": [ "string", "null" ] }, "provenance": { "properties": { "fetchedAt": { "format": "date-time", "type": [ "string", "null" ] }, "origin": { "enum": [ "connected", "public", "customer", null ], "type": [ "string", "null" ] }, "precision": { "enum": [ "exact", "rounded", null ], "type": [ "string", "null" ] }, "valueType": { "enum": [ "reported", "observed", "estimated", null ], "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "syncStatus": { "enum": [ "synced", "pending", "unavailable", null ], "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "postId": { "pattern": "^pst_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "totals": { "additionalProperties": { "type": [ "integer", "null" ] }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "Success" }, "202": { "content": { "application/json": { "schema": { "properties": { "platforms": { "items": { "properties": { "accountId": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "metrics": { "additionalProperties": { "type": [ "integer", "null" ] }, "type": [ "object", "null" ] }, "platform": { "enum": [ "tiktok", "instagram", "twitter", "youtube", "facebook", "linkedin", "pinterest", "threads", "reddit", "googlebusiness", "googleanalytics", "bluesky", "telegram", "slack", "snapchat", "hubspot", "microsoft", null ], "type": [ "string", "null" ] }, "provenance": { "properties": { "fetchedAt": { "format": "date-time", "type": [ "string", "null" ] }, "origin": { "enum": [ "connected", "public", "customer", null ], "type": [ "string", "null" ] }, "precision": { "enum": [ "exact", "rounded", null ], "type": [ "string", "null" ] }, "valueType": { "enum": [ "reported", "observed", "estimated", null ], "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "syncStatus": { "enum": [ "synced", "pending", "unavailable", null ], "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "postId": { "pattern": "^pst_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "totals": { "additionalProperties": { "type": [ "integer", "null" ] }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "Accepted; the outcome is pending and arrives by webhook" }, "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." } }, "summary": "Get post analytics", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.get@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "This operation does not settle a customer usage charge.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "2767df47f48be8650ba7bcaa1be933348a2b32a774a71b2e4a9e201c14161535" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics", "method": "GET", "path": "/apis/v1/social/analytics" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics" } }, "/apis/v1/social/analytics/authenticity": { "get": { "description": "Analytics. 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.\n\nLists the stored authenticity scores for one connected account, newest first. Requires the Analytics add-on.\n\nScores are 0 to 100 and come from AIsa's own model over verified platform samples.\n\n### Filters\n\n- `minScore` and `maxScore`: find posts that look inflated.\n- `from` and `to`: bound when the score was computed.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_authenticity", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Only scores at or above this value.", "in": "query", "name": "minScore", "required": false, "schema": { "maximum": 100, "minimum": 0, "type": "integer" } }, { "description": "Only scores at or below this value.", "in": "query", "name": "maxScore", "required": false, "schema": { "maximum": 100, "minimum": 0, "type": "integer" } }, { "description": "Only scores computed at or after this time (ISO 8601).", "in": "query", "name": "from", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only scores computed at or before this time (ISO 8601).", "in": "query", "name": "to", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Page size.", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "type": "integer" } }, { "description": "Number of scores to skip.", "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "scores": { "items": { "properties": { "computedAt": { "format": "date-time", "type": "string" }, "confidence": { "description": "How much data the score rests on", "maximum": 1, "minimum": 0, "type": "number" }, "postId": { "description": "The external post the score belongs to", "type": "string" }, "reasons": { "description": "Each factor that lowered the score, with its weight in points", "items": { "properties": { "code": { "enum": [ "late_block", "flat_engagement", "view_follower_gap", "cap_seeking", "prior_flags", "no_watch_signal" ], "type": "string" }, "weight": { "description": "Points taken off 100. Zero for no_watch_signal, which only lowers confidence.", "type": "number" } }, "required": [ "code", "weight" ], "type": "object" }, "type": "array" }, "sampleCount": { "description": "Number of samples the score was computed from", "type": "integer" }, "score": { "description": "Higher means the view pattern looks more organic", "maximum": 100, "minimum": 0, "type": "integer" }, "version": { "description": "Scoring model version", "type": "string" } }, "required": [ "computedAt", "confidence", "postId", "reasons", "sampleCount", "score", "version" ], "type": "object" }, "type": "array" } }, "required": [ "scores" ], "type": "object" } } }, "description": "Authenticity scores" }, "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." } }, "summary": "List authenticity scores", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.list_post_authenticity@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "e5d56c88490dd4e05de6e182cff915ce7e2d453411df053f91b6deba137802cc" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_authenticity", "method": "GET", "path": "/apis/v1/social/analytics/authenticity" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_authenticity" } }, "/apis/v1/social/analytics/best-time": { "get": { "description": "Analytics. 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. Without profileId or accountId it reads your default profile.\n\nReturns the best times to post based on historical engagement data.\nGroups all published posts by day of week and hour (UTC), calculating average engagement per slot.\nUse this to auto-schedule posts at optimal times.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_best_time", "parameters": [ { "description": "Filter by platform (e.g. \"instagram\", \"tiktok\"). Omit for all platforms.", "in": "query", "name": "platform", "required": false, "schema": { "type": "string" } }, { "description": "One of your profiles (prf_...). Defaults to your default profile when neither profileId nor accountId is sent.", "in": "query", "name": "profileId", "required": false, "schema": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": false, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Filter by post origin. \"late\" for posts published via AIsa, \"external\" for posts imported from platforms.", "in": "query", "name": "source", "required": false, "schema": { "default": "all", "enum": [ "all", "late", "external" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "slots": { "items": { "properties": { "avg_engagement": { "description": "Average engagement (likes + comments + shares + saves)", "type": "number" }, "day_of_week": { "description": "0=Monday, 6=Sunday", "maximum": 6, "minimum": 0, "type": "integer" }, "hour": { "description": "Hour in UTC (0-23)", "maximum": 23, "minimum": 0, "type": "integer" }, "post_count": { "description": "Number of posts in this slot", "type": "integer" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Best time slots" }, "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." } }, "summary": "Get best times to post", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.get_best_time_to_post@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "20e62e5e8d70777a5e7b0bfa4a423be801481f53ef2ae8f85dfe2c0ff40b1a9c" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_best_time", "method": "GET", "path": "/apis/v1/social/analytics/best-time" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_best_time" } }, "/apis/v1/social/analytics/content-decay": { "get": { "description": "Analytics. 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. Without profileId or accountId it reads your default profile.\n\nReturns how engagement accumulates over time after a post is published.\nEach bucket shows what percentage of the post's total engagement had been reached by that time window.\nUseful for understanding content lifespan (e.g. \"posts reach 78% of total engagement within 24 hours\").\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_content_decay", "parameters": [ { "description": "Filter by platform (e.g. \"instagram\", \"tiktok\"). Omit for all platforms.", "in": "query", "name": "platform", "required": false, "schema": { "type": "string" } }, { "description": "One of your profiles (prf_...). Defaults to your default profile when neither profileId nor accountId is sent.", "in": "query", "name": "profileId", "required": false, "schema": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": false, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Filter by post origin. \"late\" for posts published via AIsa, \"external\" for posts imported from platforms.", "in": "query", "name": "source", "required": false, "schema": { "default": "all", "enum": [ "all", "late", "external" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "buckets": { "items": { "properties": { "avg_pct_of_final": { "description": "Average % of final engagement reached (0-100)", "type": "number" }, "bucket_label": { "description": "Human-readable label", "type": "string" }, "bucket_order": { "description": "Sort order (0 = earliest, 6 = latest)", "type": "integer" }, "post_count": { "description": "Number of posts with data in this bucket", "type": "integer" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Content decay buckets" }, "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." } }, "summary": "Get content performance decay", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.get_content_decay@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "8d9d58bc9ef7978711a3981e313b7901d6407e638ba964ee1b55bc9cb39ea4b8" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_content_decay", "method": "GET", "path": "/apis/v1/social/analytics/content-decay" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_content_decay" } }, "/apis/v1/social/analytics/daily-metrics": { "get": { "description": "Analytics. 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. Without profileId or accountId it reads your default profile.\n\nReturns daily aggregated analytics metrics and a per-platform breakdown.\nEach day includes post count, platform distribution, and summed metrics (impressions, reach, likes, comments, shares, saves, clicks, views).\nDefaults to the last 180 days.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_daily_metrics", "parameters": [ { "description": "Filter by platform (e.g. \"instagram\", \"tiktok\"). Omit for all platforms.", "in": "query", "name": "platform", "required": false, "schema": { "type": "string" } }, { "description": "One of your profiles (prf_...). Defaults to your default profile when neither profileId nor accountId is sent.", "in": "query", "name": "profileId", "required": false, "schema": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": false, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Inclusive start date (ISO 8601). Defaults to 180 days ago.", "in": "query", "name": "fromDate", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Inclusive end date (ISO 8601). Defaults to now.", "in": "query", "name": "toDate", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Filter by post origin. \"late\" for posts published via AIsa, \"external\" for posts imported from platforms.", "in": "query", "name": "source", "required": false, "schema": { "default": "all", "enum": [ "all", "late", "external" ], "type": "string" } }, { "description": "How each post's engagement is attributed to a day.\n\n- \"publish\" (default): sums each post's lifetime total on its publish date.\n- \"received\": buckets the per-day increase in engagement by the day it actually arrived (engagement-over-time), so engagement on older posts appears on the day it was gained rather than the post's publish date.", "in": "query", "name": "attribution", "required": false, "schema": { "default": "publish", "enum": [ "publish", "received" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "dailyData": { "items": { "properties": { "date": { "type": "string" }, "metrics": { "properties": { "clicks": { "type": "integer" }, "comments": { "type": "integer" }, "impressions": { "type": "integer" }, "likes": { "type": "integer" }, "reach": { "type": "integer" }, "saves": { "type": "integer" }, "shares": { "type": "integer" }, "views": { "type": "integer" } }, "type": "object" }, "platforms": { "additionalProperties": { "type": "integer" }, "type": "object" }, "postCount": { "type": "integer" } }, "type": "object" }, "type": "array" }, "platformBreakdown": { "items": { "properties": { "clicks": { "type": "integer" }, "comments": { "type": "integer" }, "impressions": { "type": "integer" }, "likes": { "type": "integer" }, "platform": { "type": "string" }, "postCount": { "type": "integer" }, "reach": { "type": "integer" }, "saves": { "type": "integer" }, "shares": { "type": "integer" }, "views": { "type": "integer" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Daily metrics and platform breakdown" }, "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." } }, "summary": "Get daily aggregated metrics", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.get_daily_metrics@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "82ec4716480f56535eebfbb7a8258d0114e26a8260ed553a25c146fb2b62ec5f" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_daily_metrics", "method": "GET", "path": "/apis/v1/social/analytics/daily-metrics" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_daily_metrics" } }, "/apis/v1/social/analytics/dashboard": { "get": { "description": "Analytics. 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. Without profileId or accountId it reads your default profile.\n\nEverything an analytics dashboard needs in one call: window totals, follower growth, a per-day series, top posts, recent posts and, optionally, the same figures for the previous period.\n\nAll dates are UTC days.\n\n### Daily and total metrics\n\nDaily and total metrics use received attribution: each day holds the engagement that arrived that day, on any post. So `totals` is always the sum of `daily`.\n\n### Post lists\n\n`topPosts` and `recentPosts` list posts published in the window with their lifetime metrics. A post cross-posted to several platforms appears once per platform.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_dashboard", "parameters": [ { "description": "One of your profiles (prf_...). Defaults to your default profile when neither profileId nor accountId is sent.", "in": "query", "name": "profileId", "required": false, "schema": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Platform to cover (e.g. \"instagram\"), or \"all\".", "in": "query", "name": "platform", "required": false, "schema": { "default": "all", "type": "string" } }, { "description": "First day of the window (YYYY-MM-DD, inclusive).", "in": "query", "name": "fromDate", "required": true, "schema": { "format": "date", "type": "string" } }, { "description": "Last day of the window (YYYY-MM-DD, inclusive). May equal fromDate. The window covers at most 366 days.", "in": "query", "name": "toDate", "required": true, "schema": { "format": "date", "type": "string" } }, { "description": "Set to \"previous_period\" to also return previousTotals and previousFollowers for the window of the same length that ends the day before fromDate.", "in": "query", "name": "compare", "required": false, "schema": { "enum": [ "previous_period" ], "type": "string" } }, { "description": "How many top posts to return, ranked by engagement (likes, comments, shares and saves, the same sum as daily engagement).", "in": "query", "name": "topPosts", "required": false, "schema": { "default": 5, "maximum": 25, "minimum": 0, "type": "integer" } }, { "description": "How many of the most recently published posts to return.", "in": "query", "name": "recentPosts", "required": false, "schema": { "default": 10, "maximum": 25, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "daily": { "description": "One entry per day of the window, days without data included as zeros.", "items": { "properties": { "date": { "format": "date", "type": "string" }, "engagement": { "description": "Likes, comments, shares and saves received that day.", "type": "integer" }, "followersGained": { "description": "Net follower change against the previous snapshot. Can be negative.", "type": "integer" }, "impressions": { "type": "integer" }, "reach": { "type": "integer" }, "views": { "type": "integer" } }, "type": "object" }, "type": "array" }, "dataAsOf": { "description": "When the most recently synced account in scope was last synced. Null if none has synced yet.", "format": "date-time", "type": [ "string", "null" ] }, "dateRange": { "properties": { "fromDate": { "format": "date", "type": "string" }, "toDate": { "format": "date", "type": "string" } }, "type": "object" }, "followers": { "properties": { "byAccount": { "items": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "current": { "type": "integer" }, "gained": { "type": "integer" }, "platform": { "type": "string" } }, "type": "object" }, "type": "array" }, "current": { "description": "Live follower count when the window includes today, otherwise the count the window ended on.", "type": "integer" }, "gained": { "description": "Last minus first follower snapshot inside the window. Can be negative.", "type": "integer" } }, "type": "object" }, "previousFollowers": { "properties": { "byAccount": { "items": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "current": { "type": "integer" }, "gained": { "type": "integer" }, "platform": { "type": "string" } }, "type": "object" }, "type": "array" }, "current": { "description": "Live follower count when the window includes today, otherwise the count the window ended on.", "type": "integer" }, "gained": { "description": "Last minus first follower snapshot inside the window. Can be negative.", "type": "integer" } }, "type": "object" }, "previousTotals": { "properties": { "clicks": { "type": "integer" }, "comments": { "type": "integer" }, "engagementRate": { "description": "Percentage. Likes, comments, shares and saves over impressions, pooled per platform (reach, then views, when a platform has no impressions).", "type": "number" }, "impressions": { "type": "integer" }, "likes": { "type": "integer" }, "reach": { "type": "integer" }, "saves": { "type": "integer" }, "shares": { "type": "integer" }, "views": { "type": "integer" } }, "type": "object" }, "recentPosts": { "items": { "properties": { "metrics": { "description": "Lifetime metrics of the post on this platform.", "properties": { "clicks": { "type": "integer" }, "comments": { "type": "integer" }, "engagementRate": { "type": "number" }, "impressions": { "type": "integer" }, "likes": { "type": "integer" }, "reach": { "type": "integer" }, "saves": { "type": "integer" }, "shares": { "type": "integer" }, "views": { "type": "integer" } }, "type": "object" }, "platform": { "type": "string" }, "postId": { "type": "string" }, "publishedAt": { "format": "date-time", "type": "string" } }, "type": "object" }, "type": "array" }, "topPosts": { "items": { "properties": { "metrics": { "description": "Lifetime metrics of the post on this platform.", "properties": { "clicks": { "type": "integer" }, "comments": { "type": "integer" }, "engagementRate": { "type": "number" }, "impressions": { "type": "integer" }, "likes": { "type": "integer" }, "reach": { "type": "integer" }, "saves": { "type": "integer" }, "shares": { "type": "integer" }, "views": { "type": "integer" } }, "type": "object" }, "platform": { "type": "string" }, "postId": { "type": "string" }, "publishedAt": { "format": "date-time", "type": "string" } }, "type": "object" }, "type": "array" }, "totals": { "properties": { "clicks": { "type": "integer" }, "comments": { "type": "integer" }, "engagementRate": { "description": "Percentage. Likes, comments, shares and saves over impressions, pooled per platform (reach, then views, when a platform has no impressions).", "type": "number" }, "impressions": { "type": "integer" }, "likes": { "type": "integer" }, "reach": { "type": "integer" }, "saves": { "type": "integer" }, "shares": { "type": "integer" }, "views": { "type": "integer" } }, "type": "object" } }, "required": [ "daily", "dataAsOf", "dateRange", "followers", "recentPosts", "topPosts", "totals" ], "type": "object" } } }, "description": "Dashboard for the window" }, "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." } }, "summary": "Get an analytics dashboard", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.get_analytics_dashboard@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "567e2f95c280cdbaccbfa3ddb7a83c747779b41e9fa814a6db427183ca222ea3" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_dashboard", "method": "GET", "path": "/apis/v1/social/analytics/dashboard" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_dashboard" } }, "/apis/v1/social/analytics/delta": { "get": { "description": "Analytics. 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. Without profileId or accountId it reads your default profile.\n\nCursor feed of the analytics snapshots that CHANGED, across every account you can read, in one paginated stream. Built for integrations that would otherwise call `GET /apis/v1/social/analytics` once per connected account.\n\nEach page carries changes from many accounts at once, so your call count scales with how much actually changed rather than with how many accounts you have.\n\nMeasured against a fleet of roughly 1,600 connected accounts: about 1,599 per-account analytics calls an hour became about 205 delta calls an hour, a 7.8x reduction.\n\n### Bootstrap once, then stay in sync\n\n1. Take the cursor FIRST: call this endpoint with NO `cursor`. It answers with an empty `data` array plus the feed's current position in `nextCursor`.\n2. Load your baseline from `GET /apis/v1/social/analytics`, the historical endpoint. This one is a rolling 7-day change log and cannot replay history.\n3. Resume from the cursor you took before the baseline.\n\nTaking the cursor afterwards instead drops every change that lands while the baseline is loading: it is in neither the row you already read nor the feed you resume behind it.\n\nThe overlap this order creates is safe. Metrics are absolute values rather than increments, so draining it leaves every post on its newest value.\n\n`nextCursor` is present on every response, empty pages included, so you always have something to advance with.\n\n### Ordering\n\nEntries come back oldest first, in the order the feed received them. That order is NOT `syncedAt`. `syncedAt` is stamped when an account's sync cycle started, and a slow cycle writes its rows after a faster cycle that started later, so `syncedAt` can go backwards between consecutive entries.\n\nDo not sort, filter or resume on `syncedAt`. The cursor is the only stable position, and it is opaque: pass it back verbatim, and do not parse, construct or compare cursors.\n\n### `hasMore: false` does not mean the feed ended\n\nThis stream has no end and `nextCursor` is never null.\n\n- `hasMore: true`: more changes are already waiting, so call again straight away.\n- `hasMore: false`: you are caught up. Keep the cursor and poll again on your normal interval.\n\n### The newest changes settle before they are served\n\nThe feed deliberately holds back its last few seconds of writes, so that a row can never become visible behind a cursor you have already advanced past.\n\nA read issued the instant an `analytics.synced` webhook lands will therefore often return an empty page for that account. Do not read an empty page as \"nothing changed\": poll again with the SAME cursor you last used rather than advancing.\n\n### Repeats inside one instant\n\nA sync cycle occasionally records the same post twice at the same feed position. When that happens the feed delivers one of those rows, not both.\n\nMeasured over a day of production traffic, about 1.3% of rows fall in such a group and 99.4% of those groups are identical rows, so this is far more often deduplication than loss.\n\nMetrics are absolute values rather than increments, so a later entry for the same post supersedes an earlier one.\n\n### Retention is 7 days\n\nChanges older than that leave the feed. A cursor older than 6 days is rejected with a `400` (a day of margin, because expiry is lazy).\n\nRecover the same way you bootstrapped:\n\n1. Take a fresh cursor from a call to this endpoint with no `cursor`.\n2. Re-load from `GET /apis/v1/social/analytics`.\n3. Resume from that cursor.\n\nA consumer that polls at least daily never reaches this.\n\n### Webhook and access\n\nPairs with the `analytics.synced` webhook, so changes can be read on notification instead of on a timer. That event carries no cursor of its own: keep using the `nextCursor` this endpoint gave you.\n\nRequires the same analytics access as `GET /apis/v1/social/analytics`, and shares the stricter per-second rate-limit window applied to analytics endpoints.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_delta", "parameters": [ { "description": "Opaque cursor from a previous response's `nextCursor`. Omit it to start from\nnow: the response is then an empty page carrying the feed's current position.\nRejected with a `400` when malformed, or when older than the retention window.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "Page size. Out-of-range values are a 400, never a silent clamp.", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Filter to a single platform (for example \"youtube\"). Omit for every platform.", "in": "query", "name": "platform", "required": false, "schema": { "type": "string" } }, { "description": "One of your profiles (prf_...). Defaults to your default profile when neither profileId nor accountId is sent.", "in": "query", "name": "profileId", "required": false, "schema": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "Changed snapshots, oldest first, in the order the feed received them. Empty on\nthe bootstrap call (no `cursor` supplied) and whenever nothing has changed\nsince your cursor.", "items": { "description": "One changed analytics snapshot. Metrics are the absolute values recorded at\n`syncedAt`, not the amount they moved by since the previous snapshot, so a later\nentry for the same `postId` always supersedes an earlier one.", "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "isDeleted": { "description": "True when the post was detected as deleted on the platform at this sync", "type": "boolean" }, "metrics": { "description": "Metrics a platform does not report are 0, not absent.", "properties": { "audienceCountries": { "additionalProperties": { "type": "number" }, "description": "TikTok business lane: viewer-country shares keyed by ISO-3166 alpha-2, fractions 0 to 1, top 20 with the tail in `other`. Empty object elsewhere.", "type": "object" }, "audienceTypes": { "additionalProperties": { "type": "number" }, "description": "TikTok business lane: follower / nonFollower and newViewer / returnViewer shares, fractions 0 to 1. Empty object elsewhere.", "type": "object" }, "clicks": { "type": "integer" }, "comments": { "type": "integer" }, "completionRate": { "description": "TikTok business lane: share of viewers who watched to the end, 0 to 1", "type": "number" }, "follows": { "description": "Follows attributed to this post (Instagram feed and stories, Facebook Reels, TikTok business lane)", "type": "integer" }, "igReelsAvgWatchTime": { "description": "Average watch time per play, in milliseconds (Instagram Reels, Facebook Reels, TikTok business videos)", "type": "integer" }, "igReelsVideoViewTotalTime": { "description": "Total watch time including replays, in milliseconds (Instagram Reels, Facebook Reels, TikTok business videos)", "type": "integer" }, "impressionSources": { "additionalProperties": { "type": "number" }, "description": "TikTok business lane: share of views by surface (forYou, follow, search, personalProfile, sound, directMessage, other), fractions 0 to 1. Empty object elsewhere.", "type": "object" }, "impressions": { "type": "integer" }, "likes": { "type": "integer" }, "profileViews": { "description": "Instagram feed posts (images and carousels; 0 on Reels and Stories) and TikTok business lane: profile views attributed to the post", "type": "integer" }, "reach": { "type": "integer" }, "reelsSkipRate": { "description": "Instagram Reels skip rate, 0 to 1", "type": "number" }, "replays": { "description": "Facebook Reels only: plays that were replays. 0 elsewhere.", "type": "integer" }, "reposts": { "type": "integer" }, "retentionCurve": { "additionalProperties": { "type": "number" }, "description": "Share of viewers still watching at each second of playback, as fractions 0 to 1. Filled for Facebook Reels and the TikTok business lane; an empty object for other media and platforms.\n\n**Facebook Reels** (Meta post_video_retention_graph):\n\n- The base is a subset of plays that Meta selects and does not expose. On small Reels it can be far below views (6 of 51 measured), so a value is a share of that subset, not of all plays.\n- Keys are whole seconds from the start of a play (\"3\" is the share still watching at 3 s).\n- Loops count as continued playback, so a short Reel's curve runs past its length (an 8 s Reel has keys \"0\" to \"12\").\n- Meta returns at most 41 points, so a long Reel covers only its first 40 s.\n\n**TikTok** (accounts connected through the TikTok for Business app, from TikTok video_view_retention): share still watching at each whole second, fractions 0 to 1, at most 61 points, thinned evenly on videos longer than 60 s.", "type": "object" }, "saves": { "type": "integer" }, "sends": { "type": "integer" }, "shares": { "type": "integer" }, "views": { "type": "integer" }, "websiteClicks": { "description": "TikTok business lane: website-link clicks attributed to the post (also inside clicks)", "type": "integer" } }, "required": [ "audienceCountries", "audienceTypes", "clicks", "comments", "completionRate", "follows", "igReelsAvgWatchTime", "igReelsVideoViewTotalTime", "impressionSources", "impressions", "likes", "profileViews", "reach", "reelsSkipRate", "reposts", "saves", "sends", "shares", "views", "websiteClicks" ], "type": "object" }, "platform": { "type": "string" }, "platformPostId": { "description": "Platform-side post ID (for example the YouTube video ID)", "type": "string" }, "postId": { "description": "External post ID. The same identifier as `posts[]._id` in GET /apis/v1/social/analytics.", "type": "string" }, "profileId": { "description": "One of your profiles (prf_...).", "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" }, "publishedAt": { "description": "When the post was published, ISO-8601 UTC", "format": "date-time", "type": "string" }, "syncedAt": { "description": "When the sync cycle that produced this snapshot STARTED, ISO-8601 UTC.\n\nThis is NOT the order entries arrive in and not a resume point: a slow cycle writes its rows after a faster cycle that started later, so `syncedAt` can go backwards between consecutive entries. Use `nextCursor` to resume.", "format": "date-time", "type": "string" } }, "required": [ "accountId", "isDeleted", "metrics", "platform", "platformPostId", "postId", "profileId", "publishedAt", "syncedAt" ], "type": "object" }, "type": "array" }, "hasMore": { "description": "True when more changes are already waiting past `nextCursor`, so call again\nimmediately. False means you are caught up: keep `nextCursor` and poll again\nlater. This feed never ends, so `hasMore: false` does NOT mean `nextCursor`\nis null.", "type": "boolean" }, "nextCursor": { "description": "Cursor to send on the next call. ALWAYS present, including on an empty page,\nso you always have something to advance with, and it never moves backwards.\nOpaque: pass it back verbatim, and do not parse, construct or compare cursors.", "type": "string" } }, "required": [ "data", "hasMore", "nextCursor" ], "type": "object" } } }, "description": "One page of changed analytics" }, "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." } }, "summary": "Analytics changed since a cursor", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.get_analytics_delta@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "c48b4debafca937d4fe8bce6d117436d119c67371a530d9e4c171bf758900610" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_delta", "method": "GET", "path": "/apis/v1/social/analytics/delta" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_delta" } }, "/apis/v1/social/analytics/facebook/demographics": { "get": { "description": "Analytics. 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.\n\nReturns the follower breakdown of a connected Facebook Page by country and/or city, from Meta's latest daily snapshot.\n\n### Keys\n\n- Country keys are ISO 3166-1 alpha-2 codes.\n- City keys are \"City, Region, Country\" strings as Meta returns them.\n\n### Limits\n\nMeta removed age and gender demographics for Pages (page_fans_gender_age) on November 15 2025 with no replacement, so only country and city are available.\n\nMeta reports small counts at a privacy floor, so the long tail can show identical low values.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_facebook_4f17ba", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Comma-separated list of demographic dimensions: country, city.\nDefaults to both if omitted.", "in": "query", "name": "breakdown", "required": false, "schema": { "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" }, "demographics": { "description": "Only the requested breakdowns are present. Entries are sorted by value, largest first.", "properties": { "city": { "items": { "properties": { "dimension": { "type": "string" }, "value": { "description": "Followers", "type": "integer" } }, "type": "object" }, "type": "array" }, "country": { "items": { "properties": { "dimension": { "type": "string" }, "value": { "description": "Followers", "type": "integer" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "metric": { "enum": [ "follower_demographics" ], "type": "string" }, "note": { "type": "string" }, "platform": { "enum": [ "facebook" ], "type": "string" }, "snapshotDate": { "description": "Date of Meta's snapshot (YYYY-MM-DD), or null when Meta has no snapshot yet.", "format": "date", "type": [ "string", "null" ] }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Follower demographics for the Page" }, "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." } }, "summary": "Get Facebook Page demographics", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.get_facebook_demographics@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "b78c54a3a2ec4179b6828b6fa6fe6419d7a29454a4e22debbdb236bcb3104327" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_facebook_4f17ba", "method": "GET", "path": "/apis/v1/social/analytics/facebook/demographics" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_facebook_4f17ba" } }, "/apis/v1/social/analytics/facebook/page-insights": { "get": { "description": "Analytics. 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.\n\nReturns page-level Facebook insights (media views, views, post engagements, video metrics, follower counts). The response shape matches /apis/v1/social/analytics/instagram/account-insights, so the same client handling works across platforms.\n\nMax 89 days, defaults to last 30 days.\n\n### Metric names\n\nMetric names track the current (post-November 2025) Meta Graph API. These legacy metrics were deprecated by Meta on November 15, 2025 and are NOT accepted by this endpoint:\n\n- page_impressions\n- page_fans\n- page_fan_adds\n- page_fan_removes\n\nUse the replacements below. Because Meta did not provide direct adds/removes replacements, AIsa synthesizes followers_gained / followers_lost from the daily follower snapshotter.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_facebook_ee35af", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Comma-separated list of metrics. Defaults to \"page_media_view,page_post_engagements,page_follows,followers_gained,followers_lost\".\n\n**Live Meta metrics** (current names, post-Nov-2025):\n\n- page_media_view (replaces deprecated page_impressions)\n- page_views_total\n- page_post_engagements\n- page_video_views\n- page_video_view_time\n- page_follows (replaces deprecated page_fans)\n\n**AIsa-synthesized** from daily follower snapshots (filling the Nov-2025 gap left by the page_fan_adds / page_fan_removes deprecation):\n\n- followers_gained\n- followers_lost\n\n**Monetization** (opt-in, not in the defaults):\n\n- content_monetization_earnings: an object per day, always with unit \"micro_amount\" and an ISO 4217 \"currency\".\n- monetization_approximate_earnings: a bare number per day; unit is always \"unspecified\" and \"currency\" always null.\n\nEach monetization metric costs its own Graph call, so requesting both adds two calls. Values are approximate and Meta restates them later. The two are on different scales and not comparable. Both keep daily \"values\" on every metricType and are never rescaled by AIsa.\n\nEarnings are Page-level daily buckets and \"total\" is their sum. Meta does not document whether a bucket is that day's earnings or a running total, and every Page measured so far earned exactly 0.\n\nReconcile \"total\" against the Page's Meta export before relying on it (daily \"values\" are always returned for this).\n\nPer-post lifetime earnings: GET /apis/v1/social/analytics/facebook/post-earnings.\n\nA Page not enrolled in monetization, or that earned nothing, returns normal daily buckets of 0 in \"metrics\" (Meta does not distinguish them), so a 0 total does NOT mean the Page is enrolled.\n\n\"unavailableMetrics\" covers the narrower case where Meta returned no bucket at all (\"no_data\") or rejected the request; the metric is then omitted from \"metrics\" rather than reported as 0.", "in": "query", "name": "metrics", "required": false, "schema": { "type": "string" } }, { "description": "Start date (YYYY-MM-DD). Defaults to 30 days ago.", "in": "query", "name": "fromDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "End date (YYYY-MM-DD). Defaults to today.", "in": "query", "name": "toDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Alias of fromDate, kept for existing callers", "in": "query", "name": "since", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Alias of toDate, kept for existing callers", "in": "query", "name": "until", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "\"total_value\" (default) returns aggregated totals only.\n\"time_series\" returns daily values in the \"values\" array.", "in": "query", "name": "metricType", "required": false, "schema": { "default": "total_value", "enum": [ "time_series", "total_value" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Shared account-insights response envelope used by every platform-level\nanalytics endpoint (/apis/v1/social/analytics/{facebook|instagram|youtube|linkedin|tiktok}/*).\nThe name is historical - the shape was first shipped for Instagram and every\nnew platform endpoint reuses it for response-shape consistency. The platform\nfield echoes back which platform served the response.", "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "breakdown": { "description": "Breakdown dimension used (only present when breakdown was requested)", "type": "string" }, "dataDelay": { "type": "string" }, "dateRange": { "properties": { "since": { "format": "date", "type": "string" }, "until": { "format": "date", "type": "string" } }, "type": "object" }, "metricType": { "enum": [ "time_series", "total_value" ], "type": "string" }, "metrics": { "additionalProperties": { "properties": { "breakdowns": { "description": "Breakdown values (only for total_value with breakdown)", "items": { "properties": { "dimension": { "type": "string" }, "value": { "type": "number" } }, "type": "object" }, "type": "array" }, "currency": { "description": "ISO 4217 currency of a monetary metric, or null when the platform omitted it.\nAlways null on monetization_approximate_earnings, which Meta returns as a bare number\nwith no currency; always present on content_monetization_earnings.", "type": [ "string", "null" ] }, "total": { "description": "Sum or aggregate value for the metric", "type": "number" }, "unit": { "description": "Present on monetary metrics only. The scale of \"total\" and of every \"values[].value\", exactly as the platform returned them.\n\n- \"micro_amount\": the platform returned an object carrying a micro amount; values are that integer, summed, unconverted. AIsa publishes no divisor because Meta documents none: divide by the scale you verified against the Page's own Meta Business Suite export. On Facebook Page insights this is always content_monetization_earnings.\n- \"unspecified\": the platform returned a bare number with no unit metadata, passed through as-is; the platform does not state whether it is major or minor currency units. On Facebook Page insights this is always monetization_approximate_earnings.", "enum": [ "micro_amount", "unspecified" ], "type": "string" }, "values": { "description": "Daily values (for time_series, and always on monetary metrics)", "items": { "properties": { "date": { "format": "date", "type": "string" }, "value": { "type": "number" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "description": "Object keyed by metric name.\n\n- For time_series: each metric has \"total\" (number) and \"values\" (array of {date, value}).\n- For total_value: each metric has \"total\" (number) and optionally \"breakdowns\" (array of {dimension, value}).\n\n**Monetary metrics** also carry \"unit\" and \"currency\". AIsa never rescales money: \"total\" and every \"values[].value\" are the platform's raw numbers in the stated unit.\n\nMonetary metrics keep \"values\" even on metricType=total_value, because their \"total\" is the sum of the daily buckets the platform returned over the range. Keep the series to reconcile that sum against the platform's own reporting before invoicing on it.\n\nA metric that could not be served is absent from this object and listed in \"unavailableMetrics\" instead, so an unavailable metric is never reported as a zero.", "type": "object" }, "platform": { "description": "Platform that served this response.", "enum": [ "facebook", "instagram", "youtube", "linkedin", "tiktok" ], "type": "string" }, "success": { "type": "boolean" }, "unavailableMetrics": { "description": "Requested metrics that could not be served. Present only when at least one metric is unavailable, absent otherwise.\n\nEach listed metric is OMITTED from \"metrics\" rather than reported as 0, which is how an unavailable metric is distinguished from a genuine zero. The request itself still succeeds with HTTP 200.", "items": { "properties": { "message": { "description": "Platform-provided explanation when available (access tokens redacted), otherwise AIsa copy.", "type": "string" }, "metric": { "description": "The requested metric name.", "type": "string" }, "reason": { "description": "Why the metric is unavailable:\n\n- \"not_enrolled\": the account is not enrolled in the program behind this metric.\n- \"permission_missing\": the connected user lacks access to this metric.\n- \"unsupported_metric\": the platform does not accept this metric name on the API version AIsa uses.\n- \"no_data\": the platform returned no bucket for this metric over the requested range.\n- \"unreadable_value\": the platform returned a value shape AIsa cannot read, so no total is reported.\n- \"mixed_currency\": readable values disagree on currency or unit within the range.\n- \"upstream_error\": any other platform failure.\n\n\"no_data\" is the common case in practice. The others are defensive: \"not_enrolled\" and \"unsupported_metric\" in particular have not been observed on live Facebook traffic, since a non-enrolled Page returns zeros rather than an error and metric names are validated before any platform call.", "enum": [ "not_enrolled", "permission_missing", "unsupported_metric", "no_data", "unreadable_value", "mixed_currency", "upstream_error" ], "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Page insights data" }, "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." } }, "summary": "Get Facebook Page insights", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.get_facebook_page_insights@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "4788054644d9685e0d4c87b8c0a1be0f14afc328740844e1a5e95eea63ab8ed5" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_facebook_ee35af", "method": "GET", "path": "/apis/v1/social/analytics/facebook/page-insights" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_facebook_ee35af" } }, "/apis/v1/social/analytics/facebook/post-earnings": { "get": { "description": "Analytics. 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.\n\nReturns lifetime monetization earnings for ONE Facebook post, read live from Meta on every request.\n\n### Lifetime totals only\n\nEarnings are CUMULATIVE since the post was published, not earnings within a date range. So this endpoint takes no since/until, and the totals must not be summed across dates or across posts. Page-level daily earnings live on /apis/v1/social/analytics/facebook/page-insights.\n\n### Zeros and missing metrics\n\n- A post on a Page that is not enrolled in monetization, or that earned nothing, returns \"total\": 0 rather than an error: Meta does not distinguish the two.\n- A metric Meta returned no bucket for at all is reported in \"unavailableMetrics\" and omitted from \"metrics\", never as a 0.\n\nAmounts are the platform's raw numbers in the stated \"unit\" and are never rescaled by AIsa.\n\n### Rejected parameters\n\nThese are rejected with 400:\n\n- \"breakdown\": breakdown dimensions are not exposed.\n- \"since\", \"until\", \"period\", and \"metricType\": scoping this endpoint to a window is not possible.\n\nSilently returning the lifetime total for a window would let a caller sum a year of weekly requests into a figure ~52x the post's real earnings.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_facebook_b22e2b", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "The platform post ID, exactly as returned in platformAnalytics[].platformPostId by\n/apis/v1/social/analytics: \"{pageId}_{postId}\", or the bare video ID for Reels.", "in": "query", "name": "postId", "required": true, "schema": { "type": "string" } }, { "description": "Comma-separated list of monetization metrics. Defaults to both:\n - content_monetization_earnings\n - monetization_approximate_earnings\n\ncontent_monetization_earnings always carries unit \"micro_amount\" plus an ISO 4217\n\"currency\". monetization_approximate_earnings is always a bare number, so its unit is\n\"unspecified\" and its \"currency\" is null. The two are on different scales and are not\ncomparable to each other. Any other metric name is rejected with 400.", "in": "query", "name": "metrics", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Lifetime monetization earnings for one Facebook post. Same \"unit\" / \"currency\" contract and\nsame unavailable-vs-zero contract as the Page-level response; there is no date range, no\nmetricType, and no daily \"values\", because the single lifetime bucket IS the total.", "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "dataDelay": { "type": "string" }, "metrics": { "additionalProperties": { "properties": { "currency": { "description": "ISO 4217 currency, or null when Meta omitted it. Always null on\nmonetization_approximate_earnings; always present on content_monetization_earnings.", "type": [ "string", "null" ] }, "total": { "description": "Lifetime earnings in \"unit\", exactly as Meta returned them. Never rescaled.", "type": "number" }, "unit": { "description": "\"micro_amount\": Meta returned an object shape carrying a micro amount, and \"total\" is\nthat integer, unconverted. AIsa does not publish a divisor because Meta does not\ndocument one; divide by the scale you have verified against the Page's own Meta\nBusiness Suite export. This is always content_monetization_earnings.\n\n\"unspecified\": Meta returned a bare number with no unit metadata, passed through as-is;\nMeta does not state whether it is major or minor currency units. This is always\nmonetization_approximate_earnings.", "enum": [ "micro_amount", "unspecified" ], "type": "string" } }, "type": "object" }, "description": "One entry per served metric. A metric reported here with \"total\": 0 genuinely earned\nnothing (or its Page is not enrolled, which Meta reports identically).", "type": "object" }, "period": { "description": "Always \"lifetime\": the total is cumulative since publication and must not be summed\nacross dates or across posts.", "enum": [ "lifetime" ], "type": "string" }, "platform": { "type": "string" }, "postId": { "description": "The platform post ID that was queried, echoed back.", "type": "string" }, "success": { "type": "boolean" }, "unavailableMetrics": { "description": "Requested metrics Meta could not serve. Present only when at least one metric is\nunavailable, and absent otherwise. Each listed metric is OMITTED from \"metrics\" rather than\nreported as 0. The request itself still succeeds with HTTP 200.", "items": { "properties": { "message": { "description": "Platform-provided explanation when available (access tokens redacted), otherwise AIsa copy.", "type": "string" }, "metric": { "description": "The requested metric name.", "type": "string" }, "reason": { "description": "Why the metric is unavailable:\n\n- \"not_enrolled\": the account is not enrolled in the program behind this metric.\n- \"permission_missing\": the connected user lacks access to this metric.\n- \"unsupported_metric\": Meta does not accept this metric name on the API version AIsa uses.\n- \"no_data\": Meta returned no bucket for this metric.\n- \"unreadable_value\": Meta returned a value shape AIsa cannot read, so no total is reported.\n- \"mixed_currency\": readable values disagree on currency or unit.\n- \"upstream_error\": any other platform failure.\n\n\"no_data\" is the common case in practice; the others are defensive.", "enum": [ "not_enrolled", "permission_missing", "unsupported_metric", "no_data", "unreadable_value", "mixed_currency", "upstream_error" ], "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Lifetime per-post monetization earnings" }, "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." } }, "summary": "Get Facebook post monetization earnings", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.get_facebook_post_earnings@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "6c35663d59d86117070e6d81665da6167df38e461baac020d030e64c17b7f12c" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_facebook_b22e2b", "method": "GET", "path": "/apis/v1/social/analytics/facebook/post-earnings" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_facebook_b22e2b" } }, "/apis/v1/social/analytics/googleanalytics/metadata": { "get": { "description": "Analytics. 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.\n\nEvery dimension and metric the connected GA4 property accepts in a report, including its\ncustom definitions. Cached for one hour.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_googlean_345a0f", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "query", "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" }, "dimensions": { "items": { "properties": { "apiName": { "type": "string" }, "category": { "type": "string" }, "customDefinition": { "type": "boolean" }, "description": { "type": "string" }, "uiName": { "type": "string" } }, "type": "object" }, "type": "array" }, "metrics": { "items": { "properties": { "apiName": { "type": "string" }, "category": { "type": "string" }, "customDefinition": { "type": "boolean" }, "description": { "type": "string" }, "type": { "type": "string" }, "uiName": { "type": "string" } }, "type": "object" }, "type": "array" }, "propertyId": { "type": "string" } }, "type": "object" } } }, "description": "Available dimensions and metrics" }, "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." } }, "summary": "List Google Analytics (GA4) dimensions and metrics", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.get_google_analytics_metadata@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "d3aa2cba929e632c3346276e3c307b241809c7598669d6b0f54cd6659da66742" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_googlean_345a0f", "method": "GET", "path": "/apis/v1/social/analytics/googleanalytics/metadata" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_googlean_345a0f" } }, "/apis/v1/social/analytics/googleanalytics/realtime": { "post": { "description": "Analytics. 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.\n\nActivity on a connected GA4 property in the last 30 minutes (up to 60 for Analytics 360),\nthrough Google's `runRealtimeReport`. Not cached. Only realtime dimensions and metrics are\naccepted, e.g. `country`, `unifiedScreenName` with `activeUsers`.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_analytics_googlea_76dc87", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "accountId": "acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3", "dimensions": [ "country" ], "metrics": [ "activeUsers" ] }, "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "dimensionFilter": { "additionalProperties": true, "description": "A Google FilterExpression on dimensions, in Google's own shape.", "type": "object" }, "dimensions": { "description": "GA4 dimension API names, e.g. `date`, `sessionSource`, `pagePath`. List them with GET /apis/v1/social/analytics/googleanalytics/metadata.", "items": { "type": "string" }, "maxItems": 9, "type": "array" }, "limit": { "description": "Rows to return. Defaults to Google's default (10000).", "maximum": 10000, "minimum": 1, "type": "integer" }, "metricFilter": { "additionalProperties": true, "description": "A Google FilterExpression on metrics, in Google's own shape.", "type": "object" }, "metrics": { "description": "GA4 metric API names, e.g. `sessions`, `activeUsers`, `keyEvents`, `totalRevenue`.", "items": { "type": "string" }, "maxItems": 10, "minItems": 1, "type": "array" }, "minuteRanges": { "items": { "properties": { "endMinutesAgo": { "maximum": 59, "minimum": 0, "type": "integer" }, "name": { "type": "string" }, "startMinutesAgo": { "maximum": 59, "minimum": 0, "type": "integer" } }, "type": "object" }, "maxItems": 2, "minItems": 1, "type": "array" }, "orderBys": { "description": "Google OrderBy objects, e.g. `{ \"metric\": { \"metricName\": \"sessions\" }, \"desc\": true }`.", "items": { "additionalProperties": true, "type": "object" }, "maxItems": 10, "type": "array" } }, "required": [ "accountId", "metrics" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Google Analytics Data API report, passed through as Google returns it. Every value in `rows` is a string; read `metricHeaders[].type` to parse metrics.", "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "dimensionHeaders": { "items": { "properties": { "name": { "type": "string" } }, "type": "object" }, "type": "array" }, "metadata": { "additionalProperties": true, "description": "Google report metadata (currency, time zone, sampling and thresholding flags).", "type": "object" }, "metricHeaders": { "items": { "properties": { "name": { "type": "string" }, "type": { "description": "Google metric type, e.g. TYPE_INTEGER, TYPE_FLOAT, TYPE_SECONDS, TYPE_CURRENCY.", "type": "string" } }, "type": "object" }, "type": "array" }, "propertyId": { "description": "Numeric GA4 property ID.", "type": "string" }, "propertyQuota": { "additionalProperties": true, "description": "Google quota left on this property after the request (tokens per day and per hour, concurrent requests). Cached responses carry the quota from when they were fetched.", "type": "object" }, "rowCount": { "description": "Total rows matching the request, across all pages.", "type": "integer" }, "rows": { "items": { "properties": { "dimensionValues": { "items": { "properties": { "value": { "type": "string" } }, "type": "object" }, "type": "array" }, "metricValues": { "items": { "properties": { "value": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Realtime report rows from Google" }, "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." } }, "summary": "Run a Google Analytics (GA4) realtime report", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.run_google_analytics_realtime_report@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "aab5b5d6eecfad8dd76d331d8a617fcabefb52348521e42bdf2c1c6106d1d4aa" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_analytics_googlea_76dc87", "method": "POST", "path": "/apis/v1/social/analytics/googleanalytics/realtime" }, "x-codeSamples": [ { "lang": "text", "label": "Reference example", "source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/social/analytics/googleanalytics/realtime \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"accountId\": \"acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3\",\n \"dimensions\": [\n \"country\"\n ],\n \"metrics\": [\n \"activeUsers\"\n ]\n}'" } ], "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_analytics_googlea_76dc87" } }, "/apis/v1/social/analytics/googleanalytics/report": { "post": { "description": "Analytics. 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.\n\nRuns a report on a connected GA4 property through Google's Data API (`runReport`).\n\nPick any GA4 dimensions and metrics; filters and ordering use Google's own shapes.\n\n### Caching and quota\n\nIdentical requests on the same property are cached for 10 minutes.\n\nGoogle meters each property by quota tokens. When it is used up the request returns 429 until Google refills it (hourly quotas within the hour, daily ones at midnight Pacific time).\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_analytics_googlea_7e75f2", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "accountId": "acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3", "dateRanges": [ { "endDate": "yesterday", "startDate": "30daysAgo" } ], "dimensions": [ "sessionDefaultChannelGroup" ], "metrics": [ "sessions", "activeUsers", "keyEvents" ], "orderBys": [ { "desc": true, "metric": { "metricName": "sessions" } } ] }, "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "currencyCode": { "description": "ISO 4217 code for currency metrics. Defaults to the property currency.", "type": "string" }, "dateRanges": { "description": "Defaults to the last 28 days (`28daysAgo` to `yesterday`).", "items": { "properties": { "endDate": { "description": "YYYY-MM-DD, today, yesterday or NdaysAgo.", "type": "string" }, "name": { "type": "string" }, "startDate": { "description": "YYYY-MM-DD, today, yesterday or NdaysAgo.", "type": "string" } }, "required": [ "endDate", "startDate" ], "type": "object" }, "maxItems": 4, "minItems": 1, "type": "array" }, "dimensionFilter": { "additionalProperties": true, "description": "A Google FilterExpression on dimensions, in Google's own shape.", "type": "object" }, "dimensions": { "description": "GA4 dimension API names, e.g. `date`, `sessionSource`, `pagePath`. List them with GET /apis/v1/social/analytics/googleanalytics/metadata.", "items": { "type": "string" }, "maxItems": 9, "type": "array" }, "keepEmptyRows": { "type": "boolean" }, "limit": { "description": "Rows to return. Defaults to Google's default (10000).", "maximum": 10000, "minimum": 1, "type": "integer" }, "metricFilter": { "additionalProperties": true, "description": "A Google FilterExpression on metrics, in Google's own shape.", "type": "object" }, "metrics": { "description": "GA4 metric API names, e.g. `sessions`, `activeUsers`, `keyEvents`, `totalRevenue`.", "items": { "type": "string" }, "maxItems": 10, "minItems": 1, "type": "array" }, "offset": { "description": "Row offset for paging through a report larger than `limit`.", "minimum": 0, "type": "integer" }, "orderBys": { "description": "Google OrderBy objects, e.g. `{ \"metric\": { \"metricName\": \"sessions\" }, \"desc\": true }`.", "items": { "additionalProperties": true, "type": "object" }, "maxItems": 10, "type": "array" } }, "required": [ "accountId", "metrics" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Google Analytics Data API report, passed through as Google returns it. Every value in `rows` is a string; read `metricHeaders[].type` to parse metrics.", "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "dimensionHeaders": { "items": { "properties": { "name": { "type": "string" } }, "type": "object" }, "type": "array" }, "metadata": { "additionalProperties": true, "description": "Google report metadata (currency, time zone, sampling and thresholding flags).", "type": "object" }, "metricHeaders": { "items": { "properties": { "name": { "type": "string" }, "type": { "description": "Google metric type, e.g. TYPE_INTEGER, TYPE_FLOAT, TYPE_SECONDS, TYPE_CURRENCY.", "type": "string" } }, "type": "object" }, "type": "array" }, "propertyId": { "description": "Numeric GA4 property ID.", "type": "string" }, "propertyQuota": { "additionalProperties": true, "description": "Google quota left on this property after the request (tokens per day and per hour, concurrent requests). Cached responses carry the quota from when they were fetched.", "type": "object" }, "rowCount": { "description": "Total rows matching the request, across all pages.", "type": "integer" }, "rows": { "items": { "properties": { "dimensionValues": { "items": { "properties": { "value": { "type": "string" } }, "type": "object" }, "type": "array" }, "metricValues": { "items": { "properties": { "value": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Report rows from Google" }, "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." } }, "summary": "Run a Google Analytics (GA4) report", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.run_google_analytics_report@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "689d7e6b2c1e7951536a572a886c4cbccf9e593b72d4308067ddd6a0a822b624" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_analytics_googlea_7e75f2", "method": "POST", "path": "/apis/v1/social/analytics/googleanalytics/report" }, "x-codeSamples": [ { "lang": "text", "label": "Reference example", "source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/social/analytics/googleanalytics/report \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"accountId\": \"acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3\",\n \"dateRanges\": [\n {\n \"endDate\": \"yesterday\",\n \"startDate\": \"30daysAgo\"\n }\n ],\n \"dimensions\": [\n \"sessionDefaultChannelGroup\"\n ],\n \"metrics\": [\n \"sessions\",\n \"activeUsers\",\n \"keyEvents\"\n ],\n \"orderBys\": [\n {\n \"desc\": true,\n \"metric\": {\n \"metricName\": \"sessions\"\n }\n }\n ]\n}'" } ], "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_analytics_googlea_7e75f2" } }, "/apis/v1/social/analytics/googlebusiness/performance": { "get": { "description": "Analytics. 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.\n\nReturns daily performance metrics for a Google Business Profile location.\nMetrics include impressions (Maps/Search, desktop/mobile), website clicks,\ncall clicks, direction requests, conversations, bookings, and food orders.\nData may be delayed 2-3 days. Max 18 months of historical data.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_googlebu_7f26fd", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Comma-separated metric names. Defaults to all available metrics.\nValid values: BUSINESS_IMPRESSIONS_DESKTOP_MAPS, BUSINESS_IMPRESSIONS_DESKTOP_SEARCH,\nBUSINESS_IMPRESSIONS_MOBILE_MAPS, BUSINESS_IMPRESSIONS_MOBILE_SEARCH,\nBUSINESS_CONVERSATIONS, BUSINESS_DIRECTION_REQUESTS, CALL_CLICKS, WEBSITE_CLICKS,\nBUSINESS_BOOKINGS, BUSINESS_FOOD_ORDERS, BUSINESS_FOOD_MENU_CLICKS", "in": "query", "name": "metrics", "required": false, "schema": { "type": "string" } }, { "description": "Start date (YYYY-MM-DD). Defaults to 30 days ago. Max 18 months back.", "in": "query", "name": "fromDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "End date (YYYY-MM-DD). Defaults to today.", "in": "query", "name": "toDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Alias of fromDate, kept for existing callers", "in": "query", "name": "startDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Alias of toDate, kept for existing callers", "in": "query", "name": "endDate", "required": false, "schema": { "format": "date", "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" }, "dataDelay": { "type": "string" }, "dateRange": { "properties": { "endDate": { "format": "date", "type": "string" }, "startDate": { "format": "date", "type": "string" } }, "type": "object" }, "metrics": { "additionalProperties": { "properties": { "total": { "description": "Sum of all daily values in the range", "type": "integer" }, "values": { "items": { "properties": { "date": { "format": "date", "type": "string" }, "value": { "type": "integer" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "description": "Each key is a metric name containing total and daily values.", "type": "object" }, "platform": { "type": "string" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Performance metrics with daily time series" }, "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." } }, "summary": "Get Google Business Profile performance metrics", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.get_google_business_performance@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "ae5bad1d90c43a6b268d55bff940963d4a36a4596972bc2e5333d0b6ec91d406" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_googlebu_7f26fd", "method": "GET", "path": "/apis/v1/social/analytics/googlebusiness/performance" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_googlebu_7f26fd" } }, "/apis/v1/social/analytics/googlebusiness/search-keywords": { "get": { "description": "Analytics. 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.\n\nReturns search keywords that triggered impressions for a Google Business Profile location.\n\n- Data is aggregated monthly.\n- Keywords Google reports only as below a threshold have `impressions` 0 and `impressionsThreshold` set to that threshold.\n- Max 18 months of historical data.\n\n### Paging\n\nReturns up to 100 keywords per page. When `nextPageToken` is not null, pass it as `pageToken` with the same `startMonth` and `endMonth` to get the next page.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_googlebu_3c3e2d", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Start month (YYYY-MM). Defaults to 3 months ago.", "in": "query", "name": "startMonth", "required": false, "schema": { "pattern": "^\\d{4}-\\d{2}$", "type": "string" } }, { "description": "End month (YYYY-MM). Defaults to current month.", "in": "query", "name": "endMonth", "required": false, "schema": { "pattern": "^\\d{4}-\\d{2}$", "type": "string" } }, { "description": "The nextPageToken from the previous page. Valid only with the same startMonth and endMonth as the request that returned it.", "in": "query", "name": "pageToken", "required": false, "schema": { "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" }, "keywords": { "items": { "properties": { "impressions": { "description": "Impressions for the range. 0 when Google reports only a threshold.", "type": "integer" }, "impressionsThreshold": { "description": "Set when Google reports only that impressions were below this value. null when impressions is exact.", "type": [ "integer", "null" ] }, "keyword": { "type": "string" } }, "type": "object" }, "type": "array" }, "monthRange": { "properties": { "endMonth": { "type": "string" }, "startMonth": { "type": "string" } }, "type": "object" }, "nextPageToken": { "description": "Pass as pageToken to fetch the next page. null on the last page.", "type": [ "string", "null" ] }, "note": { "type": "string" }, "platform": { "type": "string" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Search keywords with impression counts" }, "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." } }, "summary": "Get Google Business Profile search keywords", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.get_google_business_search_keywords@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "448f1cf9f66b85c5cad935a4cba1b87317031fd93c1e2c778248beeffb812850" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_googlebu_3c3e2d", "method": "GET", "path": "/apis/v1/social/analytics/googlebusiness/search-keywords" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_googlebu_3c3e2d" } }, "/apis/v1/social/analytics/inbox/conversations": { "get": { "description": "Inbox Analytics. 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. Without profileId or accountId it reads your default profile.\n\nPer-conversation listing with per-row totals + first/last message\ntimestamps. The inbox analog of GET /apis/v1/social/analytics (posts listing):\nsame filter shape, same pagination, same sort/order semantics.\nUse as the entry point for the per-conversation analytics drawer\nat /apis/v1/social/analytics/inbox/conversations/{conversationId}.\n\nRows are enriched with the conversation's participant info\n(`participantName`, `participantUsername`, `participantPicture`)\nand last-message preview by joining the Conversation document\nscoped to the caller's team. Max date range is 365 days.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_inbox_co_b8cc2c", "parameters": [ { "in": "query", "name": "fromDate", "required": true, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "toDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "One of your profiles (prf_...). Defaults to your default profile when neither profileId nor accountId is sent.", "in": "query", "name": "profileId", "required": false, "schema": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" } }, { "in": "query", "name": "platform", "required": false, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": false, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "in": "query", "name": "source", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "page", "required": false, "schema": { "default": 1, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "sortBy", "required": false, "schema": { "default": "lastMessageAt", "enum": [ "lastMessageAt", "firstMessageAt", "totalMessages", "received", "sent", "read", "failed" ], "type": "string" } }, { "in": "query", "name": "order", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "from": { "format": "date", "type": "string" }, "items": { "items": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "conversationId": { "description": "The platformConversationId. A thread whose events were logged under both its ids comes back as one row.", "type": "string" }, "failed": { "type": "integer" }, "firstMessageAt": { "format": "date-time", "type": "string" }, "lastMessage": { "description": "Cached preview from the Conversation doc", "type": [ "string", "null" ] }, "lastMessageAt": { "format": "date-time", "type": "string" }, "participantName": { "type": [ "string", "null" ] }, "participantPicture": { "type": [ "string", "null" ] }, "participantUsername": { "type": [ "string", "null" ] }, "platform": { "type": "string" }, "read": { "type": "integer" }, "received": { "type": "integer" }, "sent": { "type": "integer" }, "totalMessages": { "type": "integer" } }, "type": "object" }, "type": "array" }, "pagination": { "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer" }, "page": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } }, "type": "object" }, "success": { "type": "boolean" }, "to": { "format": "date", "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Paginated conversation analytics list" }, "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." } }, "summary": "List conversation analytics", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.inbox_analytics.list_inbox_conversation_analytics@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "2304e92dfc1ed466343bab35c71334a10a7371250cf93205a6d9cc11bbdb0198" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_inbox_co_b8cc2c", "method": "GET", "path": "/apis/v1/social/analytics/inbox/conversations" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_inbox_co_b8cc2c" } }, "/apis/v1/social/analytics/inbox/conversations/{conversationId}": { "get": { "description": "Inbox Analytics. 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.\n\nPer-conversation inbox analytics. The inbox analog of\n/apis/v1/social/analytics/post-timeline: one conversation, daily totals,\nsource mix.\n\nThe {conversationId} path param accepts EITHER the AIsa\nconversation id OR its `platformConversationId` (the same\nidentity used by metadata.conversationId at ingest time).\nOwnership is verified against the caller's team before the\nthe analytics store query fires.\n\nMax date range is 365 days.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_inbox_co_f87ada", "parameters": [ { "description": "AIsa conversation id or platformConversationId.", "in": "path", "name": "conversationId", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "fromDate", "required": true, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "toDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "The social account (acc_...) the conversation belongs to. Required by AIsa for the ownership check; not forwarded.", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "bySource": { "items": { "properties": { "count": { "type": "integer" }, "source": { "description": "(unspecified) for legacy rows with no metadata.source", "type": "string" } }, "type": "object" }, "type": "array" }, "conversationId": { "description": "The platformConversationId", "type": "string" }, "from": { "format": "date", "type": "string" }, "platform": { "type": [ "string", "null" ] }, "success": { "type": "boolean" }, "summary": { "properties": { "failed": { "type": "integer" }, "firstMessageAt": { "format": "date-time", "type": [ "string", "null" ] }, "lastMessageAt": { "format": "date-time", "type": [ "string", "null" ] }, "read": { "type": "integer" }, "received": { "type": "integer" }, "sent": { "type": "integer" }, "totalMessages": { "type": "integer" } }, "type": "object" }, "timeseries": { "items": { "properties": { "date": { "format": "date", "type": "string" }, "failed": { "type": "integer" }, "read": { "type": "integer" }, "received": { "type": "integer" }, "sent": { "type": "integer" } }, "type": "object" }, "type": "array" }, "to": { "format": "date", "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Per-conversation analytics" }, "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." } }, "summary": "Get conversation analytics", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.inbox_analytics.get_inbox_conversation_analytics@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "726d0dbe5054f15464cda045cd55572c33251cb334eccf3d51d2fd9cea2ae1fb" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_inbox_co_f87ada", "method": "GET", "path": "/apis/v1/social/analytics/inbox/conversations/{conversationId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_inbox_co_f87ada" } }, "/apis/v1/social/analytics/inbox/heatmap": { "get": { "description": "Inbox Analytics. 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. Without profileId or accountId it reads your default profile.\n\nDay-of-week × hour-of-day breakdown of inbox messages. Buckets are\nsparse: only cells with at least one event are returned; clients\nzero-fill the rest to render the full 7×24 grid. The `dow` field\nfollows ClickHouse's `toDayOfWeek` convention (1 = Monday … 7 =\nSunday). Max date range is 365 days.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_inbox_heatmap", "parameters": [ { "in": "query", "name": "fromDate", "required": true, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "toDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "One of your profiles (prf_...). Defaults to your default profile when neither profileId nor accountId is sent.", "in": "query", "name": "profileId", "required": false, "schema": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" } }, { "in": "query", "name": "platform", "required": false, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": false, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "in": "query", "name": "source", "required": false, "schema": { "type": "string" } }, { "description": "Narrow to a single event type. \"all\" or omitted means no filter.", "in": "query", "name": "action", "required": false, "schema": { "enum": [ "message.received", "message.sent", "message.read", "all" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "buckets": { "items": { "properties": { "dow": { "description": "1 = Monday, 7 = Sunday", "maximum": 7, "minimum": 1, "type": "integer" }, "hour": { "maximum": 23, "minimum": 0, "type": "integer" }, "read": { "type": "integer" }, "received": { "type": "integer" }, "sent": { "type": "integer" } }, "type": "object" }, "type": "array" }, "from": { "format": "date", "type": "string" }, "success": { "type": "boolean" }, "to": { "format": "date", "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Heatmap buckets" }, "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." } }, "summary": "Get day × hour heatmap", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.inbox_analytics.get_inbox_heatmap@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "b386697caf05210c5127589e1a86c3120882ab39164ffb3b6e51785592e82d21" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_inbox_heatmap", "method": "GET", "path": "/apis/v1/social/analytics/inbox/heatmap" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_inbox_heatmap" } }, "/apis/v1/social/analytics/inbox/response-time": { "get": { "description": "Inbox Analytics. 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. Without profileId or accountId it reads your default profile.\n\nTime-to-first-response stats. Pairs each received message with the\nnext sent message in the same conversation and reports the delta\nas both summary statistics and a fixed-bucket histogram suited\nfor the analytics page's TTR chart.\n\n`sampleSize` reflects only conversations that received AND got a\nreply in the window. Received-but-never-answered conversations\nare excluded. Compare against /apis/v1/social/analytics/inbox/volume's\n`summary.received` to compute reply rate.\n\nMax date range is 365 days.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_inbox_re_03ccc1", "parameters": [ { "in": "query", "name": "fromDate", "required": true, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "toDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "One of your profiles (prf_...). Defaults to your default profile when neither profileId nor accountId is sent.", "in": "query", "name": "profileId", "required": false, "schema": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" } }, { "in": "query", "name": "platform", "required": false, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": false, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "from": { "format": "date", "type": "string" }, "histogram": { "items": { "properties": { "bucket": { "description": "Human label (0-1m, 1-5m, 5-15m, 15-60m, 1-4h, 4-24h, 1d+)", "type": "string" }, "count": { "type": "integer" }, "lowerSeconds": { "type": "integer" }, "upperSeconds": { "description": "null on the open-ended last bucket", "type": [ "integer", "null" ] } }, "type": "object" }, "type": "array" }, "success": { "type": "boolean" }, "summary": { "properties": { "fastestSeconds": { "type": "integer" }, "meanSeconds": { "type": "integer" }, "medianSeconds": { "type": "integer" }, "p90Seconds": { "type": "integer" }, "p99Seconds": { "type": "integer" }, "sampleSize": { "type": "integer" }, "slowestSeconds": { "type": "integer" } }, "type": "object" }, "to": { "format": "date", "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Response-time summary + histogram" }, "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." } }, "summary": "Get inbox response-time stats", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.inbox_analytics.get_inbox_response_time@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "591dd7e06175bc3644924e229a9075dceb7178de417985e47570dfb62d21a53c" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_inbox_re_03ccc1", "method": "GET", "path": "/apis/v1/social/analytics/inbox/response-time" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_inbox_re_03ccc1" } }, "/apis/v1/social/analytics/inbox/source-breakdown": { "get": { "description": "Inbox Analytics. 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. Without profileId or accountId it reads your default profile.\n\nBreakdown of inbox messages by their lineage source (the\n`metadata.source` field set at ingest time: human / workflow /\nsequence / broadcast / comment_automation / api / contact /\nplatform). Each source row also carries a per-platform sub-split.\nMax date range is 365 days.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_inbox_so_642674", "parameters": [ { "in": "query", "name": "fromDate", "required": true, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "toDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "One of your profiles (prf_...). Defaults to your default profile when neither profileId nor accountId is sent.", "in": "query", "name": "profileId", "required": false, "schema": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" } }, { "in": "query", "name": "platform", "required": false, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": false, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "from": { "format": "date", "type": "string" }, "sources": { "items": { "properties": { "byPlatform": { "items": { "properties": { "platform": { "type": "string" }, "read": { "type": "integer" }, "received": { "type": "integer" }, "sent": { "type": "integer" } }, "type": "object" }, "type": "array" }, "read": { "type": "integer" }, "received": { "type": "integer" }, "sent": { "type": "integer" }, "source": { "type": "string" } }, "type": "object" }, "type": "array" }, "success": { "type": "boolean" }, "to": { "format": "date", "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Source breakdown" }, "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." } }, "summary": "Get inbox source breakdown", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.inbox_analytics.get_inbox_source_breakdown@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "999455e683cfd82c56f73fd26bd1ed9da530fbbad53e6d623fe0a5e75022e7f1" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_inbox_so_642674", "method": "GET", "path": "/apis/v1/social/analytics/inbox/source-breakdown" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_inbox_so_642674" } }, "/apis/v1/social/analytics/inbox/top-accounts": { "get": { "description": "Inbox Analytics. 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. Without profileId or accountId it reads your default profile.\n\nLeaderboard of accounts by inbox message volume. Max date range is 365 days.\n\n- Each row is decorated with display labels from the live social account record (so the UI shows username + displayName, not only an ID).\n- Accounts that no longer map to a social account surface as \"(disconnected)\" so the row stays visible.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_inbox_to_7fe59f", "parameters": [ { "in": "query", "name": "fromDate", "required": true, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "toDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "One of your profiles (prf_...). Defaults to your default profile when neither profileId nor accountId is sent.", "in": "query", "name": "profileId", "required": false, "schema": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" } }, { "in": "query", "name": "platform", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "source", "required": false, "schema": { "type": "string" } }, { "description": "Cap on returned rows. Lower than the posting listing's 100 because each row triggers a social account lookup.", "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "maximum": 50, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "accounts": { "items": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "conversations": { "type": "integer" }, "displayName": { "description": "(disconnected) when the social account no longer exists", "type": "string" }, "medianResponseSeconds": { "type": "integer" }, "platform": { "type": "string" }, "received": { "type": "integer" }, "repliedCount": { "description": "Distinguishes 'instant replies' from 'no replies at all' so a zero medianResponseSeconds with repliedCount=0 renders as an em dash instead of '0s'", "type": "integer" }, "sent": { "type": "integer" }, "total": { "type": "integer" }, "username": { "type": "string" } }, "type": "object" }, "type": "array" }, "from": { "format": "date", "type": "string" }, "success": { "type": "boolean" }, "to": { "format": "date", "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Top accounts leaderboard" }, "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." } }, "summary": "Get top accounts by inbox volume", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.inbox_analytics.get_inbox_top_accounts@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "326b00eba8ac41ac8baefb7e0ab7961381986fdfb4e6a5884bebfbaefc983b9b" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_inbox_to_7fe59f", "method": "GET", "path": "/apis/v1/social/analytics/inbox/top-accounts" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_inbox_to_7fe59f" } }, "/apis/v1/social/analytics/inbox/volume": { "get": { "description": "Inbox Analytics. 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. Without profileId or accountId it reads your default profile.\n\nDaily inbox messaging volume + breakdowns. Folds the raw messaging\nevents into three projections so the client can render the volume\nchart, KPI strip, and per-platform stacked bar from a single call.\nMax date range is 365 days.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_inbox_volume", "parameters": [ { "description": "Inclusive lower bound (YYYY-MM-DD). Required.", "in": "query", "name": "fromDate", "required": true, "schema": { "format": "date", "type": "string" } }, { "description": "Inclusive upper bound (YYYY-MM-DD). Defaults to today.", "in": "query", "name": "toDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "One of your profiles (prf_...). Defaults to your default profile when neither profileId nor accountId is sent.", "in": "query", "name": "profileId", "required": false, "schema": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Filter by single platform (facebook, instagram, twitter, etc.).", "in": "query", "name": "platform", "required": false, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": false, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Filter by metadata.source lineage (human, workflow, sequence, broadcast, comment_automation, api, contact, platform).", "in": "query", "name": "source", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "byPlatform": { "items": { "properties": { "failed": { "type": "integer" }, "platform": { "type": "string" }, "read": { "type": "integer" }, "received": { "type": "integer" }, "sent": { "type": "integer" } }, "type": "object" }, "type": "array" }, "from": { "format": "date", "type": "string" }, "success": { "type": "boolean" }, "summary": { "properties": { "failed": { "type": "integer" }, "read": { "type": "integer" }, "received": { "type": "integer" }, "sent": { "type": "integer" }, "uniqueConversations": { "type": "integer" } }, "type": "object" }, "timeseries": { "items": { "properties": { "date": { "format": "date", "type": "string" }, "failed": { "type": "integer" }, "read": { "type": "integer" }, "received": { "type": "integer" }, "sent": { "type": "integer" } }, "type": "object" }, "type": "array" }, "to": { "format": "date", "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Volume breakdown" }, "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." } }, "summary": "Get inbox messaging volume", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.inbox_analytics.get_inbox_volume@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "1b1d3dc7ac9a6a3bf169b9934f390d9a9dde52cf8edb0fa76f106258e266ed13" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_inbox_volume", "method": "GET", "path": "/apis/v1/social/analytics/inbox/volume" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_inbox_volume" } }, "/apis/v1/social/analytics/instagram/account-insights": { "get": { "description": "Analytics. 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.\n\nReturns account-level Instagram insights such as reach, views, accounts engaged, and total interactions.\n\nThese metrics reflect the entire account's performance across all content surfaces (feed, stories, explore, profile), and are fundamentally different from post-level metrics.\n\n- Data may be delayed up to 48 hours.\n- Max 90 days (30 for accounts connected through Facebook Login), defaults to last 30 days.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_instagra_5507da", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Comma-separated list of metrics. Defaults to \"reach,views,accounts_engaged,total_interactions\".\n\nValid metrics: reach, views, accounts_engaged, total_interactions, comments, likes, saves, shares, replies, reposts, follows_and_unfollows, profile_links_taps, profile_views, website_clicks.\n\nOnly \"reach\" supports metricType=time_series. All other metrics (including follows_and_unfollows, profile_views and website_clicks) are total_value only. This is an Instagram Graph API limitation, not a AIsa one: the IG API returns no time-series data for these metrics.\n\nFor a daily running follower count, use /apis/v1/social/analytics/instagram/follower-history instead.", "in": "query", "name": "metrics", "required": false, "schema": { "type": "string" } }, { "description": "Start date (YYYY-MM-DD). Defaults to 30 days ago.", "in": "query", "name": "fromDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "End date (YYYY-MM-DD). Defaults to today.", "in": "query", "name": "toDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Alias of fromDate, kept for existing callers", "in": "query", "name": "since", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Alias of toDate, kept for existing callers", "in": "query", "name": "until", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "\"total_value\" (default) returns aggregated totals and supports breakdowns.\n\"time_series\" returns daily values but only works with the \"reach\" metric.", "in": "query", "name": "metricType", "required": false, "schema": { "default": "total_value", "enum": [ "time_series", "total_value" ], "type": "string" } }, { "description": "Breakdown dimension (only valid with metricType=total_value).\nValid values per metric: reach and views take follow_type or media_product_type; follows_and_unfollows takes follow_type; profile_links_taps takes contact_button_type; comments, likes, saves, shares and total_interactions take media_product_type.", "in": "query", "name": "breakdown", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Shared account-insights response envelope used by every platform-level\nanalytics endpoint (/apis/v1/social/analytics/{facebook|instagram|youtube|linkedin|tiktok}/*).\nThe name is historical - the shape was first shipped for Instagram and every\nnew platform endpoint reuses it for response-shape consistency. The platform\nfield echoes back which platform served the response.", "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "breakdown": { "description": "Breakdown dimension used (only present when breakdown was requested)", "type": "string" }, "dataDelay": { "type": "string" }, "dateRange": { "properties": { "since": { "format": "date", "type": "string" }, "until": { "format": "date", "type": "string" } }, "type": "object" }, "metricType": { "enum": [ "time_series", "total_value" ], "type": "string" }, "metrics": { "additionalProperties": { "properties": { "breakdowns": { "description": "Breakdown values (only for total_value with breakdown)", "items": { "properties": { "dimension": { "type": "string" }, "value": { "type": "number" } }, "type": "object" }, "type": "array" }, "currency": { "description": "ISO 4217 currency of a monetary metric, or null when the platform omitted it.\nAlways null on monetization_approximate_earnings, which Meta returns as a bare number\nwith no currency; always present on content_monetization_earnings.", "type": [ "string", "null" ] }, "total": { "description": "Sum or aggregate value for the metric", "type": "number" }, "unit": { "description": "Present on monetary metrics only. The scale of \"total\" and of every \"values[].value\", exactly as the platform returned them.\n\n- \"micro_amount\": the platform returned an object carrying a micro amount; values are that integer, summed, unconverted. AIsa publishes no divisor because Meta documents none: divide by the scale you verified against the Page's own Meta Business Suite export. On Facebook Page insights this is always content_monetization_earnings.\n- \"unspecified\": the platform returned a bare number with no unit metadata, passed through as-is; the platform does not state whether it is major or minor currency units. On Facebook Page insights this is always monetization_approximate_earnings.", "enum": [ "micro_amount", "unspecified" ], "type": "string" }, "values": { "description": "Daily values (for time_series, and always on monetary metrics)", "items": { "properties": { "date": { "format": "date", "type": "string" }, "value": { "type": "number" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "description": "Object keyed by metric name.\n\n- For time_series: each metric has \"total\" (number) and \"values\" (array of {date, value}).\n- For total_value: each metric has \"total\" (number) and optionally \"breakdowns\" (array of {dimension, value}).\n\n**Monetary metrics** also carry \"unit\" and \"currency\". AIsa never rescales money: \"total\" and every \"values[].value\" are the platform's raw numbers in the stated unit.\n\nMonetary metrics keep \"values\" even on metricType=total_value, because their \"total\" is the sum of the daily buckets the platform returned over the range. Keep the series to reconcile that sum against the platform's own reporting before invoicing on it.\n\nA metric that could not be served is absent from this object and listed in \"unavailableMetrics\" instead, so an unavailable metric is never reported as a zero.", "type": "object" }, "platform": { "description": "Platform that served this response.", "enum": [ "facebook", "instagram", "youtube", "linkedin", "tiktok" ], "type": "string" }, "success": { "type": "boolean" }, "unavailableMetrics": { "description": "Requested metrics that could not be served. Present only when at least one metric is unavailable, absent otherwise.\n\nEach listed metric is OMITTED from \"metrics\" rather than reported as 0, which is how an unavailable metric is distinguished from a genuine zero. The request itself still succeeds with HTTP 200.", "items": { "properties": { "message": { "description": "Platform-provided explanation when available (access tokens redacted), otherwise AIsa copy.", "type": "string" }, "metric": { "description": "The requested metric name.", "type": "string" }, "reason": { "description": "Why the metric is unavailable:\n\n- \"not_enrolled\": the account is not enrolled in the program behind this metric.\n- \"permission_missing\": the connected user lacks access to this metric.\n- \"unsupported_metric\": the platform does not accept this metric name on the API version AIsa uses.\n- \"no_data\": the platform returned no bucket for this metric over the requested range.\n- \"unreadable_value\": the platform returned a value shape AIsa cannot read, so no total is reported.\n- \"mixed_currency\": readable values disagree on currency or unit within the range.\n- \"upstream_error\": any other platform failure.\n\n\"no_data\" is the common case in practice. The others are defensive: \"not_enrolled\" and \"unsupported_metric\" in particular have not been observed on live Facebook traffic, since a non-enrolled Page returns zeros rather than an error and metric names are validated before any platform call.", "enum": [ "not_enrolled", "permission_missing", "unsupported_metric", "no_data", "unreadable_value", "mixed_currency", "upstream_error" ], "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Account insights data" }, "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." } }, "summary": "Get Instagram insights", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.get_instagram_account_insights@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "2e75414a42d22fa69bd1da902710c9ed946565c8d553123bb8c77a9d757400f4" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_instagra_5507da", "method": "GET", "path": "/apis/v1/social/analytics/instagram/account-insights" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_instagra_5507da" } }, "/apis/v1/social/analytics/instagram/demographics": { "get": { "description": "Analytics. 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.\n\nReturns audience demographic insights for an Instagram account, broken down by age, city, country, and/or gender.\nRequires at least 100 followers. Returns top 45 entries per dimension.\nData may be delayed up to 48 hours.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_instagra_9a7f5f", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "\"follower_demographics\" for follower audience data, or \"engaged_audience_demographics\" for engaged viewers.", "in": "query", "name": "metric", "required": false, "schema": { "default": "follower_demographics", "enum": [ "follower_demographics", "engaged_audience_demographics" ], "type": "string" } }, { "description": "Comma-separated list of demographic dimensions: age, city, country, gender.\nDefaults to all four if omitted.", "in": "query", "name": "breakdown", "required": false, "schema": { "type": "string" } }, { "description": "Time period for demographic data. Defaults to \"this_month\".", "in": "query", "name": "timeframe", "required": false, "schema": { "default": "this_month", "enum": [ "this_week", "this_month" ], "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" }, "demographics": { "additionalProperties": { "items": { "properties": { "dimension": { "description": "The dimension value (e.g., \"25-34\", \"US\", \"M\")", "type": "string" }, "value": { "description": "Count of accounts in this dimension", "type": "number" } }, "type": "object" }, "type": "array" }, "description": "Object keyed by breakdown dimension (age, city, country, gender)", "type": "object" }, "metric": { "enum": [ "follower_demographics", "engaged_audience_demographics" ], "type": "string" }, "note": { "type": "string" }, "platform": { "type": "string" }, "success": { "type": "boolean" }, "timeframe": { "description": "The timeframe used for demographic data", "enum": [ "this_week", "this_month" ], "type": "string" } }, "type": "object" } } }, "description": "Demographic insights data" }, "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." } }, "summary": "Get Instagram demographics", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.get_instagram_demographics@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "f8d70fea6a04f3cb87ff9f9b6e505972e7c6bcf036e4f82abfeb8c7d40aae28f" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_instagra_9a7f5f", "method": "GET", "path": "/apis/v1/social/analytics/instagram/demographics" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_instagra_9a7f5f" } }, "/apis/v1/social/analytics/instagram/follower-history": { "get": { "description": "Analytics. 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.\n\nReturns a daily running Instagram follower count time series, served from AIsa's\ncross-platform daily snapshotter. Exists because Meta removed follower_count from\nthe /insights endpoint in Graph API v22+ and never exposed a historical daily series\nvia any public API.\n\nResponse envelope matches /apis/v1/social/analytics/instagram/account-insights so the same client\nhandling works. Max 89 days, defaults to last 30 days.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_instagra_bbeb41", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Comma-separated list. Defaults to \"follower_count,followers_gained,followers_lost\".\n - follower_count : per-day raw follower count\n - followers_gained : sum of positive daily deltas\n - followers_lost : sum of absolute negative daily deltas", "in": "query", "name": "metrics", "required": false, "schema": { "type": "string" } }, { "description": "Start date (YYYY-MM-DD). Defaults to 30 days ago.", "in": "query", "name": "fromDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "End date (YYYY-MM-DD). Defaults to today.", "in": "query", "name": "toDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Alias of fromDate, kept for existing callers", "in": "query", "name": "since", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Alias of toDate, kept for existing callers", "in": "query", "name": "until", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "\"total_value\" returns aggregated totals (latest for follower_count, sum for gained/lost).\n\"time_series\" returns per-day values in the \"values\" array.", "in": "query", "name": "metricType", "required": false, "schema": { "default": "total_value", "enum": [ "time_series", "total_value" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Shared account-insights response envelope used by every platform-level\nanalytics endpoint (/apis/v1/social/analytics/{facebook|instagram|youtube|linkedin|tiktok}/*).\nThe name is historical - the shape was first shipped for Instagram and every\nnew platform endpoint reuses it for response-shape consistency. The platform\nfield echoes back which platform served the response.", "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "breakdown": { "description": "Breakdown dimension used (only present when breakdown was requested)", "type": "string" }, "dataDelay": { "type": "string" }, "dateRange": { "properties": { "since": { "format": "date", "type": "string" }, "until": { "format": "date", "type": "string" } }, "type": "object" }, "metricType": { "enum": [ "time_series", "total_value" ], "type": "string" }, "metrics": { "additionalProperties": { "properties": { "breakdowns": { "description": "Breakdown values (only for total_value with breakdown)", "items": { "properties": { "dimension": { "type": "string" }, "value": { "type": "number" } }, "type": "object" }, "type": "array" }, "currency": { "description": "ISO 4217 currency of a monetary metric, or null when the platform omitted it.\nAlways null on monetization_approximate_earnings, which Meta returns as a bare number\nwith no currency; always present on content_monetization_earnings.", "type": [ "string", "null" ] }, "total": { "description": "Sum or aggregate value for the metric", "type": "number" }, "unit": { "description": "Present on monetary metrics only. The scale of \"total\" and of every \"values[].value\", exactly as the platform returned them.\n\n- \"micro_amount\": the platform returned an object carrying a micro amount; values are that integer, summed, unconverted. AIsa publishes no divisor because Meta documents none: divide by the scale you verified against the Page's own Meta Business Suite export. On Facebook Page insights this is always content_monetization_earnings.\n- \"unspecified\": the platform returned a bare number with no unit metadata, passed through as-is; the platform does not state whether it is major or minor currency units. On Facebook Page insights this is always monetization_approximate_earnings.", "enum": [ "micro_amount", "unspecified" ], "type": "string" }, "values": { "description": "Daily values (for time_series, and always on monetary metrics)", "items": { "properties": { "date": { "format": "date", "type": "string" }, "value": { "type": "number" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "description": "Object keyed by metric name.\n\n- For time_series: each metric has \"total\" (number) and \"values\" (array of {date, value}).\n- For total_value: each metric has \"total\" (number) and optionally \"breakdowns\" (array of {dimension, value}).\n\n**Monetary metrics** also carry \"unit\" and \"currency\". AIsa never rescales money: \"total\" and every \"values[].value\" are the platform's raw numbers in the stated unit.\n\nMonetary metrics keep \"values\" even on metricType=total_value, because their \"total\" is the sum of the daily buckets the platform returned over the range. Keep the series to reconcile that sum against the platform's own reporting before invoicing on it.\n\nA metric that could not be served is absent from this object and listed in \"unavailableMetrics\" instead, so an unavailable metric is never reported as a zero.", "type": "object" }, "platform": { "description": "Platform that served this response.", "enum": [ "facebook", "instagram", "youtube", "linkedin", "tiktok" ], "type": "string" }, "success": { "type": "boolean" }, "unavailableMetrics": { "description": "Requested metrics that could not be served. Present only when at least one metric is unavailable, absent otherwise.\n\nEach listed metric is OMITTED from \"metrics\" rather than reported as 0, which is how an unavailable metric is distinguished from a genuine zero. The request itself still succeeds with HTTP 200.", "items": { "properties": { "message": { "description": "Platform-provided explanation when available (access tokens redacted), otherwise AIsa copy.", "type": "string" }, "metric": { "description": "The requested metric name.", "type": "string" }, "reason": { "description": "Why the metric is unavailable:\n\n- \"not_enrolled\": the account is not enrolled in the program behind this metric.\n- \"permission_missing\": the connected user lacks access to this metric.\n- \"unsupported_metric\": the platform does not accept this metric name on the API version AIsa uses.\n- \"no_data\": the platform returned no bucket for this metric over the requested range.\n- \"unreadable_value\": the platform returned a value shape AIsa cannot read, so no total is reported.\n- \"mixed_currency\": readable values disagree on currency or unit within the range.\n- \"upstream_error\": any other platform failure.\n\n\"no_data\" is the common case in practice. The others are defensive: \"not_enrolled\" and \"unsupported_metric\" in particular have not been observed on live Facebook traffic, since a non-enrolled Page returns zeros rather than an error and metric names are validated before any platform call.", "enum": [ "not_enrolled", "permission_missing", "unsupported_metric", "no_data", "unreadable_value", "mixed_currency", "upstream_error" ], "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Follower history data" }, "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." } }, "summary": "Get Instagram follower history", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.get_instagram_follower_history@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "51be5f2fa6a8ba2325fba03ad30af139f1d0475d927583c43426b64de9a217ca" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_instagra_bbeb41", "method": "GET", "path": "/apis/v1/social/analytics/instagram/follower-history" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_instagra_bbeb41" } }, "/apis/v1/social/analytics/instagram/online-followers": { "get": { "description": "Analytics. 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.\n\nReturns how many of an Instagram account's followers were online in each hour, for every day of the last 30 days that Meta has data for.\n\n- Hour keys are \"0\" to \"23\" as Meta returns them. Meta does not document the timezone of the hour keys.\n- endTime is the end_time Meta returns for that day.\n- Data is delayed up to 48 hours, so the most recent days are left out until Meta fills them.\n- Requires at least 100 followers; for smaller accounts days is empty.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_instagra_9b06ed", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "query", "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" }, "days": { "description": "Oldest first, as Meta returns them. Days Meta still reports as empty are left out.", "items": { "properties": { "endTime": { "description": "The end_time Meta returns for this day.", "type": "string" }, "hours": { "additionalProperties": { "type": "integer" }, "description": "Followers online per hour, keyed \"0\" to \"23\".", "type": "object" } }, "type": "object" }, "type": "array" }, "metric": { "enum": [ "online_followers" ], "type": "string" }, "note": { "type": "string" }, "platform": { "enum": [ "instagram" ], "type": "string" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Followers online per hour, one entry per day with data" }, "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." } }, "summary": "Get Instagram online followers", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.get_instagram_online_followers@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "8fed6d8cde1d779c8cd07f9338c510d47239da8fd5c0c7bbb0d7be7f70a2ccf7" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_instagra_9b06ed", "method": "GET", "path": "/apis/v1/social/analytics/instagram/online-followers" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_instagra_9b06ed" } }, "/apis/v1/social/analytics/linkedin/demographics": { "get": { "description": "Analytics. 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.\n\nReturns the lifetime follower breakdown of a connected LinkedIn organization page by job function, seniority, industry, company size, country and region. Without `breakdown` it returns function, seniority, industry and company size; country and region are returned only when requested.\n\n### Labels\n\n- Function, seniority and industry are labelled with LinkedIn's standardized names (English) and keep the LinkedIn URN in `id`.\n- Company size is labelled as a range such as `2-10` or `10001+`.\n- Country and region are labelled with LinkedIn's geo names (English) and keep `urn:li:geo:*` in `id`. A region is a LinkedIn market area, for example New York City Metropolitan Area.\n\nLinkedIn returns at most the top 100 values per breakdown and leaves out followers whose profile lacks that field, so a breakdown does not add up to the follower count.\n\n### Requirements\n\n- Organization accounts only: a personal LinkedIn account answers 400 `personal_account_not_supported`.\n- Requires the r_organization_social, r_organization_followers and r_organization_admin scopes (412 otherwise).\n- Requires the Analytics add-on.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_linkedin_3de12b", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Comma-separated list of demographic dimensions: function, seniority, industry, company_size, country, region.\nDefaults to function, seniority, industry and company_size if omitted. Country and region are returned only when requested.", "in": "query", "name": "breakdown", "required": false, "schema": { "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" }, "demographics": { "additionalProperties": { "items": { "properties": { "dimension": { "description": "Readable label, or the LinkedIn URN when LinkedIn returns no name for it", "type": "string" }, "id": { "description": "LinkedIn URN (urn:li:function:8 or urn:li:geo:103644278) or staff count range (SIZE_2_TO_10)", "type": "string" }, "value": { "description": "Followers (organic plus paid)", "type": "integer" } }, "type": "object" }, "type": "array" }, "description": "Only the requested breakdowns are present. Entries are sorted by value, largest first.", "type": "object" }, "metric": { "enum": [ "follower_demographics" ], "type": "string" }, "note": { "type": "string" }, "platform": { "enum": [ "linkedin" ], "type": "string" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Follower demographics for the organization page" }, "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." } }, "summary": "Get LinkedIn organization follower demographics", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.get_linked_in_demographics@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "39c355e5227706cbb92889b59197a0597cf4c0cb5285f0dd218029cf9aab5803" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_linkedin_3de12b", "method": "GET", "path": "/apis/v1/social/analytics/linkedin/demographics" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_linkedin_3de12b" } }, "/apis/v1/social/analytics/linkedin/org-aggregate-analytics": { "get": { "description": "Analytics. 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.\n\nReturns aggregate analytics for a LinkedIn organization page. Parallel to\n/apis/v1/social/accounts/{id}/linkedin-aggregate-analytics (which handles personal accounts only).\nBacked by LinkedIn's organizationalEntityShareStatistics,\norganizationalEntityFollowerStatistics, and organizationPageStatistics endpoints.\n\nResponse shape matches /apis/v1/social/analytics/instagram/account-insights. Max 89 days,\ndefaults to last 30 days.\n\nScope requirements: r_organization_social, r_organization_followers, and\nr_organization_admin must all be present on the account. Accounts connected before\nthese scopes were included in the OAuth flow will return 412 with a reauth hint.\n\nEnforced by this endpoint:\n - Page-view metrics accept only metricType=total_value (LinkedIn omits per-day\n segmentation even when the API is called with DAY granularity, so a time-series\n response would be meaningless).\n - Date range capped at 89 days.\n\nLinkedIn-side platform limits (not re-enforced here, but worth knowing for larger\nranges in a future release):\n - Follower stats: rolling 12-month window, end must be no later than 2 days ago.\n - Share stats: rolling 12-month window.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_linkedin_5a3e98", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Comma-separated list. Defaults to\n\"impressions,clicks,engagement_rate,organic_followers_gained,followers_gained,followers_lost\".\n\nShare statistics (support both total_value and time_series):\n - impressions\n - unique_impressions\n - clicks\n - likes\n - comments\n - shares\n - engagement_rate (0..1, LinkedIn-computed)\n\nFollower-gain statistics (support total_value and time_series):\n - organic_followers_gained (per-day organic gains for time_series; sum of organic gains over the range for total_value)\n - paid_followers_gained (per-day paid gains for time_series; sum of paid gains over the range for total_value)\n\nPage-view statistics (total_value ONLY - LinkedIn platform limit):\n - page_views_total\n - page_views_overview\n - page_views_careers\n - page_views_jobs\n - page_views_life\n\nAIsa-synthesized from daily follower snapshots:\n - followers_gained\n - followers_lost", "in": "query", "name": "metrics", "required": false, "schema": { "type": "string" } }, { "description": "Start date (YYYY-MM-DD). Defaults to 30 days ago.", "in": "query", "name": "fromDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "End date (YYYY-MM-DD). Defaults to today.", "in": "query", "name": "toDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Alias of fromDate, kept for existing callers", "in": "query", "name": "since", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Alias of toDate, kept for existing callers", "in": "query", "name": "until", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "metricType", "required": false, "schema": { "default": "total_value", "enum": [ "time_series", "total_value" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Shared account-insights response envelope used by every platform-level\nanalytics endpoint (/apis/v1/social/analytics/{facebook|instagram|youtube|linkedin|tiktok}/*).\nThe name is historical - the shape was first shipped for Instagram and every\nnew platform endpoint reuses it for response-shape consistency. The platform\nfield echoes back which platform served the response.", "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "breakdown": { "description": "Breakdown dimension used (only present when breakdown was requested)", "type": "string" }, "dataDelay": { "type": "string" }, "dateRange": { "properties": { "since": { "format": "date", "type": "string" }, "until": { "format": "date", "type": "string" } }, "type": "object" }, "metricType": { "enum": [ "time_series", "total_value" ], "type": "string" }, "metrics": { "additionalProperties": { "properties": { "breakdowns": { "description": "Breakdown values (only for total_value with breakdown)", "items": { "properties": { "dimension": { "type": "string" }, "value": { "type": "number" } }, "type": "object" }, "type": "array" }, "currency": { "description": "ISO 4217 currency of a monetary metric, or null when the platform omitted it.\nAlways null on monetization_approximate_earnings, which Meta returns as a bare number\nwith no currency; always present on content_monetization_earnings.", "type": [ "string", "null" ] }, "total": { "description": "Sum or aggregate value for the metric", "type": "number" }, "unit": { "description": "Present on monetary metrics only. The scale of \"total\" and of every \"values[].value\", exactly as the platform returned them.\n\n- \"micro_amount\": the platform returned an object carrying a micro amount; values are that integer, summed, unconverted. AIsa publishes no divisor because Meta documents none: divide by the scale you verified against the Page's own Meta Business Suite export. On Facebook Page insights this is always content_monetization_earnings.\n- \"unspecified\": the platform returned a bare number with no unit metadata, passed through as-is; the platform does not state whether it is major or minor currency units. On Facebook Page insights this is always monetization_approximate_earnings.", "enum": [ "micro_amount", "unspecified" ], "type": "string" }, "values": { "description": "Daily values (for time_series, and always on monetary metrics)", "items": { "properties": { "date": { "format": "date", "type": "string" }, "value": { "type": "number" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "description": "Object keyed by metric name.\n\n- For time_series: each metric has \"total\" (number) and \"values\" (array of {date, value}).\n- For total_value: each metric has \"total\" (number) and optionally \"breakdowns\" (array of {dimension, value}).\n\n**Monetary metrics** also carry \"unit\" and \"currency\". AIsa never rescales money: \"total\" and every \"values[].value\" are the platform's raw numbers in the stated unit.\n\nMonetary metrics keep \"values\" even on metricType=total_value, because their \"total\" is the sum of the daily buckets the platform returned over the range. Keep the series to reconcile that sum against the platform's own reporting before invoicing on it.\n\nA metric that could not be served is absent from this object and listed in \"unavailableMetrics\" instead, so an unavailable metric is never reported as a zero.", "type": "object" }, "platform": { "description": "Platform that served this response.", "enum": [ "facebook", "instagram", "youtube", "linkedin", "tiktok" ], "type": "string" }, "success": { "type": "boolean" }, "unavailableMetrics": { "description": "Requested metrics that could not be served. Present only when at least one metric is unavailable, absent otherwise.\n\nEach listed metric is OMITTED from \"metrics\" rather than reported as 0, which is how an unavailable metric is distinguished from a genuine zero. The request itself still succeeds with HTTP 200.", "items": { "properties": { "message": { "description": "Platform-provided explanation when available (access tokens redacted), otherwise AIsa copy.", "type": "string" }, "metric": { "description": "The requested metric name.", "type": "string" }, "reason": { "description": "Why the metric is unavailable:\n\n- \"not_enrolled\": the account is not enrolled in the program behind this metric.\n- \"permission_missing\": the connected user lacks access to this metric.\n- \"unsupported_metric\": the platform does not accept this metric name on the API version AIsa uses.\n- \"no_data\": the platform returned no bucket for this metric over the requested range.\n- \"unreadable_value\": the platform returned a value shape AIsa cannot read, so no total is reported.\n- \"mixed_currency\": readable values disagree on currency or unit within the range.\n- \"upstream_error\": any other platform failure.\n\n\"no_data\" is the common case in practice. The others are defensive: \"not_enrolled\" and \"unsupported_metric\" in particular have not been observed on live Facebook traffic, since a non-enrolled Page returns zeros rather than an error and metric names are validated before any platform call.", "enum": [ "not_enrolled", "permission_missing", "unsupported_metric", "no_data", "unreadable_value", "mixed_currency", "upstream_error" ], "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Organization analytics data" }, "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." } }, "summary": "Get LinkedIn org analytics", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.get_linked_in_org_aggregate_analytics@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "461a08729388a339f55456da08f3077a512763c09494d92eb59b4a68b4f942ac" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_linkedin_5a3e98", "method": "GET", "path": "/apis/v1/social/analytics/linkedin/org-aggregate-analytics" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_linkedin_5a3e98" } }, "/apis/v1/social/analytics/post-timeline": { "get": { "description": "Analytics. 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.\n\nReturns a daily timeline of analytics metrics for a specific post, showing how impressions, likes,\nand other metrics evolved day-by-day since publishing. Each row represents one day of data per platform.\nFor multi-platform AIsa posts, returns separate rows for each platform.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_post_timeline", "parameters": [ { "description": "The post to fetch timeline for. Accepts an ExternalPost ID, a platformPostId, or a AIsa Post ID.", "in": "query", "name": "postId", "required": true, "schema": { "type": "string" } }, { "description": "Start of date range (ISO 8601). Defaults to 90 days ago.", "in": "query", "name": "fromDate", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "End of date range (ISO 8601). Defaults to now.", "in": "query", "name": "toDate", "required": false, "schema": { "format": "date-time", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "postId": { "description": "The postId that was requested", "type": "string" }, "timeline": { "items": { "properties": { "audienceCountries": { "additionalProperties": { "type": "number" }, "description": "TikTok business lane: viewer-country shares on this date keyed by ISO-3166 alpha-2, fractions 0 to 1, top 20 with the tail in `other`; empty object elsewhere", "type": "object" }, "audienceTypes": { "additionalProperties": { "type": "number" }, "description": "TikTok business lane: follower / nonFollower and newViewer / returnViewer shares on this date, fractions 0 to 1; empty object elsewhere", "type": "object" }, "clicks": { "description": "Total clicks on this date", "type": "integer" }, "comments": { "description": "Total comments on this date", "type": "integer" }, "completionRate": { "description": "TikTok business lane: share of viewers who watched to the end on this date, 0 to 1; 0 elsewhere", "type": "number" }, "date": { "description": "Date in YYYY-MM-DD format", "format": "date", "type": "string" }, "follows": { "description": "Follows attributed to the post on this date (Instagram feed and stories, Facebook Reels, TikTok business lane). Null on Instagram Reels and video and on Facebook posts that are not Reels, where Meta has no follows metric; 0 on other platforms.", "type": [ "integer", "null" ] }, "impressionSources": { "additionalProperties": { "type": "number" }, "description": "TikTok business lane: share of views by surface on this date (forYou, follow, search, personalProfile, sound, directMessage, other), fractions 0 to 1; empty object elsewhere", "type": "object" }, "impressions": { "description": "Total impressions on this date", "type": "integer" }, "likes": { "description": "Total likes on this date", "type": "integer" }, "platform": { "description": "Platform name (e.g. instagram, tiktok)", "type": "string" }, "platformPostId": { "description": "Platform-specific post ID", "type": "string" }, "profileViews": { "description": "Instagram feed posts (images and carousels; 0 on Reels and Stories) and TikTok business lane: profile views attributed to the post on this date; 0 elsewhere", "type": "integer" }, "reach": { "description": "Total reach on this date", "type": "integer" }, "replays": { "description": "Facebook Reels only: plays that were replays, as of this date; 0 elsewhere", "type": "integer" }, "retentionCurve": { "additionalProperties": { "type": "number" }, "description": "Share of viewers still watching at each second of playback, as fractions 0 to 1. Filled for Facebook Reels and the TikTok business lane; empty object for other media and platforms. Values are as of this date.\n\n**Facebook Reels** (Meta post_video_retention_graph):\n\n- The base is a subset of plays that Meta selects and does not expose. On small Reels it can be far below views (6 of 51 measured), so a value is a share of that subset, not of all plays.\n- Keys are whole seconds from the start of a play (\"3\" is the share still watching at 3 s).\n- Loops count as continued playback, so a short Reels curve runs past its length (an 8 s Reel has keys \"0\" to \"12\").\n- Meta returns at most 41 points, so a long Reel covers only its first 40 s.\n\n**TikTok** accounts connected through the TikTok for Business app: from TikTok video_view_retention, at each whole second, at most 61 points, thinned evenly on videos longer than 60 s.", "type": "object" }, "saves": { "description": "Total saves on this date", "type": "integer" }, "shares": { "description": "Total shares on this date", "type": "integer" }, "views": { "description": "Total views on this date", "type": "integer" }, "websiteClicks": { "description": "TikTok business lane: website-link clicks attributed to the post on this date (also inside clicks); 0 elsewhere", "type": "integer" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Daily analytics timeline" }, "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." } }, "summary": "Get post analytics timeline", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.get_post_timeline@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "697af7de0676e49a445bf4a0fcc7d953ae7cb0df2353d7f6acee7ee4ea06dc3e" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_post_timeline", "method": "GET", "path": "/apis/v1/social/analytics/post-timeline" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_post_timeline" } }, "/apis/v1/social/analytics/posting-frequency": { "get": { "description": "Analytics. 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. Without profileId or accountId it reads your default profile.\n\nReturns the correlation between posting frequency (posts per week) and engagement rate, broken down by platform.\nHelps find the optimal posting cadence for each platform. Each row represents a specific (platform, posts_per_week) combination\nwith the average engagement rate observed across all weeks matching that frequency.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_posting__c7be20", "parameters": [ { "description": "Filter by platform (e.g. \"instagram\", \"tiktok\"). Omit for all platforms.", "in": "query", "name": "platform", "required": false, "schema": { "type": "string" } }, { "description": "One of your profiles (prf_...). Defaults to your default profile when neither profileId nor accountId is sent.", "in": "query", "name": "profileId", "required": false, "schema": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": false, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Filter by post origin. \"late\" for posts published via AIsa, \"external\" for posts imported from platforms.", "in": "query", "name": "source", "required": false, "schema": { "default": "all", "enum": [ "all", "late", "external" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "frequency": { "items": { "properties": { "avg_engagement": { "description": "Average raw engagement (likes+comments+shares+saves)", "type": "number" }, "avg_engagement_rate": { "description": "Average engagement rate as percentage (0-100)", "type": "number" }, "platform": { "type": "string" }, "posts_per_week": { "description": "Number of posts published that week", "type": "integer" }, "weeks_count": { "description": "Number of calendar weeks observed at this frequency", "type": "integer" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Posting frequency data" }, "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." } }, "summary": "Get frequency vs engagement", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.get_posting_frequency@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "bdeba34a740d55e3f90b62bded4534147d14650ef93d84533442fc5522d43381" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_posting__c7be20", "method": "GET", "path": "/apis/v1/social/analytics/posting-frequency" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_posting__c7be20" } }, "/apis/v1/social/analytics/posts": { "get": { "description": "Analytics. 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. Without profileId or accountId it reads your default profile.\n\nReturns analytics for posts. With postId, returns a single post. Without it, returns a paginated list with overview stats.\n\n- Accepts both AIsa Post IDs and External Post IDs (auto-resolved).\n- fromDate defaults to 90 days ago if omitted, max range 366 days.\n- Single post lookups may return 202 (sync pending) or 424 (all platforms failed).\n- For follower stats, use /apis/v1/social/accounts/follower-stats.\n\n### LinkedIn personal accounts\n\nAnalytics are only available for posts published through AIsa. LinkedIn's API only returns metrics for posts authored by the authenticated user. Organization/company page analytics work for all posts.\n\n### Facebook Page stories\n\nStories on a connected Page, published through AIsa or natively, are collected while they are live and returned like any other post (platformPostUrl points to the story). Metrics for a story published through AIsa are available on its AIsa post ID.\n\nTheir lifetime metrics refresh about hourly, with a final reading shortly before the story expires at 24 hours. After that the values stay at that last reading.\n\nMapping:\n\n- impressions = story media views (Meta stopped accepting per-story impressions in October 2026, so impressions equals views)\n- reach = unique story media viewers\n- views = story media views\n- likes = story reactions\n- comments = story replies\n- shares = story shares\n- clicks: always 0, because Meta exposes no link-click metric for stories\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_posts", "parameters": [ { "description": "Returns analytics for a single post. Accepts AIsa Post IDs, External Post IDs and the platform's native post ID. AIsa IDs are auto-resolved to External Post analytics.", "in": "query", "name": "postId", "required": false, "schema": { "type": "string" } }, { "description": "Filter by platform (default \"all\")", "in": "query", "name": "platform", "required": false, "schema": { "type": "string" } }, { "description": "One of your profiles (prf_...). Defaults to your default profile when neither profileId nor accountId is sent.", "in": "query", "name": "profileId", "required": false, "schema": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": false, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Filter by post source: late (posted via AIsa API), external (synced from platform), all (default)", "in": "query", "name": "source", "required": false, "schema": { "default": "all", "enum": [ "all", "late", "external" ], "type": "string" } }, { "description": "Inclusive lower bound (YYYY-MM-DD). Defaults to 90 days ago if omitted. Max range is 366 days.", "in": "query", "name": "fromDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Inclusive upper bound (YYYY-MM-DD). Defaults to today if omitted.", "in": "query", "name": "toDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Page size (default 50)", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Page number (default 1)", "in": "query", "name": "page", "required": false, "schema": { "default": 1, "minimum": 1, "type": "integer" } }, { "description": "Sort by date, engagement, or a specific metric. Platform-specific metrics (follows, reposts, reels_skip_rate, ig_reels_*, completion_rate, profile_views, website_clicks) sort a null value as 0.", "in": "query", "name": "sortBy", "required": false, "schema": { "default": "date", "enum": [ "date", "engagement", "impressions", "reach", "likes", "comments", "shares", "saves", "clicks", "views", "follows", "ig_reels_avg_watch_time", "ig_reels_video_view_total_time", "reposts", "reels_skip_rate", "completion_rate", "profile_views", "website_clicks" ], "type": "string" } }, { "description": "Sort order", "in": "query", "name": "order", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Comma-separated tags (at most 20). Lists only posts created through AIsa that carry every listed tag, matched exactly and case-sensitively. Up to 200 published posts can match within the date range; more returns 400 asking to narrow fromDate and toDate. Ignored when postId is set.", "in": "query", "name": "tags", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "properties": { "analytics": { "properties": { "audienceCountries": { "additionalProperties": { "type": "number" }, "description": "TikTok accounts connected through the TikTok for Business app only: share of views by viewer country, as fractions 0 to 1, keyed by upper-case ISO-3166 alpha-2 code. Available T+24-48h, only for posts active in the last 7 days.\n\nAt most 20 country keys plus `other`. The catch-all bucket TikTok sends, any country below 0.001 and anything past the twentieth all sum into `other`, so the values still add up to 1.\n\nEmpty object when TikTok reports nothing, and for other platforms. Views-weighted across accounts like impressionSources.", "type": "object" }, "audienceTypes": { "additionalProperties": { "type": "number" }, "description": "TikTok accounts connected through the TikTok for Business app only: two viewer splits as fractions 0 to 1 (T+24-48h).\n\n- Each pair sums to 1 when present: `follower` + `nonFollower`, and `newViewer` + `returnViewer`. TikTok can report one pair without the other.\n- Empty object when TikTok reports nothing, and for other platforms.\n- Views-weighted across accounts, like impressionSources.", "type": "object" }, "clicks": { "description": "Link clicks where the platform reports them. Always 0 on Facebook Page stories: Meta exposes no link-click metric for stories.", "type": "integer" }, "comments": { "type": "integer" }, "completionRate": { "description": "Share of viewers who watched the video to the end, 0 to 1, as TikTok reports it. Only for TikTok accounts connected through the TikTok for Business app.\n\n- Delayed T+24-48h, and only for posts active in the last 7 days.\n- 0 for other platforms.\n- For a post published to several accounts, the aggregate is weighted by views.", "type": "number" }, "engagementRate": { "description": "Percentage, rounded to 2 decimals: (likes + comments + shares + saves) / (impressions or reach or views) * 100. Clicks and follows are never counted.\n\nThe denominator is the FIRST of impressions, reach, views that is non-zero, so the basis varies by post: impressions if present, else reach, else views. For a single consistent basis (e.g. interactions / reach), compute it from the raw fields above.\n\nOn the post-level roll-up of a cross-posted post, the denominator is the SUM of the denominators resolved per platform entry. An entry reporting none of impressions, reach or views is excluded from both sides of the ratio. Each platformAnalytics entry below keeps its own single denominator.\n\nThe engagementRate on the LinkedIn account endpoints uses a different formula.", "type": "number" }, "follows": { "description": "Accounts that started following from this post.\n\n- Reported for Instagram feed posts and stories (organic follows), Facebook Reels (Meta post_video_followers) and the TikTok business lane.\n- Null on Instagram Reels and non-Reels video, and on Facebook posts that are not Reels, where Meta does not expose this metric for the media.\n- 0 for other platforms.", "type": [ "integer", "null" ] }, "igReelsAvgWatchTime": { "description": "Average watch time per play, in milliseconds, for Instagram Reels, Facebook Reels and TikTok videos (business accounts). On Facebook it includes replays within a play, so it can exceed the Reel length. 0 for other media and platforms, including regular Facebook videos.", "type": "integer" }, "igReelsVideoViewTotalTime": { "description": "Total watch time including replays, in milliseconds, for Instagram Reels, Facebook Reels and TikTok videos (business accounts). 0 for other media and platforms, including regular Facebook videos.", "type": "integer" }, "impressionSources": { "additionalProperties": { "type": "number" }, "description": "Share of views by surface, as fractions 0 to 1. Only for TikTok accounts connected through the TikTok for Business app (T+24-48h, only for posts active in the last 7 days).\n\n- Keys: `forYou`, `follow`, `search`, `personalProfile`, `sound`, `directMessage`, `other`. A surface TikTok adds later appears under a camelCase key derived from its name.\n- Empty object when TikTok reports nothing, and for other platforms.\n- When a post is published to several accounts, each share is weighted by views.", "type": "object" }, "impressions": { "type": "integer" }, "lastUpdated": { "format": "date-time", "type": "string" }, "likes": { "type": "integer" }, "profileViews": { "description": "Instagram feed posts (images and carousels; 0 on Reels and Stories) and TikTok accounts connected through the TikTok for Business app: profile views from users who reached the profile through this post (TikTok T+24-48h). 0 for other platforms.", "type": "integer" }, "reach": { "type": "integer" }, "reelsSkipRate": { "description": "Instagram Reels only: percentage (0-100) of initial views that skipped the reel within its first 3 seconds, as reported by Meta.\n\n- Meta labels the metric estimated and in development, so it can move between syncs.\n- 0 for non-Reels media and other platforms.\n- For a post published to several accounts, the aggregate is weighted by views.", "type": "number" }, "replays": { "description": "Facebook Reels only: plays that were replays (Meta fb_reels_replay_count). Summed across accounts. 0 for other media and platforms.", "type": "integer" }, "reposts": { "description": "Reposts of the media by other users, minus deleted reposts, on feed posts, reels and stories. Instagram accounts connected with Facebook Login only.\n\n- Instagram Login accounts: always 0 (Meta does not expose this metric for them).\n- Other platforms: 0, including Threads, where reposts are counted in shares instead.", "type": "integer" }, "retentionCurve": { "additionalProperties": { "type": "number" }, "description": "Facebook Reels and TikTok business lane: share of viewers still watching at each second of playback, as fractions 0 to 1. Keys are whole seconds from the start of a play (\"3\" is the share still watching at 3 s). Empty object for other media and platforms.\n\n- Facebook Reels (Meta post_video_retention_graph): the base is a subset of plays that Meta selects and does not expose. On small Reels it can be far below views (6 of 51 measured), so a value is a share of that subset, not of all plays.\n- Facebook Reels length: loops count as continued playback, so a short Reel's curve runs past its length (an 8 s Reel has keys \"0\" to \"12\"). Meta returns at most 41 points, so a long Reel covers only its first 40 s.\n- TikTok accounts connected through the TikTok for Business app (TikTok video_view_retention): one point per whole second, at most 61 points, thinned evenly on videos longer than 60 s.\n\nOn a cross-posted post this is the curve of the account with the most views among those reporting one, never a blend: curves from different platforms and accounts measure different audiences and different seconds. Each platformAnalytics entry keeps its own curve.", "type": "object" }, "saves": { "description": "Number of saves/bookmarks (Instagram, Pinterest, X)", "type": "integer" }, "shares": { "type": "integer" }, "videoDurationSeconds": { "description": "Video length in seconds. Null when unknown: platforms that do not report a length, non-video media, or when Instagram does not expose the media URL (e.g. reels with copyrighted audio).\n\n- YouTube: filled for public videos once their analytics next refresh (from the Data API; live streams may report null). The Data API has no Shorts flag: a video over 180 seconds cannot be a Short, but a shorter one may be a regular upload.\n- Instagram Reels: also filled. Combine with igReelsAvgWatchTime (ms) to estimate retention.", "type": [ "integer", "null" ] }, "views": { "type": "integer" }, "websiteClicks": { "description": "TikTok accounts connected through the TikTok for Business app only: clicks on the profile website link attributed to this post (T+24-48h). Also counted inside `clicks`, which sums every profile-link type (website, phone, email, address, app download). 0 for other platforms.", "type": "integer" } }, "type": "object" }, "content": { "type": "string" }, "isAiGenerated": { "description": "Instagram only: whether Instagram labeled the media as AI-generated. Absent when the platform did not report it.", "type": "boolean" }, "isExternal": { "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" }, "latePostId": { "description": "Original AIsa post ID if scheduled via AIsa", "type": [ "string", "null" ] }, "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": "All media items for this post. Carousel posts have one entry per slide.\n\n- Facebook and Instagram images and video covers whose Meta CDN links expired are re-read and served from AIsa storage (non-expiring).\n- Facebook and Instagram video file URLs, and LinkedIn media URLs, stay the platform's signed links and are refreshed on read once they lapse.", "items": { "properties": { "altText": { "description": "Accessibility alt text set on the media, when present.", "type": "string" }, "mediaStatus": { "description": "unavailable means the media file could not be retrieved (url is null or, for LinkedIn videos, a cover image standing in for the file). available or absent means the file is available at url (older synced items omit the field).", "enum": [ "available", "unavailable" ], "type": "string" }, "thumbnail": { "description": "Thumbnail URL (same as url for images). Still present when url is null.", "format": "uri", "type": [ "string", "null" ] }, "type": { "enum": [ "image", "video" ], "type": "string" }, "unavailableReason": { "description": "Why the file is missing. platform_withheld means the platform declined to return it and retrying will not help.", "enum": [ "platform_withheld" ], "type": "string" }, "url": { "description": "'Direct URL to the media file. Null when the platform withholds it: check mediaStatus before downloading. Instagram omits the video file for Reels it flags as containing copyrighted material (its docs name audio as the usual cause), so type stays \"video\" while the file is permanently unreachable.'", "format": "uri", "type": [ "string", "null" ] } }, "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": { "enum": [ "image", "video", "carousel", "text" ], "type": [ "string", "null" ] }, "message": { "description": "Human-readable status message for pending, partial, or failed states", "type": [ "string", "null" ] }, "platform": { "type": "string" }, "platformAnalytics": { "items": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "accountUsername": { "type": [ "string", "null" ] }, "analytics": { "anyOf": [ { "properties": { "audienceCountries": { "additionalProperties": { "type": "number" }, "description": "TikTok accounts connected through the TikTok for Business app only: share of views by viewer country, as fractions 0 to 1, keyed by upper-case ISO-3166 alpha-2 code. Available T+24-48h, only for posts active in the last 7 days.\n\nAt most 20 country keys plus `other`. The catch-all bucket TikTok sends, any country below 0.001 and anything past the twentieth all sum into `other`, so the values still add up to 1.\n\nEmpty object when TikTok reports nothing, and for other platforms. Views-weighted across accounts like impressionSources.", "type": "object" }, "audienceTypes": { "additionalProperties": { "type": "number" }, "description": "TikTok accounts connected through the TikTok for Business app only: two viewer splits as fractions 0 to 1 (T+24-48h).\n\n- Each pair sums to 1 when present: `follower` + `nonFollower`, and `newViewer` + `returnViewer`. TikTok can report one pair without the other.\n- Empty object when TikTok reports nothing, and for other platforms.\n- Views-weighted across accounts, like impressionSources.", "type": "object" }, "clicks": { "description": "Link clicks where the platform reports them. Always 0 on Facebook Page stories: Meta exposes no link-click metric for stories.", "type": "integer" }, "comments": { "type": "integer" }, "completionRate": { "description": "Share of viewers who watched the video to the end, 0 to 1, as TikTok reports it. Only for TikTok accounts connected through the TikTok for Business app.\n\n- Delayed T+24-48h, and only for posts active in the last 7 days.\n- 0 for other platforms.\n- For a post published to several accounts, the aggregate is weighted by views.", "type": "number" }, "engagementRate": { "description": "Percentage, rounded to 2 decimals: (likes + comments + shares + saves) / (impressions or reach or views) * 100. Clicks and follows are never counted.\n\nThe denominator is the FIRST of impressions, reach, views that is non-zero, so the basis varies by post: impressions if present, else reach, else views. For a single consistent basis (e.g. interactions / reach), compute it from the raw fields above.\n\nOn the post-level roll-up of a cross-posted post, the denominator is the SUM of the denominators resolved per platform entry. An entry reporting none of impressions, reach or views is excluded from both sides of the ratio. Each platformAnalytics entry below keeps its own single denominator.\n\nThe engagementRate on the LinkedIn account endpoints uses a different formula.", "type": "number" }, "follows": { "description": "Accounts that started following from this post.\n\n- Reported for Instagram feed posts and stories (organic follows), Facebook Reels (Meta post_video_followers) and the TikTok business lane.\n- Null on Instagram Reels and non-Reels video, and on Facebook posts that are not Reels, where Meta does not expose this metric for the media.\n- 0 for other platforms.", "type": [ "integer", "null" ] }, "igReelsAvgWatchTime": { "description": "Average watch time per play, in milliseconds, for Instagram Reels, Facebook Reels and TikTok videos (business accounts). On Facebook it includes replays within a play, so it can exceed the Reel length. 0 for other media and platforms, including regular Facebook videos.", "type": "integer" }, "igReelsVideoViewTotalTime": { "description": "Total watch time including replays, in milliseconds, for Instagram Reels, Facebook Reels and TikTok videos (business accounts). 0 for other media and platforms, including regular Facebook videos.", "type": "integer" }, "impressionSources": { "additionalProperties": { "type": "number" }, "description": "Share of views by surface, as fractions 0 to 1. Only for TikTok accounts connected through the TikTok for Business app (T+24-48h, only for posts active in the last 7 days).\n\n- Keys: `forYou`, `follow`, `search`, `personalProfile`, `sound`, `directMessage`, `other`. A surface TikTok adds later appears under a camelCase key derived from its name.\n- Empty object when TikTok reports nothing, and for other platforms.\n- When a post is published to several accounts, each share is weighted by views.", "type": "object" }, "impressions": { "type": "integer" }, "lastUpdated": { "format": "date-time", "type": "string" }, "likes": { "type": "integer" }, "profileViews": { "description": "Instagram feed posts (images and carousels; 0 on Reels and Stories) and TikTok accounts connected through the TikTok for Business app: profile views from users who reached the profile through this post (TikTok T+24-48h). 0 for other platforms.", "type": "integer" }, "reach": { "type": "integer" }, "reelsSkipRate": { "description": "Instagram Reels only: percentage (0-100) of initial views that skipped the reel within its first 3 seconds, as reported by Meta.\n\n- Meta labels the metric estimated and in development, so it can move between syncs.\n- 0 for non-Reels media and other platforms.\n- For a post published to several accounts, the aggregate is weighted by views.", "type": "number" }, "replays": { "description": "Facebook Reels only: plays that were replays (Meta fb_reels_replay_count). Summed across accounts. 0 for other media and platforms.", "type": "integer" }, "reposts": { "description": "Reposts of the media by other users, minus deleted reposts, on feed posts, reels and stories. Instagram accounts connected with Facebook Login only.\n\n- Instagram Login accounts: always 0 (Meta does not expose this metric for them).\n- Other platforms: 0, including Threads, where reposts are counted in shares instead.", "type": "integer" }, "retentionCurve": { "additionalProperties": { "type": "number" }, "description": "Facebook Reels and TikTok business lane: share of viewers still watching at each second of playback, as fractions 0 to 1. Keys are whole seconds from the start of a play (\"3\" is the share still watching at 3 s). Empty object for other media and platforms.\n\n- Facebook Reels (Meta post_video_retention_graph): the base is a subset of plays that Meta selects and does not expose. On small Reels it can be far below views (6 of 51 measured), so a value is a share of that subset, not of all plays.\n- Facebook Reels length: loops count as continued playback, so a short Reel's curve runs past its length (an 8 s Reel has keys \"0\" to \"12\"). Meta returns at most 41 points, so a long Reel covers only its first 40 s.\n- TikTok accounts connected through the TikTok for Business app (TikTok video_view_retention): one point per whole second, at most 61 points, thinned evenly on videos longer than 60 s.\n\nOn a cross-posted post this is the curve of the account with the most views among those reporting one, never a blend: curves from different platforms and accounts measure different audiences and different seconds. Each platformAnalytics entry keeps its own curve.", "type": "object" }, "saves": { "description": "Number of saves/bookmarks (Instagram, Pinterest, X)", "type": "integer" }, "shares": { "type": "integer" }, "videoDurationSeconds": { "description": "Video length in seconds. Null when unknown: platforms that do not report a length, non-video media, or when Instagram does not expose the media URL (e.g. reels with copyrighted audio).\n\n- YouTube: filled for public videos once their analytics next refresh (from the Data API; live streams may report null). The Data API has no Shorts flag: a video over 180 seconds cannot be a Short, but a shorter one may be a regular upload.\n- Instagram Reels: also filled. Combine with igReelsAvgWatchTime (ms) to estimate retention.", "type": [ "integer", "null" ] }, "views": { "type": "integer" }, "websiteClicks": { "description": "TikTok accounts connected through the TikTok for Business app only: clicks on the profile website link attributed to this post (T+24-48h). Also counted inside `clicks`, which sums every profile-link type (website, phone, email, address, app download). 0 for other platforms.", "type": "integer" } }, "type": "object" }, { "type": "null" } ] }, "errorCode": { "description": "Stable machine-readable reason for errorMessage. New values may be added.\n\n- post_not_found: the post was deleted or is no longer visible to the account.\n- not_post_owner: the post is owned by another Page or user (collab or visitor post); its analytics cannot be read with this Page's token.\n- permission_missing: the last analytics sync of the Facebook account failed because the Page no longer grants pages_read_engagement (pending entries only).\n- null: no stable code; read errorMessage.", "enum": [ "post_not_found", "not_post_owner", "permission_missing", null ], "type": [ "string", "null" ] }, "errorMessage": { "description": "Failure detail:\n\n- Failed entries: why the post failed to publish.\n- Unavailable entries: why analytics cannot be synced (e.g. Google Business Profile, a TikTok upload that never received a video id).\n- Pending entries: the most recent analytics sync error for the account (null while no sync has failed), cleared after the next successful sync.", "type": [ "string", "null" ] }, "isOwner": { "description": "Facebook only: true when the connected Page authored the post, false when Facebook reports another author (a collab post), null when unknown or for other platforms.", "type": [ "boolean", "null" ] }, "platform": { "type": "string" }, "platformPostId": { "description": "The native post ID on the platform (e.g. Instagram media ID, tweet ID)", "type": [ "string", "null" ] }, "platformPostUrl": { "format": "uri", "type": [ "string", "null" ] }, "status": { "enum": [ "published", "failed" ], "type": "string" }, "syncStatus": { "description": "Sync state of analytics for this platform", "enum": [ "synced", "pending", "unavailable" ], "type": "string" } }, "type": "object" }, "type": "array" }, "platformPostUrl": { "format": "uri", "type": [ "string", "null" ] }, "postId": { "type": "string" }, "publishedAt": { "format": "date-time", "type": [ "string", "null" ] }, "scheduledFor": { "format": "date-time", "type": "string" }, "status": { "description": "Overall post status. \"partial\" when some platforms published and others failed.\n\nWhile any platform is still pending or processing, the post's own status is returned instead (usually scheduled or publishing), even if another platform already published.\n\nA post with no published or failed platform (for example every platform cancelled) returns its own status with syncStatus unavailable and no platformAnalytics.", "enum": [ "published", "failed", "partial", "scheduled", "publishing", "draft", "cancelled" ], "type": "string" }, "syncStatus": { "description": "Overall sync state across all platforms", "enum": [ "synced", "pending", "partial", "unavailable" ], "type": "string" }, "thumbnailUrl": { "description": "Cover image URL. Facebook, Instagram and TikTok covers whose platform CDN link expired are re-read from the platform and served from AIsa storage, so that URL does not expire and can be cached.", "format": "uri", "type": [ "string", "null" ] } }, "type": "object" }, { "properties": { "accounts": { "description": "Connected accounts (followerCount and followersLastUpdated only included if user has analytics add-on)", "items": { "properties": { "_id": { "type": "string" }, "displayName": { "type": "string" }, "enabled": { "description": "Whether the user explicitly activated this account. false means the account was created as a side effect (e.g., a posting account auto-created when the user connected ads first).\n\n- GET /apis/v1/social/accounts still returns such accounts unless `excludeHidden=true` is passed.\n- They cannot be posted to (`ACCOUNT_NOT_ENABLED_FOR_POSTING`) and are not billed as connected accounts.\n- On an ads account (`metaads`, `googleads`, ...) the value does not hide the connection: ads accounts are listed whatever their `enabled` value and keep working for ads.", "type": "boolean" }, "followersCount": { "description": "Follower count (only included if user has analytics add-on)", "type": "number" }, "followersLastUpdated": { "description": "Last time follower count was updated (only included if user has analytics add-on)", "format": "date-time", "type": "string" }, "isActive": { "type": "boolean" }, "metadata": { "description": "Platform-specific metadata. Fields vary by platform.\n\n**WhatsApp accounts:**\n\n- qualityRating: phone number quality rating from Meta (GREEN, YELLOW, RED, or UNKNOWN).\n- nameStatus: display name review status (APPROVED, PENDING_REVIEW, DECLINED, or NONE). A declined or pending name does not by itself block sending; sendability is reported separately via health_status (can_send_message).\n- messagingLimitTier: maximum unique business-initiated conversations per 24h rolling window (TIER_250, TIER_1K, TIER_10K, TIER_100K, or TIER_UNLIMITED). Scales automatically as quality rating improves.\n- verifiedName: Meta-verified business display name.\n- displayPhoneNumber: formatted phone number (e.g., \"+1 555-123-4567\").\n- wabaId: WhatsApp Business Account ID.\n- phoneNumberId: Meta phone number ID.\n\n**Meta ads business-login accounts:**\n\n- tokenType: system-user.\n- businessId: the owning Business Manager ID when there is one owner; null for multiple owners.\n- businessIds: owning Business Manager IDs discovered from granted ad accounts.\n- grantedAdAccountIds: ad-account IDs granted to the token.\n- adAccountBusinesses: map from ad-account ID to its owning business ID or null.\n- availablePages: granted Page IDs and names. No Page tokens are exposed.\n- selectedPageId: the Page selected for creatives and lead forms, or null.\n- scopedAdAccountIds: existing sync scope preserved on reconnect.\n\nNon-expiring tokens have no tokenExpiresAt field. Parent posting reconnects do not replace this token.\n\n**LinkedIn accounts:** profileData carries profile details refreshed on each daily snapshot.\n\n- profileData.bio: the member's headline (personal accounts) or the organization description (organization accounts). null when not set.\n- profileData.extraData.vanityName: the member's profile slug, the /in/{vanityName} segment of profileUrl. Personal accounts only; an organization's slug is in metadata.organizationInfo.vanityName.\n\n**Instagram accounts:**\n\n- loginMethod: \"facebook_login\" when connected through Facebook Login; absent for Instagram Login. On facebook_login accounts, comment reads leave hidden comments out entirely instead of returning them with isHidden true.\n- instagramScopedId: the Instagram professional account id (`17841...`). On Instagram Login accounts it is the same whichever app connected the account, while platformUserId is app-scoped. Facebook Login accounts hold this id as platformUserId.\n\n**X (Twitter) accounts:**\n\n- profileData.extraData.isPremium: whether X reports a paid subscription (Basic, Premium, Premium+, or a blue verified badge), which raises the post length limit from 280 to 25,000 characters. Read live at connect and reconnect, refreshed by the daily follower snapshot.\n- Because X intermittently reports no subscription for subscribed accounts, a cancellation is stored on the fourth consecutive daily snapshot reporting it (about four days). Accounts connected before the extraData layout carry the flag at profileData.isPremium.", "type": "object" }, "needsReconnection": { "description": "The platform definitively reported the stored OAuth token as dead.\nWhile true, GET /apis/v1/social/connect/{platform}/ads returns a\nfresh authUrl (implicit force=true) instead of alreadyConnected,\nso re-running the connect flow recovers the account. Cleared\nautomatically when the account is re-authorized.", "type": "boolean" }, "parentAccountId": { "description": "Reference to the parent posting social account. Set for ads accounts that share\nor derive from a posting account's OAuth token. null for standalone ads (Google Ads)\nand all posting accounts. Meta ads business-login accounts also have no parent.", "type": [ "string", "null" ] }, "platform": { "enum": [ "tiktok", "instagram", "facebook", "youtube", "linkedin", "twitter", "threads", "pinterest", "reddit", "bluesky", "googlebusiness", "telegram", "snapchat", "discord", "slack", "whatsapp", "shopify", "wordpress", "wix", "linkedinads", "metaads", "pinterestads", "tiktokads", "xads", "googleads", "openaiads", "redditads", "sms", "phone", "rcs", "whopads", "google", "microsoft", "hubspot", "webflow", "googleanalytics", "imessage", "tiktokshop", "microsoftads" ], "type": "string" }, "platformUserId": { "description": "The account's id on its platform, as the platform reports it to AIsa. Stable across reconnects, so use it to match an account against your own records.\n\n- **Instagram Login accounts:** the app-scoped user id (the professional account id is in `metadata.instagramScopedId`).\n- **Instagram via Facebook Login:** the professional account id (`17841...`).\n- **TikTok:** the open_id of AIsa's TikTok app, which differs from the open_id any other app sees for the same user.\n\nEither value can be passed back as `expectedPlatformUserId` on GET /apis/v1/social/connect/{platform}.", "type": "string" }, "profileId": { "description": "One of your profiles (prf_...).", "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" }, "profilePicture": { "description": "URL to the account's profile picture on the platform. May be null if the platform does not provide one.", "type": [ "string", "null" ] }, "profileUrl": { "description": "Full profile URL for the connected account on its platform.", "type": "string" }, "rateLimitedUntil": { "description": "End of the account's publishing cooldown. Compare it with the current time: a value in the past means the cooldown has ended (the field is cleared on the next successful publish); null means no cooldown since the last successful publish.\n\n**When it starts.** A post to the account fails with `errorCategory` `user_abuse` (spam, abuse or rate-limit errors), or 10 or more posts to it fail within an hour with `user_content`, `platform_error`, `platform_rate_limit` or `unknown`.\n\n**How long.** It doubles with each start inside a 24-hour window that opens at the first one (10, 20, 40, 80 minutes and so on, capped at 24 hours).\n\nOn a YouTube account with a recorded successful upload, it instead runs until 24 hours after that upload, or 1 hour when that upload is older than 24 hours.\n\n**Effect.** While it is in the future, POST /apis/v1/social/posts (drafts excepted) and POST /apis/v1/social/posts/{postId}/retry return 429 for this account. When it starts, this account's pending targets on posts scheduled before the cooldown ends are failed.", "format": "date-time", "type": [ "string", "null" ] }, "scopeAreas": { "description": "Accounts connected through your own OAuth app: the permission areas the connect requested. Null on accounts connected through AIsa's app.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "tiktokAccountType": { "description": "TikTok accounts only. The account type TikTok reported when the account was connected.\n\n- `personal`: cannot use TikTok direct messages through the API (TikTok limits Business Messaging to Business Accounts). Skip the inbox for them and tell the user to switch to a Business Account in the TikTok app, then reconnect.\n- `business`: the prerequisite, not a guarantee. Messaging also needs the messaging scopes granted and TikTok's regional availability.\n- `unknown`: accounts connected before this was captured, or whose grant left out the account-type scope.", "enum": [ "business", "personal", "unknown" ], "type": "string" }, "username": { "type": "string" } }, "required": [ "_id", "isActive", "platform", "profileId" ], "type": "object" }, "type": "array" }, "hasAnalyticsAccess": { "description": "Whether user has analytics add-on access", "type": "boolean" }, "overview": { "properties": { "dataStaleness": { "properties": { "staleAccountCount": { "description": "Number of accounts with stale analytics data", "type": "integer" }, "syncTriggered": { "description": "Whether a background sync was triggered for stale accounts", "type": "boolean" } }, "type": "object" }, "lastSync": { "format": "date-time", "type": [ "string", "null" ] }, "publishedPosts": { "type": "integer" }, "scheduledPosts": { "type": "integer" }, "totalPosts": { "type": "integer" } }, "type": "object" }, "pagination": { "properties": { "limit": { "type": "integer" }, "page": { "type": "integer" }, "pages": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" }, "posts": { "items": { "properties": { "_id": { "type": "string" }, "analytics": { "properties": { "audienceCountries": { "additionalProperties": { "type": "number" }, "description": "TikTok accounts connected through the TikTok for Business app only: share of views by viewer country, as fractions 0 to 1, keyed by upper-case ISO-3166 alpha-2 code. Available T+24-48h, only for posts active in the last 7 days.\n\nAt most 20 country keys plus `other`. The catch-all bucket TikTok sends, any country below 0.001 and anything past the twentieth all sum into `other`, so the values still add up to 1.\n\nEmpty object when TikTok reports nothing, and for other platforms. Views-weighted across accounts like impressionSources.", "type": "object" }, "audienceTypes": { "additionalProperties": { "type": "number" }, "description": "TikTok accounts connected through the TikTok for Business app only: two viewer splits as fractions 0 to 1 (T+24-48h).\n\n- Each pair sums to 1 when present: `follower` + `nonFollower`, and `newViewer` + `returnViewer`. TikTok can report one pair without the other.\n- Empty object when TikTok reports nothing, and for other platforms.\n- Views-weighted across accounts, like impressionSources.", "type": "object" }, "clicks": { "description": "Link clicks where the platform reports them. Always 0 on Facebook Page stories: Meta exposes no link-click metric for stories.", "type": "integer" }, "comments": { "type": "integer" }, "completionRate": { "description": "Share of viewers who watched the video to the end, 0 to 1, as TikTok reports it. Only for TikTok accounts connected through the TikTok for Business app.\n\n- Delayed T+24-48h, and only for posts active in the last 7 days.\n- 0 for other platforms.\n- For a post published to several accounts, the aggregate is weighted by views.", "type": "number" }, "engagementRate": { "description": "Percentage, rounded to 2 decimals: (likes + comments + shares + saves) / (impressions or reach or views) * 100. Clicks and follows are never counted.\n\nThe denominator is the FIRST of impressions, reach, views that is non-zero, so the basis varies by post: impressions if present, else reach, else views. For a single consistent basis (e.g. interactions / reach), compute it from the raw fields above.\n\nOn the post-level roll-up of a cross-posted post, the denominator is the SUM of the denominators resolved per platform entry. An entry reporting none of impressions, reach or views is excluded from both sides of the ratio. Each platformAnalytics entry below keeps its own single denominator.\n\nThe engagementRate on the LinkedIn account endpoints uses a different formula.", "type": "number" }, "follows": { "description": "Accounts that started following from this post.\n\n- Reported for Instagram feed posts and stories (organic follows), Facebook Reels (Meta post_video_followers) and the TikTok business lane.\n- Null on Instagram Reels and non-Reels video, and on Facebook posts that are not Reels, where Meta does not expose this metric for the media.\n- 0 for other platforms.", "type": [ "integer", "null" ] }, "igReelsAvgWatchTime": { "description": "Average watch time per play, in milliseconds, for Instagram Reels, Facebook Reels and TikTok videos (business accounts). On Facebook it includes replays within a play, so it can exceed the Reel length. 0 for other media and platforms, including regular Facebook videos.", "type": "integer" }, "igReelsVideoViewTotalTime": { "description": "Total watch time including replays, in milliseconds, for Instagram Reels, Facebook Reels and TikTok videos (business accounts). 0 for other media and platforms, including regular Facebook videos.", "type": "integer" }, "impressionSources": { "additionalProperties": { "type": "number" }, "description": "Share of views by surface, as fractions 0 to 1. Only for TikTok accounts connected through the TikTok for Business app (T+24-48h, only for posts active in the last 7 days).\n\n- Keys: `forYou`, `follow`, `search`, `personalProfile`, `sound`, `directMessage`, `other`. A surface TikTok adds later appears under a camelCase key derived from its name.\n- Empty object when TikTok reports nothing, and for other platforms.\n- When a post is published to several accounts, each share is weighted by views.", "type": "object" }, "impressions": { "type": "integer" }, "lastUpdated": { "format": "date-time", "type": "string" }, "likes": { "type": "integer" }, "profileViews": { "description": "Instagram feed posts (images and carousels; 0 on Reels and Stories) and TikTok accounts connected through the TikTok for Business app: profile views from users who reached the profile through this post (TikTok T+24-48h). 0 for other platforms.", "type": "integer" }, "reach": { "type": "integer" }, "reelsSkipRate": { "description": "Instagram Reels only: percentage (0-100) of initial views that skipped the reel within its first 3 seconds, as reported by Meta.\n\n- Meta labels the metric estimated and in development, so it can move between syncs.\n- 0 for non-Reels media and other platforms.\n- For a post published to several accounts, the aggregate is weighted by views.", "type": "number" }, "replays": { "description": "Facebook Reels only: plays that were replays (Meta fb_reels_replay_count). Summed across accounts. 0 for other media and platforms.", "type": "integer" }, "reposts": { "description": "Reposts of the media by other users, minus deleted reposts, on feed posts, reels and stories. Instagram accounts connected with Facebook Login only.\n\n- Instagram Login accounts: always 0 (Meta does not expose this metric for them).\n- Other platforms: 0, including Threads, where reposts are counted in shares instead.", "type": "integer" }, "retentionCurve": { "additionalProperties": { "type": "number" }, "description": "Facebook Reels and TikTok business lane: share of viewers still watching at each second of playback, as fractions 0 to 1. Keys are whole seconds from the start of a play (\"3\" is the share still watching at 3 s). Empty object for other media and platforms.\n\n- Facebook Reels (Meta post_video_retention_graph): the base is a subset of plays that Meta selects and does not expose. On small Reels it can be far below views (6 of 51 measured), so a value is a share of that subset, not of all plays.\n- Facebook Reels length: loops count as continued playback, so a short Reel's curve runs past its length (an 8 s Reel has keys \"0\" to \"12\"). Meta returns at most 41 points, so a long Reel covers only its first 40 s.\n- TikTok accounts connected through the TikTok for Business app (TikTok video_view_retention): one point per whole second, at most 61 points, thinned evenly on videos longer than 60 s.\n\nOn a cross-posted post this is the curve of the account with the most views among those reporting one, never a blend: curves from different platforms and accounts measure different audiences and different seconds. Each platformAnalytics entry keeps its own curve.", "type": "object" }, "saves": { "description": "Number of saves/bookmarks (Instagram, Pinterest, X)", "type": "integer" }, "shares": { "type": "integer" }, "videoDurationSeconds": { "description": "Video length in seconds. Null when unknown: platforms that do not report a length, non-video media, or when Instagram does not expose the media URL (e.g. reels with copyrighted audio).\n\n- YouTube: filled for public videos once their analytics next refresh (from the Data API; live streams may report null). The Data API has no Shorts flag: a video over 180 seconds cannot be a Short, but a shorter one may be a regular upload.\n- Instagram Reels: also filled. Combine with igReelsAvgWatchTime (ms) to estimate retention.", "type": [ "integer", "null" ] }, "views": { "type": "integer" }, "websiteClicks": { "description": "TikTok accounts connected through the TikTok for Business app only: clicks on the profile website link attributed to this post (T+24-48h). Also counted inside `clicks`, which sums every profile-link type (website, phone, email, address, app download). 0 for other platforms.", "type": "integer" } }, "type": "object" }, "content": { "type": "string" }, "isAd": { "description": "True when this post's metrics include paid delivery, so organic reporting should exclude it.\n\nSet for LinkedIn dark posts and for TikTok posts one of your TikTok ads promotes (Spark / boosted).\n\nTikTok exposes no ad flag of its own. A video created by an uploaded-asset (non-Spark) TikTok ad is posted to the profile with a fresh organic id and cannot be detected, so those still report false.", "type": "boolean" }, "isAiGenerated": { "description": "Instagram only: whether Instagram labeled the media as AI-generated. Absent when the platform did not report it.", "type": "boolean" }, "isExternal": { "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" }, "latePostId": { "description": "Original AIsa post ID if scheduled via AIsa", "type": [ "string", "null" ] }, "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": "All media items for this post. Carousel posts contain one entry per slide.\n\n- Facebook and Instagram images and video covers whose Meta CDN links expired are re-read and served from AIsa storage (non-expiring).\n- Facebook and Instagram video file URLs, and LinkedIn media URLs, stay the platform's signed links and are refreshed on read once they lapse.", "items": { "properties": { "altText": { "description": "Accessibility alt text set on the media, when present.", "type": "string" }, "thumbnail": { "description": "Thumbnail URL (same as url for images)", "format": "uri", "type": "string" }, "type": { "enum": [ "image", "video" ], "type": "string" }, "url": { "description": "Direct URL to the media", "format": "uri", "type": "string" } }, "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": { "enum": [ "image", "video", "gif", "document", "carousel", "text" ], "type": "string" }, "platform": { "type": "string" }, "platformPostUrl": { "format": "uri", "type": "string" }, "platforms": { "items": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "accountUsername": { "type": [ "string", "null" ] }, "analytics": { "anyOf": [ { "properties": { "audienceCountries": { "type": "object" }, "audienceTypes": { "type": "object" }, "clicks": { "type": "integer" }, "comments": { "type": "integer" }, "completionRate": { "type": "number" }, "engagementRate": { "type": "number" }, "follows": { "type": "object" }, "igReelsAvgWatchTime": { "type": "integer" }, "igReelsVideoViewTotalTime": { "type": "integer" }, "impressionSources": { "type": "object" }, "impressions": { "type": "integer" }, "lastUpdated": { "type": "string" }, "likes": { "type": "integer" }, "profileViews": { "type": "integer" }, "reach": { "type": "integer" }, "reelsSkipRate": { "type": "number" }, "replays": { "type": "integer" }, "reposts": { "type": "integer" }, "retentionCurve": { "type": "object" }, "saves": { "type": "integer" }, "shares": { "type": "integer" }, "videoDurationSeconds": { "type": "object" }, "views": { "type": "integer" }, "websiteClicks": { "type": "integer" } }, "type": "object" }, { "type": "null" } ] }, "errorCode": { "description": "Stable machine-readable reason for errorMessage. New values may be added.\n\n- post_not_found: the post was deleted or is no longer visible to the account.\n- not_post_owner: the post is owned by another Page or user (collab or visitor post); its analytics cannot be read with this Page's token.\n- permission_missing: the last analytics sync of the Facebook account failed because the Page no longer grants pages_read_engagement (pending entries only).\n- null: no stable code; read errorMessage.", "enum": [ "post_not_found", "not_post_owner", "permission_missing", null ], "type": [ "string", "null" ] }, "errorMessage": { "description": "Failure detail:\n\n- Failed entries: why the post failed to publish.\n- Unavailable entries: why analytics cannot be synced (e.g. Google Business Profile, a TikTok upload that never received a video id).\n- Pending entries: the most recent analytics sync error for the account (null while no sync has failed), cleared after the next successful sync.", "type": [ "string", "null" ] }, "isOwner": { "description": "Facebook only: true when the connected Page authored the post, false when Facebook reports another author (a collab post), null when unknown or for other platforms.", "type": [ "boolean", "null" ] }, "platform": { "type": "string" }, "platformPostId": { "description": "The native post ID on the platform (e.g. Instagram media ID, tweet ID)", "type": [ "string", "null" ] }, "platformPostUrl": { "format": "uri", "type": [ "string", "null" ] }, "status": { "enum": [ "published", "failed" ], "type": "string" }, "syncStatus": { "description": "Sync state of analytics for this platform", "enum": [ "synced", "pending", "unavailable" ], "type": "string" } }, "type": "object" }, "type": "array" }, "profileId": { "type": [ "string", "null" ] }, "publishedAt": { "format": "date-time", "type": "string" }, "scheduledFor": { "format": "date-time", "type": "string" }, "status": { "type": "string" }, "thumbnailUrl": { "description": "Cover image URL. Facebook, Instagram and TikTok covers whose platform CDN link expired are re-read from the platform and served from AIsa storage, so that URL does not expire and can be cached.", "format": "uri", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } ] } } }, "description": "Analytics result" }, "202": { "content": { "application/json": { "schema": { "properties": { "analytics": { "properties": { "audienceCountries": { "additionalProperties": { "type": "number" }, "description": "TikTok accounts connected through the TikTok for Business app only: share of views by viewer country, as fractions 0 to 1, keyed by upper-case ISO-3166 alpha-2 code. Available T+24-48h, only for posts active in the last 7 days.\n\nAt most 20 country keys plus `other`. The catch-all bucket TikTok sends, any country below 0.001 and anything past the twentieth all sum into `other`, so the values still add up to 1.\n\nEmpty object when TikTok reports nothing, and for other platforms. Views-weighted across accounts like impressionSources.", "type": "object" }, "audienceTypes": { "additionalProperties": { "type": "number" }, "description": "TikTok accounts connected through the TikTok for Business app only: two viewer splits as fractions 0 to 1 (T+24-48h).\n\n- Each pair sums to 1 when present: `follower` + `nonFollower`, and `newViewer` + `returnViewer`. TikTok can report one pair without the other.\n- Empty object when TikTok reports nothing, and for other platforms.\n- Views-weighted across accounts, like impressionSources.", "type": "object" }, "clicks": { "description": "Link clicks where the platform reports them. Always 0 on Facebook Page stories: Meta exposes no link-click metric for stories.", "type": "integer" }, "comments": { "type": "integer" }, "completionRate": { "description": "Share of viewers who watched the video to the end, 0 to 1, as TikTok reports it. Only for TikTok accounts connected through the TikTok for Business app.\n\n- Delayed T+24-48h, and only for posts active in the last 7 days.\n- 0 for other platforms.\n- For a post published to several accounts, the aggregate is weighted by views.", "type": "number" }, "engagementRate": { "description": "Percentage, rounded to 2 decimals: (likes + comments + shares + saves) / (impressions or reach or views) * 100. Clicks and follows are never counted.\n\nThe denominator is the FIRST of impressions, reach, views that is non-zero, so the basis varies by post: impressions if present, else reach, else views. For a single consistent basis (e.g. interactions / reach), compute it from the raw fields above.\n\nOn the post-level roll-up of a cross-posted post, the denominator is the SUM of the denominators resolved per platform entry. An entry reporting none of impressions, reach or views is excluded from both sides of the ratio. Each platformAnalytics entry below keeps its own single denominator.\n\nThe engagementRate on the LinkedIn account endpoints uses a different formula.", "type": "number" }, "follows": { "description": "Accounts that started following from this post.\n\n- Reported for Instagram feed posts and stories (organic follows), Facebook Reels (Meta post_video_followers) and the TikTok business lane.\n- Null on Instagram Reels and non-Reels video, and on Facebook posts that are not Reels, where Meta does not expose this metric for the media.\n- 0 for other platforms.", "type": [ "integer", "null" ] }, "igReelsAvgWatchTime": { "description": "Average watch time per play, in milliseconds, for Instagram Reels, Facebook Reels and TikTok videos (business accounts). On Facebook it includes replays within a play, so it can exceed the Reel length. 0 for other media and platforms, including regular Facebook videos.", "type": "integer" }, "igReelsVideoViewTotalTime": { "description": "Total watch time including replays, in milliseconds, for Instagram Reels, Facebook Reels and TikTok videos (business accounts). 0 for other media and platforms, including regular Facebook videos.", "type": "integer" }, "impressionSources": { "additionalProperties": { "type": "number" }, "description": "Share of views by surface, as fractions 0 to 1. Only for TikTok accounts connected through the TikTok for Business app (T+24-48h, only for posts active in the last 7 days).\n\n- Keys: `forYou`, `follow`, `search`, `personalProfile`, `sound`, `directMessage`, `other`. A surface TikTok adds later appears under a camelCase key derived from its name.\n- Empty object when TikTok reports nothing, and for other platforms.\n- When a post is published to several accounts, each share is weighted by views.", "type": "object" }, "impressions": { "type": "integer" }, "lastUpdated": { "format": "date-time", "type": "string" }, "likes": { "type": "integer" }, "profileViews": { "description": "Instagram feed posts (images and carousels; 0 on Reels and Stories) and TikTok accounts connected through the TikTok for Business app: profile views from users who reached the profile through this post (TikTok T+24-48h). 0 for other platforms.", "type": "integer" }, "reach": { "type": "integer" }, "reelsSkipRate": { "description": "Instagram Reels only: percentage (0-100) of initial views that skipped the reel within its first 3 seconds, as reported by Meta.\n\n- Meta labels the metric estimated and in development, so it can move between syncs.\n- 0 for non-Reels media and other platforms.\n- For a post published to several accounts, the aggregate is weighted by views.", "type": "number" }, "replays": { "description": "Facebook Reels only: plays that were replays (Meta fb_reels_replay_count). Summed across accounts. 0 for other media and platforms.", "type": "integer" }, "reposts": { "description": "Reposts of the media by other users, minus deleted reposts, on feed posts, reels and stories. Instagram accounts connected with Facebook Login only.\n\n- Instagram Login accounts: always 0 (Meta does not expose this metric for them).\n- Other platforms: 0, including Threads, where reposts are counted in shares instead.", "type": "integer" }, "retentionCurve": { "additionalProperties": { "type": "number" }, "description": "Facebook Reels and TikTok business lane: share of viewers still watching at each second of playback, as fractions 0 to 1. Keys are whole seconds from the start of a play (\"3\" is the share still watching at 3 s). Empty object for other media and platforms.\n\n- Facebook Reels (Meta post_video_retention_graph): the base is a subset of plays that Meta selects and does not expose. On small Reels it can be far below views (6 of 51 measured), so a value is a share of that subset, not of all plays.\n- Facebook Reels length: loops count as continued playback, so a short Reel's curve runs past its length (an 8 s Reel has keys \"0\" to \"12\"). Meta returns at most 41 points, so a long Reel covers only its first 40 s.\n- TikTok accounts connected through the TikTok for Business app (TikTok video_view_retention): one point per whole second, at most 61 points, thinned evenly on videos longer than 60 s.\n\nOn a cross-posted post this is the curve of the account with the most views among those reporting one, never a blend: curves from different platforms and accounts measure different audiences and different seconds. Each platformAnalytics entry keeps its own curve.", "type": "object" }, "saves": { "description": "Number of saves/bookmarks (Instagram, Pinterest, X)", "type": "integer" }, "shares": { "type": "integer" }, "videoDurationSeconds": { "description": "Video length in seconds. Null when unknown: platforms that do not report a length, non-video media, or when Instagram does not expose the media URL (e.g. reels with copyrighted audio).\n\n- YouTube: filled for public videos once their analytics next refresh (from the Data API; live streams may report null). The Data API has no Shorts flag: a video over 180 seconds cannot be a Short, but a shorter one may be a regular upload.\n- Instagram Reels: also filled. Combine with igReelsAvgWatchTime (ms) to estimate retention.", "type": [ "integer", "null" ] }, "views": { "type": "integer" }, "websiteClicks": { "description": "TikTok accounts connected through the TikTok for Business app only: clicks on the profile website link attributed to this post (T+24-48h). Also counted inside `clicks`, which sums every profile-link type (website, phone, email, address, app download). 0 for other platforms.", "type": "integer" } }, "type": "object" }, "content": { "type": "string" }, "isAiGenerated": { "description": "Instagram only: whether Instagram labeled the media as AI-generated. Absent when the platform did not report it.", "type": "boolean" }, "isExternal": { "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" }, "latePostId": { "description": "Original AIsa post ID if scheduled via AIsa", "type": [ "string", "null" ] }, "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": "All media items for this post. Carousel posts have one entry per slide.\n\n- Facebook and Instagram images and video covers whose Meta CDN links expired are re-read and served from AIsa storage (non-expiring).\n- Facebook and Instagram video file URLs, and LinkedIn media URLs, stay the platform's signed links and are refreshed on read once they lapse.", "items": { "properties": { "altText": { "description": "Accessibility alt text set on the media, when present.", "type": "string" }, "mediaStatus": { "description": "unavailable means the media file could not be retrieved (url is null or, for LinkedIn videos, a cover image standing in for the file). available or absent means the file is available at url (older synced items omit the field).", "enum": [ "available", "unavailable" ], "type": "string" }, "thumbnail": { "description": "Thumbnail URL (same as url for images). Still present when url is null.", "format": "uri", "type": [ "string", "null" ] }, "type": { "enum": [ "image", "video" ], "type": "string" }, "unavailableReason": { "description": "Why the file is missing. platform_withheld means the platform declined to return it and retrying will not help.", "enum": [ "platform_withheld" ], "type": "string" }, "url": { "description": "'Direct URL to the media file. Null when the platform withholds it: check mediaStatus before downloading. Instagram omits the video file for Reels it flags as containing copyrighted material (its docs name audio as the usual cause), so type stays \"video\" while the file is permanently unreachable.'", "format": "uri", "type": [ "string", "null" ] } }, "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": { "enum": [ "image", "video", "carousel", "text" ], "type": [ "string", "null" ] }, "message": { "description": "Human-readable status message for pending, partial, or failed states", "type": [ "string", "null" ] }, "platform": { "type": "string" }, "platformAnalytics": { "items": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "accountUsername": { "type": [ "string", "null" ] }, "analytics": { "anyOf": [ { "properties": { "audienceCountries": { "additionalProperties": { "type": "number" }, "description": "TikTok accounts connected through the TikTok for Business app only: share of views by viewer country, as fractions 0 to 1, keyed by upper-case ISO-3166 alpha-2 code. Available T+24-48h, only for posts active in the last 7 days.\n\nAt most 20 country keys plus `other`. The catch-all bucket TikTok sends, any country below 0.001 and anything past the twentieth all sum into `other`, so the values still add up to 1.\n\nEmpty object when TikTok reports nothing, and for other platforms. Views-weighted across accounts like impressionSources.", "type": "object" }, "audienceTypes": { "additionalProperties": { "type": "number" }, "description": "TikTok accounts connected through the TikTok for Business app only: two viewer splits as fractions 0 to 1 (T+24-48h).\n\n- Each pair sums to 1 when present: `follower` + `nonFollower`, and `newViewer` + `returnViewer`. TikTok can report one pair without the other.\n- Empty object when TikTok reports nothing, and for other platforms.\n- Views-weighted across accounts, like impressionSources.", "type": "object" }, "clicks": { "description": "Link clicks where the platform reports them. Always 0 on Facebook Page stories: Meta exposes no link-click metric for stories.", "type": "integer" }, "comments": { "type": "integer" }, "completionRate": { "description": "Share of viewers who watched the video to the end, 0 to 1, as TikTok reports it. Only for TikTok accounts connected through the TikTok for Business app.\n\n- Delayed T+24-48h, and only for posts active in the last 7 days.\n- 0 for other platforms.\n- For a post published to several accounts, the aggregate is weighted by views.", "type": "number" }, "engagementRate": { "description": "Percentage, rounded to 2 decimals: (likes + comments + shares + saves) / (impressions or reach or views) * 100. Clicks and follows are never counted.\n\nThe denominator is the FIRST of impressions, reach, views that is non-zero, so the basis varies by post: impressions if present, else reach, else views. For a single consistent basis (e.g. interactions / reach), compute it from the raw fields above.\n\nOn the post-level roll-up of a cross-posted post, the denominator is the SUM of the denominators resolved per platform entry. An entry reporting none of impressions, reach or views is excluded from both sides of the ratio. Each platformAnalytics entry below keeps its own single denominator.\n\nThe engagementRate on the LinkedIn account endpoints uses a different formula.", "type": "number" }, "follows": { "description": "Accounts that started following from this post.\n\n- Reported for Instagram feed posts and stories (organic follows), Facebook Reels (Meta post_video_followers) and the TikTok business lane.\n- Null on Instagram Reels and non-Reels video, and on Facebook posts that are not Reels, where Meta does not expose this metric for the media.\n- 0 for other platforms.", "type": [ "integer", "null" ] }, "igReelsAvgWatchTime": { "description": "Average watch time per play, in milliseconds, for Instagram Reels, Facebook Reels and TikTok videos (business accounts). On Facebook it includes replays within a play, so it can exceed the Reel length. 0 for other media and platforms, including regular Facebook videos.", "type": "integer" }, "igReelsVideoViewTotalTime": { "description": "Total watch time including replays, in milliseconds, for Instagram Reels, Facebook Reels and TikTok videos (business accounts). 0 for other media and platforms, including regular Facebook videos.", "type": "integer" }, "impressionSources": { "additionalProperties": { "type": "number" }, "description": "Share of views by surface, as fractions 0 to 1. Only for TikTok accounts connected through the TikTok for Business app (T+24-48h, only for posts active in the last 7 days).\n\n- Keys: `forYou`, `follow`, `search`, `personalProfile`, `sound`, `directMessage`, `other`. A surface TikTok adds later appears under a camelCase key derived from its name.\n- Empty object when TikTok reports nothing, and for other platforms.\n- When a post is published to several accounts, each share is weighted by views.", "type": "object" }, "impressions": { "type": "integer" }, "lastUpdated": { "format": "date-time", "type": "string" }, "likes": { "type": "integer" }, "profileViews": { "description": "Instagram feed posts (images and carousels; 0 on Reels and Stories) and TikTok accounts connected through the TikTok for Business app: profile views from users who reached the profile through this post (TikTok T+24-48h). 0 for other platforms.", "type": "integer" }, "reach": { "type": "integer" }, "reelsSkipRate": { "description": "Instagram Reels only: percentage (0-100) of initial views that skipped the reel within its first 3 seconds, as reported by Meta.\n\n- Meta labels the metric estimated and in development, so it can move between syncs.\n- 0 for non-Reels media and other platforms.\n- For a post published to several accounts, the aggregate is weighted by views.", "type": "number" }, "replays": { "description": "Facebook Reels only: plays that were replays (Meta fb_reels_replay_count). Summed across accounts. 0 for other media and platforms.", "type": "integer" }, "reposts": { "description": "Reposts of the media by other users, minus deleted reposts, on feed posts, reels and stories. Instagram accounts connected with Facebook Login only.\n\n- Instagram Login accounts: always 0 (Meta does not expose this metric for them).\n- Other platforms: 0, including Threads, where reposts are counted in shares instead.", "type": "integer" }, "retentionCurve": { "additionalProperties": { "type": "number" }, "description": "Facebook Reels and TikTok business lane: share of viewers still watching at each second of playback, as fractions 0 to 1. Keys are whole seconds from the start of a play (\"3\" is the share still watching at 3 s). Empty object for other media and platforms.\n\n- Facebook Reels (Meta post_video_retention_graph): the base is a subset of plays that Meta selects and does not expose. On small Reels it can be far below views (6 of 51 measured), so a value is a share of that subset, not of all plays.\n- Facebook Reels length: loops count as continued playback, so a short Reel's curve runs past its length (an 8 s Reel has keys \"0\" to \"12\"). Meta returns at most 41 points, so a long Reel covers only its first 40 s.\n- TikTok accounts connected through the TikTok for Business app (TikTok video_view_retention): one point per whole second, at most 61 points, thinned evenly on videos longer than 60 s.\n\nOn a cross-posted post this is the curve of the account with the most views among those reporting one, never a blend: curves from different platforms and accounts measure different audiences and different seconds. Each platformAnalytics entry keeps its own curve.", "type": "object" }, "saves": { "description": "Number of saves/bookmarks (Instagram, Pinterest, X)", "type": "integer" }, "shares": { "type": "integer" }, "videoDurationSeconds": { "description": "Video length in seconds. Null when unknown: platforms that do not report a length, non-video media, or when Instagram does not expose the media URL (e.g. reels with copyrighted audio).\n\n- YouTube: filled for public videos once their analytics next refresh (from the Data API; live streams may report null). The Data API has no Shorts flag: a video over 180 seconds cannot be a Short, but a shorter one may be a regular upload.\n- Instagram Reels: also filled. Combine with igReelsAvgWatchTime (ms) to estimate retention.", "type": [ "integer", "null" ] }, "views": { "type": "integer" }, "websiteClicks": { "description": "TikTok accounts connected through the TikTok for Business app only: clicks on the profile website link attributed to this post (T+24-48h). Also counted inside `clicks`, which sums every profile-link type (website, phone, email, address, app download). 0 for other platforms.", "type": "integer" } }, "type": "object" }, { "type": "null" } ] }, "errorCode": { "description": "Stable machine-readable reason for errorMessage. New values may be added.\n\n- post_not_found: the post was deleted or is no longer visible to the account.\n- not_post_owner: the post is owned by another Page or user (collab or visitor post); its analytics cannot be read with this Page's token.\n- permission_missing: the last analytics sync of the Facebook account failed because the Page no longer grants pages_read_engagement (pending entries only).\n- null: no stable code; read errorMessage.", "enum": [ "post_not_found", "not_post_owner", "permission_missing", null ], "type": [ "string", "null" ] }, "errorMessage": { "description": "Failure detail:\n\n- Failed entries: why the post failed to publish.\n- Unavailable entries: why analytics cannot be synced (e.g. Google Business Profile, a TikTok upload that never received a video id).\n- Pending entries: the most recent analytics sync error for the account (null while no sync has failed), cleared after the next successful sync.", "type": [ "string", "null" ] }, "isOwner": { "description": "Facebook only: true when the connected Page authored the post, false when Facebook reports another author (a collab post), null when unknown or for other platforms.", "type": [ "boolean", "null" ] }, "platform": { "type": "string" }, "platformPostId": { "description": "The native post ID on the platform (e.g. Instagram media ID, tweet ID)", "type": [ "string", "null" ] }, "platformPostUrl": { "format": "uri", "type": [ "string", "null" ] }, "status": { "enum": [ "published", "failed" ], "type": "string" }, "syncStatus": { "description": "Sync state of analytics for this platform", "enum": [ "synced", "pending", "unavailable" ], "type": "string" } }, "type": "object" }, "type": "array" }, "platformPostUrl": { "format": "uri", "type": [ "string", "null" ] }, "postId": { "type": "string" }, "publishedAt": { "format": "date-time", "type": [ "string", "null" ] }, "scheduledFor": { "format": "date-time", "type": "string" }, "status": { "description": "Overall post status. \"partial\" when some platforms published and others failed.\n\nWhile any platform is still pending or processing, the post's own status is returned instead (usually scheduled or publishing), even if another platform already published.\n\nA post with no published or failed platform (for example every platform cancelled) returns its own status with syncStatus unavailable and no platformAnalytics.", "enum": [ "published", "failed", "partial", "scheduled", "publishing", "draft", "cancelled" ], "type": "string" }, "syncStatus": { "description": "Overall sync state across all platforms", "enum": [ "synced", "pending", "partial", "unavailable" ], "type": "string" }, "thumbnailUrl": { "description": "Cover image URL. Facebook, Instagram and TikTok covers whose platform CDN link expired are re-read from the platform and served from AIsa storage, so that URL does not expire and can be cached.", "format": "uri", "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Analytics are being synced from the platform, or (single post lookup only) the post has not finished publishing on every platform yet.\n\nThe body matches AnalyticsSinglePostResponse with syncStatus \"pending\" and a message.\n\n- While a platform has not published, status is the post's own status (for example scheduled or publishing).\n- A post with one failed platform returns 202 rather than 424 until the others finish.\n- Pending platforms whose account failed its last analytics sync carry that error in platformAnalytics[].errorMessage, and the message says so.\n" }, "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." } }, "summary": "Get post analytics", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.get_analytics@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "c3f0ecb1f2f0e97c7a20702ff2e9eec6ee0fe7a009dd07926dfa2bcf613de335" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_posts", "method": "GET", "path": "/apis/v1/social/analytics/posts" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_posts" } }, "/apis/v1/social/analytics/samples": { "get": { "description": "Analytics. 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.\n\nReturns the raw readings behind a post's numbers, oldest first.\n\nEach sample is one analytics sync: the views and engagement as the platform reported them at `syncedAt`. AIsa only stores what it fetched from the platform, so nothing here was self-reported.\n\n### Null values\n\n- `shares` and `saves` are null on platforms that do not return that counter, which is different from a real zero.\n- `watchSeconds` and `completionRate` are null when the platform gives no watch signal.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_samples", "parameters": [ { "description": "The post to read samples for. Accepts an external post id, a platform post id or a AIsa post id.", "in": "query", "name": "postId", "required": true, "schema": { "type": "string" } }, { "description": "Earliest sample to return (ISO 8601).", "in": "query", "name": "fromDate", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Latest sample to return (ISO 8601).", "in": "query", "name": "toDate", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Maximum number of samples.", "in": "query", "name": "limit", "required": false, "schema": { "default": 500, "maximum": 2000, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "postId": { "description": "The postId that was requested", "type": "string" }, "samples": { "items": { "properties": { "comments": { "type": "integer" }, "completionRate": { "description": "Share of viewers who watched to the end, 0 to 1. Null when the platform gives none.", "type": [ "number", "null" ] }, "likes": { "type": "integer" }, "saves": { "description": "Null on platforms that do not return saves", "type": [ "integer", "null" ] }, "shares": { "description": "Null on platforms that do not return shares", "type": [ "integer", "null" ] }, "syncedAt": { "description": "When AIsa fetched this reading from the platform", "format": "date-time", "type": "string" }, "views": { "type": "integer" }, "watchSeconds": { "description": "Average watch time in seconds. Null when the platform gives none.", "type": [ "number", "null" ] } }, "required": [ "comments", "completionRate", "likes", "saves", "shares", "syncedAt", "views", "watchSeconds" ], "type": "object" }, "type": "array" } }, "required": [ "postId", "samples" ], "type": "object" } } }, "description": "Samples for the post" }, "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." } }, "summary": "Get post samples", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.get_post_samples@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "ec9def3054f18e66127e0b561be37eae716499127dd71335c7e03d4dc581608e" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_samples", "method": "GET", "path": "/apis/v1/social/analytics/samples" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_samples" } }, "/apis/v1/social/analytics/tiktok/account-insights": { "get": { "description": "Analytics. 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.\n\nReturns account-level TikTok insights from /v2/user/info/ (live) plus historical time series joined from AIsa's daily snapshotter (AccountStats).\n\n- Response shape matches /apis/v1/social/analytics/instagram/account-insights.\n- Max 89 days, defaults to last 30 days.\n- Requires the user.info.stats scope on the account (412 if missing).\n\n### Why the scope is narrow\n\nThis ACCOUNT-level endpoint intentionally exposes only the four counter metrics below. These account-level figures are not on any public TikTok API, for any account type:\n\n- account-level impressions / reach\n- follower inflow / outflow breakdown\n- account-level watch time and audience demographics\n\nTikTok's Research API doesn't expose them either, and is restricted to non-commercial academic use per TikTok's eligibility policy.\n\n### Per-video metrics\n\nPER-VIDEO is a different story on the Business lane. An account connected through the TikTok for Business app reports these per video on GET /apis/v1/social/analytics?postId=...:\n\n- profile views, website clicks, follows\n- full-watched rate, watch time\n- impression sources, viewer types and viewer countries\n\nThey arrive roughly 24-48h after publishing and only for posts active in the last 7 days.\n\nAccounts on the original TikTok integration get the basic counters there (views, likes, comments, shares) and zeros for the rest. They must reconnect through the Business app.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_tiktok_a_d6b7cc", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Comma-separated list. Defaults to\n\"follower_count,likes_count,video_count,followers_gained,followers_lost\".\n\nLive from /v2/user/info/ (requires user.info.stats scope):\n - follower_count (cumulative; time series joined from AccountStats)\n - following_count (cumulative; time series joined from AccountStats.metadata)\n - likes_count (cumulative; time series joined from AccountStats.metadata)\n - video_count (cumulative; time series joined from AccountStats.metadata)\n\nAIsa-synthesized:\n - followers_gained (sum of positive daily follower deltas)\n - followers_lost (sum of absolute negative daily deltas)", "in": "query", "name": "metrics", "required": false, "schema": { "type": "string" } }, { "description": "Start date (YYYY-MM-DD). Defaults to 30 days ago.", "in": "query", "name": "fromDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "End date (YYYY-MM-DD). Defaults to today.", "in": "query", "name": "toDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Alias of fromDate, kept for existing callers", "in": "query", "name": "since", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Alias of toDate, kept for existing callers", "in": "query", "name": "until", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "\"total_value\" returns the latest cumulative counter value.\n\"time_series\" returns daily values joined from AccountStats snapshots.", "in": "query", "name": "metricType", "required": false, "schema": { "default": "total_value", "enum": [ "time_series", "total_value" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Shared account-insights response envelope used by every platform-level\nanalytics endpoint (/apis/v1/social/analytics/{facebook|instagram|youtube|linkedin|tiktok}/*).\nThe name is historical - the shape was first shipped for Instagram and every\nnew platform endpoint reuses it for response-shape consistency. The platform\nfield echoes back which platform served the response.", "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "breakdown": { "description": "Breakdown dimension used (only present when breakdown was requested)", "type": "string" }, "dataDelay": { "type": "string" }, "dateRange": { "properties": { "since": { "format": "date", "type": "string" }, "until": { "format": "date", "type": "string" } }, "type": "object" }, "metricType": { "enum": [ "time_series", "total_value" ], "type": "string" }, "metrics": { "additionalProperties": { "properties": { "breakdowns": { "description": "Breakdown values (only for total_value with breakdown)", "items": { "properties": { "dimension": { "type": "string" }, "value": { "type": "number" } }, "type": "object" }, "type": "array" }, "currency": { "description": "ISO 4217 currency of a monetary metric, or null when the platform omitted it.\nAlways null on monetization_approximate_earnings, which Meta returns as a bare number\nwith no currency; always present on content_monetization_earnings.", "type": [ "string", "null" ] }, "total": { "description": "Sum or aggregate value for the metric", "type": "number" }, "unit": { "description": "Present on monetary metrics only. The scale of \"total\" and of every \"values[].value\", exactly as the platform returned them.\n\n- \"micro_amount\": the platform returned an object carrying a micro amount; values are that integer, summed, unconverted. AIsa publishes no divisor because Meta documents none: divide by the scale you verified against the Page's own Meta Business Suite export. On Facebook Page insights this is always content_monetization_earnings.\n- \"unspecified\": the platform returned a bare number with no unit metadata, passed through as-is; the platform does not state whether it is major or minor currency units. On Facebook Page insights this is always monetization_approximate_earnings.", "enum": [ "micro_amount", "unspecified" ], "type": "string" }, "values": { "description": "Daily values (for time_series, and always on monetary metrics)", "items": { "properties": { "date": { "format": "date", "type": "string" }, "value": { "type": "number" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "description": "Object keyed by metric name.\n\n- For time_series: each metric has \"total\" (number) and \"values\" (array of {date, value}).\n- For total_value: each metric has \"total\" (number) and optionally \"breakdowns\" (array of {dimension, value}).\n\n**Monetary metrics** also carry \"unit\" and \"currency\". AIsa never rescales money: \"total\" and every \"values[].value\" are the platform's raw numbers in the stated unit.\n\nMonetary metrics keep \"values\" even on metricType=total_value, because their \"total\" is the sum of the daily buckets the platform returned over the range. Keep the series to reconcile that sum against the platform's own reporting before invoicing on it.\n\nA metric that could not be served is absent from this object and listed in \"unavailableMetrics\" instead, so an unavailable metric is never reported as a zero.", "type": "object" }, "platform": { "description": "Platform that served this response.", "enum": [ "facebook", "instagram", "youtube", "linkedin", "tiktok" ], "type": "string" }, "success": { "type": "boolean" }, "unavailableMetrics": { "description": "Requested metrics that could not be served. Present only when at least one metric is unavailable, absent otherwise.\n\nEach listed metric is OMITTED from \"metrics\" rather than reported as 0, which is how an unavailable metric is distinguished from a genuine zero. The request itself still succeeds with HTTP 200.", "items": { "properties": { "message": { "description": "Platform-provided explanation when available (access tokens redacted), otherwise AIsa copy.", "type": "string" }, "metric": { "description": "The requested metric name.", "type": "string" }, "reason": { "description": "Why the metric is unavailable:\n\n- \"not_enrolled\": the account is not enrolled in the program behind this metric.\n- \"permission_missing\": the connected user lacks access to this metric.\n- \"unsupported_metric\": the platform does not accept this metric name on the API version AIsa uses.\n- \"no_data\": the platform returned no bucket for this metric over the requested range.\n- \"unreadable_value\": the platform returned a value shape AIsa cannot read, so no total is reported.\n- \"mixed_currency\": readable values disagree on currency or unit within the range.\n- \"upstream_error\": any other platform failure.\n\n\"no_data\" is the common case in practice. The others are defensive: \"not_enrolled\" and \"unsupported_metric\" in particular have not been observed on live Facebook traffic, since a non-enrolled Page returns zeros rather than an error and metric names are validated before any platform call.", "enum": [ "not_enrolled", "permission_missing", "unsupported_metric", "no_data", "unreadable_value", "mixed_currency", "upstream_error" ], "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Account insights data" }, "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." } }, "summary": "Get TikTok account-level insights", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.get_tik_tok_account_insights@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "56fbad6af33dfb9a5b236ca531ed0bf542d18e4853f973ed5dd68587d7a933ba" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_tiktok_a_d6b7cc", "method": "GET", "path": "/apis/v1/social/analytics/tiktok/account-insights" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_tiktok_a_d6b7cc" } }, "/apis/v1/social/analytics/tracking": { "get": { "description": "Analytics. 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.\n\nLists the tracking windows you can see, newest first. Each window carries the latest verified\nnumbers we read from the platform.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_tracking", "parameters": [ { "description": "One of your social accounts (acc_...). Required by AIsa: it scopes the read to your account.", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Only windows in this status.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "open", "completing", "completed", "cancelled" ], "type": "string" } }, { "description": "Page size.", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "type": "integer" } }, { "description": "Number of windows to skip.", "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "windows": { "items": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "completionReason": { "description": "How the window closed. Null while it is open.", "enum": [ "final_read", "unreachable", "post_deleted", "cancelled", null ], "type": [ "string", "null" ] }, "endsAt": { "format": "date-time", "type": "string" }, "finalReadAt": { "description": "When the closing read ran. Null until then.", "format": "date-time", "type": [ "string", "null" ] }, "id": { "type": "string" }, "latest": { "description": "The latest verified numbers we read from the platform. Null when no sample exists yet.", "properties": { "comments": { "type": "integer" }, "likes": { "type": "integer" }, "saves": { "type": "integer" }, "shares": { "type": "integer" }, "syncedAt": { "format": "date-time", "type": [ "string", "null" ] }, "views": { "type": "integer" } }, "required": [ "comments", "likes", "saves", "shares", "syncedAt", "views" ], "type": [ "object", "null" ] }, "platform": { "type": "string" }, "platformPostId": { "description": "The post's id on the platform", "type": "string" }, "postId": { "description": "The external post being tracked", "type": "string" }, "requestedBy": { "type": "string" }, "startsAt": { "format": "date-time", "type": "string" }, "status": { "enum": [ "open", "completing", "completed", "cancelled" ], "type": "string" } }, "required": [ "accountId", "completionReason", "endsAt", "finalReadAt", "id", "latest", "platform", "platformPostId", "postId", "requestedBy", "startsAt", "status" ], "type": "object" }, "type": "array" } }, "required": [ "windows" ], "type": "object" } } }, "description": "Tracking windows" }, "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." } }, "summary": "List tracking windows", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.list_tracking_windows@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "88fc2e1d23cbd588c940a974887681e4236ce153532a0ff20c4d5fba4a607c62" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_tracking", "method": "GET", "path": "/apis/v1/social/analytics/tracking" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_tracking" }, "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. postId is not accepted: send accountId and url; a channel post id cannot be passed.\n\nStarts watching a post's views and engagement.\n\nAIsa fetches the numbers from the platform itself on its regular analytics sync, so every reading is verified. It is a value we read from the platform, never one the creator or the caller reported.\n\n### The window\n\n- Runs for `trackingDays` (30 by default, 90 at most).\n- Ends with one final read, after which the `post.tracking_completed` webhook fires.\n\n### Identifying the post\n\nSend either `postId` (an external post id from AIsa), or `accountId` together with the post's `url`.\n\n### Responses\n\n- `201`: a new window was opened.\n- `200`: the post is already tracked; the existing window is returned.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_analytics_tracking", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "accountId": "acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3", "trackingDays": 30, "url": "https://www.tiktok.com/@creator/video/7685731010461371662" }, "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "requestedBy": { "default": "api", "description": "Free-form label for who asked for the window. It is stored and returned as given.", "type": "string" }, "trackingDays": { "default": 30, "description": "How many days the window stays open.", "maximum": 90, "minimum": 1, "type": "integer" }, "url": { "description": "Public URL of the post on the platform. Send together with `accountId`.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "window": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "completionReason": { "description": "How the window closed. Null while it is open.", "enum": [ "final_read", "unreachable", "post_deleted", "cancelled", null ], "type": [ "string", "null" ] }, "endsAt": { "format": "date-time", "type": "string" }, "finalReadAt": { "description": "When the closing read ran. Null until then.", "format": "date-time", "type": [ "string", "null" ] }, "id": { "type": "string" }, "latest": { "description": "The latest verified numbers we read from the platform. Null when no sample exists yet.", "properties": { "comments": { "type": "integer" }, "likes": { "type": "integer" }, "saves": { "type": "integer" }, "shares": { "type": "integer" }, "syncedAt": { "format": "date-time", "type": [ "string", "null" ] }, "views": { "type": "integer" } }, "required": [ "comments", "likes", "saves", "shares", "syncedAt", "views" ], "type": [ "object", "null" ] }, "platform": { "type": "string" }, "platformPostId": { "description": "The post's id on the platform", "type": "string" }, "postId": { "description": "The external post being tracked", "type": "string" }, "requestedBy": { "type": "string" }, "startsAt": { "format": "date-time", "type": "string" }, "status": { "enum": [ "open", "completing", "completed", "cancelled" ], "type": "string" } }, "required": [ "accountId", "completionReason", "endsAt", "finalReadAt", "id", "latest", "platform", "platformPostId", "postId", "requestedBy", "startsAt", "status" ], "type": "object" } }, "required": [ "window" ], "type": "object" } } }, "description": "The post already had a window; it is returned unchanged" }, "201": { "content": { "application/json": { "schema": { "properties": { "window": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "completionReason": { "description": "How the window closed. Null while it is open.", "enum": [ "final_read", "unreachable", "post_deleted", "cancelled", null ], "type": [ "string", "null" ] }, "endsAt": { "format": "date-time", "type": "string" }, "finalReadAt": { "description": "When the closing read ran. Null until then.", "format": "date-time", "type": [ "string", "null" ] }, "id": { "type": "string" }, "latest": { "description": "The latest verified numbers we read from the platform. Null when no sample exists yet.", "properties": { "comments": { "type": "integer" }, "likes": { "type": "integer" }, "saves": { "type": "integer" }, "shares": { "type": "integer" }, "syncedAt": { "format": "date-time", "type": [ "string", "null" ] }, "views": { "type": "integer" } }, "required": [ "comments", "likes", "saves", "shares", "syncedAt", "views" ], "type": [ "object", "null" ] }, "platform": { "type": "string" }, "platformPostId": { "description": "The post's id on the platform", "type": "string" }, "postId": { "description": "The external post being tracked", "type": "string" }, "requestedBy": { "type": "string" }, "startsAt": { "format": "date-time", "type": "string" }, "status": { "enum": [ "open", "completing", "completed", "cancelled" ], "type": "string" } }, "required": [ "accountId", "completionReason", "endsAt", "finalReadAt", "id", "latest", "platform", "platformPostId", "postId", "requestedBy", "startsAt", "status" ], "type": "object" } }, "required": [ "window" ], "type": "object" } } }, "description": "Window opened" }, "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." } }, "summary": "Open a tracking window", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.open_tracking_window@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "8ae8053131d86cb5729cb9c7658db3a15749e5e64cdf63fa36f94ff4aa4ab822" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_analytics_tracking", "method": "POST", "path": "/apis/v1/social/analytics/tracking" }, "x-codeSamples": [ { "lang": "text", "label": "Reference example", "source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/social/analytics/tracking \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"accountId\": \"acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3\",\n \"trackingDays\": 30,\n \"url\": \"https://www.tiktok.com/@creator/video/7685731010461371662\"\n}'" } ], "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_analytics_tracking" } }, "/apis/v1/social/analytics/tracking/{windowId}": { "delete": { "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.\n\nStops tracking and returns the window with its final status. A window that already completed keeps its\n`completed` status and its final read. A cancelled window gets no final read and fires no\n`post.tracking_completed` webhook.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "delete_aisa_social_apis_v1_social_analytics_track_766ec8", "parameters": [ { "in": "path", "name": "windowId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "window": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "completionReason": { "description": "How the window closed. Null while it is open.", "enum": [ "final_read", "unreachable", "post_deleted", "cancelled", null ], "type": [ "string", "null" ] }, "endsAt": { "format": "date-time", "type": "string" }, "finalReadAt": { "description": "When the closing read ran. Null until then.", "format": "date-time", "type": [ "string", "null" ] }, "id": { "type": "string" }, "latest": { "description": "The latest verified numbers we read from the platform. Null when no sample exists yet.", "properties": { "comments": { "type": "integer" }, "likes": { "type": "integer" }, "saves": { "type": "integer" }, "shares": { "type": "integer" }, "syncedAt": { "format": "date-time", "type": [ "string", "null" ] }, "views": { "type": "integer" } }, "required": [ "comments", "likes", "saves", "shares", "syncedAt", "views" ], "type": [ "object", "null" ] }, "platform": { "type": "string" }, "platformPostId": { "description": "The post's id on the platform", "type": "string" }, "postId": { "description": "The external post being tracked", "type": "string" }, "requestedBy": { "type": "string" }, "startsAt": { "format": "date-time", "type": "string" }, "status": { "enum": [ "open", "completing", "completed", "cancelled" ], "type": "string" } }, "required": [ "accountId", "completionReason", "endsAt", "finalReadAt", "id", "latest", "platform", "platformPostId", "postId", "requestedBy", "startsAt", "status" ], "type": "object" } }, "required": [ "window" ], "type": "object" } } }, "description": "The window after cancellation" }, "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." } }, "summary": "Cancel a tracking window", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.cancel_tracking_window@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "88cf2a84e776b475786b2678d6db847e4b99b78b2b820f5c1ec9621593870485" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "delete_aisa_social_apis_v1_social_analytics_track_766ec8", "method": "DELETE", "path": "/apis/v1/social/analytics/tracking/{windowId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/delete_aisa_social_apis_v1_social_analytics_track_766ec8" }, "get": { "description": "Analytics. 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.\n\nReturns one tracking window with the latest verified numbers we read from the platform. Once the window\nhas completed, `finalReadAt` and `completionReason` say how it closed.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_tracking_766ec8", "parameters": [ { "in": "path", "name": "windowId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "window": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "completionReason": { "description": "How the window closed. Null while it is open.", "enum": [ "final_read", "unreachable", "post_deleted", "cancelled", null ], "type": [ "string", "null" ] }, "endsAt": { "format": "date-time", "type": "string" }, "finalReadAt": { "description": "When the closing read ran. Null until then.", "format": "date-time", "type": [ "string", "null" ] }, "id": { "type": "string" }, "latest": { "description": "The latest verified numbers we read from the platform. Null when no sample exists yet.", "properties": { "comments": { "type": "integer" }, "likes": { "type": "integer" }, "saves": { "type": "integer" }, "shares": { "type": "integer" }, "syncedAt": { "format": "date-time", "type": [ "string", "null" ] }, "views": { "type": "integer" } }, "required": [ "comments", "likes", "saves", "shares", "syncedAt", "views" ], "type": [ "object", "null" ] }, "platform": { "type": "string" }, "platformPostId": { "description": "The post's id on the platform", "type": "string" }, "postId": { "description": "The external post being tracked", "type": "string" }, "requestedBy": { "type": "string" }, "startsAt": { "format": "date-time", "type": "string" }, "status": { "enum": [ "open", "completing", "completed", "cancelled" ], "type": "string" } }, "required": [ "accountId", "completionReason", "endsAt", "finalReadAt", "id", "latest", "platform", "platformPostId", "postId", "requestedBy", "startsAt", "status" ], "type": "object" } }, "required": [ "window" ], "type": "object" } } }, "description": "The tracking window" }, "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." } }, "summary": "Get a tracking window", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.get_tracking_window@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "9e473b58db26b11492195b8e75c72c156ac33247163da5c8f54ce8fe2f957101" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_tracking_766ec8", "method": "GET", "path": "/apis/v1/social/analytics/tracking/{windowId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_tracking_766ec8" } }, "/apis/v1/social/analytics/youtube/channel-insights": { "get": { "description": "Analytics. 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.\n\nReturns channel-scoped aggregate metrics from YouTube Analytics API v2. Saves you\nfrom looping /apis/v1/social/analytics/youtube/daily-views over every video when you only need\nchannel totals.\n\nResponse shape matches /apis/v1/social/analytics/instagram/account-insights so the same client\nhandling works. Requires yt-analytics.readonly scope (412 with reauthorizeUrl if\nmissing). Data has a 2-3 day delay (endDate is clamped accordingly). Max 89 days,\ndefaults to last 30 days.\n\nNOT exposed: impressions (Studio thumbnail impressions) and impressionsClickThroughRate.\nYouTube Analytics API v2 does not expose these for any principal type, not channel\nowners, not Partner Program channels, not content owners with CMS access. The only way\nto get them is Studio CSV export. This is a Google-side limitation.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_youtube__b123b1", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Comma-separated list. Defaults to \"views,estimatedMinutesWatched,subscribersGained,subscribersLost\".\n\nLive YouTube Analytics v2 metrics:\n - views\n - estimatedMinutesWatched\n - averageViewDuration (ratio - weighted mean computed across days)\n - subscribersGained\n - subscribersLost\n\nAIsa-synthesized from daily follower snapshots (cross-platform parity):\n - followers_gained\n - followers_lost", "in": "query", "name": "metrics", "required": false, "schema": { "type": "string" } }, { "description": "Start date (YYYY-MM-DD). Defaults to 30 days ago.", "in": "query", "name": "fromDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "End date (YYYY-MM-DD). Defaults to today. YouTube Analytics has a 2-3 day delay,\nso the fetch is internally clamped to 3 days ago; any requested range extending\nbeyond that returns zero values for the tail days. The response's dateRange.until\nfield reflects your requested value.", "in": "query", "name": "toDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Alias of fromDate, kept for existing callers", "in": "query", "name": "since", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Alias of toDate, kept for existing callers", "in": "query", "name": "until", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "\"total_value\" (default) returns aggregated totals.\n\"time_series\" returns per-day values in the \"values\" array.", "in": "query", "name": "metricType", "required": false, "schema": { "default": "total_value", "enum": [ "time_series", "total_value" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Shared account-insights response envelope used by every platform-level\nanalytics endpoint (/apis/v1/social/analytics/{facebook|instagram|youtube|linkedin|tiktok}/*).\nThe name is historical - the shape was first shipped for Instagram and every\nnew platform endpoint reuses it for response-shape consistency. The platform\nfield echoes back which platform served the response.", "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "breakdown": { "description": "Breakdown dimension used (only present when breakdown was requested)", "type": "string" }, "dataDelay": { "type": "string" }, "dateRange": { "properties": { "since": { "format": "date", "type": "string" }, "until": { "format": "date", "type": "string" } }, "type": "object" }, "metricType": { "enum": [ "time_series", "total_value" ], "type": "string" }, "metrics": { "additionalProperties": { "properties": { "breakdowns": { "description": "Breakdown values (only for total_value with breakdown)", "items": { "properties": { "dimension": { "type": "string" }, "value": { "type": "number" } }, "type": "object" }, "type": "array" }, "currency": { "description": "ISO 4217 currency of a monetary metric, or null when the platform omitted it.\nAlways null on monetization_approximate_earnings, which Meta returns as a bare number\nwith no currency; always present on content_monetization_earnings.", "type": [ "string", "null" ] }, "total": { "description": "Sum or aggregate value for the metric", "type": "number" }, "unit": { "description": "Present on monetary metrics only. The scale of \"total\" and of every \"values[].value\", exactly as the platform returned them.\n\n- \"micro_amount\": the platform returned an object carrying a micro amount; values are that integer, summed, unconverted. AIsa publishes no divisor because Meta documents none: divide by the scale you verified against the Page's own Meta Business Suite export. On Facebook Page insights this is always content_monetization_earnings.\n- \"unspecified\": the platform returned a bare number with no unit metadata, passed through as-is; the platform does not state whether it is major or minor currency units. On Facebook Page insights this is always monetization_approximate_earnings.", "enum": [ "micro_amount", "unspecified" ], "type": "string" }, "values": { "description": "Daily values (for time_series, and always on monetary metrics)", "items": { "properties": { "date": { "format": "date", "type": "string" }, "value": { "type": "number" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "description": "Object keyed by metric name.\n\n- For time_series: each metric has \"total\" (number) and \"values\" (array of {date, value}).\n- For total_value: each metric has \"total\" (number) and optionally \"breakdowns\" (array of {dimension, value}).\n\n**Monetary metrics** also carry \"unit\" and \"currency\". AIsa never rescales money: \"total\" and every \"values[].value\" are the platform's raw numbers in the stated unit.\n\nMonetary metrics keep \"values\" even on metricType=total_value, because their \"total\" is the sum of the daily buckets the platform returned over the range. Keep the series to reconcile that sum against the platform's own reporting before invoicing on it.\n\nA metric that could not be served is absent from this object and listed in \"unavailableMetrics\" instead, so an unavailable metric is never reported as a zero.", "type": "object" }, "platform": { "description": "Platform that served this response.", "enum": [ "facebook", "instagram", "youtube", "linkedin", "tiktok" ], "type": "string" }, "success": { "type": "boolean" }, "unavailableMetrics": { "description": "Requested metrics that could not be served. Present only when at least one metric is unavailable, absent otherwise.\n\nEach listed metric is OMITTED from \"metrics\" rather than reported as 0, which is how an unavailable metric is distinguished from a genuine zero. The request itself still succeeds with HTTP 200.", "items": { "properties": { "message": { "description": "Platform-provided explanation when available (access tokens redacted), otherwise AIsa copy.", "type": "string" }, "metric": { "description": "The requested metric name.", "type": "string" }, "reason": { "description": "Why the metric is unavailable:\n\n- \"not_enrolled\": the account is not enrolled in the program behind this metric.\n- \"permission_missing\": the connected user lacks access to this metric.\n- \"unsupported_metric\": the platform does not accept this metric name on the API version AIsa uses.\n- \"no_data\": the platform returned no bucket for this metric over the requested range.\n- \"unreadable_value\": the platform returned a value shape AIsa cannot read, so no total is reported.\n- \"mixed_currency\": readable values disagree on currency or unit within the range.\n- \"upstream_error\": any other platform failure.\n\n\"no_data\" is the common case in practice. The others are defensive: \"not_enrolled\" and \"unsupported_metric\" in particular have not been observed on live Facebook traffic, since a non-enrolled Page returns zeros rather than an error and metric names are validated before any platform call.", "enum": [ "not_enrolled", "permission_missing", "unsupported_metric", "no_data", "unreadable_value", "mixed_currency", "upstream_error" ], "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Channel insights data" }, "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." } }, "summary": "Get YouTube channel insights", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.get_you_tube_channel_insights@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "0d56668d484497506a1b99e9d4b7e75d568b7fa017300d6da25967be9bb58234" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_youtube__b123b1", "method": "GET", "path": "/apis/v1/social/analytics/youtube/channel-insights" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_youtube__b123b1" } }, "/apis/v1/social/analytics/youtube/daily-views": { "get": { "description": "Analytics. 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.\n\nReturns daily view counts for a YouTube video including views, watch time, and subscriber changes. Requires yt-analytics.readonly scope (re-authorization may be needed).\n\n- YouTube finalizes analytics with a ~3-day delay. By default only finalized days are returned; an explicit endDate can reach into the delay window (see the endDate parameter).\n- Max 90 days, defaults to last 30 days.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_youtube__9c1330", "parameters": [ { "description": "The YouTube video ID (e.g., \"dQw4w9WgXcQ\")", "in": "query", "name": "videoId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Start date (YYYY-MM-DD). Defaults to 30 days ago.", "in": "query", "name": "fromDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "End date (YYYY-MM-DD). Defaults to 3 days ago, the newest fully finalized day (YouTube finalizes analytics with a ~3-day delay).\n\nAn explicit toDate is honored up to today. Days inside the delay window are provisional and may still be revised by YouTube (see provisionalSince in the response); days YouTube has not processed yet are omitted from dailyViews.", "in": "query", "name": "toDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Alias of fromDate, kept for existing callers", "in": "query", "name": "startDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Alias of toDate, kept for existing callers", "in": "query", "name": "endDate", "required": false, "schema": { "format": "date", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "dailyViews": { "items": { "properties": { "averageViewDuration": { "description": "Average view duration in seconds", "type": "number" }, "averageViewPercentage": { "description": "Average percentage of the video watched per view. Can exceed 100 on Shorts (looping rewatches), so do not clamp it client-side.", "type": "number" }, "comments": { "type": "integer" }, "date": { "format": "date", "type": "string" }, "estimatedMinutesWatched": { "type": "number" }, "likes": { "type": "integer" }, "shares": { "type": "integer" }, "subscribersGained": { "type": "integer" }, "subscribersLost": { "type": "integer" }, "views": { "type": "integer" } }, "type": "object" }, "type": "array" }, "dateRange": { "properties": { "endDate": { "format": "date", "type": "string" }, "startDate": { "format": "date", "type": "string" } }, "type": "object" }, "durationSeconds": { "description": "Video length in seconds (from YouTube contentDetails.duration)", "type": [ "integer", "null" ] }, "lastSyncedAt": { "description": "When the data was last synced from YouTube", "format": "date-time", "type": [ "string", "null" ] }, "provisionalSince": { "description": "Present only when the range reaches into YouTube's ~3-day processing window: the first date whose numbers are provisional and may still be revised by YouTube.", "format": "date", "type": "string" }, "scopeStatus": { "properties": { "hasAnalyticsScope": { "type": "boolean" } }, "type": "object" }, "success": { "type": "boolean" }, "totalViews": { "description": "Sum of views across all days in the range", "type": "integer" }, "videoId": { "description": "The YouTube video ID", "type": "string" } }, "type": "object" } } }, "description": "Daily views breakdown" }, "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." } }, "summary": "Get YouTube daily views", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.get_you_tube_daily_views@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "ab65c0f850a36f56ec18da7c35f53d08893bcdc54da5da3648231c5b6791d568" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_youtube__9c1330", "method": "GET", "path": "/apis/v1/social/analytics/youtube/daily-views" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_youtube__9c1330" } }, "/apis/v1/social/analytics/youtube/demographics": { "get": { "description": "Analytics. 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.\n\nReturns audience demographic insights for a YouTube channel, broken down by age, gender, and/or country. Pass videoId to get the audience profile of a single video instead of the whole channel.\n\n- Age and gender values are viewer percentages (0-100).\n- Country values are view counts.\n\nData is based on signed-in viewers only, with a 2-3 day delay. YouTube suppresses demographics for videos with too few signed-in views, so low-traffic videos can return empty breakdowns.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_youtube__2c7672", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "YouTube video ID. When provided, demographics are scoped to this single video\n(must belong to the connected channel; otherwise 404 video_not_found).", "in": "query", "name": "videoId", "required": false, "schema": { "type": "string" } }, { "description": "Comma-separated list of demographic dimensions: age, gender, country.\nDefaults to all three if omitted.", "in": "query", "name": "breakdown", "required": false, "schema": { "type": "string" } }, { "description": "Start date in YYYY-MM-DD format. Defaults to 90 days ago, or to the video's\npublish date (lifetime) when videoId is provided.", "in": "query", "name": "fromDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "End date (YYYY-MM-DD). Defaults to 3 days ago, the newest fully finalized day\n(YouTube finalizes analytics with a ~3-day delay). An explicit toDate is honored\nup to today: days inside the delay window are provisional and may still be revised\nby YouTube (see provisionalSince in the response).", "in": "query", "name": "toDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Alias of fromDate, kept for existing callers", "in": "query", "name": "startDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Alias of toDate, kept for existing callers", "in": "query", "name": "endDate", "required": false, "schema": { "format": "date", "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" }, "dateRange": { "properties": { "endDate": { "type": "string" }, "startDate": { "type": "string" } }, "type": "object" }, "demographics": { "additionalProperties": { "items": { "properties": { "dimension": { "description": "The dimension value (e.g., \"25-34\", \"US\", \"male\")", "type": "string" }, "value": { "description": "Viewer percentage (age/gender) or view count (country)", "type": "number" } }, "type": "object" }, "type": "array" }, "description": "Object keyed by breakdown dimension (age, gender, country)", "type": "object" }, "note": { "type": "string" }, "platform": { "type": "string" }, "provisionalSince": { "description": "Present only when the range reaches into YouTube's ~3-day processing window: the first date whose numbers are provisional and may still be revised by YouTube.", "format": "date", "type": "string" }, "publishedAt": { "description": "Video publish date (video mode only)", "format": "date-time", "type": [ "string", "null" ] }, "success": { "type": "boolean" }, "title": { "description": "Video title (video mode only)", "type": [ "string", "null" ] }, "videoId": { "description": "Present only when demographics are scoped to a single video", "type": "string" } }, "type": "object" } } }, "description": "Demographic insights data" }, "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." } }, "summary": "Get YouTube demographics", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.get_you_tube_demographics@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "a5d06f9fecaf7206d1d730a6f56b7f585c40e23258c08dd5758cb7cd1b227038" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_youtube__2c7672", "method": "GET", "path": "/apis/v1/social/analytics/youtube/demographics" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_youtube__2c7672" } }, "/apis/v1/social/analytics/youtube/video-retention": { "get": { "description": "Analytics. 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.\n\nReturns the audience retention curve for a single YouTube video, plus the video's duration for rendering the curve on a time axis. Requires yt-analytics.readonly scope (re-authorization may be needed).\n\n### The curve\n\n- Up to 100 points (elapsedVideoTimeRatio 0.01-1.0), aggregated over the whole date range. YouTube does not support per-day retention breakdowns.\n- audienceWatchRatio: the absolute share of viewers watching at that point in the video. It can exceed 1 (rewinds and looping, common on Shorts).\n- relativeRetentionPerformance: compares against videos of similar length (0 = worst, 0.5 = median, 1 = best).\n\n### Empty curves\n\nYouTube returns an empty curve for videos with very few views or before analytics processing completes (2-3 day delay).\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_analytics_youtube__5a9837", "parameters": [ { "description": "The YouTube video ID (e.g., \"dQw4w9WgXcQ\")", "in": "query", "name": "videoId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Start date (YYYY-MM-DD). Defaults to the video's publish date (lifetime curve).", "in": "query", "name": "fromDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "End date (YYYY-MM-DD). Defaults to 3 days ago, the newest fully finalized day\n(YouTube finalizes analytics with a ~3-day delay). An explicit toDate is honored\nup to today: days inside the delay window are provisional and may still be revised\nby YouTube (see provisionalSince in the response).", "in": "query", "name": "toDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Alias of fromDate, kept for existing callers", "in": "query", "name": "startDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Alias of toDate, kept for existing callers", "in": "query", "name": "endDate", "required": false, "schema": { "format": "date", "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" }, "dateRange": { "properties": { "endDate": { "format": "date", "type": "string" }, "startDate": { "format": "date", "type": "string" } }, "type": "object" }, "durationSeconds": { "description": "Video length in seconds (from YouTube contentDetails.duration)", "type": [ "integer", "null" ] }, "note": { "description": "Present only when the curve is empty, explaining why", "type": "string" }, "provisionalSince": { "description": "Present only when the range reaches into YouTube's ~3-day processing window: the first date whose numbers are provisional and may still be revised by YouTube.", "format": "date", "type": "string" }, "publishedAt": { "description": "When the video was published on YouTube", "format": "date-time", "type": [ "string", "null" ] }, "retentionCurve": { "description": "Up to 100 points covering the video timeline, aggregated over the date range. Can be empty when YouTube has no retention data for the video in the given range.", "items": { "properties": { "audienceWatchRatio": { "description": "Absolute share of viewers watching at this point. Can exceed 1 (rewinds/looping, common on Shorts).", "type": "number" }, "elapsedVideoTimeRatio": { "description": "Position in the video as a ratio (0.01-1.0, exclusive end of each interval)", "type": "number" }, "relativeRetentionPerformance": { "description": "Retention vs videos of similar length (0 = worst, 0.5 = median, 1 = best)", "type": "number" }, "startedWatching": { "description": "Viewers who started watching in this segment. 0 when YouTube has no segment-level data for the video.", "type": "integer" }, "stoppedWatching": { "description": "Viewers who stopped watching in this segment. 0 when YouTube has no segment-level data for the video.", "type": "integer" }, "totalSegmentImpressions": { "description": "Total views of this segment, including rewatches", "type": "integer" } }, "type": "object" }, "type": "array" }, "scopeStatus": { "properties": { "hasAnalyticsScope": { "type": "boolean" } }, "type": "object" }, "success": { "type": "boolean" }, "title": { "description": "Video title", "type": [ "string", "null" ] }, "videoId": { "description": "The YouTube video ID", "type": "string" } }, "type": "object" } } }, "description": "Audience retention curve" }, "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." } }, "summary": "Get YouTube video retention curve", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.get_you_tube_video_retention@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "0121fade6f3a275d372459fe5c52546b2f0b5b63e95a8f07fb2bf9341a16e7b2" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_analytics_youtube__5a9837", "method": "GET", "path": "/apis/v1/social/analytics/youtube/video-retention" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_analytics_youtube__5a9837" } }, "/apis/v1/social/calendar/availability": { "post": { "description": "Calendar. 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.\n\nSlots of `durationMinutes` every `intervalMinutes` between `from` and `to` that are free for every participant (`collective`) or for at least one (`max_availability`). Buffers pad the participants' existing meetings. Open hours are evaluated in each participant's own timezone; `defaultOpenHours` applies to participants without their own.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_calendar_availability", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "durationMinutes": 5, "from": "2026-11-01T09:00:00Z", "participants": [ { "accountId": "acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3" } ], "to": "2026-11-01T09:00:00Z" }, "schema": { "properties": { "buffer": { "properties": { "after": { "default": 0, "maximum": 240, "minimum": 0, "type": "integer" }, "before": { "default": 0, "maximum": 240, "minimum": 0, "type": "integer" } }, "type": "object" }, "defaultOpenHours": { "items": { "properties": { "days": { "description": "0 = Sunday.", "items": { "maximum": 6, "minimum": 0, "type": "integer" }, "type": "array" }, "end": { "type": "string" }, "exdates": { "description": "Dates to exclude.", "items": { "format": "date", "type": "string" }, "type": "array" }, "start": { "type": "string" }, "timezone": { "type": "string" } }, "required": [ "days", "end", "start", "timezone" ], "type": "object" }, "type": "array" }, "durationMinutes": { "maximum": 480, "minimum": 5, "type": "integer" }, "from": { "format": "date-time", "type": "string" }, "intervalMinutes": { "default": 30, "maximum": 240, "minimum": 5, "type": "integer" }, "method": { "default": "collective", "enum": [ "collective", "max_availability" ], "type": "string" }, "participants": { "items": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "openHours": { "items": { "properties": { "days": { "description": "0 = Sunday.", "items": { "maximum": 6, "minimum": 0, "type": "integer" }, "type": "array" }, "end": { "type": "string" }, "exdates": { "description": "Dates to exclude.", "items": { "format": "date", "type": "string" }, "type": "array" }, "start": { "type": "string" }, "timezone": { "type": "string" } }, "required": [ "days", "end", "start", "timezone" ], "type": "object" }, "type": "array" } }, "required": [ "accountId" ], "type": "object" }, "maxItems": 10, "minItems": 1, "type": "array" }, "roundTo": { "description": "Rounds the first candidate slot up to this many minutes.", "maximum": 60, "minimum": 5, "type": "integer" }, "to": { "format": "date-time", "type": "string" } }, "required": [ "durationMinutes", "from", "participants", "to" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "timeSlots": { "items": { "properties": { "accountIds": { "description": "Your social accounts (acc_...).", "items": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "type": "array" }, "from": { "format": "date-time", "type": "string" }, "to": { "format": "date-time", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } }, "type": "object" } } }, "description": "Candidate slots" }, "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." } }, "summary": "Find meeting slots across accounts", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.calendar.calendar_availability@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "54518755c8c3cfd31e4af0c44a3f28e69d9cbed37c52eb30b44f0d5ca7a006a0" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_calendar_availability", "method": "POST", "path": "/apis/v1/social/calendar/availability" }, "x-codeSamples": [ { "lang": "text", "label": "Reference example", "source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/social/calendar/availability \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"durationMinutes\": 5,\n \"from\": \"2026-11-01T09:00:00Z\",\n \"participants\": [\n {\n \"accountId\": \"acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3\"\n }\n ],\n \"to\": \"2026-11-01T09:00:00Z\"\n}'" } ], "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_calendar_availability" } }, "/apis/v1/social/calendar/calendars": { "get": { "description": "Calendar. 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.\n\nThe account must have been connected with `scopes=calendar` (412 `account_scope_missing` otherwise).\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_calendar_calendars", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "color": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "primary": { "type": "boolean" }, "provider": { "enum": [ "google", "microsoft" ], "type": "string" }, "readOnly": { "type": "boolean" }, "timezone": { "type": [ "string", "null" ] } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Calendars" }, "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." } }, "summary": "List calendars", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.calendar.list_calendars@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "471b261dadb44e278d131e9b9c35abaf03bbbed19cf9d9deae35f79aa59311bc" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_calendar_calendars", "method": "GET", "path": "/apis/v1/social/calendar/calendars" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_calendar_calendars" } }, "/apis/v1/social/calendar/events": { "get": { "description": "Calendar. 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.\n\nRecurring series are expanded into their occurrences inside the window by default (`expandRecurring=false` lists the masters instead). `title` and `location` are substring matches applied to the fetched page.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_calendar_events", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Defaults to the primary calendar.", "in": "query", "name": "calendarId", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "from", "required": true, "schema": { "format": "date-time", "type": "string" } }, { "in": "query", "name": "to", "required": true, "schema": { "format": "date-time", "type": "string" } }, { "in": "query", "name": "title", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "location", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "showCancelled", "required": false, "schema": { "default": false, "type": "boolean" } }, { "in": "query", "name": "expandRecurring", "required": false, "schema": { "default": true, "type": "boolean" } }, { "in": "query", "name": "icalUid", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sortOrder", "required": false, "schema": { "default": "asc", "enum": [ "asc", "desc" ], "type": "string" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "type": "integer" } }, { "description": "IANA zone the `start` and `end` offsets are rendered in. Default UTC.", "in": "query", "name": "timezone", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "allDay": { "type": "boolean" }, "busy": { "type": "boolean" }, "calendarId": { "type": "string" }, "conferencing": { "properties": { "provider": { "enum": [ "google_meet", "teams", "other" ], "type": "string" }, "url": { "format": "uri", "type": "string" } }, "type": [ "object", "null" ] }, "createdAt": { "format": "date-time", "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "end": { "type": "string" }, "htmlLink": { "type": [ "string", "null" ] }, "icalUid": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "location": { "type": [ "string", "null" ] }, "masterEventId": { "type": [ "string", "null" ] }, "metadata": { "additionalProperties": { "type": "string" }, "type": "object" }, "organizer": { "oneOf": [ { "properties": { "email": { "format": "email", "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "email" ], "type": "object" }, { "type": "null" } ] }, "participants": { "items": { "properties": { "comment": { "type": [ "string", "null" ] }, "email": { "format": "email", "type": "string" }, "name": { "type": [ "string", "null" ] }, "status": { "enum": [ "accepted", "declined", "tentative", "pending" ], "type": "string" } }, "required": [ "email" ], "type": "object" }, "type": "array" }, "provider": { "enum": [ "google", "microsoft" ], "type": "string" }, "readOnly": { "type": "boolean" }, "recurrence": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "reminders": { "properties": { "overrides": { "items": { "properties": { "minutes": { "type": "integer" } }, "type": "object" }, "type": "array" }, "useDefault": { "type": "boolean" } }, "type": "object" }, "start": { "description": "ISO date-time with the rendered offset, or a date for all-day events.", "type": "string" }, "status": { "enum": [ "confirmed", "tentative", "cancelled" ], "type": "string" }, "timezone": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "updatedAt": { "format": "date-time", "type": [ "string", "null" ] }, "visibility": { "enum": [ "default", "public", "private" ], "type": "string" } }, "type": "object" }, "type": "array" }, "pagination": { "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "description": "Opaque; pass it back as `cursor`.", "type": [ "string", "null" ] } }, "type": "object" } }, "type": "object" } } }, "description": "Events" }, "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." } }, "summary": "List events in a window", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.calendar.list_calendar_events@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "06eb6d7e82971591baeb8aee12846f02cdf094e5c9ba268310b9e1caa7d6edfe" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_calendar_events", "method": "GET", "path": "/apis/v1/social/calendar/events" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_calendar_events" }, "post": { "description": "Calendar. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nCreates a calendar event. Conferencing and recurrence behave differently on Microsoft and Google accounts.\n\n### Microsoft accounts\n\n- `conferencing: teams` adds a Teams meeting. The created event comes back with `conferencing: null` when the tenant has no Teams (the EEA Business Basic SKUs ship without it).\n- `google_meet` is rejected with 400 (`param: conferencing`).\n\n### Google accounts\n\n- `conferencing: google_meet` adds a Meet link.\n- `teams` is rejected with 400.\n- `recurrence` accepts any RRULE Google Calendar supports.\n\n### Recurrence\n\n`recurrence` takes one RRULE line with FREQ, INTERVAL, COUNT, UNTIL, BYDAY and BYSETPOS. Other parts are rejected with 400 (`param: recurrence`).\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_calendar_events", "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" }, "allDay": { "type": "boolean" }, "busy": { "type": "boolean" }, "calendarId": { "description": "Defaults to the primary calendar.", "type": "string" }, "conferencing": { "enum": [ "google_meet", "teams" ], "type": "string" }, "description": { "description": "HTML.", "type": "string" }, "end": { "description": "Exclusive for all-day events.", "type": "string" }, "location": { "type": "string" }, "metadata": { "additionalProperties": { "type": "string" }, "type": "object" }, "participants": { "items": { "properties": { "email": { "format": "email", "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "email" ], "type": "object" }, "maxItems": 100, "type": "array" }, "recurrence": { "description": "RRULE lines, e.g. `RRULE:FREQ=WEEKLY;BYDAY=MO,WE;COUNT=10`.", "items": { "type": "string" }, "maxItems": 5, "type": "array" }, "reminders": { "properties": { "overrides": { "items": { "properties": { "minutes": { "type": "integer" } }, "type": "object" }, "maxItems": 5, "type": "array" }, "useDefault": { "type": "boolean" } }, "type": "object" }, "start": { "description": "ISO date-time, or a date (`YYYY-MM-DD`) for all-day events.", "type": "string" }, "timezone": { "description": "IANA zone the event is scheduled in. Default UTC.", "type": "string" }, "title": { "maxLength": 1000, "type": "string" }, "visibility": { "enum": [ "default", "public", "private" ], "type": "string" } }, "required": [ "accountId" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "allDay": { "type": "boolean" }, "busy": { "type": "boolean" }, "calendarId": { "type": "string" }, "conferencing": { "properties": { "provider": { "enum": [ "google_meet", "teams", "other" ], "type": "string" }, "url": { "format": "uri", "type": "string" } }, "type": [ "object", "null" ] }, "createdAt": { "format": "date-time", "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "end": { "type": "string" }, "htmlLink": { "type": [ "string", "null" ] }, "icalUid": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "location": { "type": [ "string", "null" ] }, "masterEventId": { "type": [ "string", "null" ] }, "metadata": { "additionalProperties": { "type": "string" }, "type": "object" }, "organizer": { "oneOf": [ { "properties": { "email": { "format": "email", "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "email" ], "type": "object" }, { "type": "null" } ] }, "participants": { "items": { "properties": { "comment": { "type": [ "string", "null" ] }, "email": { "format": "email", "type": "string" }, "name": { "type": [ "string", "null" ] }, "status": { "enum": [ "accepted", "declined", "tentative", "pending" ], "type": "string" } }, "required": [ "email" ], "type": "object" }, "type": "array" }, "provider": { "enum": [ "google", "microsoft" ], "type": "string" }, "readOnly": { "type": "boolean" }, "recurrence": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "reminders": { "properties": { "overrides": { "items": { "properties": { "minutes": { "type": "integer" } }, "type": "object" }, "type": "array" }, "useDefault": { "type": "boolean" } }, "type": "object" }, "start": { "description": "ISO date-time with the rendered offset, or a date for all-day events.", "type": "string" }, "status": { "enum": [ "confirmed", "tentative", "cancelled" ], "type": "string" }, "timezone": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "updatedAt": { "format": "date-time", "type": [ "string", "null" ] }, "visibility": { "enum": [ "default", "public", "private" ], "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "The created event" }, "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." } }, "summary": "Create an event", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.calendar.create_calendar_event@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "ed2e2cb23c8e9829e73b63976d3de61044cf1420204cc6189ff10884c8a18a4b" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_calendar_events", "method": "POST", "path": "/apis/v1/social/calendar/events" }, "x-codeSamples": [ { "lang": "text", "label": "Reference example", "source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/social/calendar/events \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"accountId\": \"acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3\"\n}'" } ], "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_calendar_events" } }, "/apis/v1/social/calendar/events/{eventId}": { "delete": { "description": "Calendar. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "delete_aisa_social_apis_v1_social_calendar_events_9409b5", "parameters": [ { "in": "path", "name": "eventId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "The calendar holding the event (an id from GET /apis/v1/social/calendar/calendars). Defaults to the primary calendar.", "in": "query", "name": "calendarId", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "deleted": { "type": "boolean" }, "id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Deleted" }, "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." } }, "summary": "Delete an event", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.calendar.delete_calendar_event@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "dbf11fc8993ed64411d05d5a3406d9958f27dcb2d1f49148f08c7c493c735c8b" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "delete_aisa_social_apis_v1_social_calendar_events_9409b5", "method": "DELETE", "path": "/apis/v1/social/calendar/events/{eventId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/delete_aisa_social_apis_v1_social_calendar_events_9409b5" }, "get": { "description": "Calendar. 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.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_calendar_events_eventid", "parameters": [ { "in": "path", "name": "eventId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "The calendar holding the event (an id from GET /apis/v1/social/calendar/calendars). Defaults to the primary calendar.", "in": "query", "name": "calendarId", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "timezone", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "allDay": { "type": "boolean" }, "busy": { "type": "boolean" }, "calendarId": { "type": "string" }, "conferencing": { "properties": { "provider": { "enum": [ "google_meet", "teams", "other" ], "type": "string" }, "url": { "format": "uri", "type": "string" } }, "type": [ "object", "null" ] }, "createdAt": { "format": "date-time", "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "end": { "type": "string" }, "htmlLink": { "type": [ "string", "null" ] }, "icalUid": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "location": { "type": [ "string", "null" ] }, "masterEventId": { "type": [ "string", "null" ] }, "metadata": { "additionalProperties": { "type": "string" }, "type": "object" }, "organizer": { "oneOf": [ { "properties": { "email": { "format": "email", "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "email" ], "type": "object" }, { "type": "null" } ] }, "participants": { "items": { "properties": { "comment": { "type": [ "string", "null" ] }, "email": { "format": "email", "type": "string" }, "name": { "type": [ "string", "null" ] }, "status": { "enum": [ "accepted", "declined", "tentative", "pending" ], "type": "string" } }, "required": [ "email" ], "type": "object" }, "type": "array" }, "provider": { "enum": [ "google", "microsoft" ], "type": "string" }, "readOnly": { "type": "boolean" }, "recurrence": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "reminders": { "properties": { "overrides": { "items": { "properties": { "minutes": { "type": "integer" } }, "type": "object" }, "type": "array" }, "useDefault": { "type": "boolean" } }, "type": "object" }, "start": { "description": "ISO date-time with the rendered offset, or a date for all-day events.", "type": "string" }, "status": { "enum": [ "confirmed", "tentative", "cancelled" ], "type": "string" }, "timezone": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "updatedAt": { "format": "date-time", "type": [ "string", "null" ] }, "visibility": { "enum": [ "default", "public", "private" ], "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "The event" }, "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." } }, "summary": "Get an event", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.calendar.get_calendar_event@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "68670cf321ccd1eb10302417405ffbd0f2fafb612faa0853a320c1b11399f6cb" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_calendar_events_eventid", "method": "GET", "path": "/apis/v1/social/calendar/events/{eventId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_calendar_events_eventid" }, "patch": { "description": "Calendar. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "patch_aisa_social_apis_v1_social_calendar_events_eventid", "parameters": [ { "in": "path", "name": "eventId", "required": true, "schema": { "type": "string" } } ], "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" }, "allDay": { "type": "boolean" }, "busy": { "type": "boolean" }, "calendarId": { "description": "The calendar holding the event (an id from GET /apis/v1/social/calendar/calendars). Defaults to the primary calendar.", "type": "string" }, "conferencing": { "enum": [ "google_meet", "teams" ], "type": "string" }, "description": { "description": "HTML.", "type": "string" }, "end": { "description": "Exclusive for all-day events.", "type": "string" }, "location": { "type": "string" }, "metadata": { "additionalProperties": { "type": "string" }, "type": "object" }, "participants": { "items": { "properties": { "email": { "format": "email", "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "email" ], "type": "object" }, "maxItems": 100, "type": "array" }, "recurrence": { "description": "RRULE lines, e.g. `RRULE:FREQ=WEEKLY;BYDAY=MO,WE;COUNT=10`.", "items": { "type": "string" }, "maxItems": 5, "type": "array" }, "reminders": { "properties": { "overrides": { "items": { "properties": { "minutes": { "type": "integer" } }, "type": "object" }, "maxItems": 5, "type": "array" }, "useDefault": { "type": "boolean" } }, "type": "object" }, "start": { "description": "ISO date-time, or a date (`YYYY-MM-DD`) for all-day events.", "type": "string" }, "timezone": { "description": "IANA zone the event is scheduled in. Default UTC.", "type": "string" }, "title": { "maxLength": 1000, "type": "string" }, "visibility": { "enum": [ "default", "public", "private" ], "type": "string" } }, "required": [ "accountId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "allDay": { "type": "boolean" }, "busy": { "type": "boolean" }, "calendarId": { "type": "string" }, "conferencing": { "properties": { "provider": { "enum": [ "google_meet", "teams", "other" ], "type": "string" }, "url": { "format": "uri", "type": "string" } }, "type": [ "object", "null" ] }, "createdAt": { "format": "date-time", "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "end": { "type": "string" }, "htmlLink": { "type": [ "string", "null" ] }, "icalUid": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "location": { "type": [ "string", "null" ] }, "masterEventId": { "type": [ "string", "null" ] }, "metadata": { "additionalProperties": { "type": "string" }, "type": "object" }, "organizer": { "oneOf": [ { "properties": { "email": { "format": "email", "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "email" ], "type": "object" }, { "type": "null" } ] }, "participants": { "items": { "properties": { "comment": { "type": [ "string", "null" ] }, "email": { "format": "email", "type": "string" }, "name": { "type": [ "string", "null" ] }, "status": { "enum": [ "accepted", "declined", "tentative", "pending" ], "type": "string" } }, "required": [ "email" ], "type": "object" }, "type": "array" }, "provider": { "enum": [ "google", "microsoft" ], "type": "string" }, "readOnly": { "type": "boolean" }, "recurrence": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "reminders": { "properties": { "overrides": { "items": { "properties": { "minutes": { "type": "integer" } }, "type": "object" }, "type": "array" }, "useDefault": { "type": "boolean" } }, "type": "object" }, "start": { "description": "ISO date-time with the rendered offset, or a date for all-day events.", "type": "string" }, "status": { "enum": [ "confirmed", "tentative", "cancelled" ], "type": "string" }, "timezone": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "updatedAt": { "format": "date-time", "type": [ "string", "null" ] }, "visibility": { "enum": [ "default", "public", "private" ], "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "The updated event" }, "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." } }, "summary": "Update an event", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.calendar.update_calendar_event@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "6dc3a9db678db1d03aa8314b73d0af827c8a1a324778c20c0247f2ece99c9f32" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "patch_aisa_social_apis_v1_social_calendar_events_eventid", "method": "PATCH", "path": "/apis/v1/social/calendar/events/{eventId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/patch_aisa_social_apis_v1_social_calendar_events_eventid" } }, "/apis/v1/social/calendar/events/{eventId}/rsvp": { "post": { "description": "Calendar. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nAccepts, declines or tentatively accepts on behalf of the mailbox and notifies the organizer.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_calendar_events_e_5f31af", "parameters": [ { "in": "path", "name": "eventId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "accountId": "acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3", "status": "accepted" }, "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "calendarId": { "description": "The calendar holding the event (an id from GET /apis/v1/social/calendar/calendars). Defaults to the primary calendar.", "type": "string" }, "comment": { "maxLength": 1000, "type": "string" }, "status": { "enum": [ "accepted", "declined", "tentative" ], "type": "string" } }, "required": [ "accountId", "status" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "allDay": { "type": "boolean" }, "busy": { "type": "boolean" }, "calendarId": { "type": "string" }, "conferencing": { "properties": { "provider": { "enum": [ "google_meet", "teams", "other" ], "type": "string" }, "url": { "format": "uri", "type": "string" } }, "type": [ "object", "null" ] }, "createdAt": { "format": "date-time", "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "end": { "type": "string" }, "htmlLink": { "type": [ "string", "null" ] }, "icalUid": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "location": { "type": [ "string", "null" ] }, "masterEventId": { "type": [ "string", "null" ] }, "metadata": { "additionalProperties": { "type": "string" }, "type": "object" }, "organizer": { "oneOf": [ { "properties": { "email": { "format": "email", "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "email" ], "type": "object" }, { "type": "null" } ] }, "participants": { "items": { "properties": { "comment": { "type": [ "string", "null" ] }, "email": { "format": "email", "type": "string" }, "name": { "type": [ "string", "null" ] }, "status": { "enum": [ "accepted", "declined", "tentative", "pending" ], "type": "string" } }, "required": [ "email" ], "type": "object" }, "type": "array" }, "provider": { "enum": [ "google", "microsoft" ], "type": "string" }, "readOnly": { "type": "boolean" }, "recurrence": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "reminders": { "properties": { "overrides": { "items": { "properties": { "minutes": { "type": "integer" } }, "type": "object" }, "type": "array" }, "useDefault": { "type": "boolean" } }, "type": "object" }, "start": { "description": "ISO date-time with the rendered offset, or a date for all-day events.", "type": "string" }, "status": { "enum": [ "confirmed", "tentative", "cancelled" ], "type": "string" }, "timezone": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "updatedAt": { "format": "date-time", "type": [ "string", "null" ] }, "visibility": { "enum": [ "default", "public", "private" ], "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "The event after the response" }, "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." } }, "summary": "Respond to an invitation", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.calendar.rsvp_calendar_event@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "7e35d72d2d262fc596ef4817893d81bf0e4eb23f8fda67bea7352aa5418b4500" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_calendar_events_e_5f31af", "method": "POST", "path": "/apis/v1/social/calendar/events/{eventId}/rsvp" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_calendar_events_e_5f31af" } }, "/apis/v1/social/calendar/free-busy": { "post": { "description": "Calendar. 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.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_calendar_free_busy", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "accountIds": [ "acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3" ], "from": "2026-11-01T09:00:00Z", "to": "2026-11-01T09:00:00Z" }, "schema": { "properties": { "accountIds": { "description": "Your social accounts (acc_...).", "items": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "type": "array" }, "from": { "format": "date-time", "type": "string" }, "to": { "format": "date-time", "type": "string" } }, "required": [ "accountIds", "from", "to" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "busy": { "items": { "properties": { "end": { "format": "date-time", "type": "string" }, "start": { "format": "date-time", "type": "string" } }, "type": "object" }, "type": "array" }, "from": { "format": "date-time", "type": "string" }, "to": { "format": "date-time", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "One entry per account, busy blocks in UTC" }, "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." } }, "summary": "Busy blocks for one or more accounts", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.calendar.calendar_free_busy@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "469c6186a63644c3ecd48c368e2012e8b9fc86b1d8ec5ba8147d4d1e0c0426f5" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_calendar_free_busy", "method": "POST", "path": "/apis/v1/social/calendar/free-busy" }, "x-codeSamples": [ { "lang": "text", "label": "Reference example", "source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/social/calendar/free-busy \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"accountIds\": [\n \"acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3\"\n ],\n \"from\": \"2026-11-01T09:00:00Z\",\n \"to\": \"2026-11-01T09:00:00Z\"\n}'" } ], "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_calendar_free_busy" } }, "/apis/v1/social/connect/microsoft/admin-consent": { "get": { "description": "For a Microsoft 365 tenant that lets no user grant mail or calendar access: a link, valid one hour, for a tenant administrator to approve. Later requests on the account then succeed without a reconnect.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_connect_microsoft__812d81", "parameters": [ { "description": "A acc_ id.", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "https URL on the caller's allowlist where the administrator lands, with adminConsent=granted or denied.", "in": "query", "name": "redirectUrl", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "adminConsentUrl": { "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Success" }, "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." } }, "summary": "Get a Microsoft admin-consent link", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.connect.microsoft_admin_consent@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "This operation does not settle a customer usage charge.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "9065732290626ab13080bf5ba800147e9c2ba00c5c03d50c3f1d11c46d3860ee" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_connect_microsoft__812d81", "method": "GET", "path": "/apis/v1/social/connect/microsoft/admin-consent" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_connect_microsoft__812d81" } }, "/apis/v1/social/connect/sessions/{sessionId}": { "get": { "description": "Polls the progress of an authorization flow.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_connect_sessions_s_a359aa", "parameters": [ { "in": "path", "name": "sessionId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "accountId": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "createdAt": { "format": "date-time", "type": [ "string", "null" ] }, "error": { "properties": { "code": { "type": [ "string", "null" ] }, "isUserFixable": { "type": [ "boolean", "null" ] }, "message": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "expiresAt": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "platform": { "enum": [ "tiktok", "instagram", "twitter", "youtube", "facebook", "linkedin", "pinterest", "threads", "reddit", "googlebusiness", "googleanalytics", "bluesky", "telegram", "slack", "snapchat", "hubspot", "microsoft", null ], "type": [ "string", "null" ] }, "profileId": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Success" }, "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." } }, "summary": "Get a connect session", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.connect_sessions.get@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "This operation does not settle a customer usage charge.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "e63c91960a3a8ad2dad88e0f99b3ed32900d45eaa88e2c8ffd2ae6798f930caa" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_connect_sessions_s_a359aa", "method": "GET", "path": "/apis/v1/social/connect/sessions/{sessionId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_connect_sessions_s_a359aa" } }, "/apis/v1/social/connect/{platform}": { "get": { "description": "Returns an AIsa-hosted authorization URL valid for 30 minutes. A profile can hold several accounts of the same platform; reconnecting an account keeps its id and history.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_connect_platform", "parameters": [ { "description": "A prf_ id.", "in": "query", "name": "profileId", "required": false, "schema": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "https URL on the caller's allowlist; the browser returns here with connectSessionId and accountId or error. Defaults to the AIsa result page.", "in": "query", "name": "redirectUrl", "required": false, "schema": { "type": "string" } }, { "description": "A acc_ id.", "in": "query", "name": "reconnectAccountId", "required": false, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "in": "path", "name": "platform", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "authUrl": { "type": [ "string", "null" ] }, "connectSessionId": { "pattern": "^cs_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "expiresAt": { "format": "date-time", "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Success" }, "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." } }, "summary": "Start connecting an account", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.connect.start@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "This operation does not settle a customer usage charge.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "6afe4eaa391bbe1d9b5b234df1cf9e43ba4b67a7be4d1a0454d474feffcc73f8" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_connect_platform", "method": "GET", "path": "/apis/v1/social/connect/{platform}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_connect_platform" } }, "/apis/v1/social/connect/{platform}/credentials": { "post": { "description": "Connects a Bluesky account (identifier and an app password) or a Telegram channel or group (chatId; the connecting bot must already be an administrator there) without an authorization flow. The credentials go to the channel once and are never stored or logged. Answers the completed connect session, with the new account's id.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_connect_platform__55a0d6", "parameters": [ { "in": "path", "name": "platform", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "appPassword": "abcd-efgh-ijkl-mnop", "identifier": "brand.bsky.social", "profileId": "prf_2Bn8Wq5Td1Yh7Kc3Mz9Lp4" }, "schema": { "additionalProperties": false, "properties": { "appPassword": { "type": [ "string", "null" ] }, "chatId": { "type": [ "string", "null" ] }, "identifier": { "type": [ "string", "null" ] }, "profileId": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "accountId": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "createdAt": { "format": "date-time", "type": [ "string", "null" ] }, "error": { "properties": { "code": { "type": [ "string", "null" ] }, "isUserFixable": { "type": [ "boolean", "null" ] }, "message": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "expiresAt": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "platform": { "enum": [ "tiktok", "instagram", "twitter", "youtube", "facebook", "linkedin", "pinterest", "threads", "reddit", "googlebusiness", "googleanalytics", "bluesky", "telegram", "slack", "snapchat", "hubspot", "microsoft", null ], "type": [ "string", "null" ] }, "profileId": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Success" }, "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." } }, "summary": "Connect an account with credentials", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.connect.credentials@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "This operation does not settle a customer usage charge.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "2f6795dc7d343917edf98610e4396e680c52aa2ccbeb778247b429efe8fcf641" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_connect_platform__55a0d6", "method": "POST", "path": "/apis/v1/social/connect/{platform}/credentials" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_connect_platform__55a0d6" } }, "/apis/v1/social/contacts": { "get": { "description": "Contacts. 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. Without profileId or accountId it reads your default profile.\n\nList and search contacts for a profile. Supports filtering by tags, platform, subscription status, and text search on name, email and company.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_contacts", "parameters": [ { "description": "One of your profiles (prf_...). Defaults to your default profile when neither profileId nor accountId is sent.", "in": "query", "name": "profileId", "required": false, "schema": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": false, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Case-insensitive substring match on the contact name, email and company. Phone numbers and other platform identifiers are not matched: they live on the contact channel, not on the contact. To reach a contact from an inbox webhook, use the conversation.contactId it already carries.", "in": "query", "name": "search", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "tag", "required": false, "schema": { "type": "string" } }, { "description": "Comma-separated tags, matches contacts carrying any of them", "in": "query", "name": "tags", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "platform", "required": false, "schema": { "enum": [ "instagram", "facebook", "telegram", "twitter", "bluesky", "reddit", "whatsapp", "slack", "sms" ], "type": "string" } }, { "in": "query", "name": "isSubscribed", "required": false, "schema": { "enum": [ "true", "false" ], "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "type": "integer" } }, { "in": "query", "name": "skip", "required": false, "schema": { "default": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "contacts": { "items": { "properties": { "avatarUrl": { "type": "string" }, "company": { "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "customFields": { "type": "object" }, "displayIdentifier": { "type": "string" }, "email": { "type": "string" }, "id": { "type": "string" }, "isBlocked": { "type": "boolean" }, "isSubscribed": { "type": "boolean" }, "lastMessageReceivedAt": { "format": "date-time", "type": "string" }, "lastMessageSentAt": { "format": "date-time", "type": "string" }, "messagesReceivedCount": { "type": "integer" }, "messagesSentCount": { "type": "integer" }, "name": { "type": "string" }, "notes": { "type": "string" }, "platform": { "type": "string" }, "platformIdentifier": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "type": "array" }, "filters": { "properties": { "tags": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "pagination": { "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer" }, "skip": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Contacts list with pagination and filter metadata" }, "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." } }, "summary": "List contacts", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.contacts.list_contacts@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "622d0b618aea8c2436a4a646218e4733202f43ec4fb8969a21a79071b43ed24d" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_contacts", "method": "GET", "path": "/apis/v1/social/contacts" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_contacts" }, "post": { "description": "Contacts. 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.\n\nCreate a new contact. Optionally create a platform channel in the same request by providing accountId, platform, and platformIdentifier.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_contacts", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "name": "example", "profileId": "prf_2Bn8Wq5Td1Yh7Kc3Mz9Lp4" }, "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "company": { "type": "string" }, "displayIdentifier": { "type": "string" }, "email": { "type": "string" }, "isSubscribed": { "default": true, "type": "boolean" }, "name": { "type": "string" }, "notes": { "type": "string" }, "platform": { "description": "Channel platform. Only the enum values support contact channels; any other platform is rejected with code platform_not_supported.", "enum": [ "instagram", "facebook", "telegram", "twitter", "bluesky", "reddit", "whatsapp", "slack", "sms" ], "type": "string" }, "platformIdentifier": { "type": "string" }, "profileId": { "description": "One of your profiles (prf_...).", "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" } }, "required": [ "name", "profileId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "channel": { "description": "Created when accountId, platform, and platformIdentifier are provided", "properties": { "displayIdentifier": { "type": "string" }, "id": { "type": "string" }, "platform": { "type": "string" }, "platformIdentifier": { "type": "string" } }, "type": "object" }, "contact": { "properties": { "company": { "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "customFields": { "type": "object" }, "email": { "type": "string" }, "id": { "type": "string" }, "isBlocked": { "type": "boolean" }, "isSubscribed": { "type": "boolean" }, "name": { "type": "string" }, "notes": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "success": { "type": "boolean" }, "warning": { "type": "string" } }, "type": "object" } } }, "description": "Contact created" }, "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." } }, "summary": "Create contact", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.contacts.create_contact@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "570ce59c76278fe596da1b1c43fc5d52e5361e4de4c82d468913967861ffd7b8" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_contacts", "method": "POST", "path": "/apis/v1/social/contacts" }, "x-codeSamples": [ { "lang": "text", "label": "Reference example", "source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/social/contacts \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"name\": \"example\",\n \"profileId\": \"prf_2Bn8Wq5Td1Yh7Kc3Mz9Lp4\"\n}'" } ], "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_contacts" } }, "/apis/v1/social/contacts/bulk": { "post": { "description": "Contacts. 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.\n\nImport up to 1000 contacts at a time. Skips duplicates, merging any new tags onto the existing contact.\n\n### Accounts and platform\n\n- accountId is required whenever contacts carry a platformIdentifier (or a row-level accountId).\n- platform is always derived from the resolved account, never used to decide whether channels are created. A mismatched platform 404s as account not found.\n\n### Per-contact validation\n\n- When accountId is set, each contact must carry a platformIdentifier. A row missing it is rejected individually (reported in errors[], HTTP 200), not a 400 for the whole import.\n- On phone platforms (whatsapp, sms) the platformIdentifier is normalized to digits. A value that is not phone-shaped is rejected per contact and reported in errors[], not imported.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_contacts_bulk", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "contacts": [ { "name": "example" } ], "profileId": "prf_2Bn8Wq5Td1Yh7Kc3Mz9Lp4" }, "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "contacts": { "items": { "properties": { "company": { "type": "string" }, "displayIdentifier": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" }, "platformIdentifier": { "description": "Required when the top-level accountId is set (channel mode). A row missing it in that mode is rejected individually and reported in errors[], not a 400 for the whole import.", "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" } }, "required": [ "name" ], "type": "object" }, "maxItems": 1000, "type": "array" }, "platform": { "description": "Ignored when accountId is set: the platform is derived from the resolved account. Only relevant to disambiguate accountId lookup; a mismatch 404s.", "type": "string" }, "profileId": { "description": "One of your profiles (prf_...).", "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" } }, "required": [ "contacts", "profileId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created": { "type": "integer" }, "errors": { "description": "Per-contact failures, e.g. an identifier that is not a valid phone number", "items": { "type": "string" }, "type": "array" }, "skipped": { "type": "integer" }, "success": { "type": "boolean" }, "total": { "type": "integer" } }, "type": "object" } } }, "description": "Bulk import results" }, "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." } }, "summary": "Bulk create contacts", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.contacts.bulk_create_contacts@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "5c237eadd9363fcf69a46f3357a7938c7946ba0ddf778760ba4fbaefd82e08b6" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_contacts_bulk", "method": "POST", "path": "/apis/v1/social/contacts/bulk" }, "x-codeSamples": [ { "lang": "text", "label": "Reference example", "source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/social/contacts/bulk \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"contacts\": [\n {\n \"name\": \"example\"\n }\n ],\n \"profileId\": \"prf_2Bn8Wq5Td1Yh7Kc3Mz9Lp4\"\n}'" } ], "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_contacts_bulk" } }, "/apis/v1/social/contacts/{contactId}": { "delete": { "description": "Contacts. 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.\n\nPermanently deletes a contact and all associated channels.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "delete_aisa_social_apis_v1_social_contacts_contactid", "parameters": [ { "in": "path", "name": "contactId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "An empty object or a success flag.", "properties": { "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Contact deleted" }, "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." } }, "summary": "Delete contact", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.contacts.delete_contact@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "693bc745c6f7ddacbab256c3fd337ac0ecdd00ec1efef8bb08813865ff2ab40d" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "delete_aisa_social_apis_v1_social_contacts_contactid", "method": "DELETE", "path": "/apis/v1/social/contacts/{contactId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/delete_aisa_social_apis_v1_social_contacts_contactid" }, "get": { "description": "Contacts. 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.\n\nReturns a contact with all associated messaging channels.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_contacts_contactid", "parameters": [ { "in": "path", "name": "contactId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "channels": { "items": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "conversationId": { "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "displayIdentifier": { "type": "string" }, "id": { "type": "string" }, "isSubscribed": { "type": "boolean" }, "lastActiveAt": { "description": "Most recent message (either direction) in this channel's conversation, or null if none.", "format": "date-time", "type": [ "string", "null" ] }, "platform": { "type": "string" }, "platformIdentifier": { "type": "string" } }, "type": "object" }, "type": "array" }, "contact": { "properties": { "avatarUrl": { "type": "string" }, "company": { "type": "string" }, "conversationIds": { "items": { "type": "string" }, "type": "array" }, "createdAt": { "format": "date-time", "type": "string" }, "customFields": { "type": "object" }, "email": { "type": "string" }, "id": { "type": "string" }, "isBlocked": { "type": "boolean" }, "isSubscribed": { "type": "boolean" }, "lastMessageReceivedAt": { "description": "Timestamp of the most recent incoming message, or null if none.", "format": "date-time", "type": [ "string", "null" ] }, "lastMessageSentAt": { "description": "Timestamp of the most recent outgoing message, or null if none.", "format": "date-time", "type": [ "string", "null" ] }, "messagesReceivedCount": { "description": "Messages received from the contact, derived live from message history across all linked conversations.", "type": "integer" }, "messagesSentCount": { "description": "Messages sent to the contact, derived live from message history across all linked conversations.", "type": "integer" }, "name": { "type": "string" }, "notes": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" }, "updatedAt": { "format": "date-time", "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Contact with channels" }, "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." } }, "summary": "Get contact", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.contacts.get_contact@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "f775ac08d1e63d09dbc2ca0708f3d34f28a3ceef6f1bb6a97e63806fdc79218c" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_contacts_contactid", "method": "GET", "path": "/apis/v1/social/contacts/{contactId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_contacts_contactid" }, "patch": { "description": "Contacts. 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.\n\nUpdate one or more fields on a contact. Only provided fields are changed.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "patch_aisa_social_apis_v1_social_contacts_contactid", "parameters": [ { "in": "path", "name": "contactId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "properties": { "avatarUrl": { "type": "string" }, "company": { "type": "string" }, "email": { "type": "string" }, "isBlocked": { "type": "boolean" }, "isSubscribed": { "type": "boolean" }, "name": { "type": "string" }, "notes": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "contact": { "properties": { "avatarUrl": { "type": "string" }, "company": { "type": "string" }, "email": { "type": "string" }, "id": { "type": "string" }, "isBlocked": { "type": "boolean" }, "isSubscribed": { "type": "boolean" }, "name": { "type": "string" }, "notes": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" }, "updatedAt": { "format": "date-time", "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Contact 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": { "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." } }, "summary": "Update contact", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.contacts.update_contact@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "78f87da71b7ed0320f5580b3a7dd5fa293f80425997a09a2cd82b1707deb84a2" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "patch_aisa_social_apis_v1_social_contacts_contactid", "method": "PATCH", "path": "/apis/v1/social/contacts/{contactId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/patch_aisa_social_apis_v1_social_contacts_contactid" } }, "/apis/v1/social/contacts/{contactId}/channels": { "get": { "description": "Contacts. 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.\n\nReturns all messaging channels linked to a contact (e.g. Instagram DM, Telegram, WhatsApp).\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_contacts_contactid_b95a4c", "parameters": [ { "in": "path", "name": "contactId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "channels": { "items": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "conversationId": { "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "displayIdentifier": { "type": "string" }, "id": { "type": "string" }, "isSubscribed": { "type": "boolean" }, "metadata": { "type": "object" }, "platform": { "type": "string" }, "platformIdentifier": { "type": "string" } }, "type": "object" }, "type": "array" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "List of contact channels" }, "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." } }, "summary": "List channels for a contact", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.contacts.get_contact_channels@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "f6b8c5ba28a8e7cf3281e84c3c7bd0fcf1172b600ada9f66f2afccd398bbd56e" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_contacts_contactid_b95a4c", "method": "GET", "path": "/apis/v1/social/contacts/{contactId}/channels" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_contacts_contactid_b95a4c" } }, "/apis/v1/social/contacts/{contactId}/fields/{slug}": { "delete": { "description": "Custom Fields. 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.\n\nRemove a custom field value from a contact. The field definition is not affected.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "delete_aisa_social_apis_v1_social_contacts_contac_615528", "parameters": [ { "in": "path", "name": "contactId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "An empty object or a success flag.", "properties": { "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Field value cleared" }, "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." } }, "summary": "Clear custom field value", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.custom_fields.clear_contact_field_value@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "1d246af93224125e36419eab0d08a3b598c9df0b7917fef1a69bcf8bef1f604f" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "delete_aisa_social_apis_v1_social_contacts_contac_615528", "method": "DELETE", "path": "/apis/v1/social/contacts/{contactId}/fields/{slug}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/delete_aisa_social_apis_v1_social_contacts_contac_615528" }, "put": { "description": "Custom Fields. 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.\n\nSet or overwrite a custom field value on a contact. The value type must match the field definition.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "put_aisa_social_apis_v1_social_contacts_contactid_615528", "parameters": [ { "in": "path", "name": "contactId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "value": "example" }, "schema": { "properties": { "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "items": {}, "type": "array" }, { "type": "object" } ], "description": "Field value (type depends on field definition)" } }, "required": [ "value" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "An empty object or a success flag.", "properties": { "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Field value set" }, "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." } }, "summary": "Set custom field value", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.custom_fields.set_contact_field_value@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "a1fd74dc6c03a885c14c9f040592b2c86f39483a4ca9543f2964d43bc11d8dce" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "put_aisa_social_apis_v1_social_contacts_contactid_615528", "method": "PUT", "path": "/apis/v1/social/contacts/{contactId}/fields/{slug}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/put_aisa_social_apis_v1_social_contacts_contactid_615528" } }, "/apis/v1/social/custom-fields": { "get": { "description": "Custom Fields. 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. Without profileId or accountId it reads your default profile.\n\nReturns all custom field definitions. Optionally filter by profile.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_custom_fields", "parameters": [ { "description": "One of your profiles (prf_...). Defaults to your default profile when neither profileId nor accountId is sent.", "in": "query", "name": "profileId", "required": false, "schema": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "fields": { "items": { "properties": { "createdAt": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "options": { "items": { "type": "string" }, "type": "array" }, "slug": { "type": "string" }, "type": { "enum": [ "text", "number", "date", "boolean", "select" ], "type": "string" } }, "type": "object" }, "type": "array" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "List of custom field definitions" }, "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." } }, "summary": "List custom field definitions", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.custom_fields.list_custom_fields@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "46ac3f02b1ac706ebb9a7a91f4639c95217b17f8c7b1ff610af4667b62f7e367" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_custom_fields", "method": "GET", "path": "/apis/v1/social/custom-fields" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_custom_fields" }, "post": { "description": "Custom Fields. 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.\n\nCreate a new custom field definition. Supported types are text, number, date, boolean, and select.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_custom_fields", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "name": "example", "profileId": "prf_2Bn8Wq5Td1Yh7Kc3Mz9Lp4", "type": "text" }, "schema": { "properties": { "name": { "type": "string" }, "options": { "description": "Required for select type", "items": { "type": "string" }, "type": "array" }, "profileId": { "description": "One of your profiles (prf_...).", "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" }, "slug": { "description": "Auto-generated from name if not provided", "type": "string" }, "type": { "enum": [ "text", "number", "date", "boolean", "select" ], "type": "string" } }, "required": [ "name", "profileId", "type" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "field": { "properties": { "createdAt": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "options": { "items": { "type": "string" }, "type": "array" }, "slug": { "type": "string" }, "type": { "enum": [ "text", "number", "date", "boolean", "select" ], "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Custom field created" }, "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." } }, "summary": "Create custom field", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.custom_fields.create_custom_field@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "5e15bda98e2d800b5d875ff99bdf965c74ff0f3529db0cc07cfb85fdb622aa13" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_custom_fields", "method": "POST", "path": "/apis/v1/social/custom-fields" }, "x-codeSamples": [ { "lang": "text", "label": "Reference example", "source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/social/custom-fields \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"name\": \"example\",\n \"profileId\": \"prf_2Bn8Wq5Td1Yh7Kc3Mz9Lp4\",\n \"type\": \"text\"\n}'" } ], "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_custom_fields" } }, "/apis/v1/social/custom-fields/{fieldId}": { "delete": { "description": "Custom Fields. 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.\n\nDelete a custom field definition and remove its values from all contacts.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "delete_aisa_social_apis_v1_social_custom_fields_fieldid", "parameters": [ { "in": "path", "name": "fieldId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "An empty object or a success flag.", "properties": { "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Custom field deleted" }, "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." } }, "summary": "Delete custom field", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.custom_fields.delete_custom_field@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "b30d1a1b440f7e0c579461fb8bb25b7ea5633f24d91d58c07b11f19604d2b412" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "delete_aisa_social_apis_v1_social_custom_fields_fieldid", "method": "DELETE", "path": "/apis/v1/social/custom-fields/{fieldId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/delete_aisa_social_apis_v1_social_custom_fields_fieldid" }, "patch": { "description": "Custom Fields. 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.\n\nUpdate a custom field definition. The field type cannot be changed after creation.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "patch_aisa_social_apis_v1_social_custom_fields_fieldid", "parameters": [ { "in": "path", "name": "fieldId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "properties": { "name": { "type": "string" }, "options": { "items": { "type": "string" }, "type": "array" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "field": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "options": { "items": { "type": "string" }, "type": "array" }, "slug": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Custom field 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": { "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." } }, "summary": "Update custom field", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.custom_fields.update_custom_field@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "2f15b871c2e4c2e7e84ae11f56108ecaf1c3da72a4cc251bb534231114c4668f" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "patch_aisa_social_apis_v1_social_custom_fields_fieldid", "method": "PATCH", "path": "/apis/v1/social/custom-fields/{fieldId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/patch_aisa_social_apis_v1_social_custom_fields_fieldid" } }, "/apis/v1/social/discord/channels/{channelId}/messages/{messageId}": { "delete": { "description": "Discord. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nDeletes a message from a channel, for moderation and cleanup. This cannot be undone.\n\nDeleting a message the bot did not send requires the bot to hold the Manage Messages\npermission, which the AIsa bot requests at install time. Deleting the bot's own\nmessage needs no extra permission.\n\nOwnership is verified by resolving the channel's guild and confirming the caller owns\na Discord account bound to it.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "delete_aisa_social_apis_v1_social_discord_channel_e763ce", "parameters": [ { "description": "Discord channel snowflake ID", "in": "path", "name": "channelId", "required": true, "schema": { "type": "string" } }, { "description": "Discord message snowflake ID", "in": "path", "name": "messageId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Message deleted." }, "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." } }, "summary": "Delete a Discord channel message", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.discord.delete_discord_message@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "b7d3fc05b2bd9c3084d355b0a0f1ed083be28c354eeecb44649ff84186beee6e" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "delete_aisa_social_apis_v1_social_discord_channel_e763ce", "method": "DELETE", "path": "/apis/v1/social/discord/channels/{channelId}/messages/{messageId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/delete_aisa_social_apis_v1_social_discord_channel_e763ce" } }, "/apis/v1/social/discord/channels/{channelId}/messages/{messageId}/crosspost": { "post": { "description": "Discord. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nPublishes a message from an announcement channel so it propagates to every server\nfollowing that channel.\n\nThe source channel must be an announcement channel. Calling this on a regular text\nchannel returns a 400 before Discord is contacted, because Discord's own error for\nthis case is opaque.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_discord_channels__5a5295", "parameters": [ { "description": "Discord announcement channel snowflake ID", "in": "path", "name": "channelId", "required": true, "schema": { "type": "string" } }, { "description": "Discord message snowflake ID", "in": "path", "name": "messageId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "The crossposted Discord message object.", "type": "object" } }, "type": "object" } } }, "description": "Message crossposted." }, "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." } }, "summary": "Crosspost Discord message", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.discord.crosspost_discord_message@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "836a1f64fb818983a2628efd2d5999d7ebed80c8b4bb8d793760a808072734e9" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_discord_channels__5a5295", "method": "POST", "path": "/apis/v1/social/discord/channels/{channelId}/messages/{messageId}/crosspost" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_discord_channels__5a5295" } }, "/apis/v1/social/discord/channels/{channelId}/pins": { "get": { "description": "Discord. 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.\n\nReturns the channel's pinned messages, sorted most-recently-pinned\nfirst. Discord caps a channel at 50 pinned messages and returns the\nfull list unpaginated.\n\nBot needs READ_MESSAGE_HISTORY in the channel (granted by default\nBOT_PERMISSIONS).\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_discord_channels_c_81ff10", "parameters": [ { "description": "Discord channel snowflake.", "in": "path", "name": "channelId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "description": "Raw Discord Message object. See DiscordPlatformData for embed/attachment shapes.", "properties": { "attachments": { "items": { "type": "object" }, "type": "array" }, "author": { "type": "object" }, "channel_id": { "type": "string" }, "content": { "type": "string" }, "embeds": { "items": { "type": "object" }, "type": "array" }, "id": { "type": "string" }, "timestamp": { "format": "date-time", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Pinned messages." }, "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." } }, "summary": "List pinned messages", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.discord.list_discord_pinned_messages@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "56a889461e14d31a49f7f684a6237016ed92e162c0660acbe12623ef21ad1ff4" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_discord_channels_c_81ff10", "method": "GET", "path": "/apis/v1/social/discord/channels/{channelId}/pins" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_discord_channels_c_81ff10" } }, "/apis/v1/social/discord/channels/{channelId}/pins/{messageId}": { "delete": { "description": "Discord. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nUnpin a message. Same MANAGE_MESSAGES permission requirement as pin.\nIdempotent: unpinning a non-pinned message is a 204 no-op.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "delete_aisa_social_apis_v1_social_discord_channel_d3b982", "parameters": [ { "in": "path", "name": "channelId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "messageId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "channelId": { "type": "string" }, "messageId": { "type": "string" }, "operation": { "enum": [ "message_unpinned" ], "type": "string" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Message unpinned (or was not pinned, idempotent)." }, "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." } }, "summary": "Unpin a Discord message", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.discord.unpin_discord_message@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "99b66cfcb4ae24288795a5af5cc73d97360b037ef4a1c8c5e0857d74dd38c4f6" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "delete_aisa_social_apis_v1_social_discord_channel_d3b982", "method": "DELETE", "path": "/apis/v1/social/discord/channels/{channelId}/pins/{messageId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/delete_aisa_social_apis_v1_social_discord_channel_d3b982" }, "put": { "description": "Discord. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nPin a specific message in a channel. Path shape mirrors Discord's own\nAPI (`PUT /channels/{cid}/pins/{mid}`).\n\nIdempotent: re-pinning an already-pinned message is a 204 no-op.\n\nConstraints:\n - Bot needs MANAGE_MESSAGES in the channel.\n - 50-pin cap per channel: hitting it returns 400 (Discord-side).\n Caller should unpin one first.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "put_aisa_social_apis_v1_social_discord_channels_c_d3b982", "parameters": [ { "in": "path", "name": "channelId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "messageId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "channelId": { "type": "string" }, "messageId": { "type": "string" }, "operation": { "enum": [ "message_pinned" ], "type": "string" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Message pinned (or was already pinned, idempotent)." }, "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." } }, "summary": "Pin a Discord message", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.discord.pin_discord_message@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "3889d537ab6bae125b0e07a8772b2d0bfec0e369626c7ec27828e86bc8a1d178" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "put_aisa_social_apis_v1_social_discord_channels_c_d3b982", "method": "PUT", "path": "/apis/v1/social/discord/channels/{channelId}/pins/{messageId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/put_aisa_social_apis_v1_social_discord_channels_c_d3b982" } }, "/apis/v1/social/discord/channels/{channelId}/threads": { "post": { "description": "Discord. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nCreates a public thread in a channel. Pass `messageId` to start the thread from an\nexisting message, or omit it to create a standalone thread.\n\nThreads created here are always public. Requires the bot to hold Create Public\nThreads, which the AIsa bot requests at install time.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_discord_channels__ce7e49", "parameters": [ { "description": "Discord channel snowflake ID", "in": "path", "name": "channelId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "autoArchiveDuration": 1440, "name": "Release 2.4 discussion" }, "schema": { "properties": { "autoArchiveDuration": { "description": "Minutes of inactivity before the thread auto-archives. Discord accepts only these four values.", "enum": [ 60, 1440, 4320, 10080 ], "type": "integer" }, "messageId": { "description": "Optional message snowflake to start the thread from. Omit for a standalone thread.", "type": "string" }, "name": { "description": "Thread name", "maxLength": 100, "minLength": 1, "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "id": { "description": "Thread snowflake ID", "type": "string" }, "name": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Thread created." }, "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." } }, "summary": "Create a Discord public thread", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.discord.create_discord_thread@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "06b85509d86a0ebd214de1ab4855de4c4319e9ead4639379aec76b809828aecd" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_discord_channels__ce7e49", "method": "POST", "path": "/apis/v1/social/discord/channels/{channelId}/threads" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_discord_channels__ce7e49" } }, "/apis/v1/social/discord/dms": { "post": { "description": "Discord. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call. X accounts are not accepted. Paid: see x-aisa-pricing; charged only when the call succeeds.\n\nSend a 1:1 Direct Message from the bot to a Discord user (by snowflake ID). Supports the same payload shape as channel posts: content, embeds, media attachments, and TTS.\n\n### Constraints (Discord platform limits)\n\n- The bot can only DM users it shares at least one guild with.\n- If the recipient has DMs disabled for non-friends, Discord returns 403 (surfaces as a 502 platform error).\n- `content` capped at 2,000 chars.\n- At least one of `content`, `embeds`, or `attachments` is required.\n- The recipient must be identified by Discord snowflake ID (not username).\n\n### Why a separate endpoint\n\nThis is a dedicated endpoint rather than a `POST /apis/v1/social/posts` variant because DMs are 1:1 operational messages (onboarding, billing reminders, support pings) with a different lifecycle than scheduled channel posts.\n\nDMs are not persisted to `Post` / `ExternalPost` and are always sent immediately.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_discord_dms", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "accountId": "acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3", "content": "Welcome to Acme! Reply STOP to opt out.", "userId": "1234567890123456789" }, "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "attachments": { "description": "Up to 10 media attachments. Each is `{ type: image|video|gif|document, url, filename?, mimeType?, size? }`.", "items": { "properties": { "filename": { "type": "string" }, "mimeType": { "type": "string" }, "size": { "type": "integer" }, "type": { "enum": [ "image", "video", "gif", "document" ], "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "type", "url" ], "type": "object" }, "maxItems": 10, "type": "array" }, "content": { "description": "Message text, up to 2,000 characters.", "maxLength": 2000, "type": "string" }, "embeds": { "description": "Up to 10 Discord embeds. Same shape as channel-post embeds (title, description, color, fields, etc.). See DiscordPlatformData.embeds for the embed object schema.", "items": { "type": "object" }, "maxItems": 10, "type": "array" }, "tts": { "description": "Send as text-to-speech message.", "type": "boolean" }, "userId": { "description": "Discord snowflake ID of the recipient (15-21 digits).", "type": "string" } }, "required": [ "accountId", "userId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "account": { "properties": { "displayName": { "type": "string" }, "id": { "type": "string" }, "username": { "type": "string" } }, "type": "object" }, "channelId": { "description": "DM channel snowflake (Discord auto-creates one per recipient pair)", "type": "string" }, "messageId": { "description": "Discord message snowflake ID", "type": "string" }, "recipient": { "properties": { "platform": { "type": "string" }, "userId": { "type": "string" } }, "type": "object" }, "timestamp": { "format": "date-time", "type": "string" }, "url": { "description": "Direct link to the message, using Discord's @me path for DMs", "type": "string" } }, "type": "object" } } }, "description": "DM sent successfully." }, "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." } }, "summary": "Send a Discord Direct Message", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.discord.send_discord_direct_message@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "customer_micros_usd": 100, "description": "Charged once per successful call. The base price is AIsa's own cost for the call: $0.0001 (one message delivered to a recipient). X accounts are not accepted. This is the price on every plan; no plan multiplier applies. A refused or failed call, or one whose outcome is unknown, is not charged.", "kind": "fixed_request" }, "x-aisa-revision": { "handler_contract_hash": "68ebdd8a66669de553393ad030499f40d5a565a345cc1f26b028f43f644ec06b" }, "x-aisa-status": "disabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_discord_dms", "method": "POST", "path": "/apis/v1/social/discord/dms" }, "x-codeSamples": [ { "lang": "text", "label": "Reference example", "source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/social/discord/dms \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"accountId\": \"acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3\",\n \"content\": \"Welcome to Acme! Reply STOP to opt out.\",\n \"userId\": \"1234567890123456789\"\n}'" } ], "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_discord_dms" } }, "/apis/v1/social/discord/guilds/{guildId}/events": { "get": { "description": "Discord. 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.\n\nReturn all scheduled events in the guild. Events are distinct from\nmessages: they appear in the server's Events panel and Discord\nauto-notifies interested members ahead of start time.\n\nPass `withUserCount=true` to include `user_count` (number of members\nwho RSVP'd) on each event. Useful for surfacing engagement.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_discord_guilds_gui_a8112d", "parameters": [ { "in": "path", "name": "guildId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Include user_count on each event.", "in": "query", "name": "withUserCount", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "description": "Discord guild scheduled event. Returned by /apis/v1/social/discord/guilds/{guildId}/events endpoints.\nFields below are the subset AIsa consumes. Discord may return more (e.g. creator,\nimage hash) which we pass through verbatim.", "properties": { "channel_id": { "description": "Voice/stage channel ID; null for external events.", "type": [ "string", "null" ] }, "creator_id": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "entity_id": { "type": [ "string", "null" ] }, "entity_metadata": { "properties": { "location": { "description": "External event location string.", "type": "string" } }, "type": [ "object", "null" ] }, "entity_type": { "description": "1=STAGE_INSTANCE, 2=VOICE, 3=EXTERNAL", "enum": [ 1, 2, 3 ], "type": "integer" }, "guild_id": { "type": "string" }, "id": { "description": "Event snowflake ID", "type": "string" }, "image": { "description": "Cover image hash; build URL via cdn.discordapp.com.", "type": [ "string", "null" ] }, "name": { "type": "string" }, "privacy_level": { "description": "Always 2 (GUILD_ONLY). Discord deprecated PUBLIC events.", "enum": [ 2 ], "type": "integer" }, "scheduled_end_time": { "description": "Required for external events; optional for voice/stage.", "format": "date-time", "type": [ "string", "null" ] }, "scheduled_start_time": { "format": "date-time", "type": "string" }, "status": { "description": "1=SCHEDULED, 2=ACTIVE, 3=COMPLETED, 4=CANCELED", "enum": [ 1, 2, 3, 4 ], "type": "integer" }, "user_count": { "description": "Number of members who RSVP'd. Only present when withUserCount=true on list.", "type": "integer" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "List of scheduled events." }, "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." } }, "summary": "List Discord scheduled events", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.discord.list_discord_scheduled_events@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "5503aaa4cffec9ad817b531dd4e776e51b103b16f5626f89267d08f1f450fd00" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_discord_guilds_gui_a8112d", "method": "GET", "path": "/apis/v1/social/discord/guilds/{guildId}/events" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_discord_guilds_gui_a8112d" }, "post": { "description": "Discord. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nCreate a guild scheduled event. Three event types, selected via the\ndiscriminator on `entity.type`:\n\n - `external`: off-platform (Zoom, in-person, livestream). Requires\n both `location` and `endsAt`. Most common type for scheduler\n integrations.\n - `voice`: hosted in a Discord voice channel. Requires `channelId`.\n - `stage`: hosted in a Discord stage channel. Requires `channelId`.\n\nBot needs MANAGE_EVENTS in the guild. Existing installs (pre-events\nPR) need a re-invite OR a server admin manually granting the\npermission. See route header for details.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_discord_guilds_gu_a8112d", "parameters": [ { "in": "path", "name": "guildId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "accountId": "acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3", "description": "Bring your questions about the roadmap.", "entity": { "endsAt": "2026-06-15T19:00:00Z", "location": "https://zoom.us/j/123", "type": "external" }, "name": "Weekly AMA", "startsAt": "2026-06-15T18:00:00Z" }, "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "description": { "maxLength": 1000, "type": "string" }, "entity": { "oneOf": [ { "properties": { "endsAt": { "format": "date-time", "type": "string" }, "location": { "description": "Where the event takes place (e.g. \"Zoom link\", \"123 Main St\")", "maxLength": 100, "minLength": 1, "type": "string" }, "type": { "enum": [ "external" ], "type": "string" } }, "required": [ "endsAt", "location", "type" ], "type": "object" }, { "properties": { "channelId": { "description": "Voice channel snowflake.", "type": "string" }, "endsAt": { "format": "date-time", "type": "string" }, "type": { "enum": [ "voice" ], "type": "string" } }, "required": [ "channelId", "type" ], "type": "object" }, { "properties": { "channelId": { "description": "Stage channel snowflake.", "type": "string" }, "endsAt": { "format": "date-time", "type": "string" }, "type": { "enum": [ "stage" ], "type": "string" } }, "required": [ "channelId", "type" ], "type": "object" } ] }, "imageDataUri": { "description": "Optional cover image as a base64 data URI.", "pattern": "^data:image/(png|jpeg|gif);base64,", "type": "string" }, "name": { "maxLength": 100, "minLength": 1, "type": "string" }, "startsAt": { "description": "ISO 8601 start time. Must be in the future.", "format": "date-time", "type": "string" } }, "required": [ "accountId", "entity", "name", "startsAt" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "Discord guild scheduled event. Returned by /apis/v1/social/discord/guilds/{guildId}/events endpoints.\nFields below are the subset AIsa consumes. Discord may return more (e.g. creator,\nimage hash) which we pass through verbatim.", "properties": { "channel_id": { "description": "Voice/stage channel ID; null for external events.", "type": [ "string", "null" ] }, "creator_id": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "entity_id": { "type": [ "string", "null" ] }, "entity_metadata": { "properties": { "location": { "description": "External event location string.", "type": "string" } }, "type": [ "object", "null" ] }, "entity_type": { "description": "1=STAGE_INSTANCE, 2=VOICE, 3=EXTERNAL", "enum": [ 1, 2, 3 ], "type": "integer" }, "guild_id": { "type": "string" }, "id": { "description": "Event snowflake ID", "type": "string" }, "image": { "description": "Cover image hash; build URL via cdn.discordapp.com.", "type": [ "string", "null" ] }, "name": { "type": "string" }, "privacy_level": { "description": "Always 2 (GUILD_ONLY). Discord deprecated PUBLIC events.", "enum": [ 2 ], "type": "integer" }, "scheduled_end_time": { "description": "Required for external events; optional for voice/stage.", "format": "date-time", "type": [ "string", "null" ] }, "scheduled_start_time": { "format": "date-time", "type": "string" }, "status": { "description": "1=SCHEDULED, 2=ACTIVE, 3=COMPLETED, 4=CANCELED", "enum": [ 1, 2, 3, 4 ], "type": "integer" }, "user_count": { "description": "Number of members who RSVP'd. Only present when withUserCount=true on list.", "type": "integer" } }, "type": "object" } }, "type": "object" } } }, "description": "Event created." }, "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." } }, "summary": "Create a Discord scheduled event", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.discord.create_discord_scheduled_event@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "19b4607301acda516c4bb5ca457752be90b21c02c7d688be70a772779b07f730" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_discord_guilds_gu_a8112d", "method": "POST", "path": "/apis/v1/social/discord/guilds/{guildId}/events" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_discord_guilds_gu_a8112d" } }, "/apis/v1/social/discord/guilds/{guildId}/events/{eventId}": { "delete": { "description": "Discord. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nHard-delete an event. Use PATCH with `status: 'cancelled'` instead\nif you want the event preserved in the guild's history.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "delete_aisa_social_apis_v1_social_discord_guilds__d0ff92", "parameters": [ { "in": "path", "name": "guildId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "eventId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "description": "The deleted event's snowflake.", "type": "string" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Event deleted." }, "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." } }, "summary": "Delete a Discord scheduled event", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.discord.delete_discord_scheduled_event@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "0660d6c9ca83c4766e864634f7ce113f00933c4a25789a8505f23a85aa03eda9" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "delete_aisa_social_apis_v1_social_discord_guilds__d0ff92", "method": "DELETE", "path": "/apis/v1/social/discord/guilds/{guildId}/events/{eventId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/delete_aisa_social_apis_v1_social_discord_guilds__d0ff92" }, "get": { "description": "Discord. 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.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_discord_guilds_gui_d0ff92", "parameters": [ { "in": "path", "name": "guildId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "eventId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "Discord guild scheduled event. Returned by /apis/v1/social/discord/guilds/{guildId}/events endpoints.\nFields below are the subset AIsa consumes. Discord may return more (e.g. creator,\nimage hash) which we pass through verbatim.", "properties": { "channel_id": { "description": "Voice/stage channel ID; null for external events.", "type": [ "string", "null" ] }, "creator_id": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "entity_id": { "type": [ "string", "null" ] }, "entity_metadata": { "properties": { "location": { "description": "External event location string.", "type": "string" } }, "type": [ "object", "null" ] }, "entity_type": { "description": "1=STAGE_INSTANCE, 2=VOICE, 3=EXTERNAL", "enum": [ 1, 2, 3 ], "type": "integer" }, "guild_id": { "type": "string" }, "id": { "description": "Event snowflake ID", "type": "string" }, "image": { "description": "Cover image hash; build URL via cdn.discordapp.com.", "type": [ "string", "null" ] }, "name": { "type": "string" }, "privacy_level": { "description": "Always 2 (GUILD_ONLY). Discord deprecated PUBLIC events.", "enum": [ 2 ], "type": "integer" }, "scheduled_end_time": { "description": "Required for external events; optional for voice/stage.", "format": "date-time", "type": [ "string", "null" ] }, "scheduled_start_time": { "format": "date-time", "type": "string" }, "status": { "description": "1=SCHEDULED, 2=ACTIVE, 3=COMPLETED, 4=CANCELED", "enum": [ 1, 2, 3, 4 ], "type": "integer" }, "user_count": { "description": "Number of members who RSVP'd. Only present when withUserCount=true on list.", "type": "integer" } }, "type": "object" } }, "type": "object" } } }, "description": "Event." }, "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." } }, "summary": "Get a Discord scheduled event", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.discord.get_discord_scheduled_event@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "e4ddc62e976da728bd6ccec5ac4a27d741602cfb6ce14b473ef96e83d553817f" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_discord_guilds_gui_d0ff92", "method": "GET", "path": "/apis/v1/social/discord/guilds/{guildId}/events/{eventId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_discord_guilds_gui_d0ff92" }, "patch": { "description": "Discord. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nPatch any subset of fields. Passing `status: 'cancelled'` is how you\ncancel an event. Discord doesn't have a dedicated cancel endpoint,\nit's a status transition.\n\nMost status transitions Discord enforces (you can't go SCHEDULED →\nCOMPLETED directly). The common consumer case is SCHEDULED → CANCELED.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "patch_aisa_social_apis_v1_social_discord_guilds_g_d0ff92", "parameters": [ { "in": "path", "name": "guildId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "eventId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "accountId": "acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3", "status": "cancelled" }, "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "description": { "maxLength": 1000, "type": "string" }, "endsAt": { "format": "date-time", "type": "string" }, "imageDataUri": { "pattern": "^data:image/(png|jpeg|gif);base64,", "type": "string" }, "location": { "description": "For external events.", "maxLength": 100, "minLength": 1, "type": "string" }, "name": { "maxLength": 100, "minLength": 1, "type": "string" }, "startsAt": { "format": "date-time", "type": "string" }, "status": { "description": "Status transition. Most common: 'cancelled' to cancel an event.", "enum": [ "scheduled", "active", "completed", "cancelled" ], "type": "string" } }, "required": [ "accountId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "Discord guild scheduled event. Returned by /apis/v1/social/discord/guilds/{guildId}/events endpoints.\nFields below are the subset AIsa consumes. Discord may return more (e.g. creator,\nimage hash) which we pass through verbatim.", "properties": { "channel_id": { "description": "Voice/stage channel ID; null for external events.", "type": [ "string", "null" ] }, "creator_id": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "entity_id": { "type": [ "string", "null" ] }, "entity_metadata": { "properties": { "location": { "description": "External event location string.", "type": "string" } }, "type": [ "object", "null" ] }, "entity_type": { "description": "1=STAGE_INSTANCE, 2=VOICE, 3=EXTERNAL", "enum": [ 1, 2, 3 ], "type": "integer" }, "guild_id": { "type": "string" }, "id": { "description": "Event snowflake ID", "type": "string" }, "image": { "description": "Cover image hash; build URL via cdn.discordapp.com.", "type": [ "string", "null" ] }, "name": { "type": "string" }, "privacy_level": { "description": "Always 2 (GUILD_ONLY). Discord deprecated PUBLIC events.", "enum": [ 2 ], "type": "integer" }, "scheduled_end_time": { "description": "Required for external events; optional for voice/stage.", "format": "date-time", "type": [ "string", "null" ] }, "scheduled_start_time": { "format": "date-time", "type": "string" }, "status": { "description": "1=SCHEDULED, 2=ACTIVE, 3=COMPLETED, 4=CANCELED", "enum": [ 1, 2, 3, 4 ], "type": "integer" }, "user_count": { "description": "Number of members who RSVP'd. Only present when withUserCount=true on list.", "type": "integer" } }, "type": "object" } }, "type": "object" } } }, "description": "Event 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": { "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." } }, "summary": "Update a Discord scheduled event", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.discord.update_discord_scheduled_event@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "a2d2efc0b57b564bd0934362d51e96d88e0ae9e4db5d50b9e9b925d1a933b0de" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "patch_aisa_social_apis_v1_social_discord_guilds_g_d0ff92", "method": "PATCH", "path": "/apis/v1/social/discord/guilds/{guildId}/events/{eventId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/patch_aisa_social_apis_v1_social_discord_guilds_g_d0ff92" } }, "/apis/v1/social/discord/guilds/{guildId}/members": { "get": { "description": "Discord. 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.\n\nCursor-paginated list of guild members. Returns Discord's raw member\nobjects so callers can build community-ops automation (e.g. \"add role\nto all members joined in the last 7 days\") on the actual platform shape.\n\nPagination: pass `after` = the last `user.id` from the previous page.\nOmit on the first call. Response includes a `nextCursor` and `hasMore`\nflag so callers don't need to know Discord's pagination shape.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_discord_guilds_gui_87b03d", "parameters": [ { "in": "path", "name": "guildId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Page size (1-1000).", "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 1000, "minimum": 1, "type": "integer" } }, { "description": "Snowflake of the last member from the previous page.", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "description": "A Discord guild member, returned verbatim from Discord's API.", "properties": { "joined_at": { "format": "date-time", "type": "string" }, "nick": { "description": "Guild-specific nickname", "type": [ "string", "null" ] }, "premium_since": { "description": "When the user started boosting the server", "format": "date-time", "type": [ "string", "null" ] }, "roles": { "description": "Snowflake IDs of roles assigned to this member", "items": { "type": "string" }, "type": "array" }, "user": { "properties": { "avatar": { "type": [ "string", "null" ] }, "discriminator": { "type": "string" }, "global_name": { "description": "User's display name (post-2023 Discord rebrand)", "type": [ "string", "null" ] }, "id": { "description": "User snowflake", "type": "string" }, "username": { "type": "string" } }, "type": "object" } }, "type": "object" }, "type": "array" }, "pagination": { "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "description": "Pass as `after` on the next call. Null when there are no more pages.", "type": [ "string", "null" ] } }, "type": "object" } }, "type": "object" } } }, "description": "List of guild members." }, "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." } }, "summary": "List Discord guild members", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.discord.list_discord_guild_members@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "14d35081d6b7d8d399ecc57697c83b43585da846e1e0a772960680a3b049f900" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_discord_guilds_gui_87b03d", "method": "GET", "path": "/apis/v1/social/discord/guilds/{guildId}/members" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_discord_guilds_gui_87b03d" } }, "/apis/v1/social/discord/guilds/{guildId}/members/search": { "get": { "description": "Discord. 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.\n\nSearch guild members whose username or nickname **starts with** the\nquery (Discord matches prefixes only, not substrings).\n\nCheaper than paginating the full member listing when you already know\nwho you are looking for.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_discord_guilds_gui_ef6ef9", "parameters": [ { "in": "path", "name": "guildId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Username or nickname prefix to match.", "in": "query", "name": "query", "required": true, "schema": { "maxLength": 100, "minLength": 1, "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 1000, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "description": "A Discord guild member, returned verbatim from Discord's API.", "properties": { "joined_at": { "format": "date-time", "type": "string" }, "nick": { "description": "Guild-specific nickname", "type": [ "string", "null" ] }, "premium_since": { "description": "When the user started boosting the server", "format": "date-time", "type": [ "string", "null" ] }, "roles": { "description": "Snowflake IDs of roles assigned to this member", "items": { "type": "string" }, "type": "array" }, "user": { "properties": { "avatar": { "type": [ "string", "null" ] }, "discriminator": { "type": "string" }, "global_name": { "description": "User's display name (post-2023 Discord rebrand)", "type": [ "string", "null" ] }, "id": { "description": "User snowflake", "type": "string" }, "username": { "type": "string" } }, "type": "object" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Matching guild members." }, "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." } }, "summary": "Search Discord guild members", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.discord.search_discord_guild_members@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "603b1722b82c04024881a5d9b2c19ef36a8653b5187fb406b084689aec5a18aa" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_discord_guilds_gui_ef6ef9", "method": "GET", "path": "/apis/v1/social/discord/guilds/{guildId}/members/search" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_discord_guilds_gui_ef6ef9" } }, "/apis/v1/social/discord/guilds/{guildId}/members/{userId}": { "get": { "description": "Discord. 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.\n\nFetch a single guild member by Discord user id.\n\nCheaper than paginating the full member listing when you already know\nwho you are looking for.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_discord_guilds_gui_2d709a", "parameters": [ { "in": "path", "name": "guildId", "required": true, "schema": { "type": "string" } }, { "description": "Discord user snowflake.", "in": "path", "name": "userId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "A Discord guild member, returned verbatim from Discord's API.", "properties": { "joined_at": { "format": "date-time", "type": "string" }, "nick": { "description": "Guild-specific nickname", "type": [ "string", "null" ] }, "premium_since": { "description": "When the user started boosting the server", "format": "date-time", "type": [ "string", "null" ] }, "roles": { "description": "Snowflake IDs of roles assigned to this member", "items": { "type": "string" }, "type": "array" }, "user": { "properties": { "avatar": { "type": [ "string", "null" ] }, "discriminator": { "type": "string" }, "global_name": { "description": "User's display name (post-2023 Discord rebrand)", "type": [ "string", "null" ] }, "id": { "description": "User snowflake", "type": "string" }, "username": { "type": "string" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } }, "description": "The guild member." }, "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." } }, "summary": "Get a Discord guild member", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.discord.get_discord_guild_member@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "084096eb3aabfd15b5ddcc9cd9ad9d4f82790c8bb5dc69aa60512a477a8d3e1a" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_discord_guilds_gui_2d709a", "method": "GET", "path": "/apis/v1/social/discord/guilds/{guildId}/members/{userId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_discord_guilds_gui_2d709a" } }, "/apis/v1/social/discord/guilds/{guildId}/members/{userId}/roles/{roleId}": { "delete": { "description": "Discord. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nRemove one role from one member. Idempotent: removing a role the\nmember doesn't have returns 204 no-op.\n\nSame permission + hierarchy constraints as the PUT counterpart.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "delete_aisa_social_apis_v1_social_discord_guilds__af528d", "parameters": [ { "in": "path", "name": "guildId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "userId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "roleId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "guildId": { "type": "string" }, "operation": { "enum": [ "role_removed" ], "type": "string" }, "roleId": { "type": "string" }, "success": { "type": "boolean" }, "userId": { "type": "string" } }, "type": "object" } } }, "description": "Role removed (or was already absent, idempotent)." }, "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." } }, "summary": "Remove a role from a guild member", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.discord.remove_discord_member_role@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "ed1a7c461eec5b3b4bcd72cea557dcebd4751fe2e188cdeb641668b46a704f8d" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "delete_aisa_social_apis_v1_social_discord_guilds__af528d", "method": "DELETE", "path": "/apis/v1/social/discord/guilds/{guildId}/members/{userId}/roles/{roleId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/delete_aisa_social_apis_v1_social_discord_guilds__af528d" }, "put": { "description": "Discord. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nAssign one role to one member. Idempotent on Discord's side: re-running\non a member who already has the role is a 204 no-op.\n\nPath shape mirrors Discord's own API (`PUT /guilds/{guild}/members/{user}/roles/{role}`)\nfor zero-translation mental mapping.\n\nBot needs MANAGE_ROLES permission in the guild AND its highest role\nmust be above the target role (Discord hierarchy rule). The\n`@everyone` role (where roleId == guildId) cannot be assigned.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "put_aisa_social_apis_v1_social_discord_guilds_gui_af528d", "parameters": [ { "in": "path", "name": "guildId", "required": true, "schema": { "type": "string" } }, { "description": "Discord user snowflake to assign the role to.", "in": "path", "name": "userId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "roleId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "guildId": { "type": "string" }, "operation": { "enum": [ "role_assigned" ], "type": "string" }, "roleId": { "type": "string" }, "success": { "type": "boolean" }, "userId": { "type": "string" } }, "type": "object" } } }, "description": "Role assigned (or already present, idempotent)." }, "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." } }, "summary": "Assign a role to a guild member", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.discord.add_discord_member_role@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "017d8250119bfaa5989c0688ee29be3f41a5e9898485a91e5d98570f3bf18bda" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "put_aisa_social_apis_v1_social_discord_guilds_gui_af528d", "method": "PUT", "path": "/apis/v1/social/discord/guilds/{guildId}/members/{userId}/roles/{roleId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/put_aisa_social_apis_v1_social_discord_guilds_gui_af528d" } }, "/apis/v1/social/discord/guilds/{guildId}/roles": { "get": { "description": "Discord. 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.\n\nReturns all roles in a Discord guild. Useful for building role-mention\npickers, role-permission UIs, or finding the role ID before calling\nthe role-assign endpoint.\n\nRoles are returned unordered. Sort client-side by `position` if you\nneed Discord's UI ordering.\n\nCaller must pass `accountId` of a Discord social account bound to this\nguild (route verifies team access + guild match).\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_discord_guilds_gui_2438bd", "parameters": [ { "description": "Discord guild snowflake ID", "in": "path", "name": "guildId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "color": { "description": "Decimal color (0 = no color). Convert to hex via .toString(16).", "type": "integer" }, "hoist": { "description": "True if role is displayed separately in member list", "type": "boolean" }, "id": { "description": "Role snowflake ID", "type": "string" }, "managed": { "description": "True for integration-managed roles (bot roles)", "type": "boolean" }, "mentionable": { "type": "boolean" }, "name": { "type": "string" }, "permissions": { "description": "Permissions bitfield as a stringified integer", "type": "string" }, "position": { "description": "Position in role hierarchy (higher = more authority)", "type": "integer" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "List of guild roles." }, "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." } }, "summary": "List Discord guild roles", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.discord.list_discord_guild_roles@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "b07e1654d5dbaaf53a8523ac8e19f74782558f2c41a6891637fb1c4e57262487" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_discord_guilds_gui_2438bd", "method": "GET", "path": "/apis/v1/social/discord/guilds/{guildId}/roles" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_discord_guilds_gui_2438bd" }, "post": { "description": "Discord. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nCreates a new role in the guild.\n\nRequires the bot to hold the Manage Roles permission. Guilds that added the AIsa bot\nbefore role management shipped must re-invite it, because Discord applies the\npermission set at invite time.\n\nDiscord's role hierarchy applies: the bot cannot create a role positioned at or above\nits own highest role, and cannot grant permissions it does not itself hold. Either\nattempt returns a 403 carrying Discord's own error.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_discord_guilds_gu_2438bd", "parameters": [ { "description": "Discord guild snowflake ID", "in": "path", "name": "guildId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "color": 16711680, "hoist": true, "mentionable": false, "name": "Moderators" }, "schema": { "properties": { "color": { "description": "Decimal color (0 = no color). 0xFF0000 red is 16711680.", "maximum": 16777215, "minimum": 0, "type": "integer" }, "hoist": { "description": "Display members with this role separately in the member list", "type": "boolean" }, "mentionable": { "description": "Allow anyone to @mention this role", "type": "boolean" }, "name": { "maxLength": 100, "minLength": 1, "type": "string" }, "permissions": { "description": "Permissions bitfield as a stringified integer", "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "A Discord guild role, returned verbatim from Discord's API.", "properties": { "color": { "description": "Decimal color (0 = no color). Convert to hex via .toString(16).", "type": "integer" }, "hoist": { "description": "True if role is displayed separately in member list", "type": "boolean" }, "id": { "description": "Role snowflake ID", "type": "string" }, "managed": { "description": "True for integration-managed roles (bot roles)", "type": "boolean" }, "mentionable": { "type": "boolean" }, "name": { "type": "string" }, "permissions": { "description": "Permissions bitfield as a stringified integer", "type": "string" }, "position": { "description": "Position in role hierarchy (higher = more authority)", "type": "integer" } }, "type": "object" } }, "type": "object" } } }, "description": "Role created." }, "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." } }, "summary": "Create a Discord guild role", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.discord.create_discord_guild_role@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "7c49a0707c4ba0581b060b746580e02f533147e7f6e9b12e106af15f3a65f209" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_discord_guilds_gu_2438bd", "method": "POST", "path": "/apis/v1/social/discord/guilds/{guildId}/roles" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_discord_guilds_gu_2438bd" } }, "/apis/v1/social/discord/guilds/{guildId}/roles/{roleId}": { "delete": { "description": "Discord. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nPermanently deletes a role from the guild and removes it from every member.\nThis cannot be undone.\n\nRequires the bot to hold Manage Roles, and the target role must sit below the bot's\nhighest role.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "delete_aisa_social_apis_v1_social_discord_guilds__35190c", "parameters": [ { "description": "Discord guild snowflake ID", "in": "path", "name": "guildId", "required": true, "schema": { "type": "string" } }, { "description": "Discord role snowflake ID", "in": "path", "name": "roleId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Role deleted." }, "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." } }, "summary": "Delete a Discord guild role", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.discord.delete_discord_guild_role@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "69f589d181b04c0ac98c9f502ad21510df07ef09277926bdf1d39a29cd7b4fc9" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "delete_aisa_social_apis_v1_social_discord_guilds__35190c", "method": "DELETE", "path": "/apis/v1/social/discord/guilds/{guildId}/roles/{roleId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/delete_aisa_social_apis_v1_social_discord_guilds__35190c" }, "patch": { "description": "Discord. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nUpdates a role's name, color, hoist, mentionable flag, or permission bitfield.\nAt least one field must be supplied. Omitted fields are left unchanged.\n\nRequires the bot to hold Manage Roles, and the target role must sit below the bot's\nhighest role. See the create-role operation for the re-invite requirement.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "patch_aisa_social_apis_v1_social_discord_guilds_g_35190c", "parameters": [ { "description": "Discord guild snowflake ID", "in": "path", "name": "guildId", "required": true, "schema": { "type": "string" } }, { "description": "Discord role snowflake ID", "in": "path", "name": "roleId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "mentionable": true, "name": "Senior Moderators" }, "schema": { "minProperties": 1, "properties": { "color": { "maximum": 16777215, "minimum": 0, "type": "integer" }, "hoist": { "type": "boolean" }, "mentionable": { "type": "boolean" }, "name": { "maxLength": 100, "minLength": 1, "type": "string" }, "permissions": { "description": "Permissions bitfield as a stringified integer", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "A Discord guild role, returned verbatim from Discord's API.", "properties": { "color": { "description": "Decimal color (0 = no color). Convert to hex via .toString(16).", "type": "integer" }, "hoist": { "description": "True if role is displayed separately in member list", "type": "boolean" }, "id": { "description": "Role snowflake ID", "type": "string" }, "managed": { "description": "True for integration-managed roles (bot roles)", "type": "boolean" }, "mentionable": { "type": "boolean" }, "name": { "type": "string" }, "permissions": { "description": "Permissions bitfield as a stringified integer", "type": "string" }, "position": { "description": "Position in role hierarchy (higher = more authority)", "type": "integer" } }, "type": "object" } }, "type": "object" } } }, "description": "Role 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": { "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." } }, "summary": "Edit a Discord guild role", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.discord.edit_discord_guild_role@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "16fcd79c461eca022ea953093222a8c7c6e632eed0ed4fe6f8e10280e96a0e5e" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "patch_aisa_social_apis_v1_social_discord_guilds_g_35190c", "method": "PATCH", "path": "/apis/v1/social/discord/guilds/{guildId}/roles/{roleId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/patch_aisa_social_apis_v1_social_discord_guilds_g_35190c" } }, "/apis/v1/social/files": { "get": { "description": "Files. 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.\n\nLists the children of `folderId` (the root by default), folders first.\n\nWith `q` and no `folderId` the whole drive is searched by name (on Google, every drive the app can see, shared drives included).\n\n- The account must have been connected with `scopes=files` (412 `account_scope_missing` otherwise).\n- Cursors are opaque and provider-issued.\n- Google Drive returns only files AIsa created or the user picked (see the Files tag): an unpicked folder lists empty.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_files", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Provider folder id; omit for the root.", "in": "query", "name": "folderId", "required": false, "schema": { "type": "string" } }, { "description": "Name search.", "in": "query", "name": "q", "required": false, "schema": { "maxLength": 200, "type": "string" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "description": "A file or folder in a connected Google Drive or OneDrive. Ids are the provider's own.", "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "createdAt": { "format": "date-time", "type": [ "string", "null" ] }, "downloadable": { "description": "False for folders and for Drive files whose owner disabled downloading.", "type": "boolean" }, "exportMimeType": { "description": "Google Docs, Slides and Drawings download as PDF/PNG and Sheets as XLSX; this is the type the download carries.", "type": [ "string", "null" ] }, "id": { "type": "string" }, "kind": { "enum": [ "file", "folder" ], "type": "string" }, "mimeType": { "type": [ "string", "null" ] }, "modifiedAt": { "format": "date-time", "type": [ "string", "null" ] }, "name": { "type": "string" }, "parentId": { "type": [ "string", "null" ] }, "provider": { "enum": [ "google", "microsoft" ], "type": "string" }, "size": { "description": "Bytes; null for folders and Google editors files.", "type": [ "integer", "null" ] }, "trashed": { "type": "boolean" }, "webUrl": { "description": "The provider's own link to open the item.", "type": [ "string", "null" ] } }, "required": [ "accountId", "createdAt", "downloadable", "id", "kind", "mimeType", "modifiedAt", "name", "parentId", "provider", "size", "trashed", "webUrl" ], "type": "object" }, "type": "array" }, "pagination": { "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] } }, "type": "object" } }, "type": "object" } } }, "description": "Files" }, "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." } }, "summary": "List files in a folder or search the drive", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.files.list_files@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "5c26e16585fa79571db53715851f94fbaacbc550ee16d426fc8d2a2d1ecec13d" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_files", "method": "GET", "path": "/apis/v1/social/files" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_files" }, "post": { "description": "Files. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nEither `multipart/form-data` with the file under `file` plus `accountId`, `name` (defaults to the file name) and `parentId`, or JSON with a public `url` the file is fetched from (100 MB cap). Large files go through the provider's resumable upload.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_files", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "accountId": "acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3", "contentType": "example", "name": "example", "url": "https://example.com/item" }, "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "contentType": { "type": "string" }, "convertTo": { "description": "Google Drive only: import the bytes as a Docs, Sheets or Slides file (a text or Office file becomes an editable document). OneDrive answers 400.", "enum": [ "application/vnd.google-apps.document", "application/vnd.google-apps.spreadsheet", "application/vnd.google-apps.presentation" ], "type": "string" }, "name": { "maxLength": 255, "type": "string" }, "parentId": { "description": "Target folder; the root when omitted.", "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "accountId", "contentType", "name", "url" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "A file or folder in a connected Google Drive or OneDrive. Ids are the provider's own.", "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "createdAt": { "format": "date-time", "type": [ "string", "null" ] }, "downloadable": { "description": "False for folders and for Drive files whose owner disabled downloading.", "type": "boolean" }, "exportMimeType": { "description": "Google Docs, Slides and Drawings download as PDF/PNG and Sheets as XLSX; this is the type the download carries.", "type": [ "string", "null" ] }, "id": { "type": "string" }, "kind": { "enum": [ "file", "folder" ], "type": "string" }, "mimeType": { "type": [ "string", "null" ] }, "modifiedAt": { "format": "date-time", "type": [ "string", "null" ] }, "name": { "type": "string" }, "parentId": { "type": [ "string", "null" ] }, "provider": { "enum": [ "google", "microsoft" ], "type": "string" }, "size": { "description": "Bytes; null for folders and Google editors files.", "type": [ "integer", "null" ] }, "trashed": { "type": "boolean" }, "webUrl": { "description": "The provider's own link to open the item.", "type": [ "string", "null" ] } }, "required": [ "accountId", "createdAt", "downloadable", "id", "kind", "mimeType", "modifiedAt", "name", "parentId", "provider", "size", "trashed", "webUrl" ], "type": "object" } }, "type": "object" } } }, "description": "The stored file" }, "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." } }, "summary": "Upload a file", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.files.upload_file@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "997bc8e6a00ca54aee973216131f08c1e5d7326dafeb659d5de85b20b20fae7f" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_files", "method": "POST", "path": "/apis/v1/social/files" }, "x-codeSamples": [ { "lang": "text", "label": "Reference example", "source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/social/files \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"accountId\": \"acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3\",\n \"contentType\": \"example\",\n \"name\": \"example\",\n \"url\": \"https://example.com/item\"\n}'" } ], "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_files" } }, "/apis/v1/social/files/folders": { "post": { "description": "Files. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_files_folders", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "accountId": "acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3", "name": "example" }, "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "name": { "maxLength": 255, "type": "string" }, "parentId": { "type": "string" } }, "required": [ "accountId", "name" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "A file or folder in a connected Google Drive or OneDrive. Ids are the provider's own.", "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "createdAt": { "format": "date-time", "type": [ "string", "null" ] }, "downloadable": { "description": "False for folders and for Drive files whose owner disabled downloading.", "type": "boolean" }, "exportMimeType": { "description": "Google Docs, Slides and Drawings download as PDF/PNG and Sheets as XLSX; this is the type the download carries.", "type": [ "string", "null" ] }, "id": { "type": "string" }, "kind": { "enum": [ "file", "folder" ], "type": "string" }, "mimeType": { "type": [ "string", "null" ] }, "modifiedAt": { "format": "date-time", "type": [ "string", "null" ] }, "name": { "type": "string" }, "parentId": { "type": [ "string", "null" ] }, "provider": { "enum": [ "google", "microsoft" ], "type": "string" }, "size": { "description": "Bytes; null for folders and Google editors files.", "type": [ "integer", "null" ] }, "trashed": { "type": "boolean" }, "webUrl": { "description": "The provider's own link to open the item.", "type": [ "string", "null" ] } }, "required": [ "accountId", "createdAt", "downloadable", "id", "kind", "mimeType", "modifiedAt", "name", "parentId", "provider", "size", "trashed", "webUrl" ], "type": "object" } }, "type": "object" } } }, "description": "The folder" }, "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." } }, "summary": "Create a folder", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.files.create_folder@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "c93e6ba0f603e62da922b5535e27d0755b2dd6c43558d25dfb450fb5a1662760" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_files_folders", "method": "POST", "path": "/apis/v1/social/files/folders" }, "x-codeSamples": [ { "lang": "text", "label": "Reference example", "source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/social/files/folders \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"accountId\": \"acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3\",\n \"name\": \"example\"\n}'" } ], "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_files_folders" } }, "/apis/v1/social/files/{fileId}": { "delete": { "description": "Files. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nDrive trash or the OneDrive recycle bin; nothing is destroyed and the user can restore it on the provider.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "delete_aisa_social_apis_v1_social_files_fileid", "parameters": [ { "in": "path", "name": "fileId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "id": { "type": "string" }, "trashed": { "description": "Always true.", "type": "boolean" } }, "type": "object" } }, "type": "object" } } }, "description": "Trashed" }, "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." } }, "summary": "Move a file to the trash", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.files.trash_file@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "51d55ea173e87ba81fa227020b3e09cb4929238088520bfc6b6aa78e6d09554a" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "delete_aisa_social_apis_v1_social_files_fileid", "method": "DELETE", "path": "/apis/v1/social/files/{fileId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/delete_aisa_social_apis_v1_social_files_fileid" }, "get": { "description": "Files. 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.\n\nOn Google Drive, a file AIsa neither created nor was given through Google Picker answers 404 `resource_not_found` with `details: { fileId, reason: file_not_granted }`; send the user through `POST /apis/v1/social/files/picker-sessions` (pass the id in `fileIds` to show it first). The same 404 applies to download, update, trash and share-link.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_files_fileid", "parameters": [ { "in": "path", "name": "fileId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "A file or folder in a connected Google Drive or OneDrive. Ids are the provider's own.", "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "createdAt": { "format": "date-time", "type": [ "string", "null" ] }, "downloadable": { "description": "False for folders and for Drive files whose owner disabled downloading.", "type": "boolean" }, "exportMimeType": { "description": "Google Docs, Slides and Drawings download as PDF/PNG and Sheets as XLSX; this is the type the download carries.", "type": [ "string", "null" ] }, "id": { "type": "string" }, "kind": { "enum": [ "file", "folder" ], "type": "string" }, "mimeType": { "type": [ "string", "null" ] }, "modifiedAt": { "format": "date-time", "type": [ "string", "null" ] }, "name": { "type": "string" }, "parentId": { "type": [ "string", "null" ] }, "provider": { "enum": [ "google", "microsoft" ], "type": "string" }, "size": { "description": "Bytes; null for folders and Google editors files.", "type": [ "integer", "null" ] }, "trashed": { "type": "boolean" }, "webUrl": { "description": "The provider's own link to open the item.", "type": [ "string", "null" ] } }, "required": [ "accountId", "createdAt", "downloadable", "id", "kind", "mimeType", "modifiedAt", "name", "parentId", "provider", "size", "trashed", "webUrl" ], "type": "object" } }, "type": "object" } } }, "description": "The item" }, "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." } }, "summary": "Get a file or folder", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.files.get_file@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "a297fbd7afa31eae711b708735b2525653daf93d8d03077d29659f6e7d25d23c" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_files_fileid", "method": "GET", "path": "/apis/v1/social/files/{fileId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_files_fileid" }, "patch": { "description": "Files. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\n`parentId` moves the item into another folder; `name` renames it. At least one is required.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "patch_aisa_social_apis_v1_social_files_fileid", "parameters": [ { "in": "path", "name": "fileId", "required": true, "schema": { "type": "string" } } ], "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" }, "name": { "maxLength": 255, "type": "string" }, "parentId": { "type": "string" } }, "required": [ "accountId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "A file or folder in a connected Google Drive or OneDrive. Ids are the provider's own.", "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "createdAt": { "format": "date-time", "type": [ "string", "null" ] }, "downloadable": { "description": "False for folders and for Drive files whose owner disabled downloading.", "type": "boolean" }, "exportMimeType": { "description": "Google Docs, Slides and Drawings download as PDF/PNG and Sheets as XLSX; this is the type the download carries.", "type": [ "string", "null" ] }, "id": { "type": "string" }, "kind": { "enum": [ "file", "folder" ], "type": "string" }, "mimeType": { "type": [ "string", "null" ] }, "modifiedAt": { "format": "date-time", "type": [ "string", "null" ] }, "name": { "type": "string" }, "parentId": { "type": [ "string", "null" ] }, "provider": { "enum": [ "google", "microsoft" ], "type": "string" }, "size": { "description": "Bytes; null for folders and Google editors files.", "type": [ "integer", "null" ] }, "trashed": { "type": "boolean" }, "webUrl": { "description": "The provider's own link to open the item.", "type": [ "string", "null" ] } }, "required": [ "accountId", "createdAt", "downloadable", "id", "kind", "mimeType", "modifiedAt", "name", "parentId", "provider", "size", "trashed", "webUrl" ], "type": "object" } }, "type": "object" } } }, "description": "The updated item" }, "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." } }, "summary": "Rename or move a file", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.files.update_file@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "7b9e0ca0cbb186a4a089341bb4097251b1e2f7bc5c3caabfdf6ab356cb730a51" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "patch_aisa_social_apis_v1_social_files_fileid", "method": "PATCH", "path": "/apis/v1/social/files/{fileId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/patch_aisa_social_apis_v1_social_files_fileid" } }, "/apis/v1/social/files/{fileId}/share-link": { "get": { "description": "Files. 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.\n\nGrants read access to anyone holding the link (Drive `anyone` permission, OneDrive anonymous view link) and returns it. The grant stays until it is revoked on the provider.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_files_fileid_share_link", "parameters": [ { "in": "path", "name": "fileId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "scope": { "enum": [ "anyone_with_link" ], "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "scope", "url" ], "type": "object" } }, "type": "object" } } }, "description": "The link" }, "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." } }, "summary": "Get an anyone-with-the-link share link", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.files.get_file_share_link@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "30a7be955f37daa448f3f345dc25cf7d7c1df646a9c44a02755d3759d74e588e" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_files_fileid_share_link", "method": "GET", "path": "/apis/v1/social/files/{fileId}/share-link" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_files_fileid_share_link" } }, "/apis/v1/social/inbox/comments": { "get": { "description": "Comments. 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. Without profileId or accountId it reads your default profile. On a profile with an X account, pass accountId or a platform other than twitter: X bills each read.\n\nReturns posts with comment counts from all connected accounts. Aggregates data across multiple accounts.\n\n### Caching\n\nResponses are cached for up to 10 minutes, so the feed may lag new comments by that window.\n\nDo not poll this endpoint for real-time updates. Subscribe to the `comment.received` webhook, which fires for every new comment across your posts and carries the post reference needed to keep this list current.\n\n### Meta ads\n\nFor users with the Ads add-on (accounts on usage-based billing always qualify), the user's Meta ads (boosted/dark posts) are included too.\n\nThere's one row per (ad, placement-with-comments). An ad that runs on both Facebook feed and Instagram feed produces up to two rows, since the Page dark post and the IG media have separate comment threads.\n\nEach ad row is flagged `isAd: true` with `adId` and `placement` (`id` is `{adId}:{placement}`). Filter with `platform`:\n\n- `?platform=metaads`: *only* ad rows.\n- `facebook`/`instagram`: *organic* posts only (no ads).\n- Omitted: both.\n\nFetch a row's thread from GET /apis/v1/ads/{adId}/comments?placement={placement}.\n\nAd comment counts are read with the Marketing API token (Facebook side) or the connected Instagram account's token (Instagram side). A row whose count can't be read is omitted.\n\n### Pagination\n\nPagination walks each account's platform listing. Following `nextCursor` reaches past the first page on Facebook, Instagram, Threads, LinkedIn and YouTube, the platforms that support a server-side date window. On the others the listing stops at its first page.\n\nCursor pagination is only coherent for the default sort (`sortBy=date`, `sortOrder=desc`). With `sortOrder=asc`, or with `sortBy=comments`, the cursor filter does not match the sort order and the second page is unreliable.\n\n`minComments` is applied to each page after pagination. A page can hold fewer than `limit` posts, even none, while `hasMore` is true; keep following `nextCursor`.\n\n`nextCursor` is opaque: pass it back verbatim, never construct or parse it, its composition may change without notice. Because each page re-queries a live window, results can still shift between requests, so dedupe by `id` on the client.\n\n### Comment counts\n\n`commentCount` semantics differ by platform:\n\n- YouTube's includes replies.\n- Facebook's counts top-level comments only.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_inbox_comments", "parameters": [ { "description": "One of your profiles (prf_...). Defaults to your default profile when neither profileId nor accountId is sent.", "in": "query", "name": "profileId", "required": false, "schema": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Filter by platform. `metaads` is a synthetic value meaning the user's ads (boosted/dark posts) only; `facebook`/`instagram` return organic posts only. `tiktok` covers accounts connected through the TikTok Business app only; developer-app TikTok accounts are returned under `meta.accountsSkipped`.", "in": "query", "name": "platform", "required": false, "schema": { "enum": [ "facebook", "instagram", "twitter", "bluesky", "threads", "youtube", "linkedin", "reddit", "tiktok", "metaads" ], "type": "string" } }, { "description": "Minimum comment count, applied to each page after pagination", "in": "query", "name": "minComments", "required": false, "schema": { "minimum": 0, "type": "integer" } }, { "description": "Posts created after this date", "in": "query", "name": "since", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Sort field", "in": "query", "name": "sortBy", "required": false, "schema": { "default": "date", "enum": [ "date", "comments" ], "type": "string" } }, { "description": "Sort order", "in": "query", "name": "sortOrder", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": false, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "accountUsername": { "type": "string" }, "adId": { "description": "Internal AIsa ad id, only on ad rows.", "type": "string" }, "cid": { "description": "Bluesky content identifier", "type": [ "string", "null" ] }, "commentCount": { "type": "integer" }, "content": { "description": "The post text/caption. On ad rows (isAd: true) this is the AD NAME, not the underlying post's caption. The creative text isn't exposed here.", "type": "string" }, "createdTime": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "isAd": { "description": "True when this row is an ad (boosted/dark post). `platform` is then the placement (facebook = the Page dark post / instagram = the IG media), `id` is `{adId}:{placement}`, and the thread is at GET /apis/v1/ads/{adId}/comments?placement={placement}.", "type": "boolean" }, "likeCount": { "description": "Not fetched for ad rows (always 0 there).", "type": "integer" }, "permalink": { "description": "Public URL of the post. On ad rows: the Facebook dark-post URL (facebook placement) or the IG media permalink (instagram placement); may be null when unknown.", "type": [ "string", "null" ] }, "picture": { "description": "Post media thumbnail. On ad rows this is the ad creative thumbnail.", "type": [ "string", "null" ] }, "placement": { "description": "Which side of the ad this row's comments are on, only on ad rows.", "enum": [ "facebook", "instagram" ], "type": "string" }, "platform": { "type": "string" }, "subreddit": { "description": "Reddit subreddit name", "type": [ "string", "null" ] } }, "type": "object" }, "type": "array" }, "meta": { "properties": { "accountsFailed": { "type": "integer" }, "accountsQueried": { "type": "integer" }, "accountsSkipped": { "description": "Connected accounts that were not queried: their platform does not support this feature, or the account is not enabled for it", "items": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "platform": { "type": "string" } }, "type": "object" }, "type": "array" }, "failedAccounts": { "items": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "accountUsername": { "type": [ "string", "null" ] }, "code": { "description": "Error code if available (e.g. TOKEN_EXPIRED, or X_INBOX_NOT_ENABLED for an X account whose owner has not enabled X inbox)", "type": [ "string", "null" ] }, "error": { "type": "string" }, "platform": { "type": "string" }, "retryAfter": { "description": "Seconds to wait before retry (rate limits)", "type": [ "integer", "null" ] } }, "type": "object" }, "type": "array" }, "lastUpdated": { "format": "date-time", "type": "string" } }, "type": "object" }, "pagination": { "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] } }, "type": "object" } }, "type": "object" } } }, "description": "Aggregated posts with comments" }, "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." } }, "summary": "List commented posts", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.comments.list_inbox_comments@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "583433374cdac11f0a7816ecc19c58af0fe472148ce76016634dd26a68636fe5" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_inbox_comments", "method": "GET", "path": "/apis/v1/social/inbox/comments" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_inbox_comments" } }, "/apis/v1/social/inbox/comments/{postId}": { "delete": { "description": "Comments. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nDelete a comment on a post. Supported by Facebook, Instagram, Threads, LinkedIn, Reddit, Bluesky, X (Twitter), YouTube, and TikTok (accounts connected through the TikTok for Business app). Not supported on Google Business (reviews only).\nRequires accountId and commentId query parameters.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "delete_aisa_social_apis_v1_social_inbox_comments_postid", "parameters": [ { "description": "AIsa post ID or platform-specific post ID. On LinkedIn, pass the post id exactly as the feed returns it (urn:li:share: or urn:li:ugcPost:); a bare number is read as an activity id (urn:li:activity:).", "in": "path", "name": "postId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "For LinkedIn, accepts either the numeric comment ID or the composite comment URN returned by the comments listing (e.g. urn:li:comment:(threadUrn,id))", "in": "query", "name": "commentId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "message": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Comment deleted" }, "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." } }, "summary": "Delete comment", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.comments.delete_inbox_comment@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "e9228f0b3ec6b25ba753f65e46673bcf8d02f0715c0b028921ccf17e14a5db31" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "delete_aisa_social_apis_v1_social_inbox_comments_postid", "method": "DELETE", "path": "/apis/v1/social/inbox/comments/{postId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/delete_aisa_social_apis_v1_social_inbox_comments_postid" }, "get": { "description": "Comments. 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.\n\nFetch comments for a specific post. Requires accountId query parameter.\n\n### Replies to a comment\n\nPass `commentId` (Facebook, Instagram, Reddit, TikTok) to fetch replies to a specific comment instead of the post's top-level comments.\n\n- Facebook, Instagram and TikTok return the comment's replies, paged by `limit`/`cursor`.\n- Reddit returns the focused comment thread instead.\n- On Facebook and Instagram the requested comment itself comes back in the top-level `comment` field.\n\nOn Facebook, passing a COMMENT id as `postId` (instead of using `commentId`) is also supported for backwards compatibility. It returns that comment's replies the same way.\n\nPrefer `commentId` for new integrations; it also works on Instagram, which rejects a comment id passed as `postId`. YouTube does not support either form: `postId` must be a video id.\n\n### Caching\n\nResponses are cached for up to 10 minutes, so a page may lag new comments by that window.\n\nDo not poll this endpoint for real-time updates: subscribe to the `comment.received` webhook, which delivers new comments as they arrive. Your own writes (creating, replying to, or deleting a comment) refresh the cache immediately.\n\n### TikTok\n\nTikTok is served for accounts connected through the TikTok for Business app:\n\n- `postId` is the TikTok video id.\n- Each top-level comment carries up to three inline replies.\n- `commentId` pages the full reply list of one comment.\n\nDeveloper-app TikTok accounts return 400 with code `PLATFORM_LIMITATION`.\n\n### X (Twitter)\n\nWhen `postId` is itself a reply rather than the thread's root post, only replies to that specific post are returned, not the whole conversation thread.\n\n### Hidden comments\n\n- Facebook Pages and Instagram accounts connected through Instagram Login return them with `isHidden: true`.\n- Instagram accounts connected through Facebook Login do not return them at all (Meta omits them, together with their replies). So a hidden comment and a deleted one look the same on this read.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_inbox_comments_postid", "parameters": [ { "description": "AIsa post ID or platform-specific post ID. AIsa IDs are auto-resolved.\n\n- **LinkedIn:** pass the post id exactly as the feed returns it (urn:li:share: or urn:li:ugcPost:). A bare number is read as an activity id (urn:li:activity:, the number in a linkedin.com/feed/update URL), so a share or ugcPost number passed bare returns an empty list.\n- **Facebook:** a comment ID is also accepted and returns that comment's replies (kept for backwards compatibility). Prefer the `commentId` query parameter, which also works on Instagram.", "in": "path", "name": "postId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "(Reddit only) Subreddit name", "in": "query", "name": "subreddit", "required": false, "schema": { "type": "string" } }, { "description": "Maximum number of comments to return", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Pagination cursor, returned by a previous call as `pagination.cursor`. This is the platform's own opaque paging value passed through verbatim: never construct, decode or validate it client-side.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "(Facebook, Instagram, Reddit and TikTok) Get replies to a specific comment. On Facebook and Instagram, the requested comment is returned in the top-level `comment` field and comments[] holds its replies.", "in": "query", "name": "commentId", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "comment": { "description": "(Facebook and Instagram only) Present when `commentId` was passed: the requested\ncomment itself, in the same shape as an entry in comments[]. comments[] then holds\nthat comment's replies instead of the post's top-level comments.", "type": "object" }, "comments": { "items": { "properties": { "canDelete": { "type": "boolean" }, "canHide": { "description": "Whether this comment can be hidden (Facebook, Instagram, Threads)", "type": "boolean" }, "canLike": { "description": "Whether this comment can be liked (Facebook, X, Bluesky, Reddit, LinkedIn)", "type": "boolean" }, "canReply": { "type": "boolean" }, "cid": { "description": "Bluesky content identifier", "type": [ "string", "null" ] }, "createdTime": { "format": "date-time", "type": "string" }, "from": { "properties": { "id": { "type": "string" }, "isOwner": { "type": "boolean" }, "name": { "type": "string" }, "picture": { "type": [ "string", "null" ] }, "username": { "type": "string" }, "verifiedType": { "description": "X verified badge type. Only present for X comments.", "enum": [ "blue", "government", "business", "none" ], "type": [ "string", "null" ] } }, "type": "object" }, "id": { "type": "string" }, "isHidden": { "description": "Whether the comment is currently hidden. On Instagram accounts connected through Facebook Login, Meta leaves hidden comments (and their replies) out of the list entirely, so they never appear with isHidden true; Instagram Login accounts and Facebook Pages return them with isHidden true.", "type": "boolean" }, "isLiked": { "description": "Whether the current user has liked this comment", "type": "boolean" }, "likeCount": { "type": "integer" }, "likeUri": { "description": "Bluesky like URI for unliking", "type": [ "string", "null" ] }, "message": { "type": "string" }, "parentId": { "description": "ID of the parent comment.\n\n- Facebook and Instagram: present on entries inside replies[]; omitted on top-level entries.\n- X: present inside replies[] and on top-level entries, where it holds the ID of the post replied to.\n- Every other platform: omitted; the parent relationship is expressed only through replies[] nesting.\n\nWhen omitted, the key is absent, not null.", "type": [ "string", "null" ] }, "platform": { "description": "The platform this comment is from", "type": "string" }, "replies": { "items": { "type": "object" }, "type": "array" }, "repliesHasMore": { "description": "Facebook only. True when replies[] (capped at 10) does not hold the comment's full reply thread.\n\nFetch the rest by passing the comment id as the `commentId` query parameter to GET /apis/v1/social/inbox/comments/{postId} (or, for backwards compatibility, as `postId`).\n\nAbsent (not false) on every other platform, including Instagram, which has no equivalent signal.", "type": "boolean" }, "replyCount": { "description": "The platform's own reply count, which includes hidden and deleted replies. Can exceed replies[].length even when repliesHasMore is false or absent.", "type": "integer" }, "rootCid": { "description": "Bluesky root post CID", "type": [ "string", "null" ] }, "rootUri": { "description": "Bluesky root post URI", "type": [ "string", "null" ] }, "url": { "description": "Direct link to the comment on the platform (if available)", "type": [ "string", "null" ] } }, "type": "object" }, "type": "array" }, "meta": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "adComments": { "description": "(Facebook/Instagram only) Present when this post has no organic comments but is a boosted post: the engagement lives on the ad. Use the ad-comments endpoint instead.", "properties": { "adCommentsUrl": { "description": "Path to fetch the ad's comments (GET /apis/v1/ads/{adId}/comments)", "type": "string" }, "adId": { "description": "Internal AIsa ad ID", "type": "string" } }, "type": [ "object", "null" ] }, "lastUpdated": { "format": "date-time", "type": "string" }, "platform": { "type": "string" }, "postId": { "type": "string" }, "postUrn": { "description": "(LinkedIn only) The post URN that was queried, after a bare number is read as urn:li:activity:", "type": "string" }, "subreddit": { "description": "(Reddit only) Subreddit name", "type": [ "string", "null" ] } }, "type": "object" }, "pagination": { "properties": { "cursor": { "description": "Only present when hasMore is true. Absent on the last page, so treat its absence as the end of the thread.", "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "type": "object" }, "post": { "anyOf": [ { "properties": { "author": { "description": "Reddit username, without the u/ prefix", "type": "string" }, "createdUtc": { "description": "Unix timestamp in seconds", "type": "integer" }, "flairText": { "description": "Link flair text if any", "type": [ "string", "null" ] }, "fullname": { "description": "Fullname with type prefix (e.g. \"t3_1tjtj26\")", "type": "string" }, "id": { "description": "Reddit post base36 id (e.g. \"1tjtj26\")", "type": "string" }, "isGallery": { "description": "True if the post is a Reddit gallery (multiple images)", "type": "boolean" }, "numComments": { "type": "integer" }, "over18": { "type": "boolean" }, "permalink": { "description": "Absolute URL to the post on reddit.com", "type": "string" }, "score": { "description": "Net upvotes (upvotes minus downvotes)", "type": "integer" }, "selftext": { "description": "Body text for self-posts (empty for link posts)", "type": "string" }, "stickied": { "type": "boolean" }, "subreddit": { "description": "Subreddit name, without the r/ prefix", "type": "string" }, "title": { "type": "string" }, "url": { "description": "For link posts, the external URL; for self-posts, the Reddit permalink", "type": "string" } }, "type": "object" }, { "properties": { "createdAt": { "description": "Creation time as Meta returns it (e.g. 2026-05-27T17:15:51+0000)", "type": [ "string", "null" ] }, "id": { "description": "Facebook post id ({pageId}_{postId}) or Instagram media id", "type": "string" }, "mediaType": { "description": "Instagram `media_type` (IMAGE, VIDEO, CAROUSEL_ALBUM) or the Facebook attachment type (photo, video_inline, link, ...)", "type": [ "string", "null" ] }, "mediaUrl": { "description": "Instagram `media_url` (the video file for videos). Always null on Facebook. Expiring Meta CDN URL.", "format": "uri", "type": [ "string", "null" ] }, "permalink": { "format": "uri", "type": [ "string", "null" ] }, "productType": { "description": "Instagram `media_product_type`: AD, FEED, REELS or STORY. Always null on Facebook.", "type": [ "string", "null" ] }, "text": { "description": "Facebook post message or Instagram caption", "type": [ "string", "null" ] }, "thumbnailUrl": { "description": "Facebook `full_picture` (or the first attachment image); Instagram `thumbnail_url` for videos, `media_url` for images. Expiring Meta CDN URL.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "createdAt", "id", "mediaType", "mediaUrl", "permalink", "productType", "text", "thumbnailUrl" ], "type": "object" }, { "type": "null" } ], "description": "(Reddit, Facebook and Instagram) Metadata for the target post, returned with the comments so you can render a preview without another request.\n\n**Facebook and Instagram** return the Meta shape: post thumbnail, text and permalink, for any post the account can read, including hidden dark posts Meta publishes per ad variant (dynamic creative, placement asset customization, Advantage+).\n\n- Facebook posts need the Facebook Page connection; Instagram media the Instagram connection.\n- `thumbnailUrl` and `mediaUrl` are expiring Meta CDN URLs: store a copy to render them later.\n- On Instagram, `productType` tells an ad (`AD`) from organic media (`FEED`, `REELS`, `STORY`).\n\n**Absent** on other platforms, when the connection's token cannot read the post, and on Reddit when the upstream response lacks the post listing (deleted post, malformed response)." }, "status": { "type": "string" } }, "type": "object" } } }, "description": "Comments for the post" }, "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." } }, "summary": "Get post comments", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.comments.get_inbox_post_comments@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "fb3ea7a33c35b31367ced32646d9009ce0b47a721407698a4a2e3cc83c68263c" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_inbox_comments_postid", "method": "GET", "path": "/apis/v1/social/inbox/comments/{postId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_inbox_comments_postid" }, "post": { "description": "Comments. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nPost a reply to a post or specific comment. Requires accountId in request body.\n\n### Idempotency\n\nSend an `Idempotency-Key` header to make retries safe (e.g. after a client-side timeout where delivery is unknown).\n\n- Same key + same body replays the original response (with `Idempotent-Replayed: true`) instead of posting the comment a second time.\n- Same key + different body returns 422.\n- A key still in flight returns 409.\n\nKeys are retained for 24 hours and are scoped to the credential and to this exact path. Reusing a key against a different postId returns 422 rather than replaying the other post's response.\n\nOnly successful (2xx) responses are stored for replay. If the request throws or returns a non-2xx status the key is released, so the header protects the \"request succeeded but the response was lost\" case.\n\nAfter an ambiguous failure (a 5xx or a network timeout), list the post's comments before retrying with the same key. Treat an empty result as inconclusive rather than as proof nothing was posted.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_inbox_comments_postid", "parameters": [ { "description": "AIsa post ID or platform-specific post ID. On LinkedIn, pass the post id exactly as the feed returns it (urn:li:share: or urn:li:ugcPost:); a bare number is read as an activity id (urn:li:activity:).", "in": "path", "name": "postId", "required": true, "schema": { "type": "string" } }, { "description": "Passed to the channel: a retry with the same key within 24 hours returns the first result instead of acting twice. AIsa never retries a write for you.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 191, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "accountId": "acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3", "message": "example" }, "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "attachmentUrl": { "description": "(Facebook only) URL of an image to attach, publishing a photo comment alongside the text. The URL must be publicly accessible so Meta can fetch it. Returns 400 for other platforms.", "format": "uri", "type": "string" }, "commentId": { "description": "Reply to specific comment (optional)", "type": "string" }, "message": { "description": "Reply text. On LinkedIn, mention with @[https://www.linkedin.com/in/vanity] (resolved to LinkedIn's live name, same rules and errors as post content) or @Name; a hand-written name must match LinkedIn's exactly or it renders as plain text.", "type": "string" }, "parentCid": { "description": "(Bluesky only) Parent content identifier", "type": "string" }, "rootCid": { "description": "(Bluesky only) Root post CID", "type": "string" }, "rootUri": { "description": "(Bluesky only) Root post URI", "type": "string" } }, "required": [ "accountId", "message" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "cid": { "description": "Bluesky CID", "type": [ "string", "null" ] }, "commentId": { "type": "string" }, "isReply": { "type": "boolean" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Reply posted" }, "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." } }, "summary": "Reply to comment", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.comments.reply_to_inbox_post@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "d5f0d57d476b90876c9bf5826ec72444d6e26d99cae6f8c3b0a92f8109e0fb1a" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_inbox_comments_postid", "method": "POST", "path": "/apis/v1/social/inbox/comments/{postId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_inbox_comments_postid" } }, "/apis/v1/social/inbox/comments/{postId}/{commentId}": { "patch": { "description": "Comments. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nEdit the body of a comment the connected account posted. Supported on Reddit only.\n\nReddit keeps the same comment id after an edit. Reddit exposes no API to edit a post\ntitle, and a link post has no editable body. To edit a published post's body, use\n`POST /apis/v1/social/posts/{postId}/edit`.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "patch_aisa_social_apis_v1_social_inbox_comments_p_24f1a4", "parameters": [ { "in": "path", "name": "postId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "commentId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "accountId": "acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3", "content": "Edited: corrected the version number.", "platform": "reddit" }, "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "content": { "description": "The new comment body", "minLength": 1, "type": "string" }, "platform": { "description": "Only Reddit supports editing a comment", "enum": [ "reddit" ], "type": "string" } }, "required": [ "accountId", "content", "platform" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "commentId": { "type": "string" }, "platform": { "type": "string" }, "status": { "type": "string" } }, "type": "object" } } }, "description": "Comment edited" }, "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." } }, "summary": "Edit comment", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.comments.edit_inbox_comment@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "3ae5d7c4e7a5fc004e90ef611c08979560dd70b7edffb976ed57ccf5c1e32c73" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "patch_aisa_social_apis_v1_social_inbox_comments_p_24f1a4", "method": "PATCH", "path": "/apis/v1/social/inbox/comments/{postId}/{commentId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/patch_aisa_social_apis_v1_social_inbox_comments_p_24f1a4" } }, "/apis/v1/social/inbox/comments/{postId}/{commentId}/hide": { "delete": { "description": "Comments. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nUnhide a previously hidden comment. Supported by Facebook, Instagram, Threads, X, and\nTikTok (accounts connected through the TikTok for Business app).\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "delete_aisa_social_apis_v1_social_inbox_comments__88b782", "parameters": [ { "in": "path", "name": "postId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "commentId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "commentId": { "type": "string" }, "hidden": { "type": "boolean" }, "platform": { "type": "string" }, "status": { "type": "string" } }, "type": "object" } } }, "description": "Comment unhidden" }, "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." } }, "summary": "Unhide comment", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.comments.unhide_inbox_comment@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "eb5c66cbdc852cc0c8c26185c25b5c164caac190c82b72fa12e50d4dae1e9f52" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "delete_aisa_social_apis_v1_social_inbox_comments__88b782", "method": "DELETE", "path": "/apis/v1/social/inbox/comments/{postId}/{commentId}/hide" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/delete_aisa_social_apis_v1_social_inbox_comments__88b782" }, "post": { "description": "Comments. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nHide a comment on a post. Supported by Facebook, Instagram, Threads, X, and TikTok\n(accounts connected through the TikTok for Business app).\nHidden comments are only visible to the commenter and page admin.\nFor X, the reply must belong to a conversation started by the authenticated user.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_inbox_comments_po_88b782", "parameters": [ { "in": "path", "name": "postId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "commentId", "required": true, "schema": { "type": "string" } } ], "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" } }, "required": [ "accountId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "commentId": { "type": "string" }, "hidden": { "type": "boolean" }, "platform": { "type": "string" }, "status": { "type": "string" } }, "type": "object" } } }, "description": "Comment hidden" }, "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." } }, "summary": "Hide comment", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.comments.hide_inbox_comment@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "721be5387437a7caabf12b19384fda092c03704fbdaa348e1dc8738a8c2a02f5" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_inbox_comments_po_88b782", "method": "POST", "path": "/apis/v1/social/inbox/comments/{postId}/{commentId}/hide" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_inbox_comments_po_88b782" } }, "/apis/v1/social/inbox/comments/{postId}/{commentId}/like": { "delete": { "description": "Comments. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nRemove a like from a comment. Supported platforms: Facebook, X, Bluesky,\nReddit, LinkedIn, and Instagram in limited release. For Bluesky, the likeUri query\nparameter is required. Instagram has the same limited release, Facebook Login,\n`instagram_manage_engagement` and burst-limit constraints as liking.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "delete_aisa_social_apis_v1_social_inbox_comments__730d0d", "parameters": [ { "in": "path", "name": "postId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "commentId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "(Bluesky only) The like URI returned when liking", "in": "query", "name": "likeUri", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "commentId": { "type": "string" }, "liked": { "type": "boolean" }, "platform": { "type": "string" }, "status": { "type": "string" } }, "type": "object" } } }, "description": "Comment unliked" }, "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." } }, "summary": "Unlike comment", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.comments.unlike_inbox_comment@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "cdf1471b3b9180c0c46606e741be011cfdc530b38224e80575a69a7333a2f230" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "delete_aisa_social_apis_v1_social_inbox_comments__730d0d", "method": "DELETE", "path": "/apis/v1/social/inbox/comments/{postId}/{commentId}/like" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/delete_aisa_social_apis_v1_social_inbox_comments__730d0d" }, "post": { "description": "Comments. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nLike or upvote a comment on a post. Supported platforms: Facebook, X, Bluesky, Reddit, LinkedIn, and Instagram in limited release (see below).\n\n### Platform notes\n\n- Bluesky: the cid (content identifier) is required in the request body.\n- LinkedIn: pass the composite comment URN returned by the comments endpoints as commentId. An optional reactionType picks the reaction (defaults to LIKE).\n- LinkedIn: accounts connected before the social-feed scopes were requested get a 403 with code `linkedin_reconnect_required`.\n\n### Instagram (limited release)\n\nInstagram is in LIMITED RELEASE and not generally available. The call needs `instagram_manage_engagement`, which Meta has so far granted this app only under Standard Access.\n\nIt works for app admins, developers and testers of our Meta app, and returns a 403 with code `PLATFORM_BETA_RESTRICTED` for every other account. That restriction lifts when Meta App Review grants Advanced Access; the constraints below apply once it does.\n\nInstagram covers comments and replies on feed posts, reels and carousels. Only an account connected through Facebook Login can be granted `instagram_manage_engagement`.\n\n- 400 `instagram_likes_require_facebook_login`: the account is an Instagram Login connection.\n- 403 `reconnect_required`: the account's token predates the permission.\n- Content from private accounts cannot be liked.\n\nInstagram enforces a burst limit of 50 like or unlike calls per 5 seconds per Instagram account. Exceeding it locks that account out of the like API for an hour, so pace bulk loops.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_inbox_comments_po_730d0d", "parameters": [ { "in": "path", "name": "postId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "commentId", "required": true, "schema": { "type": "string" } } ], "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" }, "cid": { "description": "(Bluesky only) Content identifier for the comment", "type": "string" }, "reactionType": { "description": "(LinkedIn only) Reaction to create. Defaults to LIKE; ignored on other platforms.", "enum": [ "LIKE", "PRAISE", "EMPATHY", "INTEREST", "APPRECIATION", "ENTERTAINMENT" ], "type": "string" } }, "required": [ "accountId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "alreadyReacted": { "description": "LinkedIn only: the account already had this exact reaction, so nothing was created", "type": "boolean" }, "commentId": { "type": "string" }, "likeUri": { "description": "(Bluesky only) URI to use for unliking", "type": "string" }, "liked": { "type": "boolean" }, "platform": { "type": "string" }, "reactionType": { "description": "LinkedIn only: the reaction type now in effect", "type": "string" }, "status": { "type": "string" } }, "type": "object" } } }, "description": "Comment liked" }, "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." } }, "summary": "Like comment", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.comments.like_inbox_comment@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "c50094e3ef0f48bceded2e4ce213c182e8c74fe8a52ca2bfd6b57d0c9b1a1a4e" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_inbox_comments_po_730d0d", "method": "POST", "path": "/apis/v1/social/inbox/comments/{postId}/{commentId}/like" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_inbox_comments_po_730d0d" } }, "/apis/v1/social/inbox/comments/{postId}/{commentId}/moderation": { "post": { "description": "Comments. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nSet a comment's moderation status. Supported on YouTube only.\n\nUse this to work a moderation queue: approve a held comment (`published`), reject it\n(`rejected`), or send it back for review (`heldForReview`).\n\nThe request must be authorized by the owner of the channel or video the comment\nbelongs to. You cannot moderate comments on videos you do not own.\n\nThis is distinct from `POST /apis/v1/social/inbox/comments/{postId}/{commentId}/hide`, which\ncovers Facebook, Instagram, Threads, and X and does not apply to YouTube.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_inbox_comments_po_671930", "parameters": [ { "in": "path", "name": "postId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "commentId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "accountId": "acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3", "banAuthor": true, "moderationStatus": "rejected", "platform": "youtube" }, "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "banAuthor": { "description": "Also ban the comment's author, auto-rejecting their future comments. Only valid when moderationStatus is \"rejected\"; any other pairing is a 400.", "type": "boolean" }, "moderationStatus": { "description": "published approves the comment, rejected removes it, heldForReview returns it to the queue.", "enum": [ "published", "rejected", "heldForReview" ], "type": "string" }, "platform": { "description": "Only YouTube supports comment moderation", "enum": [ "youtube" ], "type": "string" } }, "required": [ "accountId", "moderationStatus", "platform" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Moderation status applied" }, "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." } }, "summary": "Set comment moderation status", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.comments.set_comment_moderation@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "3da3835c74344416c7c7e97b2c36fc25f2284b47ba0690f80fffead3ae3719cd" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_inbox_comments_po_671930", "method": "POST", "path": "/apis/v1/social/inbox/comments/{postId}/{commentId}/moderation" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_inbox_comments_po_671930" } }, "/apis/v1/social/inbox/comments/{postId}/{commentId}/pin": { "delete": { "description": "Comments. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nUnpin a previously pinned comment. TikTok accounts connected through the TikTok for\nBusiness app only.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "delete_aisa_social_apis_v1_social_inbox_comments__610ba9", "parameters": [ { "in": "path", "name": "postId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "commentId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "commentId": { "type": "string" }, "pinned": { "type": "boolean" }, "platform": { "type": "string" }, "status": { "type": "string" } }, "type": "object" } } }, "description": "Comment unpinned" }, "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." } }, "summary": "Unpin comment", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.comments.unpin_inbox_comment@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "147a15e3df80716a689ffdf98174a42a50872b6cca159f55a7c1a770d1ca84e0" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "delete_aisa_social_apis_v1_social_inbox_comments__610ba9", "method": "DELETE", "path": "/apis/v1/social/inbox/comments/{postId}/{commentId}/pin" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/delete_aisa_social_apis_v1_social_inbox_comments__610ba9" }, "post": { "description": "Comments. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nPin a top-level comment to the top of a post's comment section. TikTok accounts\nconnected through the TikTok for Business app only; every other platform returns 400.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_inbox_comments_po_610ba9", "parameters": [ { "in": "path", "name": "postId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "commentId", "required": true, "schema": { "type": "string" } } ], "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" } }, "required": [ "accountId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "commentId": { "type": "string" }, "pinned": { "type": "boolean" }, "platform": { "type": "string" }, "status": { "type": "string" } }, "type": "object" } } }, "description": "Comment pinned" }, "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." } }, "summary": "Pin comment", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.comments.pin_inbox_comment@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "b78a88c7f6bdcc509b129bdbe87af6c28e6b2f43891307663f2f66ef7b5c2c18" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_inbox_comments_po_610ba9", "method": "POST", "path": "/apis/v1/social/inbox/comments/{postId}/{commentId}/pin" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_inbox_comments_po_610ba9" } }, "/apis/v1/social/inbox/comments/{postId}/{commentId}/private-reply": { "post": { "description": "Comments. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call. X accounts are not accepted. Paid: see x-aisa-pricing; charged only when the call succeeds.\n\nSend a direct message to the author of a comment. Supported on Instagram and Facebook only.\n\nOne reply per comment, must be sent within 7 days.\n\n### Interactive elements\n\nOptionally attach one of these (`quickReplies` and `buttons` are mutually exclusive):\n\n- `quickReplies`: chips above the keyboard, max 13. Chips do not render in the Instagram Message Requests folder.\n- `buttons`: 1-3 inline postback/url buttons rendered in the same bubble via Meta's button_template.\n\n### Non-followers on Instagram\n\nInstagram can refuse buttons, cards and attachments to commenters who do not follow the account. This is Meta code 2, subcode 1545133, returned here as a non-retryable 400 that says so.\n\nThe refusal is uneven: most accounts do not get it, and an affected account gets it on many of its non-followers. Only that account's own past refusals show whether it is affected.\n\nThe failed call still consumes the comment's single private reply. On an affected account, send plain text to reach non-followers and add buttons once they reply.\n\n### Errors\n\n- 400 with `details.privateReplyConsumed: true`: the comment's single private reply is spent (by this call or an earlier one). Never retry it.\n- 502: Meta answered a server error after receiving the reply. It carries `details.privateReplyOutcome: \"unknown\"`. The reply is usually delivered and the comment's private reply spent, so check the conversation before retrying.\n\n### Recording\n\nThe reply is recorded in the inbox conversation with the commenter (`sentVia` `api` for key auth, `human` for a session) and fires `message.sent` once.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_inbox_comments_po_0e2abe", "parameters": [ { "description": "The media/post ID (Instagram media ID or Facebook post ID)", "in": "path", "name": "postId", "required": true, "schema": { "type": "string" } }, { "description": "The comment ID to send a private reply to", "in": "path", "name": "commentId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "accountId": "acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3", "message": "Hi! Thanks for your comment. I wanted to reach out privately to help with your question." }, "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "buttons": { "description": "Optional 1-3 inline buttons rendered as part of the same message bubble\nvia Meta's button_template. Visible in the Instagram Message Requests\nfolder (unlike quick replies). Mutually exclusive with `quickReplies`.", "items": { "oneOf": [ { "properties": { "title": { "description": "Label shown on the button.", "maxLength": 20, "type": "string" }, "type": { "enum": [ "url" ], "type": "string" }, "url": { "description": "URL opened when the button is tapped.", "format": "uri", "type": "string" } }, "required": [ "title", "type", "url" ], "type": "object" }, { "properties": { "payload": { "description": "Opaque value returned in the inbound webhook when the user taps the button.", "type": "string" }, "title": { "description": "Label shown on the button.", "maxLength": 20, "type": "string" }, "type": { "enum": [ "postback" ], "type": "string" } }, "required": [ "payload", "title", "type" ], "type": "object" }, { "properties": { "phone": { "description": "E.164 phone number dialed when tapped. Facebook only.", "type": "string" }, "title": { "description": "Label shown on the button. Facebook only.", "maxLength": 20, "type": "string" }, "type": { "enum": [ "phone" ], "type": "string" } }, "required": [ "phone", "title", "type" ], "type": "object" } ] }, "maxItems": 3, "minItems": 1, "type": "array" }, "message": { "description": "The message text to send as a private DM", "type": "string" }, "quickReplies": { "description": "Optional quick-reply chips appended to the message. Visible only in the\nInstagram and Messenger apps (not on web). Maximum 13 entries. Mutually\nexclusive with `buttons`. Note: chips do NOT render in the Instagram\nMessage Requests folder where DMs from non-followers land. Use `buttons`\ninstead for cold reach.", "items": { "properties": { "imageUrl": { "description": "Optional thumbnail shown next to the chip title.", "format": "uri", "type": "string" }, "payload": { "description": "Opaque value returned in the inbound webhook when the user taps the chip.", "type": "string" }, "title": { "description": "Label shown on the chip. Truncated by Meta beyond 20 characters.", "maxLength": 20, "type": "string" } }, "required": [ "payload", "title" ], "type": "object" }, "maxItems": 13, "type": "array" } }, "required": [ "accountId", "message" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "commentId": { "description": "The comment ID that was replied to", "type": "string" }, "messageId": { "description": "The ID of the sent message", "type": "string" }, "platform": { "enum": [ "instagram", "facebook" ], "type": "string" }, "status": { "type": "string" } }, "type": "object" } } }, "description": "Private reply sent successfully" }, "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." } }, "summary": "Send private reply", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.comments.send_private_reply_to_comment@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "customer_micros_usd": 100, "description": "Charged once per successful call. The base price is AIsa's own cost for the call: $0.0001 (one message delivered to a recipient). X accounts are not accepted. This is the price on every plan; no plan multiplier applies. A refused or failed call, or one whose outcome is unknown, is not charged.", "kind": "fixed_request" }, "x-aisa-revision": { "handler_contract_hash": "4bd0d03faeed6e70694d526ade655e7533a7580c7b3238cd3c5f7874682fc179" }, "x-aisa-status": "disabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_inbox_comments_po_0e2abe", "method": "POST", "path": "/apis/v1/social/inbox/comments/{postId}/{commentId}/private-reply" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_inbox_comments_po_0e2abe" } }, "/apis/v1/social/inbox/conversations": { "get": { "description": "Inbox. 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. Without profileId or accountId it reads your default profile. On a profile with an X account, pass accountId or a platform other than twitter: X bills each read.\n\nFetch conversations (DMs) from all connected messaging accounts in a single API call. Supports filtering by profile and platform. Results are aggregated and deduplicated.\n\nSupported platforms: Facebook, Instagram, X, Bluesky, Reddit, Telegram, WhatsApp, iMessage and SMS.\n\n### X limitation\n\nX has replaced traditional DMs with encrypted \"X Chat\" for many accounts. Messages sent or received through encrypted X Chat are not accessible via X's API (the /2/dm_events endpoint only returns legacy unencrypted DMs).\n\nThis means some X conversations may show only outgoing messages or appear empty. This is an X platform limitation that affects all third-party applications. See X's docs on encrypted messaging for more details.\n\n### Instagram and Facebook pre-connect history\n\nWhen one of these accounts is connected, AIsa replays the DM history the account already holds on Meta, so conversations that began before the account was connected appear here. Up to 500 conversations per account are replayed.\n\n- The replay runs in the background and can finish after a listing you have already taken.\n- Replayed conversations keep their original lastMessageAt, so they sort into date order rather than appearing at the top.\n- If you mirror this endpoint into your own store, re-run the sweep rather than relying on a single pass at connect time.\n- Replayed history emits no webhooks and is stored as already read, so it never affects unread counts.\n- Threads that Meta refuses to serve are skipped.\n- An account whose Instagram \"connected tools\" message access is turned off is not replayed at all.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_inbox_conversations", "parameters": [ { "description": "One of your profiles (prf_...). Defaults to your default profile when neither profileId nor accountId is sent.", "in": "query", "name": "profileId", "required": false, "schema": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Filter by platform", "in": "query", "name": "platform", "required": false, "schema": { "enum": [ "facebook", "instagram", "twitter", "bluesky", "reddit", "telegram", "whatsapp", "imessage", "sms" ], "type": "string" } }, { "description": "Filter by conversation status", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "active", "archived" ], "type": "string" } }, { "description": "`requests` lists Facebook Page Message Requests (threads from people the account has not accepted) live from Meta, each item with `folder: requests`.\n\nMeta has no accept call: replying moves a thread to the inbox, which is what POST /apis/v1/social/inbox/conversations/{conversationId}/accept does.\n\n- When Meta will not list the folder for the one account asked (`accountId`), the call answers 400 PLATFORM_LIMITATION. Across several accounts, the refusal is reported per account in meta.failedAccounts.\n- Instagram accounts (Instagram Login and Facebook Login) answer PLATFORM_LIMITATION, because Meta does not separate the folder on Instagram. Only Facebook Pages are served.\n\nOne page of up to `limit` threads. `pagination.hasMore` is true when threads past `limit` were cut (narrow with `accountId`). `pagination.nextCursor` is always null and a `cursor` answers 400.", "in": "query", "name": "folder", "required": false, "schema": { "default": "inbox", "enum": [ "inbox", "requests" ], "type": "string" } }, { "description": "Sort order by updated time", "in": "query", "name": "sortOrder", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Maximum number of conversations to return; values above 100 are served as 100.", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Pagination cursor for next page", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": false, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Comma-separated contact tags. Returns only conversations whose contact has any of them. Cannot be combined with folder=requests.", "in": "query", "name": "tags", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "accountUsername": { "type": "string" }, "adAttribution": { "description": "The ad that opened the conversation, enriched from the ads AIsa syncs for the account owner. null when the conversation did not start from a Meta referral (ad click or ig.me / m.me ref link).\n\nMeta's referral carries the ad ID but no campaign or ad set ID.\n\n- Ad in your synced ads (`GET /apis/v1/ads`): `synced` is true and the ad name, campaign, ad set and ad account come from there.\n- Otherwise: `synced` is false, `name` falls back to the ad title (Instagram, Facebook) or headline (WhatsApp) Meta sent with the click, and the other fields are null.\n\nA team member limited to some profiles, or a profile-scoped API key, is enriched only from ads it can list with `GET /apis/v1/ads`; any other ad returns `synced` false.\n\nA non-null object with `adId` null is a referral that is not an ad click: an ig.me / m.me ref link (`name` null) or a WhatsApp click on a post (`ctwa_source_type` post, `name` is Meta's headline). Nothing is looked up and `synced` is false.", "properties": { "adAccountId": { "description": "Meta ad account ID (act_...). Synced ads only.", "type": [ "string", "null" ] }, "adAccountName": { "description": "Ad account name. Synced ads only.", "type": [ "string", "null" ] }, "adId": { "description": "Meta's ad ID: `meta_ad_id` on Instagram and Facebook, `ctwa_source_id` on WhatsApp when `ctwa_source_type` is `ad`. Accepted by `GET /apis/v1/ads/{adId}`.", "type": [ "string", "null" ] }, "adSetId": { "description": "Meta ad set ID. Synced ads only.", "type": [ "string", "null" ] }, "adSetName": { "description": "Ad set name. Synced ads only.", "type": [ "string", "null" ] }, "campaignId": { "description": "Meta campaign ID. Synced ads only.", "type": [ "string", "null" ] }, "campaignName": { "description": "Campaign name. Synced ads only.", "type": [ "string", "null" ] }, "isExternal": { "description": "True when the ad was created outside AIsa (synced from Ads Manager), false when created through AIsa, null when not synced.", "type": [ "boolean", "null" ] }, "name": { "description": "The synced ad's name, else the ad title or headline Meta sent.", "type": [ "string", "null" ] }, "platformPostId": { "description": "The post the ad promotes, from the synced ad or else Meta's `post_id` on the click.", "type": [ "string", "null" ] }, "synced": { "description": "True when the ad was found in your synced ads.", "type": "boolean" } }, "required": [ "adAccountId", "adAccountName", "adId", "adSetId", "adSetName", "campaignId", "campaignName", "isExternal", "name", "platformPostId", "synced" ], "type": [ "object", "null" ] }, "businessScopedUserId": { "description": "WhatsApp only. Meta business-scoped user ID (BSUID), the stable identity anchor; present when Meta has sent it for this participant.", "type": "string" }, "folder": { "description": "Present only on items listed with folder=requests: a Message Request the account has not accepted yet.", "enum": [ "requests" ], "type": "string" }, "id": { "description": "Opaque conversation identifier. Pass it back verbatim to any /apis/v1/social/inbox/conversations/{conversationId} route; do not assume a fixed format.", "type": "string" }, "instagramProfile": { "description": "Instagram profile data for the participant. Only present for Instagram conversations.", "properties": { "fetchedAt": { "description": "When this profile data was last fetched from Instagram", "format": "date-time", "type": [ "string", "null" ] }, "followerCount": { "description": "The participant's follower count on Instagram", "type": [ "integer", "null" ] }, "isFollower": { "description": "Whether the participant follows your Instagram business account", "type": [ "boolean", "null" ] }, "isFollowing": { "description": "Whether your Instagram business account follows the participant", "type": [ "boolean", "null" ] }, "isVerified": { "description": "Whether the participant is a verified Instagram user", "type": [ "boolean", "null" ] } }, "type": [ "object", "null" ] }, "isGroup": { "description": "iMessage only, true for a group thread. Manage it through the /apis/v1/social/imessage/groups/{conversationId} endpoints.", "type": "boolean" }, "lastMessage": { "type": "string" }, "metadata": { "description": "Click attribution for a conversation that started from a Meta ad or a ref-tagged ig.me / m.me link, as Meta sent it. Absent when the conversation did not come from an attributable click. For the ad name, campaign and ad set, read `adAttribution`.\n\n**First referral wins.** Values come from the referral Meta delivers for the click. If the same person later arrives through another ad or link, the original values are kept. For the fresh referral per click, read the `message.received` / `referral.received` webhooks.\n\nOn Instagram Click-to-Direct, Meta usually delivers the ad post first as an attachment-only `share` / `ig_post` message with no referral, then attaches the referral to the next message.\n\nWhatsApp exception: when Meta omits `ctwa_clid` from the referral, a later Meta automatic event can supply it and refresh `ctwa_captured_at`. Treat `ctwa_captured_at` as when AIsa stored the value, not when the click happened.\n\n**Two key families, one per surface, never together:**\n\n- `ctwa_*`: WhatsApp Click-to-WhatsApp. The ad ID is `ctwa_source_id`. There is no `meta_ad_id` on WhatsApp.\n- `meta_ad_*`: Instagram Click-to-Direct, Facebook Messenger Click-to-Message, and ig.me / m.me ref links. The ad ID is `meta_ad_id` (ad clicks only; a link capture carries `meta_ad_ref` without it). `ctwa_clid` never appears here.\n\nEvery key is optional and only keys Meta supplied are returned, so read defensively. Meta sends no campaign or ad set ID; those are resolved from your synced ads in `adAttribution`. More keys may be added; treat unknown keys as opaque strings.\n\nKey names differ from the `message.received` webhook on purpose. The webhook forwards Meta's referral verbatim (`ad_id`, `source`, `type`), while the stored conversation uses the prefixed names. Renaming either side would break existing integrations, so both spellings stay.", "properties": { "ctwa_body": { "description": "WhatsApp only. Body text of the ad creative at click time.", "type": "string" }, "ctwa_captured_at": { "description": "WhatsApp only. When AIsa stored this referral. Always present when a WhatsApp referral was captured.", "format": "date-time", "type": "string" }, "ctwa_clid": { "description": "WhatsApp only. Meta's click identifier, the value to forward to the Meta Conversions API for Business Messaging. Meta omits it on some numbers, so a WhatsApp referral can arrive without it.", "type": "string" }, "ctwa_headline": { "description": "WhatsApp only. Headline of the ad creative at click time.", "type": "string" }, "ctwa_image_url": { "description": "WhatsApp only. Image of the ad creative at click time (image ads).", "type": "string" }, "ctwa_media_type": { "description": "WhatsApp only. Media type of the ad creative, image or video.", "type": "string" }, "ctwa_source_id": { "description": "WhatsApp only. The Meta ad ID the user clicked (or the post ID when `ctwa_source_type` is post). This is the WhatsApp equivalent of meta_ad_id.", "type": "string" }, "ctwa_source_type": { "description": "WhatsApp only. What the user clicked, as supplied by Meta (for example ad or post).", "type": "string" }, "ctwa_source_url": { "description": "WhatsApp only. Meta's URL for the ad that was clicked, normally an fb.me short link.", "type": "string" }, "ctwa_thumbnail_url": { "description": "WhatsApp only. Thumbnail of the ad video at click time (video ads).", "type": "string" }, "ctwa_video_url": { "description": "WhatsApp only. Video of the ad creative at click time (video ads).", "type": "string" }, "meta_ad_captured_at": { "description": "Instagram and Facebook only. When AIsa stored this referral. Always present when an Instagram or Facebook referral was captured.", "format": "date-time", "type": "string" }, "meta_ad_flow_id": { "description": "Instagram and Facebook only. The Meta flow the ad launched, for flow ads.", "type": "string" }, "meta_ad_id": { "description": "Instagram and Facebook only. The Meta ad ID the user clicked. Present for ad clicks; absent when the capture came from an ig.me / m.me ref link.", "type": "string" }, "meta_ad_photo_url": { "description": "Instagram and Facebook only. Image of the ad creative at click time.", "type": "string" }, "meta_ad_post_id": { "description": "Instagram and Facebook only. The organic post the ad promoted, when the ad was a boosted post.", "type": "string" }, "meta_ad_product_id": { "description": "Instagram and Facebook only. The catalogue product the user clicked, for product ads.", "type": "string" }, "meta_ad_ref": { "description": "Instagram and Facebook only. The ref parameter passed through from the ad creative or the ig.me / m.me link.", "type": "string" }, "meta_ad_source": { "description": "Instagram and Facebook only. Meta-supplied source identifier: ADS for ad clicks; SHORTLINK, SHORTLINKS or IGME-SOURCE-LINK for ref links (treat as opaque).", "type": "string" }, "meta_ad_title": { "description": "Instagram and Facebook only. Title of the ad creative at click time.", "type": "string" }, "meta_ad_type": { "description": "Instagram and Facebook only. Meta-supplied referral type, for example OPEN_THREAD.", "type": "string" }, "meta_ad_video_url": { "description": "Instagram and Facebook only. Video of the ad creative at click time.", "type": "string" } }, "type": [ "object", "null" ] }, "pageId": { "description": "The bare Facebook Page id behind the account, for Facebook and Instagram connected through Facebook Login. Null when the account has no Facebook Page.", "type": [ "string", "null" ] }, "participantId": { "type": "string" }, "participantName": { "type": "string" }, "participantPicture": { "type": [ "string", "null" ] }, "participantVerifiedType": { "description": "X verified badge type. Only present for X conversations.", "enum": [ "blue", "government", "business", "none" ], "type": [ "string", "null" ] }, "platform": { "type": "string" }, "status": { "enum": [ "active", "archived" ], "type": "string" }, "threadControl": { "description": "Present once a handover has touched the thread (WhatsApp, Facebook, Instagram). ai_agent: Meta Business Agent answers (WhatsApp) and new inbound arrive flagged metadata.standby; app: you hold control; other: another app does (a WhatsApp partner, or a Messenger / Instagram receiver such as Page Inbox). Change it with POST /apis/v1/social/inbox/conversations/{conversationId}/thread-control.", "enum": [ "app", "ai_agent", "other" ], "type": "string" }, "unreadCount": { "description": "Number of unread incoming messages, capped at 1000. Read from a replica, so it can trail a conversation you just marked read by a few seconds.", "maximum": 1000, "type": [ "integer", "null" ] }, "updatedTime": { "format": "date-time", "type": "string" }, "url": { "description": "Direct link to open the conversation on the platform (if available)", "type": [ "string", "null" ] }, "whatsappUsername": { "description": "WhatsApp only. The participant's WhatsApp username (e.g. `jane.shop`, no leading @). Not a stable identifier, because users can change it: useful for display, not recommended as an identity anchor. Captured from inbound messages, so older threads fill in on their next inbound.", "type": "string" } }, "type": "object" }, "type": "array" }, "meta": { "properties": { "accountsFailed": { "type": "integer" }, "accountsQueried": { "type": "integer" }, "accountsSkipped": { "description": "Connected accounts that were not queried: their platform does not support this feature, or the account is not enabled for it", "items": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "platform": { "type": "string" } }, "type": "object" }, "type": "array" }, "failedAccounts": { "items": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "accountUsername": { "type": [ "string", "null" ] }, "code": { "description": "Error code if available", "type": [ "string", "null" ] }, "error": { "type": "string" }, "platform": { "type": "string" }, "retryAfter": { "description": "Seconds to wait before retry (rate limits)", "type": [ "integer", "null" ] } }, "type": "object" }, "type": "array" }, "lastUpdated": { "format": "date-time", "type": "string" } }, "type": "object" }, "pagination": { "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] } }, "type": "object" } }, "type": "object" } } }, "description": "Aggregated conversations" }, "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." } }, "summary": "List conversations", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.inbox.list_inbox_conversations@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "ad5e6071e3e37eda20df5ac0774bcdb17a0d6d6ea393b187995b4abc0abc9545" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_inbox_conversations", "method": "GET", "path": "/apis/v1/social/inbox/conversations" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_inbox_conversations" }, "post": { "description": "Inbox. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call. Paid: see x-aisa-pricing; charged only when the call succeeds.\n\nStart a direct message conversation with a user. If a conversation with that recipient already exists, the message is added to the existing thread.\n\nSupported platforms: X, Bluesky, Reddit, WhatsApp, SMS, Slack, iMessage, and email (Google and Microsoft accounts). Other platforms return PLATFORM_NOT_SUPPORTED.\n\n### Email (Google / Microsoft)\n\nPass the recipient address as participantId with `subject`, `message` and optionally `cc`. The mail is sent from the mailbox and mirrored into the inbox. The response names the inbox conversation it opened (the provider thread id, usable with the other inbox endpoints).\n\n- 412 `account_scope_missing`: the account was connected without the `email` area\n- 409: the account is disconnected\n- 402 `payment_required`: Gmail accounts need a card on file\n\nSends count toward the mailbox's daily cap and never toward managed messages.\n\n### iMessage\n\nPass the recipient as participantId: a phone number in international format (+15551234567) or an iMessage email. Senders ordered through AIsa can message contacts who never wrote to them.\n\n#### Opening message rules\n\nThe first message to such a contact must be plain text from an identifiable person or business opening a conversation.\n\nA cold introduction, including a sales one, is fine (\"Hi Mark, this is John from Pratt Media. I help local roofers get more leads. Would you be open to a quick chat?\").\n\nIt may not contain links, email addresses, phone numbers, prices or attachments (the provider's own rule for opening messages). One that does returns 400 with code `invalid_content` and a message saying what was flagged, and nothing is sent.\n\n#### New contact limits\n\nEach sender may open at most one new conversation every 15 minutes. A new sender warms up, allowing this many new conversations per 24 hours:\n\n- Days 1-2 after activation: 2\n- Days 3-4: 5\n- Days 5-7: 10\n- Days 8-14: 20\n- Days 15-21: 30\n- After that: 50\n\nBeyond that the request returns 429 with code `new_contact_limit` and a time to retry. The warm-up counts from when a sender ordered through AIsa went live. Senders registered from your own provider account are not warmed up by AIsa.\n\n#### Follow-ups before the contact replies\n\nUntil the contact replies, the thread accepts the opening and at most two follow-ups, at least 24 hours apart.\n\n- A follow-up sooner returns 429 `new_contact_limit` with the time to retry.\n- A fourth message returns 409 `recipient_must_message_first`.\n\nThe provider treats every message to a contact who has not replied as a new conversation.\n\nFollow-ups therefore follow the same content rule and count toward the 15-minute spacing and the daily warm-up like an opening. Once the contact has written, the thread behaves like any other and is not limited.\n\n#### Sender safety\n\nRecipients can report a first message as junk, and reports can get a sender blocked permanently, so keep the reply rate high (above roughly 30%).\n\n- A sender registered with your own provider account may lack the add-on for new contacts. Its sends to them return 409 `recipient_must_message_first`, and an opt-in link is the way in.\n- A contact who opted out returns 409 `recipient_opted_out`.\n\n### Slack\n\nPass a workspace member id as participantId (list them with GET /apis/v1/social/accounts/{accountId}/slack-members). AIsa opens the DM channel with that member and sends the message. The thread then behaves like any other Slack conversation in the inbox. The member must belong to the connected workspace.\n\n### WhatsApp\n\nThis is the endpoint for sending an approved template message to a phone number. Put the recipient phone in participantId and provide:\n\n- templateName\n- templateLanguage\n- templateParams: variable values for the text header, body and dynamic URL buttons, in that order\n\nA template is required because WhatsApp does not permit freeform messages to open a conversation. A missing template returns TEMPLATE_REQUIRED.\n\n#### Template lookup\n\nBefore sending, AIsa must resolve an exact APPROVED template d\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_inbox_conversations", "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" }, "category": { "description": "WhatsApp only (Meta Direct Send). Combined with message and without templateName, starts the conversation with a business-initiated UTILITY message and no pre-approved template. Meta matches or auto-creates a template asynchronously.\n\n- The WhatsApp Business Account must be eligible for Direct Send; otherwise the send fails with an error telling you to use an approved message template instead.\n- Cannot be combined with templateName (templates are already categorized at creation).\n- Utility messages only: marketing content is not allowed under this category.\n- Accepted on the JSON body only, not on multipart requests.", "enum": [ "utility" ], "type": "string" }, "cc": { "description": "Email accounts only (Google / Microsoft). Extra recipients copied on the opening mail.", "items": { "format": "email", "type": "string" }, "maxItems": 50, "type": "array" }, "headerLocation": { "description": "WhatsApp only. Required to send a template whose approved header format is LOCATION: Meta only accepts the location's lat/long at send time, never at template creation, so there is nothing to fill in automatically. Cannot be combined with headerMedia (a template has exactly one header).", "properties": { "address": { "description": "Location address shown to the recipient.", "type": "string" }, "latitude": { "description": "Latitude in decimal degrees.", "type": "number" }, "longitude": { "description": "Longitude in decimal degrees.", "type": "number" }, "name": { "description": "Location name shown to the recipient (e.g. a business name).", "type": "string" } }, "required": [ "latitude", "longitude" ], "type": "object" }, "headerMedia": { "description": "WhatsApp only. Overrides a media-header template's header asset for THIS send, so a template with an image/video/document header can carry a different asset per message (e.g. each recipient their own invoice PDF). Without it, the template's approved sample asset is sent. Provide exactly one of link or id.", "properties": { "filename": { "description": "Document display name shown to the recipient (e.g. \"Factura 0001-123.pdf\"). document type only; ignored for image/video.", "type": "string" }, "id": { "description": "A Meta media id (from the media upload endpoint), as an alternative to link.", "type": "string" }, "link": { "description": "Public URL of the asset to send. Must be reachable without auth.", "type": "string" }, "type": { "description": "Must match the template header's media type.", "enum": [ "image", "video", "document" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, "linkPreview": { "default": true, "description": "WhatsApp only. Set false to send the Direct Send (category: 'utility') text message without a link-preview thumbnail for the first URL in the text.\n\nDefaults to true, which is how every WhatsApp text has been sent to date. Does not apply to template sends. Accepted on the JSON body only, not on multipart requests.", "type": "boolean" }, "message": { "description": "Text content of the message. At least one of message, attachment, or (for WhatsApp) templateName is required. Required when category is set (a Direct Send utility message is a text message). Required on email accounts.", "type": "string" }, "participantId": { "description": "Recipient identifier. Provide either this or participantUsername.\n\n- X: the numeric user ID.\n- WhatsApp and SMS: the recipient phone number in international format (digits, country code included).\n- Slack: the workspace member id (e.g. U01ABCDEF).\n- iMessage: a phone number in international format with the leading +, or an iMessage email.", "type": "string" }, "participantUsername": { "description": "Recipient handle/username, an X or Bluesky handle (with or without @) or a Reddit username (with or without u/). Resolved via lookup. Provide either this or participantId.", "type": "string" }, "skipDmCheck": { "default": false, "description": "X only. Skip the receives_your_dm eligibility check before sending. Use if you have already verified the recipient accepts DMs.", "type": "boolean" }, "subject": { "description": "Email accounts only (Google / Microsoft). Subject of the new thread.", "maxLength": 998, "type": "string" }, "templateButtonParams": { "description": "WhatsApp only. Values for template buttons that take one at send time, each addressed by the button's position in the approved template.\n\nThis is the only way to send a copy-code button's payload (a Pix payment code, a coupon) or a flow token, since templateParams is a flat array of text variables covering dynamic URL buttons only.\n\n- A button here overrides what templateParams would derive for that index, so no button is sent twice.\n- Repeating an index within this array is rejected with 400.\n- Each index must name a button of the matching kind on the approved template. This is checked before the send and returns 400 (INVALID_TEMPLATE_BUTTON_PARAM) rather than a Meta rejection.", "items": { "properties": { "index": { "description": "Zero-based position of the button in the approved template's buttons.", "maximum": 9, "minimum": 0, "type": "integer" }, "subType": { "description": "The button kind, which decides how the value is sent: copy_code sends it as the coupon_code payload, flow as the flow token, url as the dynamic suffix appended to the button's base URL.", "enum": [ "url", "copy_code", "flow" ], "type": "string" }, "value": { "description": "The value to send (e.g. the Pix copy-and-paste code for a copy_code button).", "minLength": 1, "type": "string" } }, "required": [ "index", "subType", "value" ], "type": "object" }, "maxItems": 10, "type": "array" }, "templateCards": { "description": "WhatsApp only. Per-card overrides for a CAROUSEL template, each addressed by the card's card_index.\n\nCarousel card body variables restart at {{1}} per card, so they cannot be expressed in the flat templateParams slot order; use this instead.\n\nRejected with 400 (INVALID_TEMPLATE_CARD_PARAM): a cardIndex naming a card the approved template lacks, a duplicate cardIndex, or a params count that does not match the card body's token count.", "items": { "properties": { "buttons": { "description": "Values for this card's own buttons, each addressed by the button's index within the card.", "items": { "properties": { "index": { "description": "Zero-based position of the button within the card's buttons.", "maximum": 1, "minimum": 0, "type": "integer" }, "subType": { "description": "The button kind, which decides how the value is sent.", "enum": [ "quick_reply", "url" ], "type": "string" }, "value": { "description": "The value to send (quick_reply payload, or the URL dynamic suffix).", "minLength": 1, "type": "string" } }, "required": [ "index", "subType", "value" ], "type": "object" }, "maxItems": 2, "type": "array" }, "cardIndex": { "description": "The card's card_index in the approved template.", "maximum": 9, "minimum": 0, "type": "integer" }, "headerMedia": { "description": "Overrides this card's header asset for THIS send. Without it, the card's approved sample asset is sent.", "properties": { "id": { "description": "A Meta media id (from the media upload endpoint), as an alternative to link.", "type": "string" }, "link": { "description": "Public URL of the asset to send. Must be reachable without auth.", "type": "string" }, "type": { "description": "Must match the card header's media type.", "enum": [ "image", "video", "document" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, "params": { "description": "Values for this card's own body variables, in the card's own {{1}}, {{2}}, ... order (or named-slot order of appearance).", "items": { "type": "string" }, "type": "array" } }, "required": [ "cardIndex" ], "type": "object" }, "maxItems": 10, "type": "array" }, "templateLanguage": { "description": "WhatsApp only. Template language code (e.g. en_US).", "type": "string" }, "templateName": { "description": "WhatsApp only. Name of the approved template to start the conversation with. Required for WhatsApp unless category is used instead (Direct Send). Cannot be combined with category.", "type": "string" }, "templateParams": { "description": "WhatsApp only. Template variable values as one flat array, in order of appearance across the whole template: text-header variables, then body variables, then one value per dynamic URL button (in button order).\n\nWorks with positional placeholders ({{1}}, {{2}}, ...) and named placeholders ({{name}}, {{company}}, as Meta Business Manager creates them); values fill named slots in order of appearance.\n\nExample: a body with {{1}}, {{2}} plus a URL button https://example.com/{{1}} takes three values: [body1, body2, buttonSuffix].\n\nFor positional templates the list must cover every slot. Fewer values than the header + body + dynamic URL-button count is rejected with 400 (code INVALID_TEMPLATE_PARAMS) naming the expected split, rather than filling a button URL from the wrong value.\n\nA dynamic URL button covered by templateButtonParams needs no value here, unless another uncovered dynamic URL button follows it (the override applies after slot numbering).\n\nTake no value here:\n\n- Media headers (image, video, document): filled automatically from the approved template. Use headerMedia to override the header asset per send.\n- Non-dynamic-URL buttons (copy-code, flow): use templateButtonParams.", "items": { "type": "string" }, "type": "array" } }, "required": [ "accountId" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "conversationId": { "description": "Platform conversation ID (dm_conversation_id). For WhatsApp, this is AIsa's internal conversation id (24-character hex) which matches the id returned by the list-conversations endpoint and the conversationId in the message.received and conversation.started webhooks; use it to correlate the created thread with inbound events.", "type": "string" }, "messageId": { "description": "Platform message ID (dm_event_id)", "type": "string" }, "participantId": { "description": "X numeric user ID of the recipient", "type": "string" }, "participantName": { "description": "Display name of the recipient", "type": [ "string", "null" ] }, "participantUsername": { "description": "X username of the recipient", "type": [ "string", "null" ] } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Conversation created successfully" }, "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." } }, "summary": "Create conversation", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.inbox.create_inbox_conversation@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "customer_micros_usd": 100, "description": "Charged once per successful call. The base price is AIsa's own cost for the call: $0.015 on X accounts (one X direct message sent, at X's API rate), $0.0001 on every other platform (one message delivered to a recipient). This is the price on every plan; no plan multiplier applies. A refused or failed call, or one whose outcome is unknown, is not charged.", "kind": "fixed_request", "variants": { "twitter": { "customer_micros_usd": 15000, "kind": "fixed_request" } } }, "x-aisa-revision": { "handler_contract_hash": "964e196f7f4b9482fee83afcc324e4e6f83df7357d55462ebfd822623d16e12c" }, "x-aisa-status": "disabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_inbox_conversations", "method": "POST", "path": "/apis/v1/social/inbox/conversations" }, "x-codeSamples": [ { "lang": "text", "label": "Reference example", "source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/social/inbox/conversations \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"accountId\": \"acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3\"\n}'" } ], "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_inbox_conversations" } }, "/apis/v1/social/inbox/conversations/search": { "get": { "description": "Inbox. 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. Without profileId or accountId it reads your default profile. On a profile with an X account, pass accountId or a platform other than twitter: X bills each read.\n\nSearch your conversations two ways at once, and get back the matching conversations, most-recent match first.\n\n### Message text\n\nMatches words inside message bodies. Case-insensitive and accent-insensitive, exact tokens only (no substrings, no stemming). Each hit carries up to 3 most-recent matching messages.\n\nWith direction=outgoing you can collect examples of how you write to customers, for example to teach an AI agent your tone of voice.\n\n### Contact identity\n\nMatches the participant's name, username, or phone number as a case-insensitive substring. These hits have matchCount 0 and an empty matches array.\n\nA conversation that matches both ways is returned once, carrying its message matches.\n\n### Searchable platforms\n\nOnly platforms whose messages are stored by AIsa are searchable: WhatsApp, SMS, Telegram, Facebook, Instagram, X and Reddit.\n\nBluesky conversations are fetched live from the platform and cannot be searched; those accounts are listed in meta.accountsSkipped.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_inbox_conversation_a94af9", "parameters": [ { "description": "Text to search for, in message content and in the contact's name, username, or phone number", "in": "query", "name": "query", "required": true, "schema": { "maxLength": 200, "minLength": 2, "type": "string" } }, { "description": "Only match messages sent to you (incoming) or by you (outgoing). Contact-identity matching is not applied when this is set.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "incoming", "outgoing" ], "type": "string" } }, { "description": "One of your profiles (prf_...). Defaults to your default profile when neither profileId nor accountId is sent.", "in": "query", "name": "profileId", "required": false, "schema": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Filter by platform (searchable platforms only)", "in": "query", "name": "platform", "required": false, "schema": { "enum": [ "facebook", "instagram", "telegram", "whatsapp", "sms", "rcs", "slack", "imessage" ], "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": false, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Maximum number of conversations to return", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 50, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor. Pass back pagination.nextCursor verbatim; do not construct one.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "conversation": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "businessScopedUserId": { "description": "WhatsApp only. Meta business-scoped user ID (BSUID), the stable identity anchor; present when Meta has sent it for this participant.", "type": "string" }, "id": { "description": "Conversation ID, usable with the conversation messages endpoints", "type": "string" }, "lastMessage": { "description": "The conversation's most recent message preview", "type": [ "string", "null" ] }, "lastMessageAt": { "format": "date-time", "type": [ "string", "null" ] }, "participantName": { "type": [ "string", "null" ] }, "participantPicture": { "type": [ "string", "null" ] }, "participantUsername": { "type": [ "string", "null" ] }, "platform": { "type": "string" }, "status": { "enum": [ "active", "archived" ], "type": "string" }, "whatsappUsername": { "description": "WhatsApp only. The participant's WhatsApp username (e.g. `jane.shop`, no leading @). Not a stable identifier, because users can change it: useful for display, not recommended as an identity anchor. Captured from inbound messages, so older threads fill in on their next inbound.", "type": "string" } }, "type": "object" }, "matchCount": { "description": "Number of matching messages in this conversation. 0 when the conversation matched only on contact identity (name, username, or phone number), not on message text.", "type": "integer" }, "matches": { "description": "Up to 3 most-recent matching messages (empty for an identity-only match)", "items": { "properties": { "direction": { "enum": [ "incoming", "outgoing" ], "type": "string" }, "id": { "type": "string" }, "text": { "type": [ "string", "null" ] }, "timestamp": { "format": "date-time", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" }, "meta": { "properties": { "accountsFailed": { "type": "integer" }, "accountsQueried": { "type": "integer" }, "accountsSkipped": { "description": "Connected messaging accounts that cannot be searched (live-fetched platforms)", "items": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "platform": { "type": "string" } }, "type": "object" }, "type": "array" }, "failedAccounts": { "items": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "accountUsername": { "type": [ "string", "null" ] }, "error": { "type": "string" }, "platform": { "type": "string" } }, "type": "object" }, "type": "array" }, "lastUpdated": { "format": "date-time", "type": "string" } }, "type": "object" }, "pagination": { "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] } }, "type": "object" } }, "type": "object" } } }, "description": "Conversations containing the query, most recent match first" }, "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." } }, "summary": "Search conversations", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.inbox.search_inbox_conversations@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "ac705e517d3507dc0cee1840a815e6856844813d9020d4589c46433bbc41b75e" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_inbox_conversation_a94af9", "method": "GET", "path": "/apis/v1/social/inbox/conversations/search" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_inbox_conversation_a94af9" } }, "/apis/v1/social/inbox/conversations/{conversationId}": { "delete": { "description": "Inbox. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nPermanently deletes AIsa's stored copy of one conversation and every message in it, in one transaction, and unlinks the contact channel that pointed at it.\n\n### What is kept\n\n- Nothing is deleted on the platform (the thread stays in WhatsApp, Messenger or Instagram).\n- The contact record is kept: call DELETE /apis/v1/social/contacts/{contactId} to erase the person's name and number as well.\n\nInbound media copies AIsa stored are removed on a best-effort basis.\n\n### Re-imports\n\nA platform re-sync can import the thread again:\n\n- WhatsApp coexistence numbers receive their messaging history from Meta repeatedly.\n- A Facebook or Instagram account whose DM history walk has not finished imports it on that walk.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "delete_aisa_social_apis_v1_social_inbox_conversat_d09eb3", "parameters": [ { "description": "Opaque conversation identifier, accepted verbatim from the list endpoint or from the conversationId on inbox webhooks. Format not to be assumed.", "in": "path", "name": "conversationId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "deletedMessages": { "type": "integer" }, "id": { "type": "string" }, "platform": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Conversation deleted" }, "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." } }, "summary": "Delete conversation", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.inbox.delete_inbox_conversation@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "4dc3cd7716ed278ceef5a70b5d8527c173400c1f95c778e162c1f3130b7617bb" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "delete_aisa_social_apis_v1_social_inbox_conversat_d09eb3", "method": "DELETE", "path": "/apis/v1/social/inbox/conversations/{conversationId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/delete_aisa_social_apis_v1_social_inbox_conversat_d09eb3" }, "get": { "description": "Inbox. 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.\n\nRetrieve details and metadata for a specific conversation. Requires accountId query parameter.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_inbox_conversation_d09eb3", "parameters": [ { "description": "Opaque conversation identifier, accepted verbatim from the list endpoint or from the conversationId on inbox webhooks. Format not to be assumed.", "in": "path", "name": "conversationId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "accountUsername": { "type": "string" }, "adAttribution": { "description": "The ad that opened the conversation, enriched from the ads AIsa syncs for the account owner. null when the conversation did not start from a Meta referral (ad click or ig.me / m.me ref link).\n\nMeta's referral carries the ad ID but no campaign or ad set ID.\n\n- Ad in your synced ads (`GET /apis/v1/ads`): `synced` is true and the ad name, campaign, ad set and ad account come from there.\n- Otherwise: `synced` is false, `name` falls back to the ad title (Instagram, Facebook) or headline (WhatsApp) Meta sent with the click, and the other fields are null.\n\nA team member limited to some profiles, or a profile-scoped API key, is enriched only from ads it can list with `GET /apis/v1/ads`; any other ad returns `synced` false.\n\nA non-null object with `adId` null is a referral that is not an ad click: an ig.me / m.me ref link (`name` null) or a WhatsApp click on a post (`ctwa_source_type` post, `name` is Meta's headline). Nothing is looked up and `synced` is false.", "properties": { "adAccountId": { "description": "Meta ad account ID (act_...). Synced ads only.", "type": [ "string", "null" ] }, "adAccountName": { "description": "Ad account name. Synced ads only.", "type": [ "string", "null" ] }, "adId": { "description": "Meta's ad ID: `meta_ad_id` on Instagram and Facebook, `ctwa_source_id` on WhatsApp when `ctwa_source_type` is `ad`. Accepted by `GET /apis/v1/ads/{adId}`.", "type": [ "string", "null" ] }, "adSetId": { "description": "Meta ad set ID. Synced ads only.", "type": [ "string", "null" ] }, "adSetName": { "description": "Ad set name. Synced ads only.", "type": [ "string", "null" ] }, "campaignId": { "description": "Meta campaign ID. Synced ads only.", "type": [ "string", "null" ] }, "campaignName": { "description": "Campaign name. Synced ads only.", "type": [ "string", "null" ] }, "isExternal": { "description": "True when the ad was created outside AIsa (synced from Ads Manager), false when created through AIsa, null when not synced.", "type": [ "boolean", "null" ] }, "name": { "description": "The synced ad's name, else the ad title or headline Meta sent.", "type": [ "string", "null" ] }, "platformPostId": { "description": "The post the ad promotes, from the synced ad or else Meta's `post_id` on the click.", "type": [ "string", "null" ] }, "synced": { "description": "True when the ad was found in your synced ads.", "type": "boolean" } }, "required": [ "adAccountId", "adAccountName", "adId", "adSetId", "adSetName", "campaignId", "campaignName", "isExternal", "name", "platformPostId", "synced" ], "type": [ "object", "null" ] }, "businessScopedUserId": { "description": "WhatsApp only. Meta business-scoped user ID (BSUID), the stable identity anchor; present when Meta has sent it for this participant.", "type": "string" }, "id": { "type": "string" }, "instagramProfile": { "description": "Instagram profile data for the participant. Only present for Instagram conversations.", "properties": { "fetchedAt": { "description": "When this profile data was last fetched from Instagram", "format": "date-time", "type": [ "string", "null" ] }, "followerCount": { "description": "The participant's follower count on Instagram", "type": [ "integer", "null" ] }, "isFollower": { "description": "Whether the participant follows your Instagram business account", "type": [ "boolean", "null" ] }, "isFollowing": { "description": "Whether your Instagram business account follows the participant", "type": [ "boolean", "null" ] }, "isVerified": { "description": "Whether the participant is a verified Instagram user", "type": [ "boolean", "null" ] } }, "type": [ "object", "null" ] }, "lastMessage": { "type": "string" }, "lastMessageAt": { "format": "date-time", "type": "string" }, "metadata": { "description": "Click attribution for a conversation that started from a Meta ad or a ref-tagged ig.me / m.me link, as Meta sent it. Absent when the conversation did not come from an attributable click. For the ad name, campaign and ad set, read `adAttribution`.\n\n**First referral wins.** Values come from the referral Meta delivers for the click. If the same person later arrives through another ad or link, the original values are kept. For the fresh referral per click, read the `message.received` / `referral.received` webhooks.\n\nOn Instagram Click-to-Direct, Meta usually delivers the ad post first as an attachment-only `share` / `ig_post` message with no referral, then attaches the referral to the next message.\n\nWhatsApp exception: when Meta omits `ctwa_clid` from the referral, a later Meta automatic event can supply it and refresh `ctwa_captured_at`. Treat `ctwa_captured_at` as when AIsa stored the value, not when the click happened.\n\n**Two key families, one per surface, never together:**\n\n- `ctwa_*`: WhatsApp Click-to-WhatsApp. The ad ID is `ctwa_source_id`. There is no `meta_ad_id` on WhatsApp.\n- `meta_ad_*`: Instagram Click-to-Direct, Facebook Messenger Click-to-Message, and ig.me / m.me ref links. The ad ID is `meta_ad_id` (ad clicks only; a link capture carries `meta_ad_ref` without it). `ctwa_clid` never appears here.\n\nEvery key is optional and only keys Meta supplied are returned, so read defensively. Meta sends no campaign or ad set ID; those are resolved from your synced ads in `adAttribution`. More keys may be added; treat unknown keys as opaque strings.\n\nKey names differ from the `message.received` webhook on purpose. The webhook forwards Meta's referral verbatim (`ad_id`, `source`, `type`), while the stored conversation uses the prefixed names. Renaming either side would break existing integrations, so both spellings stay.", "properties": { "ctwa_body": { "description": "WhatsApp only. Body text of the ad creative at click time.", "type": "string" }, "ctwa_captured_at": { "description": "WhatsApp only. When AIsa stored this referral. Always present when a WhatsApp referral was captured.", "format": "date-time", "type": "string" }, "ctwa_clid": { "description": "WhatsApp only. Meta's click identifier, the value to forward to the Meta Conversions API for Business Messaging. Meta omits it on some numbers, so a WhatsApp referral can arrive without it.", "type": "string" }, "ctwa_headline": { "description": "WhatsApp only. Headline of the ad creative at click time.", "type": "string" }, "ctwa_image_url": { "description": "WhatsApp only. Image of the ad creative at click time (image ads).", "type": "string" }, "ctwa_media_type": { "description": "WhatsApp only. Media type of the ad creative, image or video.", "type": "string" }, "ctwa_source_id": { "description": "WhatsApp only. The Meta ad ID the user clicked (or the post ID when `ctwa_source_type` is post). This is the WhatsApp equivalent of meta_ad_id.", "type": "string" }, "ctwa_source_type": { "description": "WhatsApp only. What the user clicked, as supplied by Meta (for example ad or post).", "type": "string" }, "ctwa_source_url": { "description": "WhatsApp only. Meta's URL for the ad that was clicked, normally an fb.me short link.", "type": "string" }, "ctwa_thumbnail_url": { "description": "WhatsApp only. Thumbnail of the ad video at click time (video ads).", "type": "string" }, "ctwa_video_url": { "description": "WhatsApp only. Video of the ad creative at click time (video ads).", "type": "string" }, "meta_ad_captured_at": { "description": "Instagram and Facebook only. When AIsa stored this referral. Always present when an Instagram or Facebook referral was captured.", "format": "date-time", "type": "string" }, "meta_ad_flow_id": { "description": "Instagram and Facebook only. The Meta flow the ad launched, for flow ads.", "type": "string" }, "meta_ad_id": { "description": "Instagram and Facebook only. The Meta ad ID the user clicked. Present for ad clicks; absent when the capture came from an ig.me / m.me ref link.", "type": "string" }, "meta_ad_photo_url": { "description": "Instagram and Facebook only. Image of the ad creative at click time.", "type": "string" }, "meta_ad_post_id": { "description": "Instagram and Facebook only. The organic post the ad promoted, when the ad was a boosted post.", "type": "string" }, "meta_ad_product_id": { "description": "Instagram and Facebook only. The catalogue product the user clicked, for product ads.", "type": "string" }, "meta_ad_ref": { "description": "Instagram and Facebook only. The ref parameter passed through from the ad creative or the ig.me / m.me link.", "type": "string" }, "meta_ad_source": { "description": "Instagram and Facebook only. Meta-supplied source identifier: ADS for ad clicks; SHORTLINK, SHORTLINKS or IGME-SOURCE-LINK for ref links (treat as opaque).", "type": "string" }, "meta_ad_title": { "description": "Instagram and Facebook only. Title of the ad creative at click time.", "type": "string" }, "meta_ad_type": { "description": "Instagram and Facebook only. Meta-supplied referral type, for example OPEN_THREAD.", "type": "string" }, "meta_ad_video_url": { "description": "Instagram and Facebook only. Video of the ad creative at click time.", "type": "string" } }, "type": [ "object", "null" ] }, "pageId": { "description": "The bare Facebook Page id behind the account, for Facebook and Instagram connected through Facebook Login. Null when the account has no Facebook Page.", "type": [ "string", "null" ] }, "participantId": { "type": "string" }, "participantName": { "type": "string" }, "participantVerifiedType": { "description": "X verified badge type. Only present for X conversations.", "enum": [ "blue", "government", "business", "none" ], "type": [ "string", "null" ] }, "participants": { "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" }, "platform": { "type": "string" }, "status": { "enum": [ "active", "archived" ], "type": "string" }, "updatedTime": { "format": "date-time", "type": "string" }, "whatsappUsername": { "description": "WhatsApp only. The participant's WhatsApp username (e.g. `jane.shop`, no leading @). Not a stable identifier, because users can change it: useful for display, not recommended as an identity anchor. Captured from inbound messages, so older threads fill in on their next inbound.", "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Conversation 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." } }, "summary": "Get conversation", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.inbox.get_inbox_conversation@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "40b24420574b42efe73079c1fbebe4351cbd778669a450923fc6a547f0efca71" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_inbox_conversation_d09eb3", "method": "GET", "path": "/apis/v1/social/inbox/conversations/{conversationId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_inbox_conversation_d09eb3" }, "put": { "description": "Inbox. 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.\n\nArchive or activate a conversation. Requires accountId in request body.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "put_aisa_social_apis_v1_social_inbox_conversation_d09eb3", "parameters": [ { "description": "Opaque conversation identifier, accepted verbatim from the list endpoint or from the conversationId on inbox webhooks. Format not to be assumed.", "in": "path", "name": "conversationId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "accountId": "acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3", "status": "active" }, "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "status": { "enum": [ "active", "archived" ], "type": "string" } }, "required": [ "accountId", "status" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "id": { "type": "string" }, "platform": { "type": "string" }, "status": { "enum": [ "active", "archived" ], "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Conversation 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": { "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." } }, "summary": "Update conversation status", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.inbox.update_inbox_conversation@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "66eea7824abe226327c969fc0cca334a82d2e34a1ed3975d9667f1e4343fec93" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "put_aisa_social_apis_v1_social_inbox_conversation_d09eb3", "method": "PUT", "path": "/apis/v1/social/inbox/conversations/{conversationId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/put_aisa_social_apis_v1_social_inbox_conversation_d09eb3" } }, "/apis/v1/social/inbox/conversations/{conversationId}/accept": { "post": { "description": "Inbox. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nAccept a Facebook or Instagram Message Request by replying to it.\n\nFacebook Page requests are listed with `GET /apis/v1/social/inbox/conversations?folder=requests`; Instagram answers PLATFORM_LIMITATION there.\n\nMeta has no separate accept call: the first reply is what moves the thread into the inbox. So this sends `message` through the same path, checks and webhooks as `POST /apis/v1/social/inbox/conversations/{conversationId}/messages`, and answers the same way.\n\nSupports the `Idempotency-Key` header.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_inbox_conversatio_c57669", "parameters": [ { "description": "The `id` of the request item from the requests folder.", "in": "path", "name": "conversationId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "accountId": "acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3", "message": "Thanks for reaching out! How can we help?" }, "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "message": { "description": "The reply that accepts the request", "minLength": 1, "type": "string" } }, "required": [ "accountId", "message" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "messageId": { "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Reply sent, the request is accepted" }, "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." } }, "summary": "Accept a message request", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.inbox.accept_conversation_request@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "5830b878cb7040372ee838e569b3c4f01bacbc608b1fee524b9f3301db520276" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_inbox_conversatio_c57669", "method": "POST", "path": "/apis/v1/social/inbox/conversations/{conversationId}/accept" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_inbox_conversatio_c57669" } }, "/apis/v1/social/inbox/conversations/{conversationId}/labels": { "get": { "description": "Inbox. 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.\n\nFacebook Messenger only. Lists the Page's custom labels applied to the person in this conversation (Graph `/{psid}/custom_labels`). Other platforms answer 400 `platform_not_supported`.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_inbox_conversation_9b2d37", "parameters": [ { "description": "Conversation ID (AIsa id or Meta platform conversation id)", "in": "path", "name": "conversationId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "labels": { "items": { "properties": { "id": { "description": "Meta label id", "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "The labels on the conversation's participant" }, "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." } }, "summary": "List the labels on a conversation", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.inbox.list_conversation_labels@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "ca37c247b206faeb40d0972c46a1a3b1b2a12dba243d243c14b57f62ae2f37b4" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_inbox_conversation_9b2d37", "method": "GET", "path": "/apis/v1/social/inbox/conversations/{conversationId}/labels" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_inbox_conversation_9b2d37" }, "post": { "description": "Inbox. 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.\n\nFacebook Messenger only. Applies one of the Page's custom labels to the person in this conversation (Graph `POST /{label-id}/label?user={psid}`). The id must be one of the Page's custom labels, otherwise 404 `resource_not_found`. Other platforms answer 400 `platform_not_supported`.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_inbox_conversatio_9b2d37", "parameters": [ { "description": "Conversation ID (AIsa id or Meta platform conversation id)", "in": "path", "name": "conversationId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "accountId": "acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3", "labelId": "1712444532121303" }, "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "labelId": { "description": "Meta label id from listInboxLabels", "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "accountId", "labelId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Label added" }, "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." } }, "summary": "Add a label to a conversation", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.inbox.add_conversation_label@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "82d677168dfd72c460726a66577eeef4b45d87749badfe8f1ac454443951d605" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_inbox_conversatio_9b2d37", "method": "POST", "path": "/apis/v1/social/inbox/conversations/{conversationId}/labels" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_inbox_conversatio_9b2d37" } }, "/apis/v1/social/inbox/conversations/{conversationId}/labels/{labelId}": { "delete": { "description": "Inbox. 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.\n\nFacebook Messenger only. Removes one of the Page's custom labels from the person in this conversation (Graph `DELETE /{label-id}/label?user={psid}`). The label itself stays on the Page. The id must be one of the Page's custom labels, otherwise 404 `resource_not_found`. Other platforms answer 400 `platform_not_supported`.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "delete_aisa_social_apis_v1_social_inbox_conversat_932ebe", "parameters": [ { "description": "Conversation ID (AIsa id or Meta platform conversation id)", "in": "path", "name": "conversationId", "required": true, "schema": { "type": "string" } }, { "description": "Meta label id", "in": "path", "name": "labelId", "required": true, "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Label removed" }, "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." } }, "summary": "Remove a label from a conversation", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.inbox.remove_conversation_label@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "047fe5ac346977e0506f705750b694e5369fa9a177534919d0e749a18f4850c2" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "delete_aisa_social_apis_v1_social_inbox_conversat_932ebe", "method": "DELETE", "path": "/apis/v1/social/inbox/conversations/{conversationId}/labels/{labelId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/delete_aisa_social_apis_v1_social_inbox_conversat_932ebe" } }, "/apis/v1/social/inbox/conversations/{conversationId}/messages": { "get": { "description": "Inbox. 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.\n\nFetch messages for a specific conversation, with cursor-based pagination and ordering control.\n\n### Pagination\n\nPass `pagination.nextCursor` from a prior response back as the `cursor` query param to fetch the next page. The cursor is opaque; do not parse or construct it client-side.\n\n### Sort order\n\nDefaults to `asc` (oldest first, chat style). For the \"show me the latest messages\" pattern, pass `?sortOrder=desc&limit=N`.\n\n- X, Instagram, Telegram, WhatsApp and Reddit honor the requested order from the local message store.\n- Facebook and Bluesky upstream APIs only return newest-first and have no order parameter. Sort order is best-effort and only reverses items within a single page (pages still walk newest→oldest).\n\nThe response field `sortOrderApplied` tells you what was actually applied.\n\n### Platform limits\n\n- **Reddit**: threads are paginated client-side because Reddit's API has no per-thread cursor. Very long threads may be upstream-truncated by Reddit's inbox/sent windows (~100 most-recent items each); this is a Reddit platform limitation.\n- **Instagram and Facebook**: conversations include history from before the account was connected, replayed from Meta. See below.\n- **X**: X's encrypted \"X Chat\" messages are not accessible via the API. Conversations where the other participant uses encrypted X Chat may only show your outgoing messages. See the list conversations endpoint for more details.\n\nThe Meta replay covers the 500 most recent messages per conversation: a longer thread keeps its newest 500 and older messages are not retrievable. Messages that arrived after the account was connected are unaffected. Replayed messages are stored as already read and emit no webhooks.\n\n### Read state\n\nThis endpoint is read-only and does NOT mark messages as read or send read receipts. To mark a conversation read (and send WhatsApp blue ticks on eligible accounts), call `POST /apis/v1/social/inbox/conversations/{conversationId}/read`.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_inbox_conversation_3ceefe", "parameters": [ { "description": "Opaque conversation identifier, accepted verbatim from the list endpoint or from the conversationId on inbox webhooks. Format not to be assumed.", "in": "path", "name": "conversationId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Number of messages to return per page. Default 100, max 100.", "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor. Pass `pagination.nextCursor` from a prior response verbatim: a cursor we cannot parse returns 400 rather than silently restarting from the first page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "Order of returned messages. Default `asc` (oldest first, chat style).\nX, Instagram, Telegram, WhatsApp and Reddit honor this order\nacross cursor pages. For Facebook and Bluesky, only intra-page\nordering is affected. Pages always walk newest→oldest. See\n`sortOrderApplied` in the response.", "in": "query", "name": "sortOrder", "required": false, "schema": { "default": "asc", "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "lastUpdated": { "format": "date-time", "type": "string" }, "messages": { "items": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "attachments": { "items": { "properties": { "filename": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "mimeType": { "description": "MIME type of the media when AIsa knows it. On Instagram and Facebook it is set for shares resolved by content type (`originalType: \"unsupported_type\"`).", "type": "string" }, "originalType": { "description": "Instagram and Facebook only, and present only when it differs from `type`. Meta's own type before normalization:\n\n- `ig_reel` and `reel` become `video`.\n- `ig_post`, `post`, `ig_story` and `story_mention` become `share`.\n\nA story mention is `type: \"share\"` with `originalType: \"story_mention\"`. Render on this field, since `share` alone is ambiguous.\n\n`originalType: \"unsupported_type\"` marks a share Meta did not classify, resolved by content type. `refreshUrl` cannot re-mint it (Meta answers `is_unsupported` with no attachments for the message node), so download it when the `message.received` webhook arrives.", "type": "string" }, "payload": { "additionalProperties": true, "description": "Template content (title, subtitle, image, buttons) when type is template", "type": "object" }, "previewUrl": { "type": [ "string", "null" ] }, "refreshUrl": { "description": "Instagram and Facebook only. Endpoint that resolves this attachment to a working url every time, re-minting it from Meta when the stored one has expired. Safe to store and render indefinitely.\n\nException: an attachment with `originalType: \"unsupported_type\"`. Meta cannot re-serve those, so the endpoint answers 404 once the url has expired.", "type": [ "string", "null" ] }, "type": { "description": "On Instagram and Facebook a shared reel, post or ad reaches AIsa with no type of its own (Meta's `unsupported_type`) and is resolved from the media's Content-Type at ingest into `image`, `video`, `audio` or `file` with `originalType: \"unsupported_type\"`. `unsupported_type` is returned only when the CDN could not be classified in time.", "enum": [ "image", "video", "audio", "file", "sticker", "share", "template", "unsupported_type" ], "type": "string" }, "url": { "description": "Direct media link. On Instagram and Facebook this is a signed Meta CDN url that EXPIRES: use it now, do not store it. Persist `refreshUrl` instead.", "type": "string" } }, "type": "object" }, "type": "array" }, "conversationId": { "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "deletedAt": { "format": "date-time", "type": [ "string", "null" ] }, "deliveredAt": { "format": "date-time", "type": [ "string", "null" ] }, "deliveryError": { "description": "Populated when deliveryStatus === \"failed\".", "properties": { "code": { "type": "integer" }, "details": { "description": "Platform's extended detail for `code` (WhatsApp: Meta's `error_data.details`), when the platform sent one. Absent on SMS.", "type": "string" }, "href": { "description": "Link to the platform's documentation for `code`, when the platform sent one.", "format": "uri", "type": "string" }, "message": { "type": "string" }, "title": { "type": "string" } }, "type": [ "object", "null" ] }, "deliveryStatus": { "description": "Lifecycle status for outgoing messages. Not all platforms emit every state (see webhook support matrix).", "enum": [ "sent", "delivered", "read", "played", "failed", "deleted" ], "type": [ "string", "null" ] }, "direction": { "enum": [ "incoming", "outgoing" ], "type": "string" }, "editCount": { "description": "Total number of edits applied.", "type": "integer" }, "editHistory": { "description": "Every prior version of the message, oldest first.", "items": { "description": "One prior version of an edited message.", "properties": { "attachments": { "items": { "description": "Attachment snapshot inside an edit-history entry.", "properties": { "payload": { "type": "object" }, "type": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "type": "array" }, "editedAt": { "format": "date-time", "type": "string" }, "text": { "type": [ "string", "null" ] } }, "required": [ "attachments", "editedAt", "text" ], "type": "object" }, "type": "array" }, "editedAt": { "description": "When the most recent edit happened.", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "The platform's own message id: the `wamid` on WhatsApp, the `mid` on Instagram and Facebook Messenger.\n\nIt is what `metadata.quotedMessageId` points at, the value to pass as `replyTo` on platforms that support quote-replies, and the `{messageId}` segment of the attachment-resolve URL.\n\nWebhooks deliver the same value as `message.platformMessageId`; this response has no field by that name.", "type": "string" }, "isDeleted": { "description": "True if the sender has deleted (unsent) this message. The original message and attachments fields remain populated.", "type": "boolean" }, "isEdited": { "description": "True if the sender has edited this message at least once.", "type": "boolean" }, "isStoryMention": { "description": "Instagram only. True when the message is the user mentioning the account in their own story. The story itself is the `share` attachment with `originalType: \"story_mention\"`. Also set on imported history, read off Meta's `story.mention`.", "type": "boolean" }, "message": { "type": "string" }, "metadata": { "additionalProperties": true, "description": "Platform-specific extras. Free-form, but commonly includes:\n\n- `quotedMessageId`: the `id` of the message this one replies to (delivered as `message.platformMessageId` on webhooks).\n- `waInteractive`: a compact descriptor of WhatsApp interactive content sent (buttons / list / cta_url / flow / location_request).\n- `metaInteractive`: outgoing Instagram/Facebook buttons, quickReplies and template, as sent.\n- `interactiveType` / `interactiveId`: for inbound interactive taps.\n- `source`: where the message reached us from, not who produced it (read `sentVia` for that). `whatsapp_business_app` / `coexistence_history` on a WhatsApp Coexistence number, `bulk-api` on a POST /apis/v1/social/whatsapp/bulk send.", "type": "object" }, "noRenderableContent": { "description": "Instagram and Facebook Messenger only; absent on other platforms. True when Meta withholds the content of this message from the API (its `is_unsupported` flag): `message` is empty, `attachments` is empty, and there is nothing to fetch, now or later.\n\nDistinguishes such a message from an ordinary empty one, such as a story reply with no text.", "type": "boolean" }, "platform": { "type": "string" }, "reactions": { "description": "Emoji reactions on this message (WhatsApp / Telegram). At most one per party in a 1:1 thread.", "items": { "properties": { "emoji": { "type": "string" }, "fromMe": { "description": "true if the connected account reacted, false if the contact did.", "type": "boolean" }, "reactedAt": { "format": "date-time", "type": "string" } }, "type": "object" }, "type": "array" }, "readAt": { "format": "date-time", "type": [ "string", "null" ] }, "senderId": { "type": "string" }, "senderName": { "type": [ "string", "null" ] }, "senderVerifiedType": { "description": "X verified badge type. Only present for X messages.", "enum": [ "blue", "government", "business", "none" ], "type": [ "string", "null" ] }, "sentAt": { "description": "Original send time for outgoing messages (used for Messenger watermark queries).", "format": "date-time", "type": [ "string", "null" ] }, "sentVia": { "description": "Which AIsa surface produced this outgoing message: `human` (an\noperator in the AIsa inbox), `api` (a call to this API),\n`broadcast`, `sequence`, `workflow`, `comment_automation`, or\n`bulk-api` (POST /apis/v1/social/whatsapp/bulk). Same vocabulary as the `source`\nfilter on the inbox analytics endpoints.\n\nAlways present, and `null` whenever the lineage is unknown: every\nincoming message, any outgoing message sent from the platform's own\napp, and every message stored before this field shipped\n(2026-08). Existing messages are NOT backfilled, so treat `null`\nas \"unknown\", never as \"sent by a human\".", "enum": [ "human", "api", "broadcast", "sequence", "workflow", "comment_automation", "bulk-api", null ], "type": [ "string", "null" ] }, "storyReply": { "description": "Instagram only. Present when the message replies to one of the account's stories. Also set on history imported after connecting, read off Meta's `story.reply_to`.", "properties": { "storyId": { "description": "The Instagram story ID the user replied to.", "type": "string" }, "storyUrl": { "description": "Meta CDN URL for the story media. Expires roughly 24 hours after the story posted; fetch promptly or treat 404s as expected.", "type": "string" } }, "type": "object" }, "subject": { "description": "Reddit message subject", "type": [ "string", "null" ] } }, "type": "object" }, "type": "array" }, "pagination": { "properties": { "hasMore": { "description": "Whether more messages are available beyond this page.", "type": "boolean" }, "nextCursor": { "description": "Opaque cursor to fetch the next page. `null` on the last page.", "type": [ "string", "null" ] } }, "type": "object" }, "sortOrderApplied": { "description": "Sort order actually applied to the returned page. May\ndiffer from the requested `sortOrder` for Facebook and\nBluesky (always `desc` regardless of request).", "enum": [ "asc", "desc" ], "type": "string" }, "status": { "type": "string" } }, "type": "object" } } }, "description": "Messages in conversation" }, "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." } }, "summary": "List messages", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.inbox.get_inbox_conversation_messages@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "81b0b14f161c6af1f24b13005ccbc4c885e97e72a731622209f3475f5e69a80c" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_inbox_conversation_3ceefe", "method": "GET", "path": "/apis/v1/social/inbox/conversations/{conversationId}/messages" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_inbox_conversation_3ceefe" }, "post": { "description": "Inbox. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call. Paid: see x-aisa-pricing; charged only when the call succeeds.\n\nSend a message in a conversation. Supports text, attachments, quick replies, buttons, templates, and message tags. Attachment and interactive message support varies by platform.\n\n### Email threads (Google / Microsoft accounts)\n\nThe text is sent as a reply to the latest mail of the thread, in either direction, with its recipients and a \"Re:\" subject. `cc` adds recipients. `message` is required.\n\n- 400: attachments and `replyTo` are rejected here (use POST /apis/v1/social/email/messages/{messageId}/reply for a reply with attachments)\n- 412 `account_scope_missing`: the account was connected without the `email` area\n- 409: the account is disconnected\n- 402: a Gmail account without a card on file\n\nMail sends count toward the mailbox's daily cap, never toward managed messages.\n\n### WhatsApp per-recipient rate limit\n\nWhatsApp caps how many messages you may send to the same recipient in a short window. It rejects the excess with error code `131056` (\"Too many messages sent to this recipient\").\n\nPace sends to a single recipient at roughly 10 per minute; bursts above that return a `400` with code `131056`. Sends to other recipients are unaffected, so parallelise across recipients rather than flooding one.\n\n### iMessage pacing\n\nMessages to contacts who have not written to the sender in the last 24 hours must be at least 2 minutes apart per sender.\n\nA send inside that window returns `429` with code `new_contact_limit` and the time to retry. Replies to contacts who wrote within the last day are not paced.\n\nA thread opened with `POST /apis/v1/social/inbox/conversations` takes at most two follow-ups before the contact replies, at least 24 hours apart:\n\n- `429 new_contact_limit`: a follow-up sent sooner\n- `409 recipient_must_message_first`: a fourth message\n\nEach such follow-up counts as a new conversation:\n\n- No links, emails, phone numbers, prices or attachments (`400 invalid_content`).\n- It uses the sender's 15-minute spacing and daily warm-up (`429 new_contact_limit`).\n\nText must be shorter than 10,000 characters.\n\n### WhatsApp template messages\n\nTo send an approved template into this conversation (required when the 24-hour customer-service window is closed), use the `template` field with a single element carrying the template reference: `{ \"elements\": [{ \"name\": ..., \"language\": ..., \"components\": [...] }] }`. See the `template` field below for the exact shape.\n\nTo send a template to a phone number you have no conversation with yet, use the create-conversation endpoint (POST /apis/v1/social/inbox/conversations) instead.\n\n#### Template lookup\n\nAIsa resolves the exact APPROVED template name and language before any WhatsApp template send. A failed lookup or missing exact definition sends no message and returns code `platform_api_error`, type `platform_error`, and platform `whatsapp`.\n\nSanitized Meta code, message, and `error_data.details` are returned in `platformError`. `details` identifies `phase: template_lookup`, the query-free endpoint, upstream status, and only safe provider usage or retry headers.\n\n### WhatsApp interactive messages\n\nRich interactive messages (list, CTA URL, Flow, location request) are available via the `interactive` field. Tap events are delivered through the `message.received` webhook with WhatsApp-specific `metadata` fields (`interactiveType`, `interactiveId`, `flowResponseJson`, `flowResponseData`).\n\n### Idempotency\n\nSend an `Idempotency-Key` header to make retries safe (e.g. after a client-side timeout where delivery is unknown). Works for JSON and multipart (file upload) requests alike. Keys are retained for 24 hours.\n\n- Same key + same body: replays the original response (with `Idempotent-Replayed: true`) instead of sending the message a second time.\n- Same key + different body: returns 422.\n- A key still in flight: returns 409.\n\nOnly successful (2xx) responses are stored for replay. If the request throws or returns a non-2xx status, the key is released so the same key can be retried once the problem is fixed.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_inbox_conversatio_3ceefe", "parameters": [ { "description": "Opaque conversation identifier, accepted verbatim from the list endpoint or from the conversationId on inbox webhooks. Format not to be assumed.", "in": "path", "name": "conversationId", "required": true, "schema": { "type": "string" } }, { "description": "Passed to the channel: a retry with the same key within 24 hours returns the first result instead of acting twice. AIsa never retries a write for you.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 191, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "accountId": "acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3", "attachmentType": "image", "attachmentUrl": "https://cdn.example.com/property.jpg", "buttons": [ { "payload": "btn_0", "title": "Yes", "type": "postback" }, { "payload": "btn_1", "title": "No", "type": "postback" } ], "message": "Reply yes to continue." }, "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "attachmentName": { "description": "WhatsApp only. Display name for a document sent via attachmentUrl with attachmentType: file (e.g. \"Report.pdf\"). Maps to the recipient's file name; without it WhatsApp derives the name from the URL and shows \"Untitled\". Ignored for image/video/audio and for binary uploads (which use the uploaded file's name).", "type": "string" }, "attachmentType": { "description": "Type of attachment. Defaults to file if not specified.", "enum": [ "image", "video", "audio", "file" ], "type": "string" }, "attachmentUrl": { "description": "URL of the attachment to send (image, video, audio, or file). Must be publicly accessible. For binary file uploads, use multipart/form-data instead.\n\nOn WhatsApp, an image, video, or file combined with `buttons` renders as the header of one interactive reply-button message. Audio cannot be combined with buttons.", "type": "string" }, "buttons": { "description": "Action buttons. Max 3 items. Mutually exclusive with quickReplies.\n\n**Instagram / Facebook.** Also mutually exclusive with `template`: a Meta message carries one body shape, so sending both is a 400 rather than a silent drop of the buttons.\n\nThe buttons and `message` render as Meta's button_template (one bubble with the text and the buttons below it), so `message` must be 640 characters or less when buttons are attached (400 otherwise).\n\n**WhatsApp.** Buttons always render as interactive reply buttons. Only `title` and `payload` are used; `type`, `url`, and `phone` are ignored. WhatsApp has no URL/phone button in this field: use the `interactive` field with `type: cta_url` for a link button.\n\n`payload` becomes the button reply ID delivered on the `message.received` webhook when the user taps. For a simple reply-button message, provide `title` + `payload` and set `type: postback`, e.g. `{ \"type\": \"postback\", \"title\": \"Yes\", \"payload\": \"yes\" }`.\n\nCombine `buttons` with `attachmentUrl` and `attachmentType` `image`, `video`, or `file` to render one WhatsApp message with a media header, body text and reply buttons. Audio is not a supported interactive header and returns 400 when combined with buttons.", "items": { "properties": { "payload": { "description": "Payload for postback-type buttons. On WhatsApp, this is the reply ID returned on the message.received webhook when the button is tapped.", "type": "string" }, "phone": { "description": "Phone number for phone-type buttons (Facebook only)", "type": "string" }, "title": { "description": "Button label (max 20 chars)", "maxLength": 20, "type": "string" }, "type": { "description": "Button type. phone is Facebook only. Ignored on WhatsApp (buttons always render as reply buttons).", "enum": [ "url", "postback", "phone" ], "type": "string" }, "url": { "description": "URL for url-type buttons (Facebook/Instagram only)", "type": "string" } }, "required": [ "title", "type" ], "type": "object" }, "maxItems": 3, "type": "array" }, "category": { "description": "WhatsApp only (Meta Direct Send). Sends a business-initiated UTILITY message without an approved template, e.g. outside the 24-hour customer service window. Meta matches or auto-creates a template asynchronously.\n\n- The WhatsApp Business Account must be eligible for Direct Send; otherwise the send fails, telling you to use an approved message template.\n- Supported only for text messages (link preview ok) and interactive messages (reply buttons, CTA URL buttons, voice-call button, header of text/image/video/document).\n- Cannot be combined with template, attachments, location, or contacts.\n- Utility messages only; marketing content is not allowed.\n- Accepted on the JSON body only, not on multipart requests.", "enum": [ "utility" ], "type": "string" }, "cc": { "description": "Email threads only (Google / Microsoft accounts, JSON body only). Extra recipients copied on the reply.", "items": { "format": "email", "type": "string" }, "maxItems": 50, "type": "array" }, "channel": { "description": "iMessage only (JSON body only). Overrides the delivery channel for this one send; the provider otherwise picks it automatically. The sender must carry the matching add-on (SMS, RCS or WhatsApp), or the send fails. Not a default to set on every request. Rejected with 400 on other platforms.", "enum": [ "imessage", "sms", "rcs", "whatsapp" ], "type": "string" }, "contactCard": { "description": "iMessage only (JSON body only). When `true`, attaches the sender's contact card (vCard) so the recipient can save the sender. Counts as message content on its own, so `message` becomes optional.", "type": "boolean" }, "contacts": { "description": "WhatsApp-only. Send one or more contact cards.", "items": { "properties": { "emails": { "items": { "properties": { "email": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "type": "array" }, "name": { "properties": { "first_name": { "type": "string" }, "formatted_name": { "description": "Full display name.", "type": "string" }, "last_name": { "type": "string" } }, "required": [ "formatted_name" ], "type": "object" }, "phones": { "items": { "properties": { "phone": { "type": "string" }, "type": { "description": "e.g. CELL, WORK, HOME.", "type": "string" } }, "type": "object" }, "type": "array" } }, "required": [ "name" ], "type": "object" }, "type": "array" }, "effect": { "description": "iMessage only (JSON body only). Apple screen/bubble animation played when the message arrives. Rejected with 400 on other platforms.", "enum": [ "slam", "loud", "gentle", "invisibleInk", "echo", "spotlight", "balloons", "confetti", "love", "lasers", "fireworks", "shootingStar", "celebration" ], "type": "string" }, "interactive": { "description": "WhatsApp only. Rich interactive payload for list messages, CTA URL buttons, Flow prompts, location requests, voice-call buttons and commerce messages (single product, product list, catalog, carousel). The shape mirrors Meta's Cloud API `interactive` object for the types in the enum below.\n\nWhen set, it takes priority over `buttons` and `quickReplies`. For simple button replies (WhatsApp's `interactive.type: \"button\"`) use `buttons` / `quickReplies` instead: that abstraction caps at 3 buttons and handles the auto-conversion for you. Use this field only for the enum types.\n\nAll interactive messages are session messages: they can only be sent inside the 24-hour customer service window opened by the user's last inbound message.\n\nCommerce types (`product`, `product_list`, `catalog_message`, and product carousels) require a Meta catalog connected to the WhatsApp Business Account in Commerce Manager. Media carousels (image/video cards) do not need a catalog.\n\nRules per type:\n\n- `product`: `body` is optional (WhatsApp renders the product card itself) and `header` is not allowed (the product image is the header).\n- `product_list`: a `header` with `type: \"text\"` is required.\n- `carousel`: top-level `header`/`footer` are not supported; media goes on each card instead.\n- `voice_call`: renders WhatsApp's native call button; tapping it starts a voice call to your business number. Requires WhatsApp Business Calling on the sending number. The optional `parameters.payload` string is echoed back on the `calls` webhook (as `cta_payload`) for attribution.\n- `location_request_message`: `action` may be omitted (we default it to `{ \"name\": \"send_location\" }`). WhatsApp renders a localized \"Send location\" button; the reply arrives as a regular location message in the conversation.\n- `request_contact_info`: `action` may be omitted (we default it to `{ \"name\": \"request_contact_info\" }`). The localized share button cannot be relabelled, so put the reason for asking in `body.text`: this is a consent prompt, and a bare request converts badly.\n- `request_contact_info` reply: arrives as an inbound `contacts` message with `metadata.contactsOrigin` set to `contact_request`, and we fold the shared number back into the contact automatically. A `contacts` message with origin `other` is a card picked from the address book, NOT proof of the user's own number.\n- `catalog_message`: `action` may also be omitted (we default it to `{ \"name\": \"catalog_message\" }`).\n- `address_message`: `parameters.country` is required (Meta rejects the whole send without it); everything else in `parameters` (`values`, `saved_addresses`, `validation_errors`) is forwarded to Meta as-is.\n- `address_message` availability: Meta's native structured shipping-address capture, generally available in India as of 2026-08. Check Meta's documentation for current country availability before relying on it elsewhere.\n- `address_message` reply: the submitted address arrives as an `nfm_reply` on the `message.received` webhook, like a Flow submission, but with `metadata.nfmReplyName` set to `address_message` so you can tell the two apart.\n\nTap events come back via the `message.received` webhook with `metadata.interactiveType` set to `list_reply` or `nfm_reply`. Carts submitted from commerce messages arrive as `metadata.order`; product inquiries arrive as `metadata.referredProduct`.", "properties": { "action": { "oneOf": [ { "description": "List action. `type` on the parent must be `list`.", "properties": { "button": { "description": "CTA label that opens the list (max ~20 chars).", "type": "string" }, "sections": { "description": "1-10 sections. Total rows across all sections cannot exceed 10.", "items": { "properties": { "rows": { "items": { "properties": { "description": { "type": "string" }, "id": { "type": "string" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "maxItems": 10, "minItems": 1, "type": "array" }, "title": { "description": "Optional section header (max 24 chars).", "type": "string" } }, "required": [ "rows" ], "type": "object" }, "maxItems": 10, "minItems": 1, "type": "array" } }, "required": [ "button", "sections" ], "type": "object" }, { "description": "CTA URL action. `type` on the parent must be `cta_url`.", "properties": { "name": { "enum": [ "cta_url" ], "type": "string" }, "parameters": { "properties": { "display_text": { "description": "Button label (max 20 chars).", "type": "string" }, "url": { "description": "Target URL opened when the user taps the button.", "format": "uri", "type": "string" } }, "required": [ "display_text", "url" ], "type": "object" } }, "required": [ "name", "parameters" ], "type": "object" }, { "description": "Voice-call action. `type` on the parent must be `voice_call`. Renders WhatsApp's native call button (requires Calling enabled on the sending number).", "properties": { "name": { "enum": [ "voice_call" ], "type": "string" }, "parameters": { "description": "All optional.", "properties": { "display_text": { "description": "Button label. Defaults to \"Call Now\".", "maxLength": 20, "type": "string" }, "payload": { "description": "Arbitrary string echoed back as `cta_payload` on the `calls` webhook (connect/terminate) for attribution.", "maxLength": 512, "type": "string" }, "ttl_minutes": { "description": "How long the button stays tappable. Defaults to 10080 (7 days).", "maximum": 43200, "minimum": 1, "type": "integer" } }, "type": "object" } }, "required": [ "name" ], "type": "object" }, { "description": "Flow action. `type` on the parent must be `flow`.", "properties": { "name": { "enum": [ "flow" ], "type": "string" }, "parameters": { "properties": { "flow_action": { "description": "`navigate` sends the user to `flow_action_payload.screen`; `data_exchange` posts data to your Flow endpoint.", "enum": [ "navigate", "data_exchange" ], "type": "string" }, "flow_action_payload": { "description": "Required when flow_action is `navigate`.", "properties": { "data": { "additionalProperties": true, "description": "Optional pre-filled data passed to the screen.", "type": "object" }, "screen": { "description": "First screen to show.", "type": "string" } }, "type": "object" }, "flow_cta": { "description": "Button label that opens the Flow (max 20 chars).", "type": "string" }, "flow_id": { "description": "Published Flow ID from Meta Business Manager.", "type": "string" }, "flow_message_version": { "description": "Defaults to \"3\" when omitted.", "enum": [ "3" ], "type": "string" }, "flow_token": { "description": "Opaque token you choose to correlate Flow responses with your own state (max 200 chars).", "type": "string" }, "mode": { "description": "Set to `draft` to test an unpublished Flow.", "enum": [ "draft" ], "type": "string" } }, "required": [ "flow_action", "flow_cta", "flow_id", "flow_token" ], "type": "object" } }, "required": [ "name", "parameters" ], "type": "object" }, { "description": "Location request action. `type` on the parent must be `location_request_message`. May be omitted entirely; it is defaulted.", "properties": { "name": { "enum": [ "send_location" ], "type": "string" } }, "required": [ "name" ], "type": "object" }, { "description": "Contact-info request action. `type` on the parent must be `request_contact_info`. May be omitted entirely; it is defaulted.", "properties": { "name": { "enum": [ "request_contact_info" ], "type": "string" } }, "required": [ "name" ], "type": "object" }, { "description": "Single-product action. `type` on the parent must be\n`product`. Requires a Meta catalog connected to the\nWhatsApp Business Account in Commerce Manager.", "properties": { "catalog_id": { "description": "Meta catalog ID connected to the WhatsApp Business Account.", "type": "string" }, "product_retailer_id": { "description": "Retailer ID (SKU) of the product inside the catalog.", "type": "string" } }, "required": [ "catalog_id", "product_retailer_id" ], "type": "object" }, { "description": "Multi-product action. `type` on the parent must be\n`product_list`. Requires a Meta catalog connected to the\nWhatsApp Business Account in Commerce Manager.", "properties": { "catalog_id": { "description": "Meta catalog ID connected to the WhatsApp Business Account.", "type": "string" }, "sections": { "description": "1-10 sections. Total products across all sections cannot exceed 30.", "items": { "properties": { "product_items": { "items": { "properties": { "product_retailer_id": { "type": "string" } }, "required": [ "product_retailer_id" ], "type": "object" }, "minItems": 1, "type": "array" }, "title": { "description": "Optional section header.", "type": "string" } }, "required": [ "product_items" ], "type": "object" }, "maxItems": 10, "minItems": 1, "type": "array" } }, "required": [ "catalog_id", "sections" ], "type": "object" }, { "description": "Catalog-message action. `type` on the parent must be\n`catalog_message`. May be omitted entirely; it is defaulted\nto `{ \"name\": \"catalog_message\" }`. Requires a Meta catalog\nconnected to the WhatsApp Business Account in Commerce\nManager.", "properties": { "name": { "enum": [ "catalog_message" ], "type": "string" }, "parameters": { "properties": { "thumbnail_product_retailer_id": { "description": "Optional product whose image is used as the message thumbnail. Falls back to the first catalog item when omitted.", "type": "string" } }, "type": "object" } }, "required": [ "name" ], "type": "object" }, { "description": "Carousel action. `type` on the parent must be `carousel`. Carries 2-10 cards, either:\n\n- all product cards (`type: \"product\"`, all referencing the same `catalog_id`); or\n- media cards (any other `type`, e.g. `cta_url`), each with a required image/video `header`.\n\n`card_index` (0-9, non-repeating) is auto-filled sequentially when omitted.\n\nProduct carousels require a Meta catalog connected to the WhatsApp Business Account in Commerce Manager; media carousels do not.", "properties": { "cards": { "items": { "additionalProperties": true, "properties": { "action": { "description": "Product cards: `{ catalog_id, product_retailer_id }` (required). Media cards: the card's button action (e.g. `cta_url` with `parameters.display_text` and `parameters.url`).", "type": "object" }, "body": { "description": "Optional card body text.", "type": "object" }, "card_index": { "description": "Card position. Auto-filled sequentially when omitted.", "maximum": 9, "minimum": 0, "type": "integer" }, "header": { "description": "Media cards only, required. Carries the card's image or video.", "type": "object" }, "type": { "description": "`product` for a product card; media cards use `cta_url` or a quick-reply type.", "type": "string" } }, "type": "object" }, "maxItems": 10, "minItems": 2, "type": "array" } }, "required": [ "cards" ], "type": "object" }, { "description": "Address-request action. `type` on the parent must be\n`address_message`. Renders Meta's native structured\naddress form in-chat (generally available in India as\nof 2026-08; check Meta's documentation for current\ncountry availability).", "properties": { "name": { "enum": [ "address_message" ], "type": "string" }, "parameters": { "properties": { "country": { "description": "ISO 3166-1 alpha-2 country code Meta should localize the address form for (e.g. IN). Required: Meta rejects the send without it.", "type": "string" }, "saved_addresses": { "description": "Optional list of the recipient's previously saved addresses to offer as quick picks.", "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "validation_errors": { "additionalProperties": { "type": "string" }, "description": "Optional per-field error messages to show when re-prompting after a failed validation.", "type": "object" }, "values": { "additionalProperties": true, "description": "Optional pre-filled address field values.", "type": "object" } }, "required": [ "country" ], "type": "object" } }, "required": [ "name", "parameters" ], "type": "object" } ] }, "body": { "description": "Required for every type except `product`, where it is optional.", "properties": { "text": { "description": "Main body text.", "type": "string" } }, "required": [ "text" ], "type": "object" }, "footer": { "description": "Optional footer shown below the action.", "properties": { "text": { "type": "string" } }, "type": "object" }, "header": { "description": "Optional header shown above the body. Required with\n`type: \"text\"` for `product_list`; not allowed for `product`\nor `carousel`.", "properties": { "document": { "properties": { "link": { "type": "string" } }, "type": "object" }, "image": { "properties": { "link": { "type": "string" } }, "type": "object" }, "text": { "description": "Required when header type is text.", "type": "string" }, "type": { "enum": [ "text", "image", "video", "document" ], "type": "string" }, "video": { "properties": { "link": { "type": "string" } }, "type": "object" } }, "type": "object" }, "type": { "description": "Which interactive layout to render.", "enum": [ "list", "cta_url", "flow", "location_request_message", "request_contact_info", "voice_call", "product", "product_list", "catalog_message", "carousel", "address_message" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, "linkPreview": { "default": true, "description": "WhatsApp and iMessage. Set false to send the message without a link-preview thumbnail. Ignored on other platforms.\n\n- WhatsApp: affects the first URL.\n- iMessage: every link renders as plain text.\n\nDefaults to true, which is how every WhatsApp text has been sent to date. Accepted on the JSON body only, not on multipart requests.", "type": "boolean" }, "location": { "description": "WhatsApp and iMessage. Send a location pin (on iMessage it renders as a native map bubble).", "properties": { "address": { "description": "Optional street address.", "type": "string" }, "latitude": { "description": "Latitude in decimal degrees.", "type": "number" }, "longitude": { "description": "Longitude in decimal degrees.", "type": "number" }, "name": { "description": "Optional location name.", "type": "string" } }, "required": [ "latitude", "longitude" ], "type": "object" }, "message": { "description": "Message text", "type": "string" }, "messageTag": { "description": "Facebook and Instagram. To reply after the 24h window, send HUMAN_AGENT with messagingType MESSAGE_TAG: it works up to 7 days after the person's last message, for replies typed by a person only (Meta does not allow it on automated messages). Meta retired the other tags, so they fail.", "enum": [ "CONFIRMED_EVENT_UPDATE", "POST_PURCHASE_UPDATE", "ACCOUNT_UPDATE", "HUMAN_AGENT" ], "type": "string" }, "messagingType": { "description": "Facebook messaging type. Required when using messageTag.", "enum": [ "RESPONSE", "UPDATE", "MESSAGE_TAG" ], "type": "string" }, "quickReplies": { "description": "Quick reply buttons. Mutually exclusive with buttons. Max 13 items.", "items": { "properties": { "imageUrl": { "description": "Optional icon URL (Meta only)", "type": "string" }, "payload": { "description": "Payload sent back on tap", "type": "string" }, "title": { "description": "Button label (max 20 chars)", "maxLength": 20, "type": "string" } }, "required": [ "payload", "title" ], "type": "object" }, "maxItems": 13, "type": "array" }, "replyMarkup": { "description": "Telegram-native keyboard markup. Ignored on other platforms.", "properties": { "keyboard": { "description": "Array of rows, each row is an array of buttons", "items": { "items": { "properties": { "callbackData": { "description": "Callback data (inline_keyboard only, max 64 bytes)", "maxLength": 64, "type": "string" }, "text": { "description": "Button text", "type": "string" }, "url": { "description": "URL to open (inline_keyboard only)", "type": "string" } }, "type": "object" }, "type": "array" }, "type": "array" }, "oneTime": { "default": true, "description": "Hide keyboard after use (reply_keyboard only)", "type": "boolean" }, "type": { "description": "Keyboard type", "enum": [ "inline_keyboard", "reply_keyboard" ], "type": "string" } }, "type": "object" }, "replyTo": { "description": "Platform message ID to quote-reply to.\n\n- WhatsApp: the wamid.\n- Telegram: the Telegram message ID (message.platformMessageId on webhooks, and `id` on each entry of the list-messages endpoint).\n- Slack: threads the reply (thread_ts) instead of quoting.\n- Instagram and Facebook Messenger: no send-side quote replies. The message is sent without a quote and the successful response includes a warnings entry with code ignored_field and param replyTo.\n- Other platforms without send-side reply support ignore this field.", "type": "string" }, "sharedMediaId": { "description": "Instagram only (JSON body only; 400 on other platforms). Shares one of the account's own published posts in the DM, by its Instagram media id (the `id` returned by the media endpoints, not a permalink). Meta only accepts media the account owns.\n\nSent on its own: cannot be combined with `message`, attachments, `quickReplies`, `buttons`, `template` or `sticker` (400). `messageTag: HUMAN_AGENT` is allowed. Works on accounts connected with Instagram Login and with Facebook Login.", "pattern": "^\\d+$", "type": "string" }, "sticker": { "description": "Instagram only (JSON body only). Sends a sticker instead of text; `like_heart` is the heart sticker. Sent on its own: cannot be combined with `message`, attachments, `quickReplies`, `buttons`, `template` or `sharedMediaId` (400). `messageTag: HUMAN_AGENT` is allowed. Rejected with 400 on other platforms.", "enum": [ "like_heart" ], "type": "string" }, "subject": { "description": "iMessage only (JSON body only). Bold title line rendered above the message text. Rejected with 400 on other platforms; ignored on voice-message sends.", "maxLength": 1000, "type": "string" }, "template": { "description": "Platform-dependent template payload. Ignored on Telegram.\n\n**Instagram / Facebook:** a generic template (carousel). Set `type: generic` and provide up to 10 `elements`, each with a `title` (required) and optional `subtitle`, `imageUrl`, and `buttons`.\n\n- Mutually exclusive with the top-level `buttons` field (sending both is a 400); put card buttons on its `elements`.\n- On Facebook, `imageAspectRatio` (`horizontal`, the default, or `square`) sets how Messenger renders element images. Instagram has no such setting and rejects it.\n\n**WhatsApp:** sends an approved template message, the only type WhatsApp accepts when the 24-hour customer-service window is closed. Provide exactly one element with the template reference (`type` is ignored):\n\n`{ \"elements\": [{ \"name\": \"order_update\", \"language\": \"en_US\", \"components\": [...] }] }`\n\n`components` is optional and forwarded unchanged as the `template.components` array of Meta's Cloud API send payload. Use it to fill body/header variables and button parameters, e.g. `[{ \"type\": \"body\", \"parameters\": [{ \"type\": \"text\", \"text\": \"John\" }] }]`.\n\nTemplates with media headers (image, video, document) must include the header component with its media link at send time. To message a phone number with no conversation, or have media headers filled automatically, use the create-conversation endpoint (POST /apis/v1/social/inbox/conversations).", "properties": { "elements": { "items": { "properties": { "buttons": { "description": "Element buttons (Instagram/Facebook only)", "items": { "properties": { "payload": { "type": "string" }, "title": { "maxLength": 20, "type": "string" }, "type": { "enum": [ "url", "postback" ], "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "maxItems": 3, "type": "array" }, "components": { "description": "WhatsApp only. Meta Cloud API send-shape components array, forwarded to Meta verbatim.", "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "imageUrl": { "description": "Element image URL (Instagram/Facebook only)", "type": "string" }, "language": { "description": "WhatsApp only. Template language code (e.g. en_US).", "type": "string" }, "name": { "description": "WhatsApp only. Name of the approved template to send.", "type": "string" }, "subtitle": { "description": "Element subtitle (Instagram/Facebook only)", "type": "string" }, "title": { "description": "Element title (max 80 chars). Required for Instagram/Facebook generic templates.", "maxLength": 80, "type": "string" } }, "type": "object" }, "maxItems": 10, "type": "array" }, "imageAspectRatio": { "description": "Facebook only. Aspect ratio Messenger renders element images at: horizontal (1.91:1, default) or square (1:1). A 400 on Instagram.", "enum": [ "horizontal", "square" ], "type": "string" }, "type": { "description": "Template type. Required for Instagram/Facebook generic templates; ignored on WhatsApp.", "enum": [ "generic" ], "type": "string" } }, "type": "object" }, "voiceNote": { "description": "WhatsApp only. When `true` on an audio attachment, the message is sent as a voice message (PTT): the recipient sees the waveform + voice-note UI instead of a basic audio attachment. Ignored for non-audio attachments.\n\nThe audio file MUST be `.ogg` encoded with the OPUS codec (mono), per Meta's voice-message contract; other formats are rejected by WhatsApp.", "type": "boolean" } }, "required": [ "accountId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "attachments": { "description": "Echo of the sent attachment with its resolved public URL, when one is available (Facebook, Instagram, Telegram, WhatsApp).", "items": { "properties": { "type": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "type": "array" }, "conversationId": { "description": "AIsa conversation id, echoed so the thread can be read back or replied to. Omitted when the send succeeded but the conversation could not be resolved to a stored record.\n\n- Telegram, WhatsApp, SMS and Slack: equals the id the list-conversations endpoint returns.\n- Facebook, Instagram, Bluesky and Reddit: that endpoint returns the platform thread id instead, so do not correlate the two by equality.\n- X: when the request addressed the conversation by its Twitter dm_conversation_id, that platform id is echoed back instead.", "type": "string" }, "messageId": { "description": "Platform id of the sent message (not returned for Reddit). For WhatsApp this is the raw Meta wamid, the same id delivered as message.platformMessageId on webhooks and delivery-status updates, and the value to pass as replyTo to quote-reply.", "type": "string" }, "messageIds": { "description": "Facebook/Instagram only. Present when an attachment and text were both requested: Meta has no single body shape for both, so the send is two Meta messages under the hood. First element === messageId (the attachment); second is the follow-up text.", "items": { "type": "string" }, "type": "array" }, "partialFailure": { "description": "Facebook/Instagram only. The attachment was delivered but the follow-up text message was rejected by Meta and was not stored; the response is still a 200 because the attachment send succeeded.", "properties": { "error": { "type": "string" }, "part": { "enum": [ "text" ], "type": "string" }, "platformError": { "description": "Meta's own diagnostic fields for the rejected follow-up, same shape as the 400 response's platformError.", "properties": { "code": { "description": "Meta error code", "type": "integer" }, "fbtraceId": { "description": "Meta fbtrace_id, quote this in a Meta bug report", "type": "string" }, "subcode": { "description": "Meta error_subcode", "type": "integer" }, "type": { "description": "Meta error type (e.g. OAuthException)", "type": "string" } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "success": { "type": "boolean" }, "warnings": { "description": "Present when a successful send ignored replyTo on Instagram or Facebook Messenger. The message was sent without a quote; do not retry it to apply the reply.", "items": { "properties": { "code": { "enum": [ "ignored_field" ], "type": "string" }, "message": { "description": "Human-readable explanation of the ignored field.", "type": "string" }, "param": { "enum": [ "replyTo" ], "type": "string" } }, "required": [ "code", "message", "param" ], "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Message sent" }, "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." } }, "summary": "Send message", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.inbox.send_inbox_message@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "customer_micros_usd": 100, "description": "Charged once per successful call. The base price is AIsa's own cost for the call: $0.015 on X accounts (one X direct message sent, at X's API rate), $0.0001 on every other platform (one message delivered to a recipient). This is the price on every plan; no plan multiplier applies. A refused or failed call, or one whose outcome is unknown, is not charged.", "kind": "fixed_request", "variants": { "twitter": { "customer_micros_usd": 15000, "kind": "fixed_request" } } }, "x-aisa-revision": { "handler_contract_hash": "f833c0658a9accd7e7290e44ba5662f1a2f1788ed7fc44fe65865d5a99cb223c" }, "x-aisa-status": "disabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_inbox_conversatio_3ceefe", "method": "POST", "path": "/apis/v1/social/inbox/conversations/{conversationId}/messages" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_inbox_conversatio_3ceefe" } }, "/apis/v1/social/inbox/conversations/{conversationId}/messages/{messageId}": { "delete": { "description": "Inbox. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nDelete a message from a conversation. Platform support varies:\n\n- Telegram: full delete (bot's own messages anytime, others if admin)\n- X: full delete (own DM events only)\n- Bluesky: delete for self only (recipient still sees it)\n- Reddit: delete from sender's view only\n- iMessage: unsend (the bubble disappears for the recipient) within 2 minutes of sending (Apple's limit; 409 `unsend_window_expired` after that). Own outbound messages only.\n- Facebook, Instagram, WhatsApp: not supported (returns 400)\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "delete_aisa_social_apis_v1_social_inbox_conversat_b6ffc4", "parameters": [ { "description": "The conversation ID", "in": "path", "name": "conversationId", "required": true, "schema": { "type": "string" } }, { "description": "The platform message ID to delete", "in": "path", "name": "messageId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Message deleted" }, "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." } }, "summary": "Delete message", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.inbox.delete_inbox_message@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "c5ab6648873625e20ea7f1b89977fc76ff644692a64f9a5824ec7f5b3270a6e9" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "delete_aisa_social_apis_v1_social_inbox_conversat_b6ffc4", "method": "DELETE", "path": "/apis/v1/social/inbox/conversations/{conversationId}/messages/{messageId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/delete_aisa_social_apis_v1_social_inbox_conversat_b6ffc4" }, "patch": { "description": "Inbox. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nEdit a previously sent message. Platform support:\n- Telegram: text and/or reply markup, any time\n- 'iMessage: text only, within 15 minutes of sending (Apple''s limit; 409 `edit_window_expired` after that). Group messages included. The stored message keeps its edit history.'\n- All others: returns 400\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "patch_aisa_social_apis_v1_social_inbox_conversati_b6ffc4", "parameters": [ { "description": "The conversation ID", "in": "path", "name": "conversationId", "required": true, "schema": { "type": "string" } }, { "description": "The platform message ID to edit (iMessage also accepts the AIsa message id)", "in": "path", "name": "messageId", "required": true, "schema": { "type": "string" } } ], "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" }, "replyMarkup": { "description": "New inline keyboard markup", "properties": { "keyboard": { "items": { "items": { "properties": { "callbackData": { "type": "string" }, "text": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "type": "array" }, "type": "array" }, "type": { "enum": [ "inline_keyboard" ], "type": "string" } }, "type": "object" }, "text": { "description": "New message text", "type": "string" } }, "required": [ "accountId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "messageId": { "type": "integer" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Message edited" }, "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." } }, "summary": "Edit message", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.inbox.edit_inbox_message@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "e339f4e4fbb99ea583cea68960d0119b3027710e3d2baf39846c8b9a22fc1b60" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "patch_aisa_social_apis_v1_social_inbox_conversati_b6ffc4", "method": "PATCH", "path": "/apis/v1/social/inbox/conversations/{conversationId}/messages/{messageId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/patch_aisa_social_apis_v1_social_inbox_conversati_b6ffc4" } }, "/apis/v1/social/inbox/conversations/{conversationId}/messages/{messageId}/attachments/{index}": { "get": { "description": "Inbox. 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.\n\nResolve one attachment on a message to a media url that works right now.\n\n### Why it exists\n\nInstagram and Facebook sign DM media urls per request and expire them. So the `url` on a message is a snapshot: it works when you read the message and stops working later.\n\nThis endpoint checks the stored url and, when it has gone stale, re-mints the message's media from Meta and persists it before answering.\n\nThe message id never expires, so this URL is the one to store. It is returned ready-made on each attachment as `refreshUrl` when you read a message over REST.\n\n### Building the URL from a webhook\n\n**Webhook payloads do not carry `refreshUrl`**, so a webhook-driven integration builds this URL itself. Every piece is in the event:\n\n- `message.conversationId`\n- `message.platformMessageId`\n- the attachment's zero-based position\n- `account.accountId`\n\n**`accountId` is a required query parameter**. Omitting it returns `400` `missing_required_field`, which is the same requirement `GET /apis/v1/social/whatsapp/media/{mediaId}` has.\n\n### Response format\n\n- By default it responds `302` to the live media url, so it can be used directly as an `` on a browser session.\n- API-key integrators should pass `?format=json` and read `url` off the body, since a browser cannot attach an Authorization header to an image request.\n\n### Other platforms\n\nOnly Instagram and Facebook media can be re-minted. On other platforms the stored url is returned as-is when it still resolves, and `404` otherwise.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_inbox_conversation_54bd26", "parameters": [ { "description": "The conversation ID (AIsa id or platform conversation id)", "in": "path", "name": "conversationId", "required": true, "schema": { "type": "string" } }, { "description": "The message id as returned by the list-messages endpoint (the platform message id)", "in": "path", "name": "messageId", "required": true, "schema": { "type": "string" } }, { "description": "Zero-based position of the attachment in the message's attachments array", "in": "path", "name": "index", "required": true, "schema": { "minimum": 0, "type": "integer" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "`redirect` (default) answers 302 to the media; `json` returns the url in the body", "in": "query", "name": "format", "required": false, "schema": { "default": "redirect", "enum": [ "redirect", "json" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "refreshed": { "description": "True when the stored url had expired and was re-minted from the platform.", "type": "boolean" }, "status": { "type": "string" }, "url": { "description": "Live media url. Short-lived; re-request this endpoint rather than storing it.", "type": "string" } }, "type": "object" } } }, "description": "Resolved url (only when format=json)" }, "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." } }, "summary": "Resolve message attachment", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.inbox.get_message_attachment@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "6f6fa828076f942f5e12740196722b40a555f61a869d5d4f95a2785011292467" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_inbox_conversation_54bd26", "method": "GET", "path": "/apis/v1/social/inbox/conversations/{conversationId}/messages/{messageId}/attachments/{index}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_inbox_conversation_54bd26" } }, "/apis/v1/social/inbox/conversations/{conversationId}/messages/{messageId}/reactions": { "delete": { "description": "Inbox. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nRemove a reaction from a message.\n\n### Platform support\n\n- Telegram: send empty reaction array to clear\n- WhatsApp: send empty emoji to remove\n- Instagram and Facebook Messenger: sends Meta's `unreact` action; the emoji does not need to be repeated\n- Slack: removes the reaction we previously sent on that message\n- iMessage: retracts your existing tapback or emoji reaction on the message (400 when you have none)\n- All others: returns 400 (not supported)\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "delete_aisa_social_apis_v1_social_inbox_conversat_565940", "parameters": [ { "description": "The conversation ID", "in": "path", "name": "conversationId", "required": true, "schema": { "type": "string" } }, { "description": "The platform message ID (as returned by GET /messages) or the AIsa message ID (as returned by the reaction webhook)", "in": "path", "name": "messageId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "messageId": { "description": "The AIsa message ID the removal was resolved against", "type": "string" }, "platformMessageId": { "description": "The platform message ID the removal was sent for", "type": "string" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "The platform accepted the removal request. This does not guarantee a reaction was removed: the platform never confirms what it acted on, and a reaction placed by the other participant cannot be removed (platform rule). Check `fromMe` on GET /messages to know who placed a reaction." }, "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." } }, "summary": "Remove reaction", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.inbox.remove_message_reaction@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "6f087e44c3a789d44892468535558b98db6d2d57ff408be9dc7f315868cc7de8" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "delete_aisa_social_apis_v1_social_inbox_conversat_565940", "method": "DELETE", "path": "/apis/v1/social/inbox/conversations/{conversationId}/messages/{messageId}/reactions" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/delete_aisa_social_apis_v1_social_inbox_conversat_565940" }, "post": { "description": "Inbox. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nAdd an emoji reaction to a message.\n\n### Platform support\n\n- Telegram: supports a subset of Unicode emoji reactions\n- WhatsApp: supports any standard emoji (one reaction per message per sender)\n- Instagram and Facebook Messenger: any standard emoji, subject to Meta's 24h messaging window\n- Slack: the emoji must have a Slack name (e.g. `:thumbsup:`); unnamed characters return 400\n- iMessage: the six Apple tapbacks (❤️ 👍 👎 😂 ‼️ ❓) render natively; any other emoji is sent as a custom emoji tapback (iOS 18+ recipients)\n- All others: returns 400 (not supported)\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_inbox_conversatio_565940", "parameters": [ { "description": "The conversation ID", "in": "path", "name": "conversationId", "required": true, "schema": { "type": "string" } }, { "description": "The platform message ID (as returned by GET /messages) or the AIsa message ID (as returned by the reaction webhook)", "in": "path", "name": "messageId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "accountId": "acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3", "emoji": "example" }, "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "emoji": { "description": "Emoji character (e.g. \"👍\", \"❤️\")", "type": "string" } }, "required": [ "accountId", "emoji" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "messageId": { "description": "The AIsa message ID the reaction was resolved against", "type": "string" }, "platformMessageId": { "description": "The platform message ID the reaction was sent for", "type": "string" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "The platform accepted the reaction request. This does not guarantee the reaction was placed: the platform never confirms what it acted on." }, "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." } }, "summary": "Add reaction", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.inbox.add_message_reaction@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "11b499d122c9ad6174448c93b25453ae504f94a50d87c989e6af3134da0ed492" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_inbox_conversatio_565940", "method": "POST", "path": "/apis/v1/social/inbox/conversations/{conversationId}/messages/{messageId}/reactions" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_inbox_conversatio_565940" } }, "/apis/v1/social/inbox/conversations/{conversationId}/read": { "post": { "description": "Inbox. 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.\n\nMarks all unread incoming messages in the conversation as read.\n\nFor WhatsApp, this also sends read receipts (blue ticks) to the contact,\nEXCEPT on coexistence accounts (where the WhatsApp Business app on the\ncustomer's phone owns read state and we never override it).\n\nFor iMessage, this also marks the conversation read with the contact\n(1:1 conversations only). Best-effort.\n\nFor Instagram (Instagram Login and Facebook Login) and Facebook Messenger,\nthis also sends a `mark_seen` read receipt to the contact, so they see the\nconversation as seen. Best-effort: a Meta failure never fails the request.\n\nThis is the explicit, human-driven counterpart to `GET .../messages`,\nwhich is side-effect-free and does NOT mark anything read. Call this when\na user actually views the conversation.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_inbox_conversatio_2a39d2", "parameters": [ { "description": "The conversation ID", "in": "path", "name": "conversationId", "required": true, "schema": { "type": "string" } } ], "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" } }, "required": [ "accountId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "markedCount": { "description": "Number of messages marked read by this call", "type": "integer" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Conversation marked read" }, "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." } }, "summary": "Mark a conversation as read", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.inbox.mark_conversation_read@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "862b33b2430a1b182087fee442a4dcc97f8aa6ec21a20e838aa94b00061640f7" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_inbox_conversatio_2a39d2", "method": "POST", "path": "/apis/v1/social/inbox/conversations/{conversationId}/read" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_inbox_conversatio_2a39d2" } }, "/apis/v1/social/inbox/conversations/{conversationId}/thread-control": { "post": { "description": "Inbox. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nChanges who answers a conversation, using Meta's handover protocol on WhatsApp, Facebook and Instagram.\n\n**WhatsApp**, on numbers with Meta Business Agent enabled:\n\n- `release`: hand the conversation back to the agent so it resumes answering. You must currently hold control (sending any message takes it implicitly).\n- `take`: take control before sending anything, so the agent stops replying while an operator reads the thread. Meta accepts this only from the business configured as the number's escalation partner; other apps take control by sending a message.\n- `pass`: transfer control to the number's configured escalation partner, or to the agent with `target: ai_agent`. Meta's Cloud API currently rejects it (\"Pass action is not supported\", verified 2026-09-08); use `release` to hand a thread back to the agent.\n\n**Facebook and Instagram** (Messenger Platform handover between the apps on the Page, such as Page Inbox):\n\n- `pass` with `targetAppId`: give the thread to another app (`pass_thread_control`). Page Inbox is 263902037430900.\n- `take`: take the thread back (`take_thread_control`). Meta allows it only to the Page's primary receiver, and only on accounts connected through a Facebook Page. On an Instagram Login connection it answers 400 `platform_not_supported`.\n- `request`: ask the current owner to pass the thread (`request_thread_control`); nothing changes until it does. Not available on Instagram Login connections (400 `platform_not_supported`).\n- `release`: give the thread back to the primary receiver (`release_thread_control`).\n\n### While another app owns the thread\n\nWhile another app owns a Facebook or Instagram thread, inbound messages arrive with `metadata.standby: true` and a send answers 409 `not_thread_owner`.\n\nThe conversation's `threadControl` follows the result. A `conversation.control_changed` webhook fires when Meta later reports the change.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_inbox_conversatio_e875e9", "parameters": [ { "description": "The conversation ID", "in": "path", "name": "conversationId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "accountId": "acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3", "action": "pass", "metadata": "Customer asked for a human", "targetAppId": "263902037430900" }, "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "action": { "description": "`request` is Facebook and Instagram only. `take` and `request` are refused with `platform_not_supported` on Instagram accounts connected with Instagram Login.", "enum": [ "release", "take", "pass", "request" ], "type": "string" }, "metadata": { "description": "Free-form note forwarded verbatim to the app receiving control (its messaging_handovers webhook).", "maxLength": 2000, "type": "string" }, "target": { "description": "WhatsApp only. With action pass: send control to Meta Business Agent instead of the escalation partner.", "enum": [ "ai_agent" ], "type": "string" }, "targetAppId": { "description": "Facebook and Instagram only, required with action pass: the Meta app id receiving the thread.", "pattern": "^[0-9]+$", "type": "string" } }, "required": [ "accountId", "action" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "control": { "properties": { "owner": { "enum": [ "app", "ai_agent", "other" ], "type": "string" }, "ownerAppId": { "description": "The app that received the thread, on a Facebook or Instagram pass.", "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Control transferred (or, for request, asked for)" }, "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." } }, "summary": "Change who answers a conversation (handover)", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.inbox.set_conversation_thread_control@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "9728164035082e370e08c8612ba08d46529831f11b106f277e2206690191b773" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_inbox_conversatio_e875e9", "method": "POST", "path": "/apis/v1/social/inbox/conversations/{conversationId}/thread-control" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_inbox_conversatio_e875e9" } }, "/apis/v1/social/inbox/conversations/{conversationId}/typing": { "post": { "description": "Inbox. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nShow a typing indicator in a conversation.\n\n### Platform support\n\n- Facebook Messenger: shows \"Page is typing...\" for 20 seconds.\n- Instagram: shows \"typing...\" to the recipient (works for both Instagram Login and Facebook Login accounts). The recipient must be signed in to Instagram to see it.\n- Telegram: shows \"Bot is typing...\" for 5 seconds.\n- WhatsApp: shows \"typing...\" for up to 25 seconds. Requires a recent inbound message in the conversation (Meta references the inbound message id) and also marks that message as read as a side-effect.\n- iMessage: shows a typing bubble for ~15 seconds (1:1 conversations only; requires a recent two-way exchange).\n- All others: returns 200 but no-op (platform doesn't support it).\n\n### Response\n\nTyping indicators are best-effort. The endpoint always returns 200 even if the platform call fails.\n\n`success` reports whether a typing indicator was actually sent to the platform (`false` on unsupported platforms or when the platform call failed).\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_inbox_conversatio_bc3d1f", "parameters": [ { "description": "The conversation ID", "in": "path", "name": "conversationId", "required": true, "schema": { "type": "string" } } ], "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" } }, "required": [ "accountId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Typing indicator sent (or no-op on unsupported platforms)" }, "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." } }, "summary": "Send typing indicator", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.inbox.send_typing_indicator@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "bb8b68f4a722885df55645298d36d2c968c91eaf27f13dda20414d833064069d" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_inbox_conversatio_bc3d1f", "method": "POST", "path": "/apis/v1/social/inbox/conversations/{conversationId}/typing" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_inbox_conversatio_bc3d1f" } }, "/apis/v1/social/inbox/labels": { "get": { "description": "Inbox. 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.\n\nFacebook Messenger only. Lists the custom labels defined on the Page (Graph `/{page-id}/custom_labels`). Other platforms answer 400 `platform_not_supported`.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_inbox_labels", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "labels": { "items": { "properties": { "id": { "description": "Meta label id", "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "The Page's labels" }, "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." } }, "summary": "List the Page's conversation labels", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.inbox.list_inbox_labels@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "0959e199208b4b8960dcbda1252428e10d48f67b6b0fe347dcee2309d7c2d160" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_inbox_labels", "method": "GET", "path": "/apis/v1/social/inbox/labels" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_inbox_labels" }, "post": { "description": "Inbox. 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.\n\nFacebook Messenger only. Creates a custom label on the Page (Graph `POST /{page-id}/custom_labels`). Other platforms answer 400 `platform_not_supported`.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_inbox_labels", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "accountId": "acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3", "name": "VIP" }, "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "name": { "description": "Label name", "minLength": 1, "type": "string" } }, "required": [ "accountId", "name" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "label": { "properties": { "id": { "description": "Meta label id", "type": "string" }, "name": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Label created" }, "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." } }, "summary": "Create a conversation label", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.inbox.create_inbox_label@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "fe74cb3e76f21af1411b26d4de61b751d48c1ef26d591b01c8a7b6f87aa496d1" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_inbox_labels", "method": "POST", "path": "/apis/v1/social/inbox/labels" }, "x-codeSamples": [ { "lang": "text", "label": "Reference example", "source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/social/inbox/labels \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"accountId\": \"acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3\",\n \"name\": \"VIP\"\n}'" } ], "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_inbox_labels" } }, "/apis/v1/social/inbox/labels/{labelId}": { "delete": { "description": "Inbox. 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.\n\nFacebook Messenger only. Deletes a custom label from the Page (Graph `DELETE /{label-id}`), which also removes it from every conversation. The id must be one of the Page's custom labels, otherwise 404 `resource_not_found`. Other platforms answer 400 `platform_not_supported`.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "delete_aisa_social_apis_v1_social_inbox_labels_labelid", "parameters": [ { "description": "Meta label id", "in": "path", "name": "labelId", "required": true, "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Label deleted" }, "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." } }, "summary": "Delete a conversation label", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.inbox.delete_inbox_label@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "e22eb4fbb1a07d8c64cd4dc6d08f6661face3c33c169d0c9b5f089763a7be581" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "delete_aisa_social_apis_v1_social_inbox_labels_labelid", "method": "DELETE", "path": "/apis/v1/social/inbox/labels/{labelId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/delete_aisa_social_apis_v1_social_inbox_labels_labelid" } }, "/apis/v1/social/inbox/mentions": { "get": { "description": "Mentions. 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. Without profileId or accountId it reads your default profile. On a profile with an X account, pass accountId or a platform other than twitter: X bills each read.\n\nReturns mentions of your connected accounts from the last 7 days. Requires Inbox addon.\n\n### LinkedIn\n\nOrganization mentions, delivered by webhooks and a background pull.\n\n### Instagram\n\nComment mentions (someone tags the account in a comment on their own media) and caption mentions (someone tags it in their media caption), delivered by the Meta `mentions` webhook.\n\n- Only accounts connected through Facebook Login receive them.\n- Comments on the account's own posts are never listed, even when they contain its @handle.\n- Their text is read from Instagram in the background after the first request, so `content` can be empty on the first read.\n- Pass `mediaId` and `commentId` to `POST /apis/v1/social/inbox/mentions/reply` to answer one.\n\n### Facebook\n\nPost mentions (someone tags the Page in a post) and comment mentions (someone tags it in a comment), delivered by the Page `mention` webhook with their text.\n\n- Comments on the Page's own posts and anything the Page wrote itself are never listed.\n- Facebook mentions cannot be replied to through `POST /apis/v1/social/inbox/mentions/reply`.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_inbox_mentions", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": false, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "One of your profiles (prf_...). Defaults to your default profile when neither profileId nor accountId is sent.", "in": "query", "name": "profileId", "required": false, "schema": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Sort order by publishedAt", "in": "query", "name": "sortOrder", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Cursor for pagination (ID of the last item from the previous page)", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "accountUsername": { "type": "string" }, "authorName": { "description": "Display name of the author, resolved from authorUrn on LinkedIn (null when LinkedIn does not allow resolving the profile) and taken from the webhook on Facebook.", "type": [ "string", "null" ] }, "authorPicture": { "description": "Profile picture URL of the author. LinkedIn CDN URLs expire after some time, so fetch promptly rather than storing long-term.", "type": [ "string", "null" ] }, "authorUrn": { "description": "LinkedIn URN of the person who mentioned you, the Instagram-scoped ID of the commenter on an Instagram comment mention, or the ID of the Facebook user or Page that mentioned your Page when Meta sends it.", "type": [ "string", "null" ] }, "authorUsername": { "description": "LinkedIn vanity name of the author (the slug in their profile URL), or the Instagram username of the commenter or media owner.", "type": [ "string", "null" ] }, "commentId": { "description": "Instagram and Facebook: ID of the comment that mentioned the account. Null for caption and post mentions and for LinkedIn.", "type": [ "string", "null" ] }, "content": { "description": "Text that mentioned you: the post text on LinkedIn, the caption or comment text on Instagram, the post or comment text on Facebook. Empty until it has been read.", "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "id": { "description": "Mention document ID", "type": "string" }, "mediaId": { "description": "Instagram only: ID of the media the account was mentioned in (or under). Null for LinkedIn and Facebook.", "type": [ "string", "null" ] }, "organizationalEntity": { "description": "URN of the LinkedIn organization that was mentioned, the Instagram user ID of the mentioned account, or the ID of the mentioned Facebook Page.", "type": "string" }, "permalink": { "description": "URL to the source post on LinkedIn. Null on Instagram and Facebook.", "type": [ "string", "null" ] }, "platform": { "enum": [ "linkedin", "instagram", "facebook" ], "type": "string" }, "postId": { "description": "Facebook only: ID of the post the Page was mentioned in (or under). Null for LinkedIn and Instagram.", "type": [ "string", "null" ] }, "publishedAt": { "format": "date-time", "type": "string" }, "type": { "description": "Instagram and Facebook: `caption` when the Instagram account was tagged in a media caption, `post` when the Facebook Page was tagged in a post, `comment` when either was tagged in a comment. Null for LinkedIn.", "enum": [ "caption", "post", "comment", null ], "type": [ "string", "null" ] } }, "type": "object" }, "type": "array" }, "meta": { "properties": { "sortOrder": { "enum": [ "asc", "desc" ], "type": "string" }, "total": { "type": "integer" } }, "type": "object" }, "pagination": { "properties": { "cursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "type": "object" } }, "type": "object" } } }, "description": "Paginated list of mentions" }, "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." } }, "summary": "List mentions", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.mentions.list_inbox_mentions@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "cd54c2712f36a41a185e1565095f399fcdcf05ef12492e2a0139616f631cf3ca" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_inbox_mentions", "method": "GET", "path": "/apis/v1/social/inbox/mentions" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_inbox_mentions" } }, "/apis/v1/social/inbox/mentions/reply": { "post": { "description": "Mentions. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nReply to a mention of the connected account. Supported on Instagram only.\n\nTwo shapes, selected by whether `commentId` is present:\n\n- **Comment mention** (someone @mentioned the account inside a comment): pass both\n `mediaId` and `commentId`. Instagram posts a reply under that comment.\n- **Caption mention** (someone @mentioned the account in their media caption, so no\n comment exists): pass `mediaId` only. Instagram posts a comment on their media.\n\nStory mentions are not supported by Instagram's API.\n\n`GET /apis/v1/social/inbox/mentions` returns Instagram mentions with the `mediaId` and `commentId`\nto pass here.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_inbox_mentions_reply", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "accountId": "acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3", "commentId": "17870913561140000", "mediaId": "17895695668004550", "message": "Thanks for the shout-out!" }, "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "commentId": { "description": "The mentioning comment's ID. Omit for a caption mention.", "type": "string" }, "mediaId": { "description": "The ID of the media the account was mentioned in", "type": "string" }, "message": { "description": "The reply text", "type": "string" } }, "required": [ "accountId", "mediaId", "message" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "id": { "description": "ID of the created reply or comment", "type": "string" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Reply posted" }, "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." } }, "summary": "Reply to a mention", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.mentions.reply_to_mention@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "d0c8989a950deb8f61d17fc2f150e784e827f6fac50c404d1c9622ca6bb29347" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_inbox_mentions_reply", "method": "POST", "path": "/apis/v1/social/inbox/mentions/reply" }, "x-codeSamples": [ { "lang": "text", "label": "Reference example", "source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/social/inbox/mentions/reply \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"accountId\": \"acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3\",\n \"commentId\": \"17870913561140000\",\n \"mediaId\": \"17895695668004550\",\n \"message\": \"Thanks for the shout-out!\"\n}'" } ], "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_inbox_mentions_reply" } }, "/apis/v1/social/inbox/posts/{postId}/like": { "delete": { "description": "Comments. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nRemove this account's like from a post.\n\nSupported platforms: LinkedIn, X, Facebook, YouTube, Bluesky, and Instagram in limited release.\n\n- YouTube: this clears the rating.\n- Instagram: has the same limited release, Facebook Login, `instagram_manage_engagement` and burst-limit constraints as liking.\n- Bluesky: `likeUri` (returned when the post was liked) is required.\n- Reddit: uses `POST /apis/v1/social/accounts/{accountId}/reddit-vote` with `direction: 0`.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "delete_aisa_social_apis_v1_social_inbox_posts_pos_be077a", "parameters": [ { "description": "AIsa post ID or the platform's native post ID", "in": "path", "name": "postId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "(Bluesky only) The like URI returned when liking", "in": "query", "name": "likeUri", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "liked": { "type": "boolean" }, "platform": { "type": "string" }, "postId": { "description": "The resolved native post ID", "type": "string" }, "status": { "type": "string" } }, "type": "object" } } }, "description": "Post unliked" }, "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." } }, "summary": "Unlike post", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.comments.unlike_post@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "16bfee4bd6741bb9ec0039fafb1d554b603943b71eb4dbd308d7275cd7e48f52" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "delete_aisa_social_apis_v1_social_inbox_posts_pos_be077a", "method": "DELETE", "path": "/apis/v1/social/inbox/posts/{postId}/like" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/delete_aisa_social_apis_v1_social_inbox_posts_pos_be077a" }, "post": { "description": "Comments. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nLike (or react to) a post as a connected account.\n\n### Platform support\n\n- Supported: LinkedIn, X, Facebook, YouTube, Bluesky, and Instagram in limited release (see below).\n- Threads, TikTok and Pinterest expose no like endpoint in their APIs and return 400.\n- Reddit returns 400 too, pointing at `POST /apis/v1/social/accounts/{accountId}/reddit-vote`, which covers upvote, downvote and clear on both posts and comments.\n\n### Liking as another account\n\nThe account does not have to be the one that published the post, which is what makes executive engagement possible: pass an exec's `accountId` and the brand post's ID.\n\n`postId` accepts either a AIsa post ID or the platform's native post ID. A AIsa post ID resolves to the entry for `accountId`, falling back to the post's single entry on the same platform. Two entries on that platform is a 400, so pass the native ID.\n\n### LinkedIn and YouTube\n\nLinkedIn requires the `w_member_social_feed` / `w_organization_social_feed` scopes, which are not retroactive. Accounts connected before those were requested get a 403 with code `linkedin_reconnect_required` until the user reconnects the account.\n\nYouTube spends 50 quota units per call.\n\n### Instagram (limited release)\n\nInstagram is in LIMITED RELEASE and not generally available. The call needs `instagram_manage_engagement`, which Meta has so far granted this app only under Standard Access.\n\nSo it works for app admins, developers and testers of our Meta app, and returns a 403 with code `PLATFORM_BETA_RESTRICTED` for every other account. That restriction lifts when Meta App Review grants Advanced Access; the constraints below apply once it does.\n\n- Instagram covers feed images, reels and carousels (stories and private-account media are not likeable).\n- Only an account connected through Facebook Login can be granted `instagram_manage_engagement`. An Instagram Login connection returns a 400 with code `instagram_likes_require_facebook_login`.\n- An account whose token predates the permission returns a 403 with code `reconnect_required`.\n- Instagram enforces a burst limit of 50 like or unlike calls per 5 seconds per Instagram account. Exceeding it locks that account out of the like API for an hour, so pace bulk loops.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_inbox_posts_postid_like", "parameters": [ { "description": "AIsa post ID or the platform's native post ID", "in": "path", "name": "postId", "required": true, "schema": { "type": "string" } } ], "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" }, "cid": { "description": "(Bluesky only) Content identifier of the post", "type": "string" }, "reactionType": { "description": "(LinkedIn only) Reaction to create. Defaults to LIKE; ignored on other platforms.", "enum": [ "LIKE", "PRAISE", "EMPATHY", "INTEREST", "APPRECIATION", "ENTERTAINMENT" ], "type": "string" } }, "required": [ "accountId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "alreadyReacted": { "description": "LinkedIn only: the account already had this exact reaction, so nothing was created", "type": "boolean" }, "likeUri": { "description": "(Bluesky only) URI to use for unliking", "type": "string" }, "liked": { "type": "boolean" }, "platform": { "type": "string" }, "postId": { "description": "The resolved native post ID", "type": "string" }, "reactionType": { "description": "LinkedIn only: the reaction type now in effect", "type": "string" }, "status": { "type": "string" } }, "type": "object" } } }, "description": "Post liked" }, "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." } }, "summary": "Like post", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.comments.like_post@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "a4aacf51957e111787c39eb198ed1291b960d48192fa22d4206fdb71f95102a8" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_inbox_posts_postid_like", "method": "POST", "path": "/apis/v1/social/inbox/posts/{postId}/like" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_inbox_posts_postid_like" } }, "/apis/v1/social/inbox/reviews": { "get": { "description": "Reviews. 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. Without profileId or accountId it reads your default profile.\n\nFetch reviews from all connected Facebook Pages and Google Business Profile accounts. Aggregates data with filtering and sorting options.\nSupported platforms: Facebook, Google Business Profile.\n\nEach account's reviews are read from the platform page by page within a 20-second budget per request, so very large accounts can come back truncated. Each account's listing is cached for up to 60 seconds.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_inbox_reviews", "parameters": [ { "description": "One of your profiles (prf_...). Defaults to your default profile when neither profileId nor accountId is sent.", "in": "query", "name": "profileId", "required": false, "schema": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" } }, { "in": "query", "name": "platform", "required": false, "schema": { "enum": [ "facebook", "googlebusiness" ], "type": "string" } }, { "in": "query", "name": "minRating", "required": false, "schema": { "maximum": 5, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "maxRating", "required": false, "schema": { "maximum": 5, "minimum": 1, "type": "integer" } }, { "description": "Filter by reply status", "in": "query", "name": "hasReply", "required": false, "schema": { "type": "boolean" } }, { "in": "query", "name": "sortBy", "required": false, "schema": { "default": "date", "enum": [ "date", "rating" ], "type": "string" } }, { "in": "query", "name": "sortOrder", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 50, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": false, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "accountUsername": { "type": "string" }, "created": { "format": "date-time", "type": "string" }, "hasPhotos": { "description": "Whether the review has at least one photo. Google Business Profile only; always false for other platforms.", "type": "boolean" }, "hasReply": { "type": "boolean" }, "id": { "description": "Review identifier. For Google Business Profile this is the full review resource name (accounts/{accountId}/locations/{locationId}/reviews/{reviewId}), so it also encodes the location.", "type": "string" }, "locationId": { "description": "Bare Google Business Profile location id the review belongs to. Google Business Profile only; absent for other platforms.", "type": "string" }, "locationName": { "description": "Human-readable Google Business Profile location display name. Google Business Profile only; absent for other platforms.", "type": [ "string", "null" ] }, "photoCount": { "description": "Number of photos attached to the review (photos only; videos are not counted). Google Business Profile only; 0 for other platforms.", "type": "integer" }, "photos": { "description": "Photos attached to the review. Google Business Profile only; always an empty array for other platforms.", "items": { "properties": { "url": { "format": "uri", "type": "string" } }, "type": "object" }, "type": "array" }, "platform": { "type": "string" }, "rating": { "type": "integer" }, "recommendationType": { "description": "Facebook recommendation: positive means recommends, negative means does not recommend. Null or absent when unavailable; absent for other platforms. Independent of the numeric rating.", "enum": [ "positive", "negative", null ], "type": [ "string", "null" ] }, "reply": { "properties": { "created": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "text": { "type": "string" } }, "type": [ "object", "null" ] }, "reviewUrl": { "type": [ "string", "null" ] }, "reviewer": { "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "profileImage": { "type": [ "string", "null" ] } }, "type": "object" }, "text": { "type": "string" } }, "type": "object" }, "type": "array" }, "meta": { "properties": { "accountsFailed": { "type": "integer" }, "accountsQueried": { "type": "integer" }, "accountsSkipped": { "description": "Connected accounts that were not queried: their platform does not support this feature, or the account is not enabled for it", "items": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "platform": { "type": "string" } }, "type": "object" }, "type": "array" }, "failedAccounts": { "items": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "accountUsername": { "type": [ "string", "null" ] }, "code": { "description": "Error code if available", "type": [ "string", "null" ] }, "error": { "type": "string" }, "platform": { "type": "string" }, "retryAfter": { "description": "Seconds to wait before retry (rate limits)", "type": [ "integer", "null" ] } }, "type": "object" }, "type": "array" }, "lastUpdated": { "format": "date-time", "type": "string" } }, "type": "object" }, "pagination": { "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] } }, "type": "object" }, "status": { "type": "string" }, "summary": { "properties": { "averageRating": { "type": [ "number", "null" ] }, "totalReviews": { "type": "integer" } }, "type": "object" } }, "type": "object" } } }, "description": "Aggregated reviews" }, "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." } }, "summary": "List reviews", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.reviews.list_inbox_reviews@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "1544fa37e53e9ffa16e40b942805f8a683c668598f07dea2f8ddb004fb4c6bb0" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_inbox_reviews", "method": "GET", "path": "/apis/v1/social/inbox/reviews" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_inbox_reviews" } }, "/apis/v1/social/inbox/reviews/{reviewId}/reply": { "delete": { "description": "Reviews. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nDelete a reply to a review (Google Business Profile only). Requires accountId in request body.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "delete_aisa_social_apis_v1_social_inbox_reviews_r_d03901", "parameters": [ { "in": "path", "name": "reviewId", "required": true, "schema": { "type": "string" } } ], "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" } }, "required": [ "accountId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "platform": { "type": "string" }, "status": { "type": "string" } }, "type": "object" } } }, "description": "Reply deleted" }, "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." } }, "summary": "Delete review reply", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.reviews.delete_inbox_review_reply@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "7e4600ec0b7c4aea6cdeb5b87a90073714f2938854f4621f4aa27e9cf6fadd90" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "delete_aisa_social_apis_v1_social_inbox_reviews_r_d03901", "method": "DELETE", "path": "/apis/v1/social/inbox/reviews/{reviewId}/reply" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/delete_aisa_social_apis_v1_social_inbox_reviews_r_d03901" }, "post": { "description": "Reviews. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nPost a reply to a review. Requires accountId in request body.\n\n### Idempotency\n\nSend an `Idempotency-Key` header to make retries safe (e.g. after a client-side timeout where delivery is unknown).\n\n- Same key + same body: replays the original response (with `Idempotent-Replayed: true`) instead of sending the reply to the platform again.\n- Same key + different body: returns 422.\n- A key still in flight: returns 409.\n\nKeys are retained for 24 hours and are scoped to the credential and to this exact path. Reusing a key against a different reviewId returns 422 rather than replaying the other review's response.\n\n### Failed requests\n\nOnly successful (2xx) responses are stored for replay. If the request throws or returns a non-2xx status the key is released, so the header protects the \"request succeeded but the response was lost\" case.\n\nAfter an ambiguous failure (a 5xx or a network timeout), fetch the review before retrying with the same key. Treat a missing reply as inconclusive rather than as proof nothing was sent.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_inbox_reviews_rev_d03901", "parameters": [ { "description": "Review ID (URL-encoded for Google Business Profile)", "in": "path", "name": "reviewId", "required": true, "schema": { "type": "string" } }, { "description": "Passed to the channel: a retry with the same key within 24 hours returns the first result instead of acting twice. AIsa never retries a write for you.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 191, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "accountId": "acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3", "message": "example" }, "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "message": { "type": "string" } }, "required": [ "accountId", "message" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "platform": { "type": "string" }, "reply": { "properties": { "created": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "text": { "type": "string" } }, "type": "object" }, "status": { "type": "string" } }, "type": "object" } } }, "description": "Reply posted" }, "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." } }, "summary": "Reply to review", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.reviews.reply_to_inbox_review@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "8fa824d6025f3c9952bdb14a98b201251e5f66b2bfd378a3b550387cd79f5fc8" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_inbox_reviews_rev_d03901", "method": "POST", "path": "/apis/v1/social/inbox/reviews/{reviewId}/reply" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_inbox_reviews_rev_d03901" } }, "/apis/v1/social/media/presign": { "post": { "description": "Returns a one-hour PUT URL. Media stays private until a post that uses it is scheduled or published.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_media_presign", "requestBody": { "content": { "application/json": { "example": { "contentType": "video/mp4", "filename": "launch.mp4", "size": 7340032 }, "schema": { "additionalProperties": false, "properties": { "contentType": { "type": [ "string", "null" ] }, "filename": { "type": [ "string", "null" ] }, "size": { "type": [ "integer", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "expiresAt": { "format": "date-time", "type": [ "string", "null" ] }, "headers": { "additionalProperties": { "type": [ "string", "null" ] }, "type": [ "object", "null" ] }, "mediaId": { "pattern": "^med_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "method": { "type": [ "string", "null" ] }, "uploadUrl": { "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Success" }, "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." } }, "summary": "Create a media upload URL", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.media.presign@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "This operation does not settle a customer usage charge.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "78f9e3ce7c8534d4beabbec3cfb41d29b2702fc5ccd612889e3be43146b0336f" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_media_presign", "method": "POST", "path": "/apis/v1/social/media/presign" }, "x-codeSamples": [ { "lang": "text", "label": "Reference example", "source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/social/media/presign \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"contentType\": \"video/mp4\",\n \"filename\": \"launch.mp4\",\n \"size\": 7340032\n}'" } ], "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_media_presign" } }, "/apis/v1/social/posts": { "get": { "description": "\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_posts", "parameters": [ { "description": "A prf_ id.", "in": "query", "name": "profileId", "required": false, "schema": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Filter by post status.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "draft", "scheduled", "publishing", "published", "partial", "failed", "cancelled" ], "type": "string" } }, { "description": "Filter by platform.", "in": "query", "name": "platform", "required": false, "schema": { "enum": [ "tiktok", "instagram", "twitter", "youtube", "facebook", "linkedin", "pinterest", "threads", "reddit", "x" ], "type": "string" } }, { "description": "Created at or after (RFC 3339).", "in": "query", "name": "from", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Created before (RFC 3339).", "in": "query", "name": "to", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Page size, default 20.", "in": "query", "name": "limit", "required": false, "schema": { "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque cursor from the previous page's nextCursor.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "content": { "type": [ "string", "null" ] }, "createdAt": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "mediaItems": { "items": { "properties": { "altText": { "type": [ "string", "null" ] }, "mediaId": { "pattern": "^med_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "notice": { "type": [ "string", "null" ] }, "platforms": { "items": { "properties": { "accountId": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "customContent": { "type": [ "string", "null" ] }, "customMedia": { "items": { "properties": { "altText": { "type": [ "string", "null" ] }, "mediaId": { "pattern": "^med_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "error": { "properties": { "category": { "enum": [ "platform_rate_limit", "platform_error", "system_error", "unknown", "auth_expired", "account_issue", "user_content", "user_abuse", "platform_rejected", "quota_exhausted", null ], "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "platformError": { "additionalProperties": {}, "type": [ "object", "null" ] }, "retryHint": { "enum": [ "never", "after_delay", "after_reconnect", "reconcile_first", null ], "type": [ "string", "null" ] }, "retryable": { "type": [ "boolean", "null" ] }, "source": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "platform": { "enum": [ "tiktok", "instagram", "twitter", "youtube", "facebook", "linkedin", "pinterest", "threads", "reddit", "googlebusiness", "googleanalytics", "bluesky", "telegram", "slack", "snapchat", "hubspot", "microsoft", null ], "type": [ "string", "null" ] }, "platformPostId": { "type": [ "string", "null" ] }, "platformPostUrl": { "type": [ "string", "null" ] }, "platformSpecificData": { "additionalProperties": {}, "type": [ "object", "null" ] }, "publishedAt": { "format": "date-time", "type": [ "string", "null" ] }, "removedAt": { "format": "date-time", "type": [ "string", "null" ] }, "scheduledFor": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "profileId": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "scheduledFor": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "updatedAt": { "format": "date-time", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "nextCursor": { "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Success" }, "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." } }, "summary": "List posts", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.posts.list@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "This operation does not settle a customer usage charge.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "1569d014833343498bb8f2bbf8eabab61362e174cae57598bd7a791ae6d88aa2" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_posts", "method": "GET", "path": "/apis/v1/social/posts" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_posts" }, "post": { "description": "Creates a draft, a scheduled post, or publishes now. Drafts stay in AIsa until scheduled or published. Returns 201, 207 when some platforms failed synchronously, or 202 with status publishing or scheduled while the outcome is pending. A replay of an idempotent request returns 200 with the original post.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_posts", "parameters": [ { "description": "Strongly recommended. Reusing a key within 24 hours returns the original result; a different body returns 409 idempotency_key_reused. Without a key the server derives one from the body in 10-minute buckets and echoes it in the response header.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 191, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "content": "Our spring collection is live.", "mediaItems": [ { "mediaId": "med_5Tc8Hn2Wq7Lx3Bv9Kd4Fr6", "type": "video" } ], "platforms": [ { "accountId": "acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3", "platform": "tiktok", "platformSpecificData": { "privacyLevel": "PUBLIC_TO_EVERYONE" } } ], "profileId": "prf_2Bn8Wq5Td1Yh7Kc3Mz9Lp4", "scheduledFor": "2026-11-20T15:00:00Z", "timezone": "America/New_York" }, "schema": { "additionalProperties": false, "properties": { "content": { "type": [ "string", "null" ] }, "isDraft": { "type": [ "boolean", "null" ] }, "mediaItems": { "items": { "additionalProperties": false, "properties": { "altText": { "type": [ "string", "null" ] }, "mediaId": { "pattern": "^med_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "platforms": { "items": { "additionalProperties": false, "allOf": [ { "if": { "properties": { "platform": { "enum": [ "tiktok" ] } }, "required": [ "platform" ] }, "then": { "properties": { "platformSpecificData": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "description": "Required to schedule or publish: privacyLevel, allowComment. Also required for video: allowDuet, allowStitch. Must be true, from the user: contentPreviewConfirmed, expressConsentGiven.", "properties": { "allowComment": { "description": "Allow comments. Must be false when creator-info reports commentDisabled.", "type": "boolean" }, "allowDuet": { "description": "Allow duets; required for video. Must be false when creator-info reports duetDisabled.", "type": "boolean" }, "allowStitch": { "description": "Allow stitches; required for video. Must be false when creator-info reports stitchDisabled.", "type": "boolean" }, "brandPartnerPromote": { "description": "Also disclose a paid partnership; only alongside commercialContentType brand_organic.", "type": "boolean" }, "commercialContentType": { "description": "Commercial content disclosure; one of commercialContentTypes from creator-info. brand_content cannot be SELF_ONLY.", "enum": [ "none", "brand_organic", "brand_content" ], "type": "string" }, "contentPreviewConfirmed": { "description": "The user previewed exactly this content. Must be true and must come from the user.", "type": "boolean" }, "description": { "description": "Long caption for photo posts.", "maxLength": 4000, "minLength": 1, "type": "string" }, "expressConsentGiven": { "description": "The user consented to posting. Must be true and must come from the user.", "type": "boolean" }, "isBrandOrganicPost": { "description": "Also disclose the creator's own brand; only alongside commercialContentType brand_content.", "type": "boolean" }, "mediaType": { "description": "Overrides the media type derived from the media items.", "enum": [ "video", "photo" ], "type": "string" }, "privacyLevel": { "description": "One of privacyLevelOptions from GET /accounts/{accountId}/tiktok/creator-info for this mediaType.", "maxLength": 64, "minLength": 1, "type": "string" }, "videoMadeWithAi": { "description": "Label the post as AI-generated.", "type": "boolean" } }, "type": "object" } ] } } } }, { "if": { "properties": { "platform": { "enum": [ "instagram" ] } }, "required": [ "platform" ] }, "then": { "properties": { "platformSpecificData": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "description": "", "properties": { "collaborators": { "description": "Up to 3 usernames to invite as collaborators (feed and Reels).", "items": { "maxLength": 64, "minLength": 1, "type": "string" }, "maxItems": 3, "type": "array" }, "contentType": { "description": "story publishes a Story.", "enum": [ "story" ], "type": "string" }, "firstComment": { "description": "First comment added after publishing (not on Stories).", "maxLength": 2200, "minLength": 1, "type": "string" }, "isAiGenerated": { "description": "Label the post as containing AI-generated media.", "type": "boolean" }, "shareToFeed": { "description": "Reels only: also show the Reel on the main feed (default true).", "type": "boolean" } }, "type": "object" } ] } } } }, { "if": { "properties": { "platform": { "enum": [ "twitter", "x" ] } }, "required": [ "platform" ] }, "then": { "properties": { "platformSpecificData": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "description": "", "properties": { "madeWithAi": { "description": "Label the post as containing AI-generated media.", "type": "boolean" }, "poll": { "additionalProperties": false, "description": "A poll; cannot be combined with media or threadItems.", "properties": { "duration_minutes": { "maximum": 10080, "minimum": 5, "type": "integer" }, "options": { "items": { "maxLength": 25, "minLength": 1, "type": "string" }, "maxItems": 4, "minItems": 2, "type": "array" } }, "required": [ "options", "duration_minutes" ], "type": "object" }, "replySettings": { "description": "Who can reply.", "enum": [ "following", "mentionedUsers", "subscribers", "verified" ], "type": "string" }, "threadItems": { "description": "The whole thread; the first item is the root post. Cannot be combined with poll.", "items": { "additionalProperties": false, "properties": { "content": { "description": "Text of this post.", "maxLength": 25000, "minLength": 1, "type": "string" } }, "required": [ "content" ], "type": "object" }, "minItems": 1, "type": "array" } }, "type": "object" } ] } } } }, { "if": { "properties": { "platform": { "enum": [ "youtube" ] } }, "required": [ "platform" ] }, "then": { "properties": { "platformSpecificData": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "description": "Required to schedule or publish: madeForKids.", "properties": { "containsSyntheticMedia": { "description": "Label the video as containing synthetic (AI-generated) content.", "type": "boolean" }, "firstComment": { "description": "First comment posted after upload.", "maxLength": 10000, "minLength": 1, "type": "string" }, "madeForKids": { "description": "COPPA: whether the video is made for kids. Required, and must be the user's explicit choice.", "type": "boolean" }, "title": { "description": "Video title.", "maxLength": 100, "minLength": 1, "type": "string" }, "visibility": { "description": "Video visibility.", "enum": [ "public", "private", "unlisted" ], "type": "string" } }, "type": "object" } ] } } } }, { "if": { "properties": { "platform": { "enum": [ "facebook" ] } }, "required": [ "platform" ] }, "then": { "properties": { "platformSpecificData": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "description": "", "properties": { "contentType": { "description": "story or reel; omitted is a feed post.", "enum": [ "story", "reel" ], "type": "string" }, "firstComment": { "description": "First comment added after publishing (not on stories).", "maxLength": 8000, "minLength": 1, "type": "string" }, "pageId": { "description": "Page to post to when the account manages several.", "maxLength": 64, "minLength": 1, "type": "string" } }, "type": "object" } ] } } } }, { "if": { "properties": { "platform": { "enum": [ "linkedin" ] } }, "required": [ "platform" ] }, "then": { "properties": { "platformSpecificData": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "description": "linkedin accepts no platformSpecificData yet.", "properties": {}, "type": "object" } ] } } } }, { "if": { "properties": { "platform": { "enum": [ "pinterest" ] } }, "required": [ "platform" ] }, "then": { "properties": { "platformSpecificData": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "description": "", "properties": { "isAiGenerated": { "description": "Label the Pin as AI modified.", "type": "boolean" } }, "type": "object" } ] } } } }, { "if": { "properties": { "platform": { "enum": [ "threads" ] } }, "required": [ "platform" ] }, "then": { "properties": { "platformSpecificData": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "description": "threads accepts no platformSpecificData yet.", "properties": {}, "type": "object" } ] } } } }, { "if": { "properties": { "platform": { "enum": [ "reddit" ] } }, "required": [ "platform" ] }, "then": { "properties": { "platformSpecificData": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "description": "reddit accepts no platformSpecificData yet.", "properties": {}, "type": "object" } ] } } } } ], "properties": { "accountId": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "customContent": { "type": [ "string", "null" ] }, "customMedia": { "items": { "additionalProperties": false, "properties": { "altText": { "type": [ "string", "null" ] }, "mediaId": { "pattern": "^med_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "platform": { "enum": [ "tiktok", "instagram", "twitter", "youtube", "facebook", "linkedin", "pinterest", "threads", "reddit", "x", null ], "type": [ "string", "null" ] }, "platformSpecificData": { "additionalProperties": {}, "description": "Platform options, checked against the platform registry: unknown fields are rejected with unknown_field. The accepted fields depend on platform; fields required to schedule or publish are named in each description.", "type": [ "object", "null" ] }, "scheduledFor": { "format": "date-time", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "profileId": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "publishNow": { "type": [ "boolean", "null" ] }, "scheduledFor": { "format": "date-time", "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "content": { "type": [ "string", "null" ] }, "createdAt": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "mediaItems": { "items": { "properties": { "altText": { "type": [ "string", "null" ] }, "mediaId": { "pattern": "^med_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "notice": { "type": [ "string", "null" ] }, "platforms": { "items": { "properties": { "accountId": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "customContent": { "type": [ "string", "null" ] }, "customMedia": { "items": { "properties": { "altText": { "type": [ "string", "null" ] }, "mediaId": { "pattern": "^med_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "error": { "properties": { "category": { "enum": [ "platform_rate_limit", "platform_error", "system_error", "unknown", "auth_expired", "account_issue", "user_content", "user_abuse", "platform_rejected", "quota_exhausted", null ], "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "platformError": { "additionalProperties": {}, "type": [ "object", "null" ] }, "retryHint": { "enum": [ "never", "after_delay", "after_reconnect", "reconcile_first", null ], "type": [ "string", "null" ] }, "retryable": { "type": [ "boolean", "null" ] }, "source": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "platform": { "enum": [ "tiktok", "instagram", "twitter", "youtube", "facebook", "linkedin", "pinterest", "threads", "reddit", "googlebusiness", "googleanalytics", "bluesky", "telegram", "slack", "snapchat", "hubspot", "microsoft", null ], "type": [ "string", "null" ] }, "platformPostId": { "type": [ "string", "null" ] }, "platformPostUrl": { "type": [ "string", "null" ] }, "platformSpecificData": { "additionalProperties": {}, "type": [ "object", "null" ] }, "publishedAt": { "format": "date-time", "type": [ "string", "null" ] }, "removedAt": { "format": "date-time", "type": [ "string", "null" ] }, "scheduledFor": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "profileId": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "scheduledFor": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "updatedAt": { "format": "date-time", "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Success" }, "201": { "content": { "application/json": { "schema": { "properties": { "content": { "type": [ "string", "null" ] }, "createdAt": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "mediaItems": { "items": { "properties": { "altText": { "type": [ "string", "null" ] }, "mediaId": { "pattern": "^med_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "notice": { "type": [ "string", "null" ] }, "platforms": { "items": { "properties": { "accountId": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "customContent": { "type": [ "string", "null" ] }, "customMedia": { "items": { "properties": { "altText": { "type": [ "string", "null" ] }, "mediaId": { "pattern": "^med_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "error": { "properties": { "category": { "enum": [ "platform_rate_limit", "platform_error", "system_error", "unknown", "auth_expired", "account_issue", "user_content", "user_abuse", "platform_rejected", "quota_exhausted", null ], "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "platformError": { "additionalProperties": {}, "type": [ "object", "null" ] }, "retryHint": { "enum": [ "never", "after_delay", "after_reconnect", "reconcile_first", null ], "type": [ "string", "null" ] }, "retryable": { "type": [ "boolean", "null" ] }, "source": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "platform": { "enum": [ "tiktok", "instagram", "twitter", "youtube", "facebook", "linkedin", "pinterest", "threads", "reddit", "googlebusiness", "googleanalytics", "bluesky", "telegram", "slack", "snapchat", "hubspot", "microsoft", null ], "type": [ "string", "null" ] }, "platformPostId": { "type": [ "string", "null" ] }, "platformPostUrl": { "type": [ "string", "null" ] }, "platformSpecificData": { "additionalProperties": {}, "type": [ "object", "null" ] }, "publishedAt": { "format": "date-time", "type": [ "string", "null" ] }, "removedAt": { "format": "date-time", "type": [ "string", "null" ] }, "scheduledFor": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "profileId": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "scheduledFor": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "updatedAt": { "format": "date-time", "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Success" }, "202": { "content": { "application/json": { "schema": { "properties": { "content": { "type": [ "string", "null" ] }, "createdAt": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "mediaItems": { "items": { "properties": { "altText": { "type": [ "string", "null" ] }, "mediaId": { "pattern": "^med_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "notice": { "type": [ "string", "null" ] }, "platforms": { "items": { "properties": { "accountId": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "customContent": { "type": [ "string", "null" ] }, "customMedia": { "items": { "properties": { "altText": { "type": [ "string", "null" ] }, "mediaId": { "pattern": "^med_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "error": { "properties": { "category": { "enum": [ "platform_rate_limit", "platform_error", "system_error", "unknown", "auth_expired", "account_issue", "user_content", "user_abuse", "platform_rejected", "quota_exhausted", null ], "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "platformError": { "additionalProperties": {}, "type": [ "object", "null" ] }, "retryHint": { "enum": [ "never", "after_delay", "after_reconnect", "reconcile_first", null ], "type": [ "string", "null" ] }, "retryable": { "type": [ "boolean", "null" ] }, "source": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "platform": { "enum": [ "tiktok", "instagram", "twitter", "youtube", "facebook", "linkedin", "pinterest", "threads", "reddit", "googlebusiness", "googleanalytics", "bluesky", "telegram", "slack", "snapchat", "hubspot", "microsoft", null ], "type": [ "string", "null" ] }, "platformPostId": { "type": [ "string", "null" ] }, "platformPostUrl": { "type": [ "string", "null" ] }, "platformSpecificData": { "additionalProperties": {}, "type": [ "object", "null" ] }, "publishedAt": { "format": "date-time", "type": [ "string", "null" ] }, "removedAt": { "format": "date-time", "type": [ "string", "null" ] }, "scheduledFor": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "profileId": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "scheduledFor": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "updatedAt": { "format": "date-time", "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Accepted; the outcome is pending and arrives by webhook" }, "207": { "content": { "application/json": { "schema": { "properties": { "content": { "type": [ "string", "null" ] }, "createdAt": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "mediaItems": { "items": { "properties": { "altText": { "type": [ "string", "null" ] }, "mediaId": { "pattern": "^med_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "notice": { "type": [ "string", "null" ] }, "platforms": { "items": { "properties": { "accountId": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "customContent": { "type": [ "string", "null" ] }, "customMedia": { "items": { "properties": { "altText": { "type": [ "string", "null" ] }, "mediaId": { "pattern": "^med_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "error": { "properties": { "category": { "enum": [ "platform_rate_limit", "platform_error", "system_error", "unknown", "auth_expired", "account_issue", "user_content", "user_abuse", "platform_rejected", "quota_exhausted", null ], "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "platformError": { "additionalProperties": {}, "type": [ "object", "null" ] }, "retryHint": { "enum": [ "never", "after_delay", "after_reconnect", "reconcile_first", null ], "type": [ "string", "null" ] }, "retryable": { "type": [ "boolean", "null" ] }, "source": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "platform": { "enum": [ "tiktok", "instagram", "twitter", "youtube", "facebook", "linkedin", "pinterest", "threads", "reddit", "googlebusiness", "googleanalytics", "bluesky", "telegram", "slack", "snapchat", "hubspot", "microsoft", null ], "type": [ "string", "null" ] }, "platformPostId": { "type": [ "string", "null" ] }, "platformPostUrl": { "type": [ "string", "null" ] }, "platformSpecificData": { "additionalProperties": {}, "type": [ "object", "null" ] }, "publishedAt": { "format": "date-time", "type": [ "string", "null" ] }, "removedAt": { "format": "date-time", "type": [ "string", "null" ] }, "scheduledFor": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "profileId": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "scheduledFor": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "updatedAt": { "format": "date-time", "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Some platforms failed; see each platform's status and error" }, "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." } }, "summary": "Create a post", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.posts.create@1", "publish_scope": "social:publish", "required_scope": "social:draft", "scope_rule": "Drafts need social:draft; scheduling or publishing needs social:publish." }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Each platform target that publishes successfully is metered once under social.post.published:, including after retries. Not charged in the current period.", "kind": "metered_event", "meter": "social.post.published" }, "x-aisa-revision": { "handler_contract_hash": "0089153f6231c777bbd9ecb43832a84043fcb4a9afb888c2ae870d85ac279d52" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_posts", "method": "POST", "path": "/apis/v1/social/posts" }, "x-codeSamples": [ { "lang": "text", "label": "Reference example", "source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/social/posts \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"content\": \"Our spring collection is live.\",\n \"mediaItems\": [\n {\n \"mediaId\": \"med_5Tc8Hn2Wq7Lx3Bv9Kd4Fr6\",\n \"type\": \"video\"\n }\n ],\n \"platforms\": [\n {\n \"accountId\": \"acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3\",\n \"platform\": \"tiktok\",\n \"platformSpecificData\": {\n \"privacyLevel\": \"PUBLIC_TO_EVERYONE\"\n }\n }\n ],\n \"profileId\": \"prf_2Bn8Wq5Td1Yh7Kc3Mz9Lp4\",\n \"scheduledFor\": \"2026-11-20T15:00:00Z\",\n \"timezone\": \"America/New_York\"\n}'" } ], "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_posts" } }, "/apis/v1/social/posts/sync-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.\n\nFetch 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.\n\nPrimary 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.\n\n### Behavior\n\n- Account access and connection state are checked before any platform call, including requests inside the debounce window.\n- 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.\n- For connected accounts, we fetch the latest posts live from the platform, then match and return the submitted post.\n- Requests are debounced per account (~15s): if the account was synced inside that window, the live fetch is skipped.\n\n### Account and platforms\n\n`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).\n\nSupported for every platform with a listing API: Instagram, Facebook, TikTok, YouTube, X, Threads, Pinterest, Reddit, Bluesky, Google Business Profile, and LinkedIn organization accounts.\n\n### Locating the post\n\n`url` accepts any format the platform uses, for example:\n\n- `instagram.com/p/…`, `instagram.com/reel/…`\n- `youtu.be/…`, `youtube.com/shorts/…`\n- `tiktok.com/@user/video/…`, `vm.tiktok.com` short links\n- `pinterest.com/pin/…` on any regional domain, and `pin.it` short links\n\nPass `postId` (the platform media/video/pin id) as an alternative locator.\n\n### LinkedIn personal profiles\n\nLinkedIn 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.\n\nIt works for posts published outside AIsa and before the account was connected, at any age. The post must be authored by the connected member.\n\nImported 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.\n\n`publishedAt` comes from the post id:\n\n- An activity URL (`linkedin.com/feed/update/urn:li:activity:…`) carries the publication time.\n- A `urn:li:share:…` / `urn:li:ugcPost:…` URN only carries the creation time, which is earlier for a post scheduled in another tool.\n\nPass 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.\n\nRight 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.\n\n### TikTok Business accounts\n\nA `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.\n\n### Analytics delay\n\nPost-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.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "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\nthrough AIsa). Returned by GET /apis/v1/social/posts?source=external and\nPOST /apis/v1/social/posts/sync-external. Analytics are exposed separately via\nGET /apis/v1/social/analytics?source=external.", "properties": { "analytics": { "description": "Engagement + insights for the post. `likes` and `comments` are\navailable immediately after an on-demand sync (they come from the\nplatform listing). `reach`, `impressions`, `views` depend on the\nplatform's insights, which carry their own delay (e.g. ~24h on\nInstagram) 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\nthrough AIsa). Returned by GET /apis/v1/social/posts?source=external and\nPOST /apis/v1/social/posts/sync-external. Analytics are exposed separately via\nGET /apis/v1/social/analytics?source=external.", "properties": { "analytics": { "description": "Engagement + insights for the post. `likes` and `comments` are\navailable immediately after an on-demand sync (they come from the\nplatform listing). `reach`, `impressions`, `views` depend on the\nplatform's insights, which carry their own delay (e.g. ~24h on\nInstagram) 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.\n" }, "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." } }, "summary": "Sync an external post", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.sync_external_posts@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "f6afd11dfc6770737f05fb9aeefda31a5f4f322f2e558e307716e01c5054713b" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_posts_sync_external", "method": "POST", "path": "/apis/v1/social/posts/sync-external" }, "x-codeSamples": [ { "lang": "text", "label": "Reference example", "source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/social/posts/sync-external \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"accountId\": \"acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3\"\n}'" } ], "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_posts_sync_external" } }, "/apis/v1/social/posts/{postId}": { "delete": { "description": "Deletes or cancels a post. Published posts return 409 post_published. Deleting a publishing or partial post stops pending platforms; platforms already in flight may still publish.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "delete_aisa_social_apis_v1_social_posts_postid", "parameters": [ { "in": "path", "name": "postId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "type": [ "boolean", "null" ] }, "id": { "type": [ "string", "null" ] }, "notice": { "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Success" }, "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." } }, "summary": "Delete a post", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.posts.delete@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "This operation does not settle a customer usage charge.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "48e23ca51f92ca851c173d6d01fe47022b39adba8c9c8137d18d7b3aff76781d" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "delete_aisa_social_apis_v1_social_posts_postid", "method": "DELETE", "path": "/apis/v1/social/posts/{postId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/delete_aisa_social_apis_v1_social_posts_postid" }, "get": { "description": "\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_posts_postid", "parameters": [ { "in": "path", "name": "postId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "content": { "type": [ "string", "null" ] }, "createdAt": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "mediaItems": { "items": { "properties": { "altText": { "type": [ "string", "null" ] }, "mediaId": { "pattern": "^med_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "notice": { "type": [ "string", "null" ] }, "platforms": { "items": { "properties": { "accountId": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "customContent": { "type": [ "string", "null" ] }, "customMedia": { "items": { "properties": { "altText": { "type": [ "string", "null" ] }, "mediaId": { "pattern": "^med_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "error": { "properties": { "category": { "enum": [ "platform_rate_limit", "platform_error", "system_error", "unknown", "auth_expired", "account_issue", "user_content", "user_abuse", "platform_rejected", "quota_exhausted", null ], "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "platformError": { "additionalProperties": {}, "type": [ "object", "null" ] }, "retryHint": { "enum": [ "never", "after_delay", "after_reconnect", "reconcile_first", null ], "type": [ "string", "null" ] }, "retryable": { "type": [ "boolean", "null" ] }, "source": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "platform": { "enum": [ "tiktok", "instagram", "twitter", "youtube", "facebook", "linkedin", "pinterest", "threads", "reddit", "googlebusiness", "googleanalytics", "bluesky", "telegram", "slack", "snapchat", "hubspot", "microsoft", null ], "type": [ "string", "null" ] }, "platformPostId": { "type": [ "string", "null" ] }, "platformPostUrl": { "type": [ "string", "null" ] }, "platformSpecificData": { "additionalProperties": {}, "type": [ "object", "null" ] }, "publishedAt": { "format": "date-time", "type": [ "string", "null" ] }, "removedAt": { "format": "date-time", "type": [ "string", "null" ] }, "scheduledFor": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "profileId": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "scheduledFor": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "updatedAt": { "format": "date-time", "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Success" }, "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." } }, "summary": "Get a post", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.posts.get@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "This operation does not settle a customer usage charge.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "7c8108f350ea636026016818b6ec1f39505122bb42e7b7cbc85462089c7bbaa6" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_posts_postid", "method": "GET", "path": "/apis/v1/social/posts/{postId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_posts_postid" }, "put": { "description": "Edits a draft, scheduled or failed post. Turning a draft into a scheduled or published post needs social:publish. Published, publishing, partial and cancelled posts return 409 post_not_editable.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "put_aisa_social_apis_v1_social_posts_postid", "parameters": [ { "in": "path", "name": "postId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "content": "Our spring collection is live.", "scheduledFor": "2026-11-20T15:00:00Z", "timezone": "America/New_York" }, "schema": { "additionalProperties": false, "properties": { "content": { "type": [ "string", "null" ] }, "isDraft": { "type": [ "boolean", "null" ] }, "mediaItems": { "items": { "additionalProperties": false, "properties": { "altText": { "type": [ "string", "null" ] }, "mediaId": { "pattern": "^med_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "platforms": { "items": { "additionalProperties": false, "allOf": [ { "if": { "properties": { "platform": { "enum": [ "tiktok" ] } }, "required": [ "platform" ] }, "then": { "properties": { "platformSpecificData": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "description": "Required to schedule or publish: privacyLevel, allowComment. Also required for video: allowDuet, allowStitch. Must be true, from the user: contentPreviewConfirmed, expressConsentGiven.", "properties": { "allowComment": { "description": "Allow comments. Must be false when creator-info reports commentDisabled.", "type": "boolean" }, "allowDuet": { "description": "Allow duets; required for video. Must be false when creator-info reports duetDisabled.", "type": "boolean" }, "allowStitch": { "description": "Allow stitches; required for video. Must be false when creator-info reports stitchDisabled.", "type": "boolean" }, "brandPartnerPromote": { "description": "Also disclose a paid partnership; only alongside commercialContentType brand_organic.", "type": "boolean" }, "commercialContentType": { "description": "Commercial content disclosure; one of commercialContentTypes from creator-info. brand_content cannot be SELF_ONLY.", "enum": [ "none", "brand_organic", "brand_content" ], "type": "string" }, "contentPreviewConfirmed": { "description": "The user previewed exactly this content. Must be true and must come from the user.", "type": "boolean" }, "description": { "description": "Long caption for photo posts.", "maxLength": 4000, "minLength": 1, "type": "string" }, "expressConsentGiven": { "description": "The user consented to posting. Must be true and must come from the user.", "type": "boolean" }, "isBrandOrganicPost": { "description": "Also disclose the creator's own brand; only alongside commercialContentType brand_content.", "type": "boolean" }, "mediaType": { "description": "Overrides the media type derived from the media items.", "enum": [ "video", "photo" ], "type": "string" }, "privacyLevel": { "description": "One of privacyLevelOptions from GET /accounts/{accountId}/tiktok/creator-info for this mediaType.", "maxLength": 64, "minLength": 1, "type": "string" }, "videoMadeWithAi": { "description": "Label the post as AI-generated.", "type": "boolean" } }, "type": "object" } ] } } } }, { "if": { "properties": { "platform": { "enum": [ "instagram" ] } }, "required": [ "platform" ] }, "then": { "properties": { "platformSpecificData": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "description": "", "properties": { "collaborators": { "description": "Up to 3 usernames to invite as collaborators (feed and Reels).", "items": { "maxLength": 64, "minLength": 1, "type": "string" }, "maxItems": 3, "type": "array" }, "contentType": { "description": "story publishes a Story.", "enum": [ "story" ], "type": "string" }, "firstComment": { "description": "First comment added after publishing (not on Stories).", "maxLength": 2200, "minLength": 1, "type": "string" }, "isAiGenerated": { "description": "Label the post as containing AI-generated media.", "type": "boolean" }, "shareToFeed": { "description": "Reels only: also show the Reel on the main feed (default true).", "type": "boolean" } }, "type": "object" } ] } } } }, { "if": { "properties": { "platform": { "enum": [ "twitter", "x" ] } }, "required": [ "platform" ] }, "then": { "properties": { "platformSpecificData": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "description": "", "properties": { "madeWithAi": { "description": "Label the post as containing AI-generated media.", "type": "boolean" }, "poll": { "additionalProperties": false, "description": "A poll; cannot be combined with media or threadItems.", "properties": { "duration_minutes": { "maximum": 10080, "minimum": 5, "type": "integer" }, "options": { "items": { "maxLength": 25, "minLength": 1, "type": "string" }, "maxItems": 4, "minItems": 2, "type": "array" } }, "required": [ "options", "duration_minutes" ], "type": "object" }, "replySettings": { "description": "Who can reply.", "enum": [ "following", "mentionedUsers", "subscribers", "verified" ], "type": "string" }, "threadItems": { "description": "The whole thread; the first item is the root post. Cannot be combined with poll.", "items": { "additionalProperties": false, "properties": { "content": { "description": "Text of this post.", "maxLength": 25000, "minLength": 1, "type": "string" } }, "required": [ "content" ], "type": "object" }, "minItems": 1, "type": "array" } }, "type": "object" } ] } } } }, { "if": { "properties": { "platform": { "enum": [ "youtube" ] } }, "required": [ "platform" ] }, "then": { "properties": { "platformSpecificData": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "description": "Required to schedule or publish: madeForKids.", "properties": { "containsSyntheticMedia": { "description": "Label the video as containing synthetic (AI-generated) content.", "type": "boolean" }, "firstComment": { "description": "First comment posted after upload.", "maxLength": 10000, "minLength": 1, "type": "string" }, "madeForKids": { "description": "COPPA: whether the video is made for kids. Required, and must be the user's explicit choice.", "type": "boolean" }, "title": { "description": "Video title.", "maxLength": 100, "minLength": 1, "type": "string" }, "visibility": { "description": "Video visibility.", "enum": [ "public", "private", "unlisted" ], "type": "string" } }, "type": "object" } ] } } } }, { "if": { "properties": { "platform": { "enum": [ "facebook" ] } }, "required": [ "platform" ] }, "then": { "properties": { "platformSpecificData": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "description": "", "properties": { "contentType": { "description": "story or reel; omitted is a feed post.", "enum": [ "story", "reel" ], "type": "string" }, "firstComment": { "description": "First comment added after publishing (not on stories).", "maxLength": 8000, "minLength": 1, "type": "string" }, "pageId": { "description": "Page to post to when the account manages several.", "maxLength": 64, "minLength": 1, "type": "string" } }, "type": "object" } ] } } } }, { "if": { "properties": { "platform": { "enum": [ "linkedin" ] } }, "required": [ "platform" ] }, "then": { "properties": { "platformSpecificData": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "description": "linkedin accepts no platformSpecificData yet.", "properties": {}, "type": "object" } ] } } } }, { "if": { "properties": { "platform": { "enum": [ "pinterest" ] } }, "required": [ "platform" ] }, "then": { "properties": { "platformSpecificData": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "description": "", "properties": { "isAiGenerated": { "description": "Label the Pin as AI modified.", "type": "boolean" } }, "type": "object" } ] } } } }, { "if": { "properties": { "platform": { "enum": [ "threads" ] } }, "required": [ "platform" ] }, "then": { "properties": { "platformSpecificData": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "description": "threads accepts no platformSpecificData yet.", "properties": {}, "type": "object" } ] } } } }, { "if": { "properties": { "platform": { "enum": [ "reddit" ] } }, "required": [ "platform" ] }, "then": { "properties": { "platformSpecificData": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "description": "reddit accepts no platformSpecificData yet.", "properties": {}, "type": "object" } ] } } } } ], "properties": { "accountId": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "customContent": { "type": [ "string", "null" ] }, "customMedia": { "items": { "additionalProperties": false, "properties": { "altText": { "type": [ "string", "null" ] }, "mediaId": { "pattern": "^med_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "platform": { "enum": [ "tiktok", "instagram", "twitter", "youtube", "facebook", "linkedin", "pinterest", "threads", "reddit", "x", null ], "type": [ "string", "null" ] }, "platformSpecificData": { "additionalProperties": {}, "description": "Platform options, checked against the platform registry: unknown fields are rejected with unknown_field. The accepted fields depend on platform; fields required to schedule or publish are named in each description.", "type": [ "object", "null" ] }, "scheduledFor": { "format": "date-time", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "publishNow": { "type": [ "boolean", "null" ] }, "scheduledFor": { "format": "date-time", "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "content": { "type": [ "string", "null" ] }, "createdAt": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "mediaItems": { "items": { "properties": { "altText": { "type": [ "string", "null" ] }, "mediaId": { "pattern": "^med_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "notice": { "type": [ "string", "null" ] }, "platforms": { "items": { "properties": { "accountId": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "customContent": { "type": [ "string", "null" ] }, "customMedia": { "items": { "properties": { "altText": { "type": [ "string", "null" ] }, "mediaId": { "pattern": "^med_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "error": { "properties": { "category": { "enum": [ "platform_rate_limit", "platform_error", "system_error", "unknown", "auth_expired", "account_issue", "user_content", "user_abuse", "platform_rejected", "quota_exhausted", null ], "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "platformError": { "additionalProperties": {}, "type": [ "object", "null" ] }, "retryHint": { "enum": [ "never", "after_delay", "after_reconnect", "reconcile_first", null ], "type": [ "string", "null" ] }, "retryable": { "type": [ "boolean", "null" ] }, "source": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "platform": { "enum": [ "tiktok", "instagram", "twitter", "youtube", "facebook", "linkedin", "pinterest", "threads", "reddit", "googlebusiness", "googleanalytics", "bluesky", "telegram", "slack", "snapchat", "hubspot", "microsoft", null ], "type": [ "string", "null" ] }, "platformPostId": { "type": [ "string", "null" ] }, "platformPostUrl": { "type": [ "string", "null" ] }, "platformSpecificData": { "additionalProperties": {}, "type": [ "object", "null" ] }, "publishedAt": { "format": "date-time", "type": [ "string", "null" ] }, "removedAt": { "format": "date-time", "type": [ "string", "null" ] }, "scheduledFor": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "profileId": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "scheduledFor": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "updatedAt": { "format": "date-time", "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Success" }, "202": { "content": { "application/json": { "schema": { "properties": { "content": { "type": [ "string", "null" ] }, "createdAt": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "mediaItems": { "items": { "properties": { "altText": { "type": [ "string", "null" ] }, "mediaId": { "pattern": "^med_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "notice": { "type": [ "string", "null" ] }, "platforms": { "items": { "properties": { "accountId": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "customContent": { "type": [ "string", "null" ] }, "customMedia": { "items": { "properties": { "altText": { "type": [ "string", "null" ] }, "mediaId": { "pattern": "^med_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "error": { "properties": { "category": { "enum": [ "platform_rate_limit", "platform_error", "system_error", "unknown", "auth_expired", "account_issue", "user_content", "user_abuse", "platform_rejected", "quota_exhausted", null ], "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "platformError": { "additionalProperties": {}, "type": [ "object", "null" ] }, "retryHint": { "enum": [ "never", "after_delay", "after_reconnect", "reconcile_first", null ], "type": [ "string", "null" ] }, "retryable": { "type": [ "boolean", "null" ] }, "source": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "platform": { "enum": [ "tiktok", "instagram", "twitter", "youtube", "facebook", "linkedin", "pinterest", "threads", "reddit", "googlebusiness", "googleanalytics", "bluesky", "telegram", "slack", "snapchat", "hubspot", "microsoft", null ], "type": [ "string", "null" ] }, "platformPostId": { "type": [ "string", "null" ] }, "platformPostUrl": { "type": [ "string", "null" ] }, "platformSpecificData": { "additionalProperties": {}, "type": [ "object", "null" ] }, "publishedAt": { "format": "date-time", "type": [ "string", "null" ] }, "removedAt": { "format": "date-time", "type": [ "string", "null" ] }, "scheduledFor": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "profileId": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "scheduledFor": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "updatedAt": { "format": "date-time", "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Accepted; the outcome is pending and arrives by webhook" }, "207": { "content": { "application/json": { "schema": { "properties": { "content": { "type": [ "string", "null" ] }, "createdAt": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "mediaItems": { "items": { "properties": { "altText": { "type": [ "string", "null" ] }, "mediaId": { "pattern": "^med_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "notice": { "type": [ "string", "null" ] }, "platforms": { "items": { "properties": { "accountId": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "customContent": { "type": [ "string", "null" ] }, "customMedia": { "items": { "properties": { "altText": { "type": [ "string", "null" ] }, "mediaId": { "pattern": "^med_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "error": { "properties": { "category": { "enum": [ "platform_rate_limit", "platform_error", "system_error", "unknown", "auth_expired", "account_issue", "user_content", "user_abuse", "platform_rejected", "quota_exhausted", null ], "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "platformError": { "additionalProperties": {}, "type": [ "object", "null" ] }, "retryHint": { "enum": [ "never", "after_delay", "after_reconnect", "reconcile_first", null ], "type": [ "string", "null" ] }, "retryable": { "type": [ "boolean", "null" ] }, "source": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "platform": { "enum": [ "tiktok", "instagram", "twitter", "youtube", "facebook", "linkedin", "pinterest", "threads", "reddit", "googlebusiness", "googleanalytics", "bluesky", "telegram", "slack", "snapchat", "hubspot", "microsoft", null ], "type": [ "string", "null" ] }, "platformPostId": { "type": [ "string", "null" ] }, "platformPostUrl": { "type": [ "string", "null" ] }, "platformSpecificData": { "additionalProperties": {}, "type": [ "object", "null" ] }, "publishedAt": { "format": "date-time", "type": [ "string", "null" ] }, "removedAt": { "format": "date-time", "type": [ "string", "null" ] }, "scheduledFor": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "profileId": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "scheduledFor": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "updatedAt": { "format": "date-time", "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Some platforms failed; see each platform's status and error" }, "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." } }, "summary": "Update a post", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.posts.update@1", "publish_scope": "social:publish", "required_scope": "social:draft", "scope_rule": "Drafts need social:draft; scheduling or publishing needs social:publish." }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Each platform target that publishes successfully is metered once under social.post.published:, including after retries. Not charged in the current period.", "kind": "metered_event", "meter": "social.post.published" }, "x-aisa-revision": { "handler_contract_hash": "5635a8da559c648abebc508ef5e5f02a1cfbd1866a31b700ba2beba397842459" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "put_aisa_social_apis_v1_social_posts_postid", "method": "PUT", "path": "/apis/v1/social/posts/{postId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/put_aisa_social_apis_v1_social_posts_postid" } }, "/apis/v1/social/posts/{postId}/authenticity": { "get": { "description": "Analytics. 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.\n\nReturns AIsa's authenticity score for a post: an integer from 0 to 100 where higher means the view pattern looks more like organic viewing.\n\nThe score is ours. It is computed only from the verified samples we fetched from the platform, never from anything the creator or caller reported.\n\n- `reasons` lists each factor that lowered it with its weight in points.\n- `confidence` (0 to 1) says how much data the score rests on.\n\nA stored score newer than 30 minutes is returned as is, otherwise it is recomputed. The `post.authenticity_changed` webhook fires when a score crosses 40.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_posts_postid_authenticity", "parameters": [ { "description": "An external post id, a platform post id or a AIsa post id.", "in": "path", "name": "postId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "computedAt": { "format": "date-time", "type": "string" }, "confidence": { "description": "How much data the score rests on", "maximum": 1, "minimum": 0, "type": "number" }, "postId": { "description": "The external post the score belongs to", "type": "string" }, "reasons": { "description": "Each factor that lowered the score, with its weight in points", "items": { "properties": { "code": { "enum": [ "late_block", "flat_engagement", "view_follower_gap", "cap_seeking", "prior_flags", "no_watch_signal" ], "type": "string" }, "weight": { "description": "Points taken off 100. Zero for no_watch_signal, which only lowers confidence.", "type": "number" } }, "required": [ "code", "weight" ], "type": "object" }, "type": "array" }, "sampleCount": { "description": "Number of samples the score was computed from", "type": "integer" }, "score": { "description": "Higher means the view pattern looks more organic", "maximum": 100, "minimum": 0, "type": "integer" }, "version": { "description": "Scoring model version", "type": "string" } }, "required": [ "computedAt", "confidence", "postId", "reasons", "sampleCount", "score", "version" ], "type": "object" } } }, "description": "The post's authenticity score" }, "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." } }, "summary": "Get a post's authenticity score", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.analytics.get_post_authenticity@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "b34ed4d947457b6809926863c5b05ed415cc88b037526bfcd753076dafeb912c" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_posts_postid_authenticity", "method": "GET", "path": "/apis/v1/social/posts/{postId}/authenticity" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_posts_postid_authenticity" } }, "/apis/v1/social/posts/{postId}/edit": { "post": { "description": "Posts. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nEdit the text of an already-published post. Supported on X, Discord, Facebook, Reddit, LinkedIn, Telegram, Pinterest, Google Business Profile, YouTube, and Slack.\n\nWhen a post was published to several accounts on the same platform, pass `accountId` to pick which account's copy to edit (without it the request returns 409). Each platform enforces its own rules.\n\n**X**\n\n- Connected X account must have an active X Premium subscription\n- Must be within 1 hour of original publish time\n- Maximum 5 edits per tweet (enforced by X)\n- Threads cannot be edited, only single tweets\n- X assigns a NEW post ID on edit, returned as `id`\n\n**Discord**\n\n- No time limit and no premium requirement\n- The message ID is unchanged after the edit\n\n**Facebook**\n\n- Graph only permits editing a post that the same app created. This works on posts published through AIsa and is rejected for posts created in Meta Business Suite / Composer or by another tool\n- Media cannot be swapped, only the message text\n- Reactions, comments, and shares are preserved. The post ID is unchanged\n\n**Reddit**\n\n- Self-posts only. A link post has no editable body and is rejected before the write\n- Body only. Reddit exposes no API to edit a post title, ever\n- The post ID is unchanged\n\n**LinkedIn**\n\n- Text only, no time limit. Media, polls, articles, and reshare targets cannot be changed\n- Works for member and organization posts published through this API. The post keeps its ID and LinkedIn shows an \"edited\" marker\n- Text is limited to 3,000 characters; mentions and hashtags are preserved\n\n**Telegram**\n\n- No time limit; messages published through AIsa are editable indefinitely\n- Text posts: edits the message text (up to 4096 characters)\n- Media posts: edits the caption only (up to 1024 characters). The media itself cannot be swapped\n- For albums, the caption shown on the album (its first message) is edited\n- The message ID is unchanged\n\n**Pinterest**\n\n- Description only, maximum 800 characters. Media, link, and board cannot be changed, and a pin title derived from the old content's first line at publish stays as-is\n- Pinterest's pin-update endpoint is currently in closed beta. Until the app is allowlisted by Pinterest, edits are rejected with a \"beta feature not yet enabled\" error\n- The pin ID is unchanged\n\n**Google Business Profile**\n\n- Post body (summary) text only. Call-to-action, event/offer fields, and media are untouched\n- No time limit and no edit limit. The post ID is unchanged\n- The post must still exist on Google: a post deleted from the Business Profile dashboard, or an event/offer post past its end date, returns a 404\n\n**YouTube**\n\n- `content` replaces the video description only. The title is unchanged, even if it was originally derived from the content's first line at publish time\n- Title, tags, thumbnail, and privacy edits belong to `POST /apis/v1/social/posts/{postId}/update-metadata`\n- No time window and no edit cap. The video ID is unchanged\n\n**Slack**\n\n- Text only, up to 4,000 characters. Media cannot be swapped, and media posts whose share message reference never resolved cannot be edited\n- No time limit unless workspace admins restrict message editing\n- The message ID is unchanged\n\nMedia edits are not supported on any platform. The post record in AIsa is updated with the new content and an edit-history entry.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_posts_postid_edit", "parameters": [ { "in": "path", "name": "postId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "content": "Updated post text with corrected information", "platform": "facebook" }, "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "content": { "description": "The new post text content", "type": "string" }, "platform": { "description": "The platform to edit the post on.", "enum": [ "twitter", "discord", "facebook", "reddit", "linkedin", "telegram", "pinterest", "googlebusiness", "youtube", "slack" ], "type": "string" } }, "required": [ "content", "platform" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "id": { "description": "The platform post ID after the edit. X assigns a new ID; every other platform returns the original ID unchanged.", "type": "string" }, "message": { "type": "string" }, "success": { "type": "boolean" }, "url": { "description": "URL of the edited post", "format": "uri", "type": "string" } }, "type": "object" } } }, "description": "Post edited successfully" }, "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." } }, "summary": "Edit published post", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.posts.edit_post@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "843f8e6da1d8f382ba36ea4709e7f2121ae3d38a7bddebe497e77a1a4ddbfd20" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_posts_postid_edit", "method": "POST", "path": "/apis/v1/social/posts/{postId}/edit" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_posts_postid_edit" } }, "/apis/v1/social/posts/{postId}/pin": { "post": { "description": "Posts. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nPins a published Facebook Page post to the top of its Page. Only Facebook posts can be pinned; any other platform answers 400 `platform_not_supported`. Works for posts on Pages connected through Facebook Login.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_posts_postid_pin", "parameters": [ { "in": "path", "name": "postId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "platform": "facebook" }, "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "platform": { "description": "Must be `facebook`. Any other value answers 400 `platform_not_supported`.", "type": "string" } }, "required": [ "platform" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "pinned": { "description": "Whether the post is now pinned to the top of the Page.", "type": "boolean" }, "platformPostId": { "description": "The Facebook post ID that was changed.", "type": "string" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Pin applied on Facebook" }, "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." } }, "summary": "Pin post", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.posts.pin_post@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "f90b3aa4d01504a35b2d380b27fd25071d78a1cb40222ae83c6fbaab9911df73" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_posts_postid_pin", "method": "POST", "path": "/apis/v1/social/posts/{postId}/pin" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_posts_postid_pin" } }, "/apis/v1/social/posts/{postId}/retry": { "post": { "description": "Retries failed platforms of a failed or partial post. Platforms whose retryHint is never are skipped.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_posts_postid_retry", "parameters": [ { "in": "path", "name": "postId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "content": { "type": [ "string", "null" ] }, "createdAt": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "mediaItems": { "items": { "properties": { "altText": { "type": [ "string", "null" ] }, "mediaId": { "pattern": "^med_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "notice": { "type": [ "string", "null" ] }, "platforms": { "items": { "properties": { "accountId": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "customContent": { "type": [ "string", "null" ] }, "customMedia": { "items": { "properties": { "altText": { "type": [ "string", "null" ] }, "mediaId": { "pattern": "^med_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "error": { "properties": { "category": { "enum": [ "platform_rate_limit", "platform_error", "system_error", "unknown", "auth_expired", "account_issue", "user_content", "user_abuse", "platform_rejected", "quota_exhausted", null ], "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "platformError": { "additionalProperties": {}, "type": [ "object", "null" ] }, "retryHint": { "enum": [ "never", "after_delay", "after_reconnect", "reconcile_first", null ], "type": [ "string", "null" ] }, "retryable": { "type": [ "boolean", "null" ] }, "source": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "platform": { "enum": [ "tiktok", "instagram", "twitter", "youtube", "facebook", "linkedin", "pinterest", "threads", "reddit", "googlebusiness", "googleanalytics", "bluesky", "telegram", "slack", "snapchat", "hubspot", "microsoft", null ], "type": [ "string", "null" ] }, "platformPostId": { "type": [ "string", "null" ] }, "platformPostUrl": { "type": [ "string", "null" ] }, "platformSpecificData": { "additionalProperties": {}, "type": [ "object", "null" ] }, "publishedAt": { "format": "date-time", "type": [ "string", "null" ] }, "removedAt": { "format": "date-time", "type": [ "string", "null" ] }, "scheduledFor": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "profileId": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "scheduledFor": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "updatedAt": { "format": "date-time", "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Success" }, "202": { "content": { "application/json": { "schema": { "properties": { "content": { "type": [ "string", "null" ] }, "createdAt": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "mediaItems": { "items": { "properties": { "altText": { "type": [ "string", "null" ] }, "mediaId": { "pattern": "^med_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "notice": { "type": [ "string", "null" ] }, "platforms": { "items": { "properties": { "accountId": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "customContent": { "type": [ "string", "null" ] }, "customMedia": { "items": { "properties": { "altText": { "type": [ "string", "null" ] }, "mediaId": { "pattern": "^med_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "error": { "properties": { "category": { "enum": [ "platform_rate_limit", "platform_error", "system_error", "unknown", "auth_expired", "account_issue", "user_content", "user_abuse", "platform_rejected", "quota_exhausted", null ], "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "platformError": { "additionalProperties": {}, "type": [ "object", "null" ] }, "retryHint": { "enum": [ "never", "after_delay", "after_reconnect", "reconcile_first", null ], "type": [ "string", "null" ] }, "retryable": { "type": [ "boolean", "null" ] }, "source": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "platform": { "enum": [ "tiktok", "instagram", "twitter", "youtube", "facebook", "linkedin", "pinterest", "threads", "reddit", "googlebusiness", "googleanalytics", "bluesky", "telegram", "slack", "snapchat", "hubspot", "microsoft", null ], "type": [ "string", "null" ] }, "platformPostId": { "type": [ "string", "null" ] }, "platformPostUrl": { "type": [ "string", "null" ] }, "platformSpecificData": { "additionalProperties": {}, "type": [ "object", "null" ] }, "publishedAt": { "format": "date-time", "type": [ "string", "null" ] }, "removedAt": { "format": "date-time", "type": [ "string", "null" ] }, "scheduledFor": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "profileId": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "scheduledFor": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "updatedAt": { "format": "date-time", "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Accepted; the outcome is pending and arrives by webhook" }, "207": { "content": { "application/json": { "schema": { "properties": { "content": { "type": [ "string", "null" ] }, "createdAt": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "mediaItems": { "items": { "properties": { "altText": { "type": [ "string", "null" ] }, "mediaId": { "pattern": "^med_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "notice": { "type": [ "string", "null" ] }, "platforms": { "items": { "properties": { "accountId": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "customContent": { "type": [ "string", "null" ] }, "customMedia": { "items": { "properties": { "altText": { "type": [ "string", "null" ] }, "mediaId": { "pattern": "^med_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "error": { "properties": { "category": { "enum": [ "platform_rate_limit", "platform_error", "system_error", "unknown", "auth_expired", "account_issue", "user_content", "user_abuse", "platform_rejected", "quota_exhausted", null ], "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "platformError": { "additionalProperties": {}, "type": [ "object", "null" ] }, "retryHint": { "enum": [ "never", "after_delay", "after_reconnect", "reconcile_first", null ], "type": [ "string", "null" ] }, "retryable": { "type": [ "boolean", "null" ] }, "source": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "platform": { "enum": [ "tiktok", "instagram", "twitter", "youtube", "facebook", "linkedin", "pinterest", "threads", "reddit", "googlebusiness", "googleanalytics", "bluesky", "telegram", "slack", "snapchat", "hubspot", "microsoft", null ], "type": [ "string", "null" ] }, "platformPostId": { "type": [ "string", "null" ] }, "platformPostUrl": { "type": [ "string", "null" ] }, "platformSpecificData": { "additionalProperties": {}, "type": [ "object", "null" ] }, "publishedAt": { "format": "date-time", "type": [ "string", "null" ] }, "removedAt": { "format": "date-time", "type": [ "string", "null" ] }, "scheduledFor": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "profileId": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "scheduledFor": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "updatedAt": { "format": "date-time", "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Some platforms failed; see each platform's status and error" }, "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." } }, "summary": "Retry failed platforms", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.posts.retry@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Each platform target that publishes successfully is metered once under social.post.published:, including after retries. Not charged in the current period.", "kind": "metered_event", "meter": "social.post.published" }, "x-aisa-revision": { "handler_contract_hash": "3bf2f9d059feea3e9e3112372d2fd1a4328175bf73df5ab7769c96929f829ab1" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_posts_postid_retry", "method": "POST", "path": "/apis/v1/social/posts/{postId}/retry" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_posts_postid_retry" } }, "/apis/v1/social/posts/{postId}/unpin": { "post": { "description": "Posts. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nUnpins a published Facebook Page post from the top of its Page. Only Facebook posts can be unpinned; any other platform answers 400 `platform_not_supported`.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_posts_postid_unpin", "parameters": [ { "in": "path", "name": "postId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "platform": "facebook" }, "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "platform": { "description": "Must be `facebook`. Any other value answers 400 `platform_not_supported`.", "type": "string" } }, "required": [ "platform" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "pinned": { "description": "Whether the post is now pinned to the top of the Page.", "type": "boolean" }, "platformPostId": { "description": "The Facebook post ID that was changed.", "type": "string" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Unpin applied on Facebook" }, "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." } }, "summary": "Unpin post", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.posts.unpin_post@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "6b7971dab761169975d095757878d574a94c3615098e002ee2de89b769313eb4" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_posts_postid_unpin", "method": "POST", "path": "/apis/v1/social/posts/{postId}/unpin" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_posts_postid_unpin" } }, "/apis/v1/social/posts/{postId}/unpublish": { "post": { "description": "Posts. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nDeletes a published post from the specified platform. The post record in AIsa is kept but its status is updated to cancelled.\nNot supported on Instagram, TikTok, or Snapchat. Threaded posts delete all items. YouTube deletion is permanent.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_posts_postid_unpublish", "parameters": [ { "in": "path", "name": "postId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "platform": "threads" }, "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "platform": { "description": "The platform to delete the post from", "enum": [ "threads", "facebook", "twitter", "linkedin", "youtube", "pinterest", "reddit", "bluesky", "googlebusiness", "telegram" ], "type": "string" } }, "required": [ "platform" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Post deleted from platform" }, "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." } }, "summary": "Unpublish post", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.posts.unpublish_post@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "bb7ee785ecfa288a20c0641205ab06b3fa4dbc509e772abb97014f7493c4b5b2" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_posts_postid_unpublish", "method": "POST", "path": "/apis/v1/social/posts/{postId}/unpublish" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_posts_postid_unpublish" } }, "/apis/v1/social/posts/{postId}/update-metadata": { "post": { "description": "Posts. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call.\n\nUpdates metadata of a published video on the specified platform without re-uploading. Currently only supported for YouTube. At least one updatable field is required.\n\n### Two modes\n\n1. Post-based (video published through AIsa): pass the AIsa postId in the URL and platform in the body.\n2. Direct video ID (video uploaded outside AIsa, e.g. directly to YouTube): use _ as the postId, and pass videoId + accountId + platform in the body. The accountId is the AIsa account ID for the connected YouTube channel.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_posts_postid_upda_cf80eb", "parameters": [ { "description": "AIsa post ID, or \"_\" when using direct video ID mode", "in": "path", "name": "postId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "description": "New SEO-optimized description", "platform": "youtube", "tags": [ "seo", "marketing", "tutorial" ], "title": "Updated Video Title" }, "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "categoryId": { "description": "YouTube video category ID", "type": "string" }, "containsSyntheticMedia": { "description": "AI-generated content disclosure. Set true if the video contains synthetic content that could be mistaken for real. YouTube may add a label.", "type": "boolean" }, "description": { "description": "New video description", "type": "string" }, "madeForKids": { "description": "COPPA compliance flag. Set true for child-directed content (restricts comments, notifications, ad targeting).", "type": "boolean" }, "platform": { "description": "The platform to update metadata on", "enum": [ "youtube" ], "type": "string" }, "playlistId": { "description": "YouTube playlist ID to add the video to (e.g. 'PLxxxxxxxxxxxxx'). Use GET /apis/v1/social/accounts/{id}/youtube-playlists to list available playlists. Only playlists owned by the channel are supported.", "type": "string" }, "privacyStatus": { "description": "Video privacy setting", "enum": [ "public", "private", "unlisted" ], "type": "string" }, "tags": { "description": "Array of keyword tags (max 500 characters combined for YouTube)", "items": { "maxLength": 100, "type": "string" }, "type": "array" }, "thumbnailUrl": { "description": "Public URL of a custom thumbnail image (JPEG, PNG, or GIF, max 50 MB, recommended 1280x720). Works on any video you own, including videos not published through AIsa. The channel must be verified (phone verification) to set custom thumbnails.\n\n**Errors:**\n\n- 400 with the reason, no field updated: YouTube refuses the thumbnail (e.g. channel without the custom-thumbnail permission, video not owned by the connected channel), or the image URL cannot be fetched or has an unsupported format or size.\n- 429: YouTube thumbnail rate limit (uploadRateLimitExceeded). Retry later, not immediately, because retries keep the channel over its limit.\n- 500: any other temporary YouTube or network failure; can be retried.", "format": "uri", "type": "string" }, "title": { "description": "New video title (max 100 characters for YouTube)", "maxLength": 100, "type": "string" }, "videoId": { "description": "YouTube video ID (required for direct mode, ignored for post-based mode)", "type": "string" } }, "required": [ "platform" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "success": { "type": "boolean" }, "updatedFields": { "items": { "type": "string" }, "type": "array" }, "videoId": { "description": "Only present in direct video ID mode", "type": "string" } }, "type": "object" } } }, "description": "Metadata updated successfully" }, "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." } }, "summary": "Update post metadata", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.posts.update_post_metadata@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "e5cbb6eb81f1e74e248fbe17499c7caa302b681a436d26a44269df4c85af6bef" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_posts_postid_upda_cf80eb", "method": "POST", "path": "/apis/v1/social/posts/{postId}/update-metadata" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_posts_postid_upda_cf80eb" } }, "/apis/v1/social/profiles": { "get": { "description": "Lists the caller's profiles. A default profile is created on first use.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_profiles", "parameters": [ { "description": "Page size, default 20.", "in": "query", "name": "limit", "required": false, "schema": { "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque cursor from the previous page's nextCursor.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "accountCount": { "type": [ "integer", "null" ] }, "createdAt": { "format": "date-time", "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "isDefault": { "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "nextCursor": { "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Success" }, "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." } }, "summary": "List profiles", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.profiles.list@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "This operation does not settle a customer usage charge.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "9f7e0b76d5b86ea5a9c142601a6281098f30c7873f5d99a999cdc95d84d338a5" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_profiles", "method": "GET", "path": "/apis/v1/social/profiles" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_profiles" }, "post": { "description": "Creates a profile. Requires a key that is not restricted to specific profiles.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_profiles", "requestBody": { "content": { "application/json": { "example": { "description": "Accounts for the spring campaign", "name": "Spring launch" }, "schema": { "additionalProperties": false, "properties": { "description": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "accountCount": { "type": [ "integer", "null" ] }, "createdAt": { "format": "date-time", "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "isDefault": { "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Success" }, "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." } }, "summary": "Create a profile", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.profiles.create@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "This operation does not settle a customer usage charge.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "8a5c659cb845e0236c20baf6674236f773f21d6ea830f261540a53a8ae335889" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_profiles", "method": "POST", "path": "/apis/v1/social/profiles" }, "x-codeSamples": [ { "lang": "text", "label": "Reference example", "source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/social/profiles \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"description\": \"Accounts for the spring campaign\",\n \"name\": \"Spring launch\"\n}'" } ], "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_profiles" } }, "/apis/v1/social/profiles/{profileId}": { "delete": { "description": "Deletes an empty profile. Returns 409 profile_not_empty while it still has connected accounts.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "delete_aisa_social_apis_v1_social_profiles_profileid", "parameters": [ { "in": "path", "name": "profileId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "accountCount": { "type": [ "integer", "null" ] }, "createdAt": { "format": "date-time", "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "isDefault": { "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Success" }, "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." } }, "summary": "Delete a profile", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.profiles.delete@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "This operation does not settle a customer usage charge.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "7ba80d4ed1b850e0178651ecf3a5a890a4715254bd5482c90238a5dc8f3ce304" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "delete_aisa_social_apis_v1_social_profiles_profileid", "method": "DELETE", "path": "/apis/v1/social/profiles/{profileId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/delete_aisa_social_apis_v1_social_profiles_profileid" }, "get": { "description": "\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_profiles_profileid", "parameters": [ { "in": "path", "name": "profileId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "accountCount": { "type": [ "integer", "null" ] }, "createdAt": { "format": "date-time", "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "isDefault": { "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Success" }, "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." } }, "summary": "Get a profile", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.profiles.get@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "This operation does not settle a customer usage charge.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "7c106ef3fe070649c2c43931d914f9152a194d301c14e8c046a657476fbb5fcb" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_profiles_profileid", "method": "GET", "path": "/apis/v1/social/profiles/{profileId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_profiles_profileid" }, "put": { "description": "\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "put_aisa_social_apis_v1_social_profiles_profileid", "parameters": [ { "in": "path", "name": "profileId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "name": "Spring launch 2026" }, "schema": { "additionalProperties": false, "properties": { "description": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "accountCount": { "type": [ "integer", "null" ] }, "createdAt": { "format": "date-time", "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "isDefault": { "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Success" }, "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." } }, "summary": "Update a profile", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.profiles.update@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "This operation does not settle a customer usage charge.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "5e4df1630a7e7fb47692c0d205391c8149e5f8629b48bcb90b5783074ee94ec2" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "put_aisa_social_apis_v1_social_profiles_profileid", "method": "PUT", "path": "/apis/v1/social/profiles/{profileId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/put_aisa_social_apis_v1_social_profiles_profileid" } }, "/apis/v1/social/public/accounts/{platform}/{handle}": { "get": { "description": "handle is case-insensitive and without @. YouTube also accepts a channel id.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_public_accounts_pl_199b86", "parameters": [ { "in": "path", "name": "platform", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "handle", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "avatarUrl": { "type": [ "string", "null" ] }, "bio": { "type": [ "string", "null" ] }, "displayName": { "type": [ "string", "null" ] }, "followersCount": { "type": [ "integer", "null" ] }, "followingCount": { "type": [ "integer", "null" ] }, "handle": { "type": [ "string", "null" ] }, "platform": { "enum": [ "tiktok", "instagram", "twitter", "youtube", "facebook", "linkedin", "pinterest", "threads", "reddit", "googlebusiness", "googleanalytics", "bluesky", "telegram", "slack", "snapchat", "hubspot", "microsoft", null ], "type": [ "string", "null" ] }, "platformAccountId": { "type": [ "string", "null" ] }, "postsCount": { "type": [ "integer", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "provenance": { "properties": { "fetchedAt": { "format": "date-time", "type": [ "string", "null" ] }, "origin": { "enum": [ "connected", "public", "customer", null ], "type": [ "string", "null" ] }, "precision": { "enum": [ "exact", "rounded", null ], "type": [ "string", "null" ] }, "valueType": { "enum": [ "reported", "observed", "estimated", null ], "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "verified": { "type": [ "boolean", "null" ] } }, "type": "object" } } }, "description": "Success" }, "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." } }, "summary": "Get a public account", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.public.account.get@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "No price is published for this operation yet; calls answer as unavailable until backend-service resource anchors publishes its price anchor.", "kind": "unpriced" }, "x-aisa-revision": { "handler_contract_hash": "26e43d2750dee018a9f7f70296a4ed61851efde8253ba622840aebc09f505e6c" }, "x-aisa-status": "disabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_public_accounts_pl_199b86", "method": "GET", "path": "/apis/v1/social/public/accounts/{platform}/{handle}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_public_accounts_pl_199b86" } }, "/apis/v1/social/public/accounts/{platform}/{handle}/posts": { "get": { "description": "\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_public_accounts_pl_2a50bc", "parameters": [ { "description": "Page size, default 20.", "in": "query", "name": "limit", "required": false, "schema": { "maximum": 50, "minimum": 1, "type": "integer" } }, { "description": "Opaque cursor; returns cursor_expired after 24 hours or when the data source changed.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "in": "path", "name": "platform", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "handle", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "analytics": { "properties": { "comments": { "type": [ "integer", "null" ] }, "likes": { "type": [ "integer", "null" ] }, "saves": { "type": [ "integer", "null" ] }, "shares": { "type": [ "integer", "null" ] }, "views": { "type": [ "integer", "null" ] } }, "type": [ "object", "null" ] }, "authorHandle": { "type": [ "string", "null" ] }, "content": { "type": [ "string", "null" ] }, "mediaType": { "type": [ "string", "null" ] }, "platform": { "enum": [ "tiktok", "instagram", "twitter", "youtube", "facebook", "linkedin", "pinterest", "threads", "reddit", "googlebusiness", "googleanalytics", "bluesky", "telegram", "slack", "snapchat", "hubspot", "microsoft", null ], "type": [ "string", "null" ] }, "platformPostId": { "type": [ "string", "null" ] }, "platformPostUrl": { "type": [ "string", "null" ] }, "provenance": { "properties": { "fetchedAt": { "format": "date-time", "type": [ "string", "null" ] }, "origin": { "enum": [ "connected", "public", "customer", null ], "type": [ "string", "null" ] }, "precision": { "enum": [ "exact", "rounded", null ], "type": [ "string", "null" ] }, "valueType": { "enum": [ "reported", "observed", "estimated", null ], "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "publishedAt": { "format": "date-time", "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "nextCursor": { "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Success" }, "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." } }, "summary": "List a public account's posts", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.public.account.posts.query@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "No price is published for this operation yet; calls answer as unavailable until backend-service resource anchors publishes its price anchor.", "kind": "unpriced" }, "x-aisa-revision": { "handler_contract_hash": "b6f1d03b3873ec888839f3ac3f2c0418c1dd8713bc4860c1282a34cec458fe72" }, "x-aisa-status": "disabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_public_accounts_pl_2a50bc", "method": "GET", "path": "/apis/v1/social/public/accounts/{platform}/{handle}/posts" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_public_accounts_pl_2a50bc" } }, "/apis/v1/social/public/posts/{platform}/{platformPostId}": { "get": { "description": "Instagram accepts both shortcode and numeric media id.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_public_posts_platf_f6f300", "parameters": [ { "in": "path", "name": "platform", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "platformPostId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "analytics": { "properties": { "comments": { "type": [ "integer", "null" ] }, "likes": { "type": [ "integer", "null" ] }, "saves": { "type": [ "integer", "null" ] }, "shares": { "type": [ "integer", "null" ] }, "views": { "type": [ "integer", "null" ] } }, "type": [ "object", "null" ] }, "authorHandle": { "type": [ "string", "null" ] }, "content": { "type": [ "string", "null" ] }, "mediaType": { "type": [ "string", "null" ] }, "platform": { "enum": [ "tiktok", "instagram", "twitter", "youtube", "facebook", "linkedin", "pinterest", "threads", "reddit", "googlebusiness", "googleanalytics", "bluesky", "telegram", "slack", "snapchat", "hubspot", "microsoft", null ], "type": [ "string", "null" ] }, "platformPostId": { "type": [ "string", "null" ] }, "platformPostUrl": { "type": [ "string", "null" ] }, "provenance": { "properties": { "fetchedAt": { "format": "date-time", "type": [ "string", "null" ] }, "origin": { "enum": [ "connected", "public", "customer", null ], "type": [ "string", "null" ] }, "precision": { "enum": [ "exact", "rounded", null ], "type": [ "string", "null" ] }, "valueType": { "enum": [ "reported", "observed", "estimated", null ], "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "publishedAt": { "format": "date-time", "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Success" }, "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." } }, "summary": "Get a public post", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.public.post.get@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "No price is published for this operation yet; calls answer as unavailable until backend-service resource anchors publishes its price anchor.", "kind": "unpriced" }, "x-aisa-revision": { "handler_contract_hash": "5aa0bee4772cac03de712fc854f778b38471bb25da1ea2da24160eac89cf75eb" }, "x-aisa-status": "disabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_public_posts_platf_f6f300", "method": "GET", "path": "/apis/v1/social/public/posts/{platform}/{platformPostId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_public_posts_platf_f6f300" } }, "/apis/v1/social/queue/next-slot": { "get": { "description": "Queue. 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.\n\nReturns the next available queue slot for preview purposes. To create a queue post, use POST /apis/v1/social/posts with queuedFromProfile instead of scheduledFor.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_queue_next_slot", "parameters": [ { "description": "One of your profiles (prf_...).", "in": "query", "name": "profileId", "required": true, "schema": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Specific queue ID (optional, defaults to profile's default queue)", "in": "query", "name": "queueId", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "nextSlot": { "format": "date-time", "type": "string" }, "profileId": { "description": "One of your profiles (prf_...).", "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" }, "queueId": { "description": "Queue ID this slot belongs to", "type": "string" }, "queueName": { "description": "Queue name", "type": "string" }, "timezone": { "type": "string" } }, "type": "object" } } }, "description": "Next available slot" }, "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." } }, "summary": "Get next available slot", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.queue.get_next_queue_slot@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "4a2ca4af77b3a5b1ac77bd035907cf24452e920376f98252f784cb1160891bfa" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_queue_next_slot", "method": "GET", "path": "/apis/v1/social/queue/next-slot" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_queue_next_slot" } }, "/apis/v1/social/queue/preview": { "get": { "description": "Queue. 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.\n\nReturns the next N upcoming queue slot times for a profile as ISO datetime strings.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_queue_preview", "parameters": [ { "description": "One of your profiles (prf_...).", "in": "query", "name": "profileId", "required": true, "schema": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Filter by specific queue ID. Omit to use the default queue.", "in": "query", "name": "queueId", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "count", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "count": { "type": "integer" }, "profileId": { "description": "One of your profiles (prf_...).", "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" }, "queueId": { "type": "string" }, "queueName": { "type": "string" }, "slots": { "items": { "format": "date-time", "type": "string" }, "type": "array" } }, "type": "object" } } }, "description": "Queue slots preview" }, "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." } }, "summary": "Preview upcoming slots", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.queue.preview_queue@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "3787e93e559490c8038457f3e106d262225f3fbbb81bd70c6ef88fd3ec3962a3" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_queue_preview", "method": "GET", "path": "/apis/v1/social/queue/preview" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_queue_preview" } }, "/apis/v1/social/queue/slots": { "delete": { "description": "Queue. 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.\n\nDelete a queue from a profile. Pass queueId to delete a specific queue;\nomit it to delete all queues for the profile.\nIf deleting the default queue, another queue will be promoted to default.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "delete_aisa_social_apis_v1_social_queue_slots", "parameters": [ { "description": "One of your profiles (prf_...).", "in": "query", "name": "profileId", "required": true, "schema": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Queue ID to delete. Omit to delete all queues for the profile", "in": "query", "name": "queueId", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "type": "boolean" }, "deletedCount": { "type": "integer" }, "message": { "type": "string" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Queue schedule deleted" }, "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." } }, "summary": "Delete schedule", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.queue.delete_queue_slot@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "7fbe5992c35441b974e180fb8c8c03101c70bf2e49bc5d21d833a23cfd39aa0d" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "delete_aisa_social_apis_v1_social_queue_slots", "method": "DELETE", "path": "/apis/v1/social/queue/slots" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/delete_aisa_social_apis_v1_social_queue_slots" }, "get": { "description": "Queue. 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.\n\nReturns queue schedules for a profile. Use all=true for all queues, or queueId for a specific one. Defaults to the default queue.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_queue_slots", "parameters": [ { "description": "One of your profiles (prf_...).", "in": "query", "name": "profileId", "required": true, "schema": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Specific queue ID to retrieve (optional)", "in": "query", "name": "queueId", "required": false, "schema": { "type": "string" } }, { "description": "Set to 'true' to list all queues for the profile", "in": "query", "name": "all", "required": false, "schema": { "enum": [ "true", "false" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "description": "Single queue response (default behavior)", "properties": { "exists": { "type": "boolean" }, "nextSlots": { "items": { "format": "date-time", "type": "string" }, "type": "array" }, "schedule": { "properties": { "_id": { "description": "Unique queue identifier", "type": "string" }, "active": { "description": "Whether the queue is active", "type": "boolean" }, "createdAt": { "format": "date-time", "type": "string" }, "isDefault": { "description": "Whether this is the default queue for the profile (used when no queueId specified)", "type": "boolean" }, "name": { "description": "Queue name (e.g., \"Morning Posts\", \"Evening Content\")", "type": "string" }, "profileId": { "description": "One of your profiles (prf_...).", "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" }, "slots": { "items": { "properties": { "dayOfWeek": { "description": "Day of week (0=Sunday, 6=Saturday)", "maximum": 6, "minimum": 0, "type": "integer" }, "time": { "description": "Time in HH:mm format (24-hour)", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "type": "string" } }, "type": "object" }, "type": "array" }, "timezone": { "description": "IANA timezone (e.g., America/New_York)", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "type": "object" } }, "type": "object" }, { "description": "All queues response (when all=true)", "properties": { "count": { "type": "integer" }, "queues": { "items": { "properties": { "_id": { "description": "Unique queue identifier", "type": "string" }, "active": { "description": "Whether the queue is active", "type": "boolean" }, "createdAt": { "format": "date-time", "type": "string" }, "isDefault": { "description": "Whether this is the default queue for the profile (used when no queueId specified)", "type": "boolean" }, "name": { "description": "Queue name (e.g., \"Morning Posts\", \"Evening Content\")", "type": "string" }, "profileId": { "description": "One of your profiles (prf_...).", "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" }, "slots": { "items": { "properties": { "dayOfWeek": { "description": "Day of week (0=Sunday, 6=Saturday)", "maximum": 6, "minimum": 0, "type": "integer" }, "time": { "description": "Time in HH:mm format (24-hour)", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "type": "string" } }, "type": "object" }, "type": "array" }, "timezone": { "description": "IANA timezone (e.g., America/New_York)", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } ] } } }, "description": "Queue schedule(s) retrieved" }, "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." } }, "summary": "List schedules", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.queue.list_queue_slots@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "0ed8913bb343a8ba0bdd8fb058fcefd77a4c7cc65f7fec1057d480b94f71e5a9" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_queue_slots", "method": "GET", "path": "/apis/v1/social/queue/slots" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_queue_slots" }, "post": { "description": "Queue. 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.\n\nCreate an additional queue for a profile. The first queue created becomes the default.\nSubsequent queues are non-default unless explicitly set.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_queue_slots", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "active": true, "name": "Evening Posts", "profileId": "prf_2Bn8Wq5Td1Yh7Kc3Mz9Lp4", "slots": [ { "dayOfWeek": 1, "time": "18:00" }, { "dayOfWeek": 3, "time": "18:00" }, { "dayOfWeek": 5, "time": "18:00" } ], "timezone": "America/New_York" }, "schema": { "properties": { "active": { "default": true, "type": "boolean" }, "name": { "description": "Queue name (e.g., Evening Posts)", "type": "string" }, "profileId": { "description": "One of your profiles (prf_...).", "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" }, "slots": { "items": { "properties": { "dayOfWeek": { "description": "Day of week (0=Sunday, 6=Saturday)", "maximum": 6, "minimum": 0, "type": "integer" }, "time": { "description": "Time in HH:mm format (24-hour)", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "type": "string" } }, "type": "object" }, "type": "array" }, "timezone": { "description": "IANA timezone", "type": "string" } }, "required": [ "name", "profileId", "slots", "timezone" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "nextSlots": { "items": { "format": "date-time", "type": "string" }, "type": "array" }, "schedule": { "properties": { "_id": { "description": "Unique queue identifier", "type": "string" }, "active": { "description": "Whether the queue is active", "type": "boolean" }, "createdAt": { "format": "date-time", "type": "string" }, "isDefault": { "description": "Whether this is the default queue for the profile (used when no queueId specified)", "type": "boolean" }, "name": { "description": "Queue name (e.g., \"Morning Posts\", \"Evening Content\")", "type": "string" }, "profileId": { "description": "One of your profiles (prf_...).", "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" }, "slots": { "items": { "properties": { "dayOfWeek": { "description": "Day of week (0=Sunday, 6=Saturday)", "maximum": 6, "minimum": 0, "type": "integer" }, "time": { "description": "Time in HH:mm format (24-hour)", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "type": "string" } }, "type": "object" }, "type": "array" }, "timezone": { "description": "IANA timezone (e.g., America/New_York)", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Queue created" }, "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." } }, "summary": "Create schedule", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.queue.create_queue_slot@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "9c7c11eecfa64625100743aee38139c99dd3a8de5fd252b6818670ed0582ccb0" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_queue_slots", "method": "POST", "path": "/apis/v1/social/queue/slots" }, "x-codeSamples": [ { "lang": "text", "label": "Reference example", "source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/social/queue/slots \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"active\": true,\n \"name\": \"Evening Posts\",\n \"profileId\": \"prf_2Bn8Wq5Td1Yh7Kc3Mz9Lp4\",\n \"slots\": [\n {\n \"dayOfWeek\": 1,\n \"time\": \"18:00\"\n },\n {\n \"dayOfWeek\": 3,\n \"time\": \"18:00\"\n },\n {\n \"dayOfWeek\": 5,\n \"time\": \"18:00\"\n }\n ],\n \"timezone\": \"America/New_York\"\n}'" } ], "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_queue_slots" }, "put": { "description": "Queue. 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.\n\nCreate a new queue or update an existing one. Without queueId, creates/updates the default queue. With queueId, updates a specific queue. With setAsDefault=true, makes this queue the default for the profile.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "put_aisa_social_apis_v1_social_queue_slots", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "active": true, "name": "Morning Posts", "profileId": "prf_2Bn8Wq5Td1Yh7Kc3Mz9Lp4", "queueId": "", "setAsDefault": false, "slots": [ { "dayOfWeek": 1, "time": "09:00" }, { "dayOfWeek": 3, "time": "09:00" }, { "dayOfWeek": 5, "time": "10:00" } ], "timezone": "America/New_York" }, "schema": { "properties": { "active": { "default": true, "type": "boolean" }, "name": { "description": "Queue name", "type": "string" }, "profileId": { "description": "One of your profiles (prf_...).", "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" }, "queueId": { "description": "Queue ID to update (optional)", "type": "string" }, "reshuffleExisting": { "default": false, "description": "Whether to reschedule existing queued posts to match new slots", "type": "boolean" }, "setAsDefault": { "description": "Make this queue the default", "type": "boolean" }, "slots": { "items": { "properties": { "dayOfWeek": { "description": "Day of week (0=Sunday, 6=Saturday)", "maximum": 6, "minimum": 0, "type": "integer" }, "time": { "description": "Time in HH:mm format (24-hour)", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "type": "string" } }, "type": "object" }, "type": "array" }, "timezone": { "type": "string" } }, "required": [ "profileId", "slots", "timezone" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "isNewQueue": { "type": "boolean" }, "nextSlots": { "items": { "format": "date-time", "type": "string" }, "type": "array" }, "reshuffledCount": { "type": "integer" }, "schedule": { "properties": { "_id": { "description": "Unique queue identifier", "type": "string" }, "active": { "description": "Whether the queue is active", "type": "boolean" }, "createdAt": { "format": "date-time", "type": "string" }, "isDefault": { "description": "Whether this is the default queue for the profile (used when no queueId specified)", "type": "boolean" }, "name": { "description": "Queue name (e.g., \"Morning Posts\", \"Evening Content\")", "type": "string" }, "profileId": { "description": "One of your profiles (prf_...).", "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" }, "slots": { "items": { "properties": { "dayOfWeek": { "description": "Day of week (0=Sunday, 6=Saturday)", "maximum": 6, "minimum": 0, "type": "integer" }, "time": { "description": "Time in HH:mm format (24-hour)", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "type": "string" } }, "type": "object" }, "type": "array" }, "timezone": { "description": "IANA timezone (e.g., America/New_York)", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "type": "object" }, "skippedDailyLimit": { "type": "integer" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Queue schedule 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": { "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." } }, "summary": "Update schedule", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.queue.update_queue_slot@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "94bbe8b544ab8c18bc0fa91f044050fbe906f369c92166c2e66b8aa81171ad40" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "put_aisa_social_apis_v1_social_queue_slots", "method": "PUT", "path": "/apis/v1/social/queue/slots" }, "x-codeSamples": [ { "lang": "text", "label": "Reference example", "source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request PUT \\\n --url https://api.aisa.one/apis/v1/social/queue/slots \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"active\": true,\n \"name\": \"Morning Posts\",\n \"profileId\": \"prf_2Bn8Wq5Td1Yh7Kc3Mz9Lp4\",\n \"queueId\": \"\",\n \"setAsDefault\": false,\n \"slots\": [\n {\n \"dayOfWeek\": 1,\n \"time\": \"09:00\"\n },\n {\n \"dayOfWeek\": 3,\n \"time\": \"09:00\"\n },\n {\n \"dayOfWeek\": 5,\n \"time\": \"10:00\"\n }\n ],\n \"timezone\": \"America/New_York\"\n}'" } ], "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/put_aisa_social_apis_v1_social_queue_slots" } }, "/apis/v1/social/reddit/comments/{postId}": { "get": { "description": "Reddit Search. 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.\n\nTemporarily unavailable: Reddit has blocked third-party apps from its API, so this endpoint returns 503 `PLATFORM_DISABLED` until Reddit restores access. Reddit Ads is not affected.\n\nReads the comments of any Reddit post the connected account can see, for example one found through `/apis/v1/social/reddit/feed` or `/apis/v1/social/reddit/search`, straight from Reddit on every call.\n\n### Thread shape\n\n- The tree comes flattened in thread order (a reply follows its parent).\n- Rebuild it from `parentId`, which is `t3_…` for a reply to the post and `t1_…` for a reply to a comment.\n- Deleted and removed comments are passed through as Reddit sends them (`[deleted]` / `[removed]`).\n- Where Reddit truncates a thread, the ids it left out are listed in `more`. `commentId` fetches one such comment with its replies.\n\n### Errors\n\n- 404 `platform_api_error`: Reddit no longer serves the post.\n- 403 `platform_api_error`: the subreddit is private.\n\nFor comments on posts published through AIsa, `/apis/v1/social/inbox/comments/{postId}` adds caching, moderation and replies.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_reddit_comments_postid", "parameters": [ { "description": "Reddit post id, with or without the `t3_` prefix (as `id` or `fullname` on RedditPost).", "in": "path", "name": "postId", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "default": "new", "enum": [ "new", "top", "best", "controversial", "old", "qa" ], "type": "string" } }, { "description": "Maximum number of top-level comments.", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "type": "integer" } }, { "description": "Return only this comment and its replies, with or without the `t1_` prefix; pass an id from `more` to expand it.", "in": "query", "name": "commentId", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "items": { "items": { "description": "One comment of a Reddit thread as returned by GET /apis/v1/social/reddit/comments/{postId}; the list is flat and in thread order", "properties": { "author": { "description": "The username, or [deleted]", "type": "string" }, "body": { "description": "Comment text as written (Markdown, not HTML-escaped), or [deleted] / [removed]", "type": "string" }, "createdUtc": { "description": "Unix timestamp of the comment", "type": "number" }, "depth": { "description": "0 for a top-level comment of this response, 1 for a reply to it, and so on", "type": "integer" }, "distinguished": { "description": "\"moderator\" or \"admin\" when the comment is distinguished, else null", "type": [ "string", "null" ] }, "edited": { "type": "boolean" }, "fullname": { "description": "Reddit fullname (e.g. t1_abc123)", "type": "string" }, "id": { "description": "Reddit comment ID (without type prefix)", "type": "string" }, "isSubmitter": { "description": "Whether the author is the post's author", "type": "boolean" }, "numReplies": { "description": "Direct replies included in this response; replies Reddit left out are listed in more", "type": "integer" }, "parentId": { "description": "Fullname of what the comment answers: the post (t3_…) or a parent comment (t1_…)", "type": "string" }, "permalink": { "description": "Full permalink to the comment", "type": "string" }, "score": { "type": "integer" }, "stickied": { "type": "boolean" } }, "type": "object" }, "type": "array" }, "more": { "description": "Ids of comments Reddit left out of this page, at any depth.", "items": { "type": "string" }, "type": "array" }, "post": { "description": "The post header; null when Reddit omits it (deleted post).", "oneOf": [ { "description": "A normalized Reddit post returned by the feed and search endpoints", "properties": { "author": { "type": "string" }, "createdUtc": { "description": "Unix timestamp of post creation", "type": "number" }, "flairText": { "description": "Link flair text if set", "type": [ "string", "null" ] }, "fullname": { "description": "Reddit fullname (e.g. t3_abc123)", "type": "string" }, "galleryImages": { "description": "Individual image URLs for gallery posts (only present when isGallery is true)", "items": { "format": "uri", "type": "string" }, "type": "array" }, "id": { "description": "Reddit post ID (without type prefix)", "type": "string" }, "isGallery": { "description": "Whether the post is a gallery with multiple images", "type": "boolean" }, "numComments": { "type": "integer" }, "over18": { "description": "Whether the post is marked NSFW", "type": "boolean" }, "permalink": { "description": "Full permalink to the Reddit post", "type": "string" }, "score": { "type": "integer" }, "selftext": { "description": "Self-post body text (empty string for link posts)", "type": "string" }, "stickied": { "type": "boolean" }, "subreddit": { "type": "string" }, "title": { "type": "string" }, "url": { "description": "Post URL (may be a gallery URL, external link, or self-post URL)", "type": "string" } }, "type": "object" }, { "type": "null" } ] } }, "type": "object" } } }, "description": "The post and its comments" }, "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." } }, "summary": "Get the comments of a Reddit post", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.reddit_search.get_reddit_post_comments@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "daf4016654b8ee2f307109dfc0a1f3f162d4e2022b7f1828abe16235295f8cf7" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_reddit_comments_postid", "method": "GET", "path": "/apis/v1/social/reddit/comments/{postId}" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_reddit_comments_postid" } }, "/apis/v1/social/reddit/feed": { "get": { "description": "Reddit Search. 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.\n\nTemporarily unavailable: Reddit has blocked third-party apps from its API, so this endpoint returns 503 `PLATFORM_DISABLED` until Reddit restores access. Reddit Ads is not affected.\n\nFetch posts from a subreddit feed. Supports sorting, time filtering, and cursor-based pagination.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_reddit_feed", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "in": "query", "name": "subreddit", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "default": "hot", "enum": [ "hot", "new", "top", "rising" ], "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "type": "integer" } }, { "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "t", "required": false, "schema": { "enum": [ "hour", "day", "week", "month", "year", "all" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "items": { "items": { "description": "A normalized Reddit post returned by the feed and search endpoints", "properties": { "author": { "type": "string" }, "createdUtc": { "description": "Unix timestamp of post creation", "type": "number" }, "flairText": { "description": "Link flair text if set", "type": [ "string", "null" ] }, "fullname": { "description": "Reddit fullname (e.g. t3_abc123)", "type": "string" }, "galleryImages": { "description": "Individual image URLs for gallery posts (only present when isGallery is true)", "items": { "format": "uri", "type": "string" }, "type": "array" }, "id": { "description": "Reddit post ID (without type prefix)", "type": "string" }, "isGallery": { "description": "Whether the post is a gallery with multiple images", "type": "boolean" }, "numComments": { "type": "integer" }, "over18": { "description": "Whether the post is marked NSFW", "type": "boolean" }, "permalink": { "description": "Full permalink to the Reddit post", "type": "string" }, "score": { "type": "integer" }, "selftext": { "description": "Self-post body text (empty string for link posts)", "type": "string" }, "stickied": { "type": "boolean" }, "subreddit": { "type": "string" }, "title": { "type": "string" }, "url": { "description": "Post URL (may be a gallery URL, external link, or self-post URL)", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Feed items" }, "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." } }, "summary": "Get subreddit feed", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.reddit_search.get_reddit_feed@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "e2ac13c80c8d985b6da127ff0caee6a9f10502c39f0456329f2fbd666c9798dd" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_reddit_feed", "method": "GET", "path": "/apis/v1/social/reddit/feed" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_reddit_feed" } }, "/apis/v1/social/reddit/search": { "get": { "description": "Reddit Search. 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.\n\nTemporarily unavailable: Reddit has blocked third-party apps from its API, so this endpoint returns 503 `PLATFORM_DISABLED` until Reddit restores access. Reddit Ads is not affected.\n\nSearch Reddit posts using a connected account. Optionally scope to a specific subreddit.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_reddit_search", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "in": "query", "name": "subreddit", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "q", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "restrict_sr", "required": false, "schema": { "enum": [ "0", "1" ], "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "default": "new", "enum": [ "relevance", "hot", "top", "new", "comments" ], "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "type": "integer" } }, { "in": "query", "name": "after", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "items": { "items": { "description": "A normalized Reddit post returned by the feed and search endpoints", "properties": { "author": { "type": "string" }, "createdUtc": { "description": "Unix timestamp of post creation", "type": "number" }, "flairText": { "description": "Link flair text if set", "type": [ "string", "null" ] }, "fullname": { "description": "Reddit fullname (e.g. t3_abc123)", "type": "string" }, "galleryImages": { "description": "Individual image URLs for gallery posts (only present when isGallery is true)", "items": { "format": "uri", "type": "string" }, "type": "array" }, "id": { "description": "Reddit post ID (without type prefix)", "type": "string" }, "isGallery": { "description": "Whether the post is a gallery with multiple images", "type": "boolean" }, "numComments": { "type": "integer" }, "over18": { "description": "Whether the post is marked NSFW", "type": "boolean" }, "permalink": { "description": "Full permalink to the Reddit post", "type": "string" }, "score": { "type": "integer" }, "selftext": { "description": "Self-post body text (empty string for link posts)", "type": "string" }, "stickied": { "type": "boolean" }, "subreddit": { "type": "string" }, "title": { "type": "string" }, "url": { "description": "Post URL (may be a gallery URL, external link, or self-post URL)", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Search results" }, "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." } }, "summary": "Search posts", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.reddit_search.search_reddit@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "fbdd814606f48a1423e15684ca44df878aecc613b86bdbbb1faf8d759c6d5b85" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_reddit_search", "method": "GET", "path": "/apis/v1/social/reddit/search" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_reddit_search" } }, "/apis/v1/social/tools/validate/media": { "post": { "description": "\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_tools_validate_media", "requestBody": { "content": { "application/json": { "example": { "mediaId": "med_5Tc8Hn2Wq7Lx3Bv9Kd4Fr6", "platforms": [ "tiktok", "instagram" ] }, "schema": { "additionalProperties": false, "properties": { "mediaId": { "pattern": "^med_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "platforms": { "items": { "type": [ "string", "null" ] }, "type": [ "array", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "issues": { "items": { "properties": { "accountId": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "code": { "type": [ "string", "null" ] }, "field": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "platform": { "enum": [ "tiktok", "instagram", "twitter", "youtube", "facebook", "linkedin", "pinterest", "threads", "reddit", "googlebusiness", "googleanalytics", "bluesky", "telegram", "slack", "snapchat", "hubspot", "microsoft", null ], "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "valid": { "type": [ "boolean", "null" ] } }, "type": "object" } } }, "description": "Success" }, "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." } }, "summary": "Validate media for platforms", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.tools.validate_media@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "This operation does not settle a customer usage charge.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "e8b3ee05d0bd1a4f17a5461b09f5676b1e95866055f03785e49bc34301e7c27a" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_tools_validate_media", "method": "POST", "path": "/apis/v1/social/tools/validate/media" }, "x-codeSamples": [ { "lang": "text", "label": "Reference example", "source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/social/tools/validate/media \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"mediaId\": \"med_5Tc8Hn2Wq7Lx3Bv9Kd4Fr6\",\n \"platforms\": [\n \"tiktok\",\n \"instagram\"\n ]\n}'" } ], "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_tools_validate_media" } }, "/apis/v1/social/tools/validate/post": { "post": { "description": "Runs every structural and platform check that POST /posts would run, without creating anything.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_tools_validate_post", "requestBody": { "content": { "application/json": { "example": { "content": "Our spring collection is live.", "mediaItems": [ { "mediaId": "med_5Tc8Hn2Wq7Lx3Bv9Kd4Fr6", "type": "video" } ], "platforms": [ { "accountId": "acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3", "platform": "tiktok", "platformSpecificData": { "privacyLevel": "PUBLIC_TO_EVERYONE" } } ], "profileId": "prf_2Bn8Wq5Td1Yh7Kc3Mz9Lp4", "scheduledFor": "2026-11-20T15:00:00Z", "timezone": "America/New_York" }, "schema": { "additionalProperties": false, "properties": { "content": { "type": [ "string", "null" ] }, "isDraft": { "type": [ "boolean", "null" ] }, "mediaItems": { "items": { "additionalProperties": false, "properties": { "altText": { "type": [ "string", "null" ] }, "mediaId": { "pattern": "^med_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "platforms": { "items": { "additionalProperties": false, "allOf": [ { "if": { "properties": { "platform": { "enum": [ "tiktok" ] } }, "required": [ "platform" ] }, "then": { "properties": { "platformSpecificData": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "description": "Required to schedule or publish: privacyLevel, allowComment. Also required for video: allowDuet, allowStitch. Must be true, from the user: contentPreviewConfirmed, expressConsentGiven.", "properties": { "allowComment": { "description": "Allow comments. Must be false when creator-info reports commentDisabled.", "type": "boolean" }, "allowDuet": { "description": "Allow duets; required for video. Must be false when creator-info reports duetDisabled.", "type": "boolean" }, "allowStitch": { "description": "Allow stitches; required for video. Must be false when creator-info reports stitchDisabled.", "type": "boolean" }, "brandPartnerPromote": { "description": "Also disclose a paid partnership; only alongside commercialContentType brand_organic.", "type": "boolean" }, "commercialContentType": { "description": "Commercial content disclosure; one of commercialContentTypes from creator-info. brand_content cannot be SELF_ONLY.", "enum": [ "none", "brand_organic", "brand_content" ], "type": "string" }, "contentPreviewConfirmed": { "description": "The user previewed exactly this content. Must be true and must come from the user.", "type": "boolean" }, "description": { "description": "Long caption for photo posts.", "maxLength": 4000, "minLength": 1, "type": "string" }, "expressConsentGiven": { "description": "The user consented to posting. Must be true and must come from the user.", "type": "boolean" }, "isBrandOrganicPost": { "description": "Also disclose the creator's own brand; only alongside commercialContentType brand_content.", "type": "boolean" }, "mediaType": { "description": "Overrides the media type derived from the media items.", "enum": [ "video", "photo" ], "type": "string" }, "privacyLevel": { "description": "One of privacyLevelOptions from GET /accounts/{accountId}/tiktok/creator-info for this mediaType.", "maxLength": 64, "minLength": 1, "type": "string" }, "videoMadeWithAi": { "description": "Label the post as AI-generated.", "type": "boolean" } }, "type": "object" } ] } } } }, { "if": { "properties": { "platform": { "enum": [ "instagram" ] } }, "required": [ "platform" ] }, "then": { "properties": { "platformSpecificData": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "description": "", "properties": { "collaborators": { "description": "Up to 3 usernames to invite as collaborators (feed and Reels).", "items": { "maxLength": 64, "minLength": 1, "type": "string" }, "maxItems": 3, "type": "array" }, "contentType": { "description": "story publishes a Story.", "enum": [ "story" ], "type": "string" }, "firstComment": { "description": "First comment added after publishing (not on Stories).", "maxLength": 2200, "minLength": 1, "type": "string" }, "isAiGenerated": { "description": "Label the post as containing AI-generated media.", "type": "boolean" }, "shareToFeed": { "description": "Reels only: also show the Reel on the main feed (default true).", "type": "boolean" } }, "type": "object" } ] } } } }, { "if": { "properties": { "platform": { "enum": [ "twitter", "x" ] } }, "required": [ "platform" ] }, "then": { "properties": { "platformSpecificData": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "description": "", "properties": { "madeWithAi": { "description": "Label the post as containing AI-generated media.", "type": "boolean" }, "poll": { "additionalProperties": false, "description": "A poll; cannot be combined with media or threadItems.", "properties": { "duration_minutes": { "maximum": 10080, "minimum": 5, "type": "integer" }, "options": { "items": { "maxLength": 25, "minLength": 1, "type": "string" }, "maxItems": 4, "minItems": 2, "type": "array" } }, "required": [ "options", "duration_minutes" ], "type": "object" }, "replySettings": { "description": "Who can reply.", "enum": [ "following", "mentionedUsers", "subscribers", "verified" ], "type": "string" }, "threadItems": { "description": "The whole thread; the first item is the root post. Cannot be combined with poll.", "items": { "additionalProperties": false, "properties": { "content": { "description": "Text of this post.", "maxLength": 25000, "minLength": 1, "type": "string" } }, "required": [ "content" ], "type": "object" }, "minItems": 1, "type": "array" } }, "type": "object" } ] } } } }, { "if": { "properties": { "platform": { "enum": [ "youtube" ] } }, "required": [ "platform" ] }, "then": { "properties": { "platformSpecificData": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "description": "Required to schedule or publish: madeForKids.", "properties": { "containsSyntheticMedia": { "description": "Label the video as containing synthetic (AI-generated) content.", "type": "boolean" }, "firstComment": { "description": "First comment posted after upload.", "maxLength": 10000, "minLength": 1, "type": "string" }, "madeForKids": { "description": "COPPA: whether the video is made for kids. Required, and must be the user's explicit choice.", "type": "boolean" }, "title": { "description": "Video title.", "maxLength": 100, "minLength": 1, "type": "string" }, "visibility": { "description": "Video visibility.", "enum": [ "public", "private", "unlisted" ], "type": "string" } }, "type": "object" } ] } } } }, { "if": { "properties": { "platform": { "enum": [ "facebook" ] } }, "required": [ "platform" ] }, "then": { "properties": { "platformSpecificData": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "description": "", "properties": { "contentType": { "description": "story or reel; omitted is a feed post.", "enum": [ "story", "reel" ], "type": "string" }, "firstComment": { "description": "First comment added after publishing (not on stories).", "maxLength": 8000, "minLength": 1, "type": "string" }, "pageId": { "description": "Page to post to when the account manages several.", "maxLength": 64, "minLength": 1, "type": "string" } }, "type": "object" } ] } } } }, { "if": { "properties": { "platform": { "enum": [ "linkedin" ] } }, "required": [ "platform" ] }, "then": { "properties": { "platformSpecificData": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "description": "linkedin accepts no platformSpecificData yet.", "properties": {}, "type": "object" } ] } } } }, { "if": { "properties": { "platform": { "enum": [ "pinterest" ] } }, "required": [ "platform" ] }, "then": { "properties": { "platformSpecificData": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "description": "", "properties": { "isAiGenerated": { "description": "Label the Pin as AI modified.", "type": "boolean" } }, "type": "object" } ] } } } }, { "if": { "properties": { "platform": { "enum": [ "threads" ] } }, "required": [ "platform" ] }, "then": { "properties": { "platformSpecificData": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "description": "threads accepts no platformSpecificData yet.", "properties": {}, "type": "object" } ] } } } }, { "if": { "properties": { "platform": { "enum": [ "reddit" ] } }, "required": [ "platform" ] }, "then": { "properties": { "platformSpecificData": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "description": "reddit accepts no platformSpecificData yet.", "properties": {}, "type": "object" } ] } } } } ], "properties": { "accountId": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "customContent": { "type": [ "string", "null" ] }, "customMedia": { "items": { "additionalProperties": false, "properties": { "altText": { "type": [ "string", "null" ] }, "mediaId": { "pattern": "^med_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "thumbnailUrl": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "platform": { "enum": [ "tiktok", "instagram", "twitter", "youtube", "facebook", "linkedin", "pinterest", "threads", "reddit", "x", null ], "type": [ "string", "null" ] }, "platformSpecificData": { "additionalProperties": {}, "description": "Platform options, checked against the platform registry: unknown fields are rejected with unknown_field. The accepted fields depend on platform; fields required to schedule or publish are named in each description.", "type": [ "object", "null" ] }, "scheduledFor": { "format": "date-time", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "profileId": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "publishNow": { "type": [ "boolean", "null" ] }, "scheduledFor": { "format": "date-time", "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "issues": { "items": { "properties": { "accountId": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": [ "string", "null" ] }, "code": { "type": [ "string", "null" ] }, "field": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "platform": { "enum": [ "tiktok", "instagram", "twitter", "youtube", "facebook", "linkedin", "pinterest", "threads", "reddit", "googlebusiness", "googleanalytics", "bluesky", "telegram", "slack", "snapchat", "hubspot", "microsoft", null ], "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "valid": { "type": [ "boolean", "null" ] } }, "type": "object" } } }, "description": "Success" }, "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." } }, "summary": "Validate a post", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.tools.validate_post@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "This operation does not settle a customer usage charge.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "2e6dd055cab8dbbd571cf0cda058d325c0eebebea45c6bad67a4cecfd761c5a6" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_tools_validate_post", "method": "POST", "path": "/apis/v1/social/tools/validate/post" }, "x-codeSamples": [ { "lang": "text", "label": "Reference example", "source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/social/tools/validate/post \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"content\": \"Our spring collection is live.\",\n \"mediaItems\": [\n {\n \"mediaId\": \"med_5Tc8Hn2Wq7Lx3Bv9Kd4Fr6\",\n \"type\": \"video\"\n }\n ],\n \"platforms\": [\n {\n \"accountId\": \"acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3\",\n \"platform\": \"tiktok\",\n \"platformSpecificData\": {\n \"privacyLevel\": \"PUBLIC_TO_EVERYONE\"\n }\n }\n ],\n \"profileId\": \"prf_2Bn8Wq5Td1Yh7Kc3Mz9Lp4\",\n \"scheduledFor\": \"2026-11-20T15:00:00Z\",\n \"timezone\": \"America/New_York\"\n}'" } ], "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_tools_validate_post" } }, "/apis/v1/social/tools/validate/post-length": { "post": { "description": "Validate. 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.\n\nCheck weighted character count per platform and whether the text is within each platform's limit.\n\nReturns counts and limits for all 15 supported platform variants.\n\n### Counting\n\n- X uses weighted counting (URLs = 23 chars via t.co, emojis = 2 chars).\n- All other platforms use plain character length.\n\n### X rows\n\nX returns two rows, and this endpoint cannot tell you which one applies to you: it takes only `text`, so it never resolves an account.\n\n- `twitter` (280) is the free tier limit.\n- `twitterPremium` (25000) applies only when the target X account has a paid X subscription. Publishing enforces 280 instead for any post carrying a poll. This endpoint has no poll input, so the `twitterPremium` row always shows 25000.\n\nA free account trusting the `twitterPremium` row can pass validation here and still fail at publish time, where the account's real limit is enforced.\n\n### Per-account limits\n\nTo validate against the per-account limit, use `POST /apis/v1/social/tools/validate/post` instead. It accepts an `accountId` per platform entry, resolves X Premium status, and checks the text against the limit publishing enforces, including the poll cap.\n\nA missing, foreign, or invalid `accountId` falls back to the conservative 280.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_tools_validate_po_783463", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "text": "example" }, "schema": { "properties": { "text": { "description": "The post text to check", "type": "string" } }, "required": [ "text" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "platforms": { "additionalProperties": { "properties": { "count": { "description": "Character count for this platform", "type": "integer" }, "limit": { "description": "Maximum allowed characters", "type": "integer" }, "valid": { "description": "Whether the text is within the limit", "type": "boolean" } }, "type": "object" }, "type": "object" }, "text": { "type": "string" } }, "type": "object" } } }, "description": "Character counts per platform" }, "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." } }, "summary": "Validate character count", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.validate.validate_post_length@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "f4b64a9fb457f7d61a9a595a782e73794fa093a5089082787fcecd4c56e912ad" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_tools_validate_po_783463", "method": "POST", "path": "/apis/v1/social/tools/validate/post-length" }, "x-codeSamples": [ { "lang": "text", "label": "Reference example", "source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/social/tools/validate/post-length \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"text\": \"example\"\n}'" } ], "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_tools_validate_po_783463" } }, "/apis/v1/social/tools/validate/subreddit": { "get": { "description": "Validate. 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.\n\nTemporarily unavailable: Reddit has blocked third-party apps from its API, so this endpoint returns 503 `PLATFORM_DISABLED` until Reddit restores access. Reddit Ads is not affected.\n\nCheck if a subreddit exists and return basic info (title, subscriber count, NSFW status, post types allowed).\n\nWhen accountId is provided, uses authenticated Reddit OAuth API with automatic token refresh (recommended). Falls back to Reddit's public JSON API, which may be unreliable from server IPs. Returns exists: false for private, banned, or nonexistent subreddits.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_tools_validate_subreddit", "parameters": [ { "description": "Subreddit name (with or without \"r/\" prefix)", "in": "query", "name": "name", "required": true, "schema": { "type": "string" } }, { "description": "One of your social accounts (acc_...). Required by AIsa: it scopes the read to your account.", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "description": "Subreddit exists", "properties": { "exists": { "type": "boolean" }, "subreddit": { "properties": { "allowImages": { "type": "boolean" }, "allowVideos": { "type": "boolean" }, "description": { "type": "string" }, "isNSFW": { "type": "boolean" }, "name": { "type": "string" }, "subscribers": { "type": "integer" }, "title": { "type": "string" }, "type": { "enum": [ "public", "private", "restricted" ], "type": "string" } }, "type": "object" } }, "type": "object" }, { "description": "Subreddit not found", "properties": { "error": { "type": "string" }, "exists": { "type": "boolean" } }, "type": "object" } ] } } }, "description": "Subreddit lookup result" }, "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." } }, "summary": "Check subreddit existence", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.validate.validate_subreddit@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "a9987385e4795f90a8d7acd5cd0b73e00daede4c7b7dbe190079a110f28d63ef" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_tools_validate_subreddit", "method": "GET", "path": "/apis/v1/social/tools/validate/subreddit" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_tools_validate_subreddit" } }, "/apis/v1/social/twitter/bookmark": { "post": { "description": "Twitter Engagement. Acts in public on your connected account; needs social:publish. Audited. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call. Needs an X account. Paid: see x-aisa-pricing; charged only when the call succeeds.\n\nBookmark a tweet by ID.\nRequires the bookmark.write OAuth scope.\nRate limit: 50 requests per 15-min window.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_twitter_bookmark", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "accountId": "acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3", "tweetId": "example" }, "schema": { "properties": { "accountId": { "description": "One of your social accounts (acc_...).", "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" }, "tweetId": { "description": "The ID of the tweet to bookmark", "type": "string" } }, "required": [ "accountId", "tweetId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "bookmarked": { "type": "boolean" }, "platform": { "type": "string" }, "status": { "type": "string" }, "tweetId": { "type": "string" } }, "type": "object" } } }, "description": "Tweet bookmarked" }, "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." } }, "summary": "Bookmark a tweet", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.twitter_engagement.bookmark_post@1", "required_scope": "social:publish" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "customer_micros_usd": 5000, "description": "Charged once per successful call. The base price is AIsa's own cost for the call: $0.005 (one X bookmark, at X's API rate). Needs an X account. This is the price on every plan; no plan multiplier applies. A refused or failed call, or one whose outcome is unknown, is not charged.", "kind": "fixed_request" }, "x-aisa-revision": { "handler_contract_hash": "821a82caf505cb91c3f02f4fe190df6c0d3849b73faae90fbd0b9696ed514616" }, "x-aisa-status": "disabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_twitter_bookmark", "method": "POST", "path": "/apis/v1/social/twitter/bookmark" }, "x-codeSamples": [ { "lang": "text", "label": "Reference example", "source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/social/twitter/bookmark \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"accountId\": \"acc_7Hq2Lm9Xc4Rt8Vw1Nb6Ks3\",\n \"tweetId\": \"example\"\n}'" } ], "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_twitter_bookmark" } }, "/apis/v1/social/twitter/tweet": { "get": { "description": "Twitter Engagement. 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. Needs an X account. Paid: see x-aisa-pricing; charged only when the call succeeds.\n\nResolve a single tweet by ID or URL into its text, author and public metrics.\n\nUse this to render a post you are referencing, e.g. the tweet quoted by a quote-style post.\nUnlike `/apis/v1/social/twitter/search` this is not limited to the last 7 days and works for any tweet\nvisible to the connected account.\n\nBilled as an X posts read . Repeat lookups of the same tweet within the same UTC day\nare charged once.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_twitter_tweet", "parameters": [ { "description": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": true, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Numeric tweet ID or a tweet URL (e.g. https://x.com/user/status/123...). The same name the other /apis/v1/social/twitter operations use (retweet, bookmark).", "in": "query", "name": "tweetId", "required": true, "schema": { "type": "string" } }, { "description": "Alias of tweetId, kept for existing callers", "in": "query", "name": "id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "status": { "type": "string" }, "tweet": { "properties": { "author": { "properties": { "avatar": { "type": "string" }, "displayName": { "type": "string" }, "id": { "type": "string" }, "username": { "type": "string" }, "verifiedType": { "type": "string" } }, "type": "object" }, "conversationId": { "type": "string" }, "created": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "inReplyToTweetId": { "description": "Parent tweet ID when the tweet is itself a reply", "type": [ "string", "null" ] }, "lang": { "type": "string" }, "likeCount": { "type": "integer" }, "platform": { "type": "string" }, "quoteCount": { "type": "integer" }, "replyCount": { "type": "integer" }, "retweetCount": { "type": "integer" }, "text": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "The resolved tweet" }, "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." } }, "summary": "Look up a tweet", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.twitter_engagement.get_tweet@1", "required_scope": "social:read" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "customer_micros_usd": 5000, "description": "Charged once per successful call. The base price is AIsa's own cost for the call: $0.005 (one X post read, at X's API rate). Needs an X account. This is the price on every plan; no plan multiplier applies. A refused or failed call, or one whose outcome is unknown, is not charged.", "kind": "fixed_request" }, "x-aisa-revision": { "handler_contract_hash": "4a55feb19c95eae3eac13bd145d4728c229196e4e7e6ea1e926066c49df344f5" }, "x-aisa-status": "disabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_twitter_tweet", "method": "GET", "path": "/apis/v1/social/twitter/tweet" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_twitter_tweet" } }, "/apis/v1/social/webhooks/settings": { "delete": { "description": "\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "delete_aisa_social_apis_v1_social_webhooks_settings", "parameters": [ { "description": "A whk_ id.", "in": "query", "name": "id", "required": true, "schema": { "pattern": "^whk_[0-9A-Za-z]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "createdAt": { "format": "date-time", "type": [ "string", "null" ] }, "eventTypes": { "items": { "enum": [ "post.scheduled", "post.published", "post.partial", "post.failed", "post.cancelled", "post.deleted", "post.platform.published", "post.platform.failed", "post.platform.deleted", "post.tiktok.url_resolved", "account.connected", "account.disconnected", "account.needs_reconnect", "connect_session.completed", "connect_session.failed", null ], "type": [ "string", "null" ] }, "type": [ "array", "null" ] }, "failingSince": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "profileFilter": { "items": { "type": [ "string", "null" ] }, "type": [ "array", "null" ] }, "secret": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Success" }, "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." } }, "summary": "Delete a webhook endpoint", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.webhooks.delete@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "This operation does not settle a customer usage charge.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "949735f7456a71807bae5cb75f9425cd93ecdd93a43fb9ac05fc92483630eb62" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "delete_aisa_social_apis_v1_social_webhooks_settings", "method": "DELETE", "path": "/apis/v1/social/webhooks/settings" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/delete_aisa_social_apis_v1_social_webhooks_settings" }, "get": { "description": "\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "get_aisa_social_apis_v1_social_webhooks_settings", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "createdAt": { "format": "date-time", "type": [ "string", "null" ] }, "eventTypes": { "items": { "enum": [ "post.scheduled", "post.published", "post.partial", "post.failed", "post.cancelled", "post.deleted", "post.platform.published", "post.platform.failed", "post.platform.deleted", "post.tiktok.url_resolved", "account.connected", "account.disconnected", "account.needs_reconnect", "connect_session.completed", "connect_session.failed", null ], "type": [ "string", "null" ] }, "type": [ "array", "null" ] }, "failingSince": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "profileFilter": { "items": { "type": [ "string", "null" ] }, "type": [ "array", "null" ] }, "secret": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "type": [ "array", "null" ] }, "nextCursor": { "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Success" }, "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." } }, "summary": "List webhook endpoints", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.webhooks.list@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "This operation does not settle a customer usage charge.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "419874c3887df467ec34776dabfe8dfecdb0768c157d9a03823e651d4c050b2b" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "get_aisa_social_apis_v1_social_webhooks_settings", "method": "GET", "path": "/apis/v1/social/webhooks/settings" }, "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/get_aisa_social_apis_v1_social_webhooks_settings" }, "post": { "description": "The secret is returned only in this response. A key restricted to some profiles must set profileFilter within its profiles.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_webhooks_settings", "requestBody": { "content": { "application/json": { "example": { "eventTypes": [ "post.published", "post.failed" ], "url": "https://example.com/hooks/social" }, "schema": { "additionalProperties": false, "properties": { "eventTypes": { "items": { "enum": [ "post.scheduled", "post.published", "post.partial", "post.failed", "post.cancelled", "post.deleted", "post.platform.published", "post.platform.failed", "post.platform.deleted", "post.tiktok.url_resolved", "account.connected", "account.disconnected", "account.needs_reconnect", "connect_session.completed", "connect_session.failed", null ], "type": [ "string", "null" ] }, "type": [ "array", "null" ] }, "profileFilter": { "items": { "type": [ "string", "null" ] }, "type": [ "array", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "createdAt": { "format": "date-time", "type": [ "string", "null" ] }, "eventTypes": { "items": { "enum": [ "post.scheduled", "post.published", "post.partial", "post.failed", "post.cancelled", "post.deleted", "post.platform.published", "post.platform.failed", "post.platform.deleted", "post.tiktok.url_resolved", "account.connected", "account.disconnected", "account.needs_reconnect", "connect_session.completed", "connect_session.failed", null ], "type": [ "string", "null" ] }, "type": [ "array", "null" ] }, "failingSince": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "profileFilter": { "items": { "type": [ "string", "null" ] }, "type": [ "array", "null" ] }, "secret": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Success" }, "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." } }, "summary": "Create a webhook endpoint", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.webhooks.create@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "This operation does not settle a customer usage charge.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "c2da2aa7c76897f74b503f20196f5f5631b77e93113ef6c84b97c049375acea9" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_webhooks_settings", "method": "POST", "path": "/apis/v1/social/webhooks/settings" }, "x-codeSamples": [ { "lang": "text", "label": "Reference example", "source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/social/webhooks/settings \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"eventTypes\": [\n \"post.published\",\n \"post.failed\"\n ],\n \"url\": \"https://example.com/hooks/social\"\n}'" } ], "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_webhooks_settings" }, "put": { "description": "rotateSecret returns a new secret; the previous one stays valid for 24 hours.\n\n\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "put_aisa_social_apis_v1_social_webhooks_settings", "requestBody": { "content": { "application/json": { "example": { "eventTypes": [ "post.published", "post.failed", "post.partial" ], "id": "whk_8Pm3Vy6Rk1Ns9Gt4Qw2Jh5" }, "schema": { "additionalProperties": false, "properties": { "eventTypes": { "items": { "enum": [ "post.scheduled", "post.published", "post.partial", "post.failed", "post.cancelled", "post.deleted", "post.platform.published", "post.platform.failed", "post.platform.deleted", "post.tiktok.url_resolved", "account.connected", "account.disconnected", "account.needs_reconnect", "connect_session.completed", "connect_session.failed", null ], "type": [ "string", "null" ] }, "type": [ "array", "null" ] }, "id": { "type": [ "string", "null" ] }, "profileFilter": { "items": { "type": [ "string", "null" ] }, "type": [ "array", "null" ] }, "rotateSecret": { "type": [ "boolean", "null" ] }, "status": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "createdAt": { "format": "date-time", "type": [ "string", "null" ] }, "eventTypes": { "items": { "enum": [ "post.scheduled", "post.published", "post.partial", "post.failed", "post.cancelled", "post.deleted", "post.platform.published", "post.platform.failed", "post.platform.deleted", "post.tiktok.url_resolved", "account.connected", "account.disconnected", "account.needs_reconnect", "connect_session.completed", "connect_session.failed", null ], "type": [ "string", "null" ] }, "type": [ "array", "null" ] }, "failingSince": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "profileFilter": { "items": { "type": [ "string", "null" ] }, "type": [ "array", "null" ] }, "secret": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": "object" } } }, "description": "Success" }, "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." } }, "summary": "Update a webhook endpoint", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.webhooks.update@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "This operation does not settle a customer usage charge.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "79079d0d3ace2a00c6ce5133bb7bb2b39531714ede0fa024117fb1cafc4b61e6" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "put_aisa_social_apis_v1_social_webhooks_settings", "method": "PUT", "path": "/apis/v1/social/webhooks/settings" }, "x-codeSamples": [ { "lang": "text", "label": "Reference example", "source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request PUT \\\n --url https://api.aisa.one/apis/v1/social/webhooks/settings \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"eventTypes\": [\n \"post.published\",\n \"post.failed\",\n \"post.partial\"\n ],\n \"id\": \"whk_8Pm3Vy6Rk1Ns9Gt4Qw2Jh5\"\n}'" } ], "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/put_aisa_social_apis_v1_social_webhooks_settings" } }, "/apis/v1/social/webhooks/test": { "post": { "description": "\nA request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.\n", "operationId": "post_aisa_social_apis_v1_social_webhooks_test", "requestBody": { "content": { "application/json": { "example": { "id": "whk_8Pm3Vy6Rk1Ns9Gt4Qw2Jh5" }, "schema": { "additionalProperties": false, "properties": { "id": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "delivered": { "type": [ "boolean", "null" ] }, "eventId": { "type": [ "string", "null" ] }, "httpStatus": { "type": [ "integer", "null" ] } }, "type": "object" } } }, "description": "Success" }, "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." } }, "summary": "Send a test event", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "reason": "not_quoted", "supported": false }, "capability": "social.webhooks.test@1", "required_scope": "social:draft" }, "x-aisa-contract-source": "handler", "x-aisa-identity-source": "derived", "x-aisa-pricing": { "description": "This operation does not settle a customer usage charge.", "kind": "no_customer_charge" }, "x-aisa-revision": { "handler_contract_hash": "bbe191aec99a37fe8923f817970ae39cf9c7fd0ace3855a99f8199237942920f" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-aisa-catalog-id": "aisa-social", "x-aisa-runtime-operation": { "operation_id": "post_aisa_social_apis_v1_social_webhooks_test", "method": "POST", "path": "/apis/v1/social/webhooks/test" }, "x-codeSamples": [ { "lang": "text", "label": "Reference example", "source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/social/webhooks/test \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"id\": \"whk_8Pm3Vy6Rk1Ns9Gt4Qw2Jh5\"\n}'" } ], "x-aisa-docs-url": "https://aisa.one/docs/api-reference/aisa-social/post_aisa_social_apis_v1_social_webhooks_test" } } } }