이 개발자 문서는 현재 영어로만 제공됩니다. 코드 및 API 동작은 모든 지역에서 동일합니다.

Social Connections API

Connect a brand's social platforms over OAuth so the platform can post and read on its behalf. These endpoints mirror the campaign Connections hub into the API instance: list a brand's connected platforms, start an OAuth connect, and disconnect. All routes are served under /v1/social and proxy module-a's state-based OAuth flow.

Connecting is plumbing, so connect, disconnect and status are free. The one metered route here is POST /v1/social/{platform}/publish, which costs 5 credits per published post.

Authentication

Every request must carry a tenant API key as a Bearer token:

Authorization: Bearer ai92_live_<key>     # production
Authorization: Bearer ai92_test_<key>     # sandbox

OAuth 2.0 access tokens (Authorization: Bearer eyJ…) are also accepted. All routes are brand-scoped: brand_id is required and is verified against your account. Mutating requests support the Idempotency-Key header.

Credit costs at a glance

Endpoint	Cost
`GET /v1/social/status`	Free
`GET /v1/social/{platform}/initiate`	Free
`POST /v1/social/{platform}/disconnect`	Free
`POST /v1/social/{platform}/publish`	5 cr

POST /v1/social/{platform}/publish

Cost: 5 credits

Publish a post to a connected platform. Charged only after the post succeeds — if the publishing backend fails you get a 4xx/5xx and nothing is deducted. Sandbox keys never publish and never charge.

Auth: Bearer

Field	Type	Required	Description
`brand_id`	string	Yes	The brand to post as. Verified against the account.
`caption`	string	Yes	Post text, 1–5000 characters.
`asset_id`	string	No	A creative asset id from `GET /v1/creative/assets`.
`media_url`	string	No	A media URL to attach instead of an asset id.
`schedule_at`	string	No	ISO-8601 timestamp to schedule the post. Publishes immediately when omitted.

Request

bash

curl https://api.ai92.ai/v1/social/instagram/publish \
  -H "Authorization: Bearer ai92_live_51a9c0de…" \
  -H "Content-Type: application/json" \
  -d '{"brand_id": "b1f0…", "caption": "Spring collection is live."}'

The response echoes the platform and credits_charged: 5.

GET /v1/social/status

Cost: Free

Per-platform connection status for a brand. Returns which social platforms are connected and the state of each.

Auth: Bearer (tenant key or OAuth token)

Parameter	In	Type	Required	Description
`brand_id`	query	string	Yes	The brand to inspect. Verified against the account.

Request

bash

curl "https://api.ai92.ai/v1/social/status?brand_id=b1f0…" \
  -H "Authorization: Bearer ai92_test_51a9c0de…"

Response 200 OK

json

{
  "brand_id": "b1f0…",
  "platforms": [
    { "platform": "instagram", "connected": true,  "account_name": "@acme", "connected_at": "2026-06-10T12:00:00Z" },
    { "platform": "facebook",  "connected": true,  "account_name": "Acme Corp", "connected_at": "2026-06-10T12:00:00Z" },
    { "platform": "linkedin",  "connected": false, "account_name": null, "connected_at": null }
  ]
}

Errors

Status	Code	When
`404`	`BRAND_NOT_FOUND`	Brand not owned by the account.

GET /v1/social/{platform}/initiate

Cost: Free

Start an OAuth connect for a platform. Returns the provider auth_url (plus an opaque state) to open in the browser; module-a's public, state-based callback stores the connection for the brand once the user finishes the OAuth flow — no callback change is needed on your side.

Auth: Bearer

Parameter	In	Type	Required	Description
`platform`	path	string	Yes	Platform key (e.g. `instagram`, `facebook`, `linkedin`, `x`, `tiktok`).
`brand_id`	query	string	Yes	The brand to connect. Verified against the account.
`redirect_url`	query	string	No	Where to send the browser after the connect completes.

Request

bash

curl "https://api.ai92.ai/v1/social/instagram/initiate?brand_id=b1f0…&redirect_url=https://app.acme.com/done" \
  -H "Authorization: Bearer ai92_test_51a9c0de…"

Response 200 OK

json

{
  "platform": "instagram",
  "auth_url": "https://www.facebook.com/v19.0/dialog/oauth?client_id=…&state=st_9f2a…",
  "state": "st_9f2a…"
}

Errors

Status	Code	When
`404`	`BRAND_NOT_FOUND`	Brand not owned by the account.
`422`	`UNSUPPORTED_PLATFORM`	`platform` is not a supported provider.

POST /v1/social/{platform}/disconnect

Cost: Free

Revoke and clear a brand's connection for a platform.

Auth: Bearer

Parameter	In	Type	Required	Description
`platform`	path	string	Yes	Platform key to disconnect.
`brand_id`	query	string	Yes	The brand to disconnect. Verified against the account.
`reason`	body	string / null	No	Optional reason recorded with the disconnect.

Request

bash

curl -X POST "https://api.ai92.ai/v1/social/instagram/disconnect?brand_id=b1f0…" \
  -H "Authorization: Bearer ai92_test_51a9c0de…" \
  -H "Content-Type: application/json" \
  -d '{"reason": "rotating the connected account"}'

Response 200 OK

json

{ "platform": "instagram", "brand_id": "b1f0…", "disconnected": true }

Errors

Status	Code	When
`404`	`BRAND_NOT_FOUND`	Brand not owned by the account, or no connection for the platform.