SocialAPI.ai

https://docs.social-api.ai/
Admin
SocialAPI.ai is a unified social media API that allows developers and AI agents to manage a inbox,...
Tokens:214,372
Snippets:1,312
Trust Score:4.9
Update:2 months ago
Show doc for...
Tokens:
Raw
### Native Scheduling Example

Source: https://docs.social-api.ai/posts/youtube

Example of how to perform a native scheduled publish on YouTube.

```APIDOC
## Native Scheduling

### Description
YouTube schedules a publish natively by uploading the video as 'private' with a 'publish_at' timestamp. YouTube will automatically flip the video to public at the specified time.

### Request Example
{
  "targets": [{ "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J" }],
  "title": "Launch day announcement",
  "text": "Going live for everyone at 10am.",
  "visibility": "private",
  "media_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"],
  "platform_data": {
    "youtube": {
      "publish_at": "2026-04-15T10:00:00Z"
    }
  }
}
```

--------------------------------

### Retrieve API key details

Source: https://docs.social-api.ai/guides/scoped-keys

Example JSON response from the GET /v1/keys endpoint showing scopes and brand restrictions.

```json
{
  "id": "b7e2...",
  "name": "Acme client bot",
  "preview": "sapi_key_a1b2c...",
  "is_active": true,
  "last_used_at": "2026-07-12T12:00:00Z",
  "created_at": "2026-07-10T09:00:00Z",
  "scopes": ["inbox:read", "inbox:write", "dms:send"],
  "brand_ids": ["1c9f6f0e-2b3a-4c5d-8e7f-0a1b2c3d4e5f"]
}
```

--------------------------------

### TikTok account summary response example

Source: https://docs.social-api.ai/connectors/tiktok

Example JSON response containing profile statistics and account details.

```json
{
  "display_name": "Acme Corp",
  "username": "acmecorp",
  "avatar_url": "https://p16-sign.tiktokcdn-us.com/...",
  "follower_count": 12400,
  "following_count": 87,
  "likes_count": 980000,
  "video_count": 47
}
```

--------------------------------

### GET /v1/webhooks

Source: https://docs.social-api.ai/guides/webhooks

List all configured webhook endpoints.

```APIDOC
## GET /v1/webhooks

### Description
Retrieve a list of all webhook endpoints.

### Method
GET

### Endpoint
https://api.social-api.ai/v1/webhooks
```

--------------------------------

### GET /v1/keys

Source: https://docs.social-api.ai/guides/authentication

Lists all API keys associated with the account.

```APIDOC
## GET /v1/keys

### Description
Retrieves a list of API keys. The response includes key previews, activity status, and restriction details.

### Method
GET

### Endpoint
https://api.social-api.ai/v1/keys

### Response
#### Success Response (200)
- **preview** (string) - Truncated key preview.
- **is_active** (boolean) - Status of the key.
- **last_used_at** (string) - Timestamp of last usage.
- **scopes** (array) - Key scope restrictions.
- **brand_ids** (array) - Brand ID restrictions.
```

--------------------------------

### Create a post with media

Source: https://docs.social-api.ai/guides/media

Attach media to a post by providing an array of media_ids. Ensure media is uploaded first as raw public URLs are ignored.

```bash
curl -X POST https://api.social-api.ai/v1/posts \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "targets": [{ "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J" }],
    "text": "Behind the scenes from our studio shoot.",
    "media_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"]
  }'
```

--------------------------------

### Account Object JSON Structure

Source: https://docs.social-api.ai/connectors/overview

Example of the JSON response returned by the GET /v1/accounts endpoint.

```json
{
  "id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J",
  "platform": "instagram",
  "name": "Acme Corp",
  "username": "acmecorp",
  "brand_id": "b7e2c1a0-4f3d-11ee-be56-0242ac120002",
  "status": "active"
}
```

--------------------------------

### Initiate WhatsApp connection

Source: https://docs.social-api.ai/connectors/whatsapp

Call the accounts endpoint to start the connection flow and retrieve necessary metadata for the Meta popup.

```bash
curl -X POST https://api.social-api.ai/v1/accounts/connect \
  -H "Authorization: Bearer $SOCIALAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "platform": "whatsapp" }'
```

--------------------------------

### Register a New Client

Source: https://docs.social-api.ai/guides/oauth

Dynamically register an application to obtain client credentials. The client secret is returned only once and must be stored securely.

```bash
curl -X POST https://api.social-api.ai/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My MCP Client",
    "redirect_uris": ["https://app.example.com/callback"]
  }'
```

```json
{
  "client_id": "a1b2c3d4e5f6...",
  "client_secret": "s3cr3t...",
  "client_id_issued_at": 1719000000,
  "client_secret_expires_at": 0,
  "client_name": "My MCP Client",
  "redirect_uris": ["https://app.example.com/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "client_secret_post"
}
```

--------------------------------

### Get webhook endpoint OpenAPI definition

Source: https://docs.social-api.ai/api-reference/webhooks/get-webhook-endpoint

Defines the GET /webhooks/{id} endpoint, including required parameters, response schemas, and security requirements.

```yaml
openapi: 3.0.0
info:
  description: >-
    Unified social media inbox API. Read and respond to comments, DMs, reviews,
    and mentions across Instagram, Facebook, Threads, Google Business Profile,
    TikTok, LinkedIn, and YouTube through a single REST API. X/Twitter and
    Trustpilot coming soon.
  title: SocialAPI.AI
  contact:
    name: SocialAPI.AI Support
    email: support@social-api.ai
  license:
    name: MIT
  version: '1.0'
servers:
  - url: https://api.social-api.ai/v1
security: []
paths:
  /webhooks/{id}:
    get:
      tags:
        - Webhooks
      summary: Get webhook endpoint
      description: >-
        Returns the configuration and aggregate delivery stats for a single
        webhook endpoint owned by the caller.
      parameters:
        - description: Webhook endpoint ID
          name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_endpoints.WebhookDetailResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_endpoints.ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_endpoints.ErrorResponse'
      security:
        - BearerAuth: []
components:
  schemas:
    api_endpoints.WebhookDetailResponse:
      type: object
      properties:
        created_at:
          type: string
        events:
          type: array
          items:
            type: string
        id:
          type: string
        is_active:
          type: boolean
        secret_hint:
          type: string
        stats:
          $ref: '#/components/schemas/social-api_ai_core_api_service.WebhookStats'
        url:
          type: string
    api_endpoints.ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/api_endpoints.ErrorBody'
    social-api_ai_core_api_service.WebhookStats:
      type: object
      properties:
        last_24h:
          $ref: >-
            #/components/schemas/social-api_ai_core_api_service.DeliveryStatBucket
        last_7d:
          $ref: >-
            #/components/schemas/social-api_ai_core_api_service.DeliveryStatBucket
    api_endpoints.ErrorBody:
      type: object
      properties:
        code:
          type: string
          example: resource.not_found
        message:
          type: string
          example: Account not found
        meta:
          type: object
          additionalProperties: {}
    social-api_ai_core_api_service.DeliveryStatBucket:
      type: object
      properties:
        delivered:
          type: integer
        failed:
          type: integer
  securitySchemes:
    BearerAuth:
      description: >-
        Prefix your API key with "Bearer ". Example: `Authorization: Bearer
        sapi_key_...`
      type: apiKey
      name: Authorization
      in: header
```

--------------------------------

### List media files

Source: https://docs.social-api.ai/guides/media

Retrieve a paginated list of ready media files, sorted by newest first.

```bash
curl "https://api.social-api.ai/v1/media?limit=50" \
  -H "Authorization: Bearer $SOCAPI_KEY"
```

--------------------------------

### GET /v1/media

Source: https://docs.social-api.ai/guides/media

List your ready media files, sorted by newest first, with cursor pagination.

```APIDOC
## GET /v1/media

### Description
Returns your ready files, newest first, with cursor pagination.

### Method
GET

### Endpoint
https://api.social-api.ai/v1/media

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Number of items per page (default 50, max 100)
```

--------------------------------

### OpenAPI definition for Get a conversation

Source: https://docs.social-api.ai/api-reference/inbox/get-a-conversation

The OpenAPI specification defining the GET request for retrieving a conversation by ID, including security requirements and response schemas.

```yaml
openapi: 3.0.0
info:
  description: >-
    Unified social media inbox API. Read and respond to comments, DMs, reviews,
    and mentions across Instagram, Facebook, Threads, Google Business Profile,
    TikTok, LinkedIn, and YouTube through a single REST API. X/Twitter and
    Trustpilot coming soon.
  title: SocialAPI.AI
  contact:
    name: SocialAPI.AI Support
    email: support@social-api.ai
  license:
    name: MIT
  version: '1.0'
servers:
  - url: https://api.social-api.ai/v1
security: []
paths:
  /inbox/conversations/{id}:
    get:
      tags:
        - Inbox
      summary: Get a conversation
      description: Returns a single inbox conversation by ID.
      parameters:
        - description: Conversation ID
          name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Conversation details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_endpoints.ConversationResponse'
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_endpoints.ErrorResponse'
        '404':
          description: Conversation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_endpoints.ErrorResponse'
      security:
        - BearerAuth: []
components:
  schemas:
    api_endpoints.ConversationResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/social-api_ai_core_api_service.ConversationRow'
    api_endpoints.ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/api_endpoints.ErrorBody'
    social-api_ai_core_api_service.ConversationRow:
      type: object
      properties:
        account_id:
          type: string
        created_at:
          type: string
        id:
          type: string
        last_message:
          type: string
        last_message_at:
          type: string
        page_id:
          type: string
        participant_id:
          type: string
        participant_name:
          type: string
        participant_picture:
          type: string
        platform:
          type: string
        platform_id:
          type: string
        status:
          type: string
        unread_count:
          type: integer
        updated_at:
          type: string
        user_id:
          type: string
    api_endpoints.ErrorBody:
      type: object
      properties:
        code:
          type: string
          example: resource.not_found
        message:
          type: string
          example: Account not found
        meta:
          type: object
          additionalProperties: {}
  securitySchemes:
    BearerAuth:
      description: >-
        Prefix your API key with "Bearer ". Example: `Authorization: Bearer
        sapi_key_...`
      type: apiKey
      name: Authorization
      in: header
```

--------------------------------

### OpenAPI specification for Get storage usage

Source: https://docs.social-api.ai/api-reference/media/get-storage-usage

Defines the GET /media/storage endpoint, including response headers for storage limits and usage, and the expected JSON response schema.

```yaml
openapi: 3.0.0
info:
  description: >-
    Unified social media inbox API. Read and respond to comments, DMs, reviews,
    and mentions across Instagram, Facebook, Threads, Google Business Profile,
    TikTok, LinkedIn, and YouTube through a single REST API. X/Twitter and
    Trustpilot coming soon.
  title: SocialAPI.AI
  contact:
    name: SocialAPI.AI Support
    email: support@social-api.ai
  license:
    name: MIT
  version: '1.0'
servers:
  - url: https://api.social-api.ai/v1
security: []
paths:
  /media/storage:
    get:
      tags:
        - Media
      summary: Get storage usage
      description: >-
        Returns total bytes used, the plan limit, and file count for the
        authenticated user.
      responses:
        '200':
          description: OK
          headers:
            X-Storage-Limit:
              description: Storage limit in bytes (-1 = unlimited)
              schema:
                type: integer
            X-Storage-Used:
              description: Bytes of storage used
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_endpoints.StorageUsageResponse'
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_endpoints.ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_endpoints.ErrorResponse'
      security:
        - BearerAuth: []
components:
  schemas:
    api_endpoints.StorageUsageResponse:
      type: object
      properties:
        count:
          type: integer
          example: 12
        limit_bytes:
          type: integer
          example: 104857600
        used_bytes:
          type: integer
          example: 52428800
    api_endpoints.ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/api_endpoints.ErrorBody'
    api_endpoints.ErrorBody:
      type: object
      properties:
        code:
          type: string
          example: resource.not_found
        message:
          type: string
          example: Account not found
        meta:
          type: object
          additionalProperties: {}
  securitySchemes:
    BearerAuth:
      description: >-
        Prefix your API key with "Bearer ". Example: `Authorization: Bearer
        sapi_key_...`
      type: apiKey
      name: Authorization
      in: header
```

--------------------------------

### POST /v1/accounts/connect

Source: https://docs.social-api.ai/connectors/whatsapp

Initiates the WhatsApp connection flow by requesting the necessary metadata from the server.

```APIDOC
## POST /v1/accounts/connect

### Description
Initiates the WhatsApp connection flow. Returns the metadata required to launch the Meta Embedded Signup popup.

### Method
POST

### Endpoint
https://api.social-api.ai/v1/accounts/connect

### Request Body
- **platform** (string) - Required - Must be set to "whatsapp"

### Response
#### Success Response (202)
- **auth_url** (string) - URL for authentication
- **state** (string) - CSRF token with 10-minute TTL
- **metadata** (object) - Contains app_id, config_id, and solution_id for the Meta SDK
```

--------------------------------

### Publish a post with an image

Source: https://docs.social-api.ai/quickstart

Requires a four-step process: requesting an upload URL, uploading the file, verifying the upload, and creating the post with the media ID.

```bash
# 1. Request a signed upload URL (media_type and filename are required)
curl "https://api.social-api.ai/v1/media/upload-url?media_type=image/jpeg&filename=launch.jpg" \
  -H "Authorization: Bearer $SOCAPI_KEY"
# -> { "media_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "upload_url": "https://...", "expires_at": "..." }

# 2. Upload the bytes to the signed URL (Content-Type must match media_type)
curl -X PUT "https://...signed-upload-url..." \
  -H "Content-Type: image/jpeg" \
  --data-binary @launch.jpg

# 3. Verify the upload (required: flips the media from pending to ready)
curl -X POST https://api.social-api.ai/v1/media/f47ac10b-58cc-4372-a567-0e02b2c3d479/verify \
  -H "Authorization: Bearer $SOCAPI_KEY"

# 4. Create the post, referencing the media by ID
curl -X POST https://api.social-api.ai/v1/posts \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Our spring collection is live.",
    "publish_now": true,
    "media_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"],
    "targets": [ { "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J" } ]
  }'
```

--------------------------------

### OpenAPI Specification for Get a Single Post

Source: https://docs.social-api.ai/api-reference/posts/get-a-single-post

Defines the GET /posts/{pid} endpoint, including required path parameters, response schemas for success and error states, and security requirements.

```yaml
openapi: 3.0.0
info:
  description: >-
    Unified social media inbox API. Read and respond to comments, DMs, reviews,
    and mentions across Instagram, Facebook, Threads, Google Business Profile,
    TikTok, LinkedIn, and YouTube through a single REST API. X/Twitter and
    Trustpilot coming soon.
  title: SocialAPI.AI
  contact:
    name: SocialAPI.AI Support
    email: support@social-api.ai
  license:
    name: MIT
  version: '1.0'
servers:
  - url: https://api.social-api.ai/v1
security: []
paths:
  /posts/{pid}:
    get:
      tags:
        - Posts
      summary: Get a single post
      description: Fetch a post by its ID with all platform delivery details.
      parameters:
        - description: Post ID
          name: pid
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_endpoints.PostResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_endpoints.ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_endpoints.ErrorResponse'
      security:
        - BearerAuth: []
components:
  schemas:
    api_endpoints.PostResponse:
      type: object
      properties:
        created_at:
          type: string
          example: '2026-03-14T09:00:00Z'
        hidden:
          type: boolean
          example: false
        id:
          type: string
          example: p_01HZ9X3Q4R5M6N7P8V2K0W1J
        media_ids:
          type: array
          items:
            type: string
        published_at:
          type: string
          example: '2026-04-01T10:00:05Z'
        retry_count:
          type: integer
          example: 0
        scheduled_at:
          type: string
          example: '2026-04-01T10:00:00Z'
        status:
          type: string
          enum:
            - draft
            - scheduled
            - publishing
            - published
            - partial
            - failed
            - cancelled
          example: published
        targets:
          type: array
          items:
            $ref: '#/components/schemas/api_endpoints.PostTargetResponse'
        text:
          type: string
          example: Check out our new product launch!
        title:
          type: string
          example: Exciting News
        updated_at:
          type: string
          example: '2026-03-14T09:00:00Z'
        visibility:
          type: string
          enum:
            - public
            - private
            - connections_only
            - logged_in
          example: public
    api_endpoints.ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/api_endpoints.ErrorBody'
    api_endpoints.PostTargetResponse:
      type: object
      properties:
        account_id:
          type: string
          example: acc_01HZ9X3Q4R5M6N7P8V2K0W1J
        error:
          $ref: '#/components/schemas/api_endpoints.PostTargetErrorResponse'
        first_comment:
          type: string
        media_type:
          type: string
          enum:
            - feed
            - reel
            - stories
            - carousel
          example: reel
        metadata:
          type: object
          additionalProperties: {}
        metrics:
          $ref: '#/components/schemas/api_endpoints.PostTargetMetricsResponse'
        metrics_synced_at:
          type: string
          example: '2026-04-01T12:00:00Z'
        page_id:
          type: string
          example: sapi_page_01HZ9X3Q4R5M6N7P8V2K0W1J
        permalink:
          type: string
          example: https://www.instagram.com/p/ABC123/
        platform:
          type: string
          enum:
            - instagram
            - facebook
            - threads
            - tiktok
            - linkedin
            - google
            - zalo
          example: instagram
        platform_post_id:
          type: string
          example: '17895695668004550'
        published_at:
          type: string
          example: '2026-04-01T10:00:05Z'
        scheduled_at:
          type: string
          example: '2026-04-01T10:00:00Z'
        status:
          type: string
          enum:
            - pending
            - publishing
            - published
            - failed
          example: published
```

--------------------------------

### Create a Google Offer Post

Source: https://docs.social-api.ai/posts/google

Sends a POST request to create a new offer post with specific Google platform data.

```bash
curl -X POST https://api.social-api.ai/v1/posts \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "targets": [{ "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J" }],
    "text": "Get 20% off all services this week only. Use code SPRING20 at checkout.",
    "platform_data": {
      "google": {
        "topicType": "OFFER",
        "offer": {
          "couponCode": "SPRING20",
          "redeemOnlineUrl": "https://example.com/book"
        }
      }
    }
  }'
```

--------------------------------

### Connect a Google Account

Source: https://docs.social-api.ai/connectors/google

Initiates the OAuth connection flow for a Google Business Profile.

```bash
curl -X POST https://api.social-api.ai/v1/accounts/connect \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "google",
    "redirect_uri": "https://app.example.com/oauth/callback",
    "state": "session_abc123"
  }'
```

--------------------------------

### GET /.well-known/oauth-protected-resource

Source: https://docs.social-api.ai/guides/oauth

Retrieves protected resource metadata.

```APIDOC
## GET /.well-known/oauth-protected-resource

### Description
Retrieves protected resource metadata (RFC 9470).

### Method
GET

### Endpoint
/.well-known/oauth-protected-resource
```

--------------------------------

### GET /oauth/authorize

Source: https://docs.social-api.ai/guides/oauth

Initiates the authorization flow with PKCE.

```APIDOC
## GET /oauth/authorize

### Description
Initiates the authorization flow with PKCE.

### Method
GET

### Endpoint
/oauth/authorize
```

--------------------------------

### Create a standard local post

Source: https://docs.social-api.ai/posts/google

Use this request to publish a general informational post to a connected Google Business Profile location.

```bash
curl -X POST https://api.social-api.ai/v1/posts \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "targets": [{ "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J" }],
    "text": "Join us this Saturday for our grand reopening. Free coffee for the first 100 visitors.",
    "platform_data": {
      "google": {
        "topicType": "STANDARD"
      }
    }
  }'
```

--------------------------------

### GET /v1/inbox/reviews

Source: https://docs.social-api.ai/guides/inbox

List reviews from platforms that support them.

```APIDOC
## GET /v1/inbox/reviews

### Description
List reviews on platforms that support them.

### Method
GET

### Endpoint
/v1/inbox/reviews
```

--------------------------------

### GET /oauth/authorize/request

Source: https://docs.social-api.ai/guides/oauth

Fetches a pending authorization request by request_id.

```APIDOC
## GET /oauth/authorize/request

### Description
Fetches a pending authorization request by request_id, typically used by the consent UI.

### Method
GET

### Endpoint
/oauth/authorize/request
```

--------------------------------

### POST /v1/accounts/connect

Source: https://docs.social-api.ai/connectors/overview

Connects a new account to the platform and returns metadata specific to the platform profile.

```APIDOC
## POST /v1/accounts/connect

### Description
Initiates an account connection. The response includes a `metadata` object containing platform-specific profile data for supported platforms.

### Method
POST

### Endpoint
/v1/accounts/connect
```

--------------------------------

### Request a presigned upload URL

Source: https://docs.social-api.ai/posts/instagram

Initiate the media upload process by requesting a secure URL for the video file.

```bash
curl "https://api.social-api.ai/v1/media/upload-url?filename=reel.mp4&media_type=video/mp4" \
  -H "Authorization: Bearer $SOCAPI_KEY"
```

--------------------------------

### GET /.well-known/oauth-authorization-server

Source: https://docs.social-api.ai/guides/oauth

Retrieves the authorization server configuration and metadata.

```APIDOC
## GET /.well-known/oauth-authorization-server

### Description
Retrieves the authorization server configuration and metadata for discovery.

### Method
GET

### Endpoint
/.well-known/oauth-authorization-server

### Response
#### Success Response (200)
- **issuer** (string) - The issuer URL
- **authorization_endpoint** (string) - The authorization endpoint URL
- **token_endpoint** (string) - The token endpoint URL
- **registration_endpoint** (string) - The registration endpoint URL
- **revocation_endpoint** (string) - The revocation endpoint URL
- **response_types_supported** (array) - Supported response types
- **grant_types_supported** (array) - Supported grant types
- **token_endpoint_auth_methods_supported** (array) - Supported authentication methods
- **code_challenge_methods_supported** (array) - Supported PKCE challenge methods
- **scopes_supported** (array) - Supported scopes
```

--------------------------------

### Plan catalog response structure

Source: https://docs.social-api.ai/guides/rate-limits

Example JSON response showing tier metadata and resource limits, where -1 indicates unlimited usage.

```json
{
  "plans": [
    {
      "tier": "free",
      "name": "Hobby",
      "tagline": "Kick the tires, no card required",
      "monthly_price_usd": 0,
      "annual_price_usd": 0,
      "popular": false,
      "limits": {
        "profiles": 2,
        "posts_per_month": 10,
        "interactions_per_month": 50,
        "storage_bytes": 104857600,
        "event_retention_days": 1,
        "exports_per_month": 2
      }
    },
    {
      "tier": "pro",
      "name": "Full Send",
      "tagline": "For growing teams and products",
      "monthly_price_usd": 109,
      "annual_price_usd": 1044,
      "popular": true,
      "limits": {
        "profiles": 50,
        "posts_per_month": -1,
        "interactions_per_month": -1,
        "storage_bytes": -1,
        "event_retention_days": 30,
        "exports_per_month": 20
      }
    }
  ]
}
```

--------------------------------

### GET /v1/inbox/conversations/:id

Source: https://docs.social-api.ai/guides/inbox

Retrieve details for a specific conversation.

```APIDOC
## GET /v1/inbox/conversations/:id

### Description
Get a single conversation.

### Method
GET

### Endpoint
/v1/inbox/conversations/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The conversation ID
```

--------------------------------

### GET /v1/inbox/comments/:postId

Source: https://docs.social-api.ai/guides/inbox

List comments on a specific post.

```APIDOC
## GET /v1/inbox/comments/:postId

### Description
List comments on a specific post.

### Method
GET

### Endpoint
/v1/inbox/comments/:postId

### Parameters
#### Path Parameters
- **postId** (string) - Required - Platform post ID
```

--------------------------------

### Create a Facebook post with link

Source: https://docs.social-api.ai/posts/facebook

Use the POST /v1/posts endpoint to create a post with a link preview. The link is specified within the platform_data object.

```bash
curl -X POST https://api.social-api.ai/v1/posts \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Exciting news from our team. Read the full announcement on our website.",
    "targets": [{
      "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J",
      "platform_data": {
        "link": "https://example.com/announcement"
      }
    }]
  }'
```

--------------------------------

### Fetch plan catalog via cURL

Source: https://docs.social-api.ai/guides/rate-limits

Retrieve the full list of available plans and their associated resource limits.

```bash
curl https://api.social-api.ai/v1/billing/plans \
  -H "Authorization: Bearer $SOCIALAPI_KEY"
```

--------------------------------

### GET /v1/inbox/conversations

Source: https://docs.social-api.ai/connectors/twitter

Retrieves a list of direct message conversations.

```APIDOC
## GET /v1/inbox/conversations

### Description
Retrieves a list of direct message conversations for a specific account.

### Method
GET

### Endpoint
https://api.social-api.ai/v1/inbox/conversations

### Parameters
#### Query Parameters
- **account_id** (string) - Required - The account ID
```

--------------------------------

### Connect a YouTube account

Source: https://docs.social-api.ai/connectors/youtube

Initiates the OAuth flow by sending a POST request to the connect endpoint. Redirect the user to the returned auth_url to complete authorization.

```bash
curl -X POST https://api.social-api.ai/v1/accounts/connect \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "youtube",
    "redirect_uri": "https://app.example.com/oauth/callback",
    "state": "session_abc123"
  }'
```

--------------------------------

### GET /v1/posts

Source: https://docs.social-api.ai/posts/tiktok

Retrieves TikTok posts stored in the SocialAPI database.

```APIDOC
## GET /v1/posts

### Description
Returns TikTok posts stored in the SocialAPI database. Posts created through SocialAPI are stored immediately, while native TikTok posts are fetched via background sync.

### Method
GET

### Endpoint
/v1/posts
```

--------------------------------

### Publish a post

Source: https://docs.social-api.ai/quickstart

Creates and publishes a text post to specified accounts. Use publish_now to trigger immediate delivery or omit to save as a draft.

```bash
curl -X POST https://api.social-api.ai/v1/posts \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello world from SocialAPI!",
    "publish_now": true,
    "targets": [
      { "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J" }
    ]
  }'
```

```json
{
  "id": "p_01HZ9X3Q4R5M6N7P8V2K0W1J",
  "text": "Hello world from SocialAPI!",
  "status": "publishing",
  "hidden": false,
  "retry_count": 0,
  "created_at": "2026-04-15T12:00:00Z",
  "updated_at": "2026-04-15T12:00:00Z",
  "targets": [
    {
      "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J",
      "platform": "instagram",
      "status": "publishing"
    }
  ]
}
```

--------------------------------

### Create a video post

Source: https://docs.social-api.ai/posts/facebook

Publish a video by providing a single video ID in the media_ids array. The title field in platform_data is supported for video posts.

```bash
curl -X POST https://api.social-api.ai/v1/posts \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "targets": [{ "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J" }],
    "text": "Watch our latest brand film.",
    "media_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"]
  }'
```

--------------------------------

### GET /.well-known/oauth-authorization-server

Source: https://docs.social-api.ai/guides/oauth

Retrieves RFC 8414 metadata for the authorization server.

```APIDOC
## GET /.well-known/oauth-authorization-server

### Description
Retrieves RFC 8414 metadata discovery information for the authorization server.

### Method
GET

### Endpoint
/.well-known/oauth-authorization-server
```

--------------------------------

### Connection initiation response

Source: https://docs.social-api.ai/connectors/whatsapp

The expected JSON response containing the auth URL, state token, and configuration metadata.

```json
{
  "auth_url": "",
  "state": "<CSRF token, bound to your API key, 10-minute TTL>",
  "metadata": {
    "app_id": "...",
    "config_id": "...",
    "solution_id": "..."
  }
}
```

--------------------------------

### GET /oauth/authorize

Source: https://docs.social-api.ai/guides/oauth

Redirects the user to the authorization server to grant access.

```APIDOC
## GET /oauth/authorize

### Description
Initiates the user authorization flow. PKCE is required.

### Method
GET

### Endpoint
/oauth/authorize

### Query Parameters
- **client_id** (string) - Required - The client ID
- **redirect_uri** (string) - Required - The redirect URI
- **response_type** (string) - Required - Must be 'code'
- **scope** (string) - Optional - Defaults to 'social:all'
- **state** (string) - Required - CSRF protection value
- **code_challenge** (string) - Required - PKCE challenge
- **code_challenge_method** (string) - Required - Must be 'S256'
```

--------------------------------

### GET /v1/inbox/conversations/:id/messages

Source: https://docs.social-api.ai/guides/inbox

Retrieve messages within a specific conversation.

```APIDOC
## GET /v1/inbox/conversations/:id/messages

### Description
Get messages in a conversation.

### Method
GET

### Endpoint
/v1/inbox/conversations/:id/messages

### Parameters
#### Path Parameters
- **id** (string) - Required - The conversation ID
```

--------------------------------

### POST /posts

Source: https://docs.social-api.ai/api-reference/posts/create-or-schedule-a-post

Creates a new post. If targets are provided and PublishNow is true, it publishes immediately. If scheduled_at is provided, it queues the post. Otherwise, it saves the post as a draft.

```APIDOC
## POST /posts

### Description
Creates a new post. Depending on the parameters provided, the post can be published immediately, scheduled for a later time, or saved as a draft.

### Method
POST

### Endpoint
/posts

### Request Body
- **text** (string) - Required - The post body content.
- **title** (string) - Optional - An optional post title (used by LinkedIn, Google).
- **targets** (array) - Optional - Specifies which connected accounts to publish to.
- **segments** (array) - Optional - Continuation posts for native threads.
- **scheduled_at** (string) - Optional - RFC3339 timestamp to queue the post for future publication.
- **publish_now** (boolean) - Optional - If true, publishes immediately (ignores scheduled_at).
- **visibility** (string) - Optional - Controls post visibility (public, private, connections_only, logged_in).
- **skip_validation** (boolean) - Optional - Bypasses pre-publish validation.
- **skip_duplicate_check** (boolean) - Optional - Bypasses duplicate content detection.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the created post.
- **status** (string) - The current status of the post (draft, scheduled, publishing, published, etc.).
- **created_at** (string) - Timestamp of creation.
```

--------------------------------

### Initiate platform account connection via cURL

Source: https://docs.social-api.ai/guides/oauth

Use this request to start the OAuth connection process for a specific social platform.

```bash
curl -X POST https://api.social-api.ai/v1/accounts/connect \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "instagram",
    "redirect_uri": "https://app.example.com/oauth/callback",
    "state": "session_abc123"
  }'
```

--------------------------------

### GET /v1/inbox/conversations

Source: https://docs.social-api.ai/guides/inbox

List DM conversations with optional filtering and pagination.

```APIDOC
## GET /v1/inbox/conversations

### Description
List DM conversations.

### Method
GET

### Endpoint
/v1/inbox/conversations

### Parameters
#### Query Parameters
- **account_id** (string) - Optional - Filter by connected account ID
- **platform** (string) - Optional - Filter by platform (e.g., instagram, facebook)
- **status** (string) - Optional - Conversation status: active or archived (Default: active)
- **limit** (integer) - Optional - Page size (1-100) (Default: 25)
- **cursor** (string) - Optional - Pagination cursor from the previous response
```

--------------------------------

### GET /v1/inbox/comments/:postId/:commentId/replies

Source: https://docs.social-api.ai/guides/inbox

List replies to a specific comment.

```APIDOC
## GET /v1/inbox/comments/:postId/:commentId/replies

### Description
List replies to a specific comment.

### Method
GET

### Endpoint
/v1/inbox/comments/:postId/:commentId/replies

### Parameters
#### Path Parameters
- **postId** (string) - Required - Platform post ID
- **commentId** (string) - Required - SocialAPI interaction ID
```

--------------------------------

### Create API Key

Source: https://docs.social-api.ai/guides/authentication

Create a new API key via the API. The full key is returned only once.

```bash
curl -X POST https://api.social-api.ai/v1/keys \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production App"}'
```

--------------------------------

### Publish Scheduled Video

Source: https://docs.social-api.ai/posts/youtube

Create a post with YouTube-specific settings and a scheduled publish time.

```bash
curl -X POST https://api.social-api.ai/v1/posts \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "targets": [{ "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J" }],
    "title": "Spring collection walkthrough",
    "text": "A full tour of the new lineup. Chapters below.",
    "visibility": "private",
    "media_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"],
    "first_comment": "Which piece is your favorite? Let us know below.",
    "platform_data": {
      "youtube": {
        "category_id": "22",
        "tags": ["fashion", "spring", "lookbook"],
        "publish_at": "2026-04-15T10:00:00Z",
        "notify_subscribers": true,
        "playlist_id": "PL0123456789abcdef"
      }
    }
  }'
```

--------------------------------

### GET /v1/inbox/comments/{videoId}

Source: https://docs.social-api.ai/connectors/youtube

Retrieves comments for a specific YouTube video.

```APIDOC
## GET /v1/inbox/comments/{videoId}

### Description
Retrieves a list of comments for a specific video identified by its ID.

### Method
GET

### Endpoint
/v1/inbox/comments/{videoId}

### Parameters
#### Path Parameters
- **videoId** (string) - Required - The unique identifier of the video.

### Response
#### Success Response (200)
- **data** (array) - List of comment objects.
- **count** (integer) - Total number of comments returned.
```

--------------------------------

### Retrieve Interaction Object

Source: https://docs.social-api.ai/guides/concepts

Example of a full interaction object showing the ID prefix, platform metadata, and capability flags.

```json
{
  "id": "sapi_cmt_GXRM4BNTW7KFYSD3HAEV6QJZ2CLP9U",
  "platform": "instagram",
  "type": "comment",
  "author": {
    "id": "17841405793187218",
    "name": "Jane Smith"
  },
  "content": { "text": "Love this product!" },
  "created_at": "2026-04-15T14:30:00Z",
  "capabilities": {
    "can_reply": true,
    "can_delete": true,
    "can_hide": true,
    "can_like": false,
    "can_private_reply": true
  }
}
```
Tokens:
Raw