Connections API

The Connections API enables you to list and inspect connected social media accounts (Instagram, Threads, Bluesky, Facebook Page, TikTok, YouTube) under your brand. Use this API to retrieve target connection_ids and verify permissions before publishing content.

📌 Endpoints

Method	Path	Description	Required Scope
`GET`	`/v1/brand/connections`	List connected SNS accounts with optional platform filtering	`connections:read` or `*`
`GET`	`/v1/brand/connections/{connection_id}`	Retrieve connection details and live authorization diagnostics	`connections:read` or `*`

📋 List Connections (`GET /v1/brand/connections`)

Retrieve all connected SNS accounts under the brand.

Query Parameters

Parameter	Type	Required	Description
`sns_type`	`string`	Optional	Filter by `instagram`, `threads`, `bluesky`, `facebook_page`, `tiktok`, or `youtube`

Request Example

curl -X GET "https://api.ankk.app/v1/brand/connections?sns_type=instagram" \
  -H "Authorization: Bearer spk_live_xxxxxxxx"

Response Example (`200 OK`)

{
  "items": [
    {
      "id": "conn_01jm8x9k2example",
      "sns_type": "instagram",
      "platform": "meta.instagram",
      "display_name": "ACME Official",
      "username": "acme_official",
      "profile_image_url": "https://example.com/profiles/acme.jpg",
      "status": "connected",
      "created_at": "2026-08-01T10:00:00Z"
    }
  ]
}

🔍 Get Connection Details (`GET /v1/brand/connections/{connection_id}`)

Retrieve connection details along with live Publish Authorization diagnostics.

Request Example

curl -X GET "https://api.ankk.app/v1/brand/connections/conn_01jm8x9k2example" \
  -H "Authorization: Bearer spk_live_xxxxxxxx"

Response Example (`200 OK`)

{
  "id": "conn_01jm8x9k2example",
  "sns_type": "instagram",
  "platform": "meta.instagram",
  "display_name": "ACME Official",
  "username": "acme_official",
  "profile_image_url": "https://example.com/profiles/acme.jpg",
  "status": "connected",
  "created_at": "2026-08-01T10:00:00Z",
  "publish_authorization": {
    "status": "scope_authorized",
    "required_scopes": ["instagram_business_basic", "instagram_business_content_publish"],
    "missing_scopes": [],
    "retryable": false
  }
}

Authorization Status Codes (`publish_authorization.status`)

Status	Meaning & Action
`scope_authorized`	Fully authorized. Ready to publish.
`scope_permission_unverified`	Verification pending. Publish may be attempted.
`scope_permission_missing`	Required scopes missing. Reauthorization required in Web UI.
`scope_review_disabled`	Blocked by platform app review status or developer mode limits.
`unsupported`	Operation not supported on this connection.