API Documentation

Overview

Ampost provides a unified social media API. Instead of integrating each platform individually, you connect to Ampost once and get access to instagram, facebook, twitter, linkedin, tiktok, youtube, threads through a single REST API.

Quickstart

Make your first API call in under a minute:

Public REST and MCP traffic is hosted on https://api.ampost.io. The dashboard, OAuth callbacks, and billing/session flows stay on https://ampost.io. Public API paths on https://ampost.io still respond temporarily for backwards compatibility, but new integrations should use the API host.

curl -X POST https://api.ampost.io/api/v1/posts \
  -H "Authorization: Bearer amp_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "text": "Hello from the Ampost API!",
      "media": [],
      "linkUrl": null,
      "platformOverrides": {}
    },
    "platforms": ["threads"],
    "scheduledFor": null,
    "platformSetId": "set_uuid"
  }'

Authentication

All API requests require a valid API key passed as a Bearer token in the Authorization header. API keys are created and managed through the Ampost dashboard. Dashboard-only management routes such as /api/keys, billing, and platform OAuth/connection administration do not accept Bearer API keys.

Key format

API keys use the prefix amp_live_ followed by a base64url-encoded random secret. The raw key is shown only once at creation time.

Any valid API key can access the public Ampost API and MCP endpoints that your plan allows. Route-level access is determined by whether an endpoint is part of the public API surface, not by key-level permissions. Ampost API keys are scope-free: the key identifies the owning user, and the endpoint decides whether Bearer-key access is allowed.

Posts

The Posts API is the core of Ampost. Create, retrieve, and manage social media posts across all connected platforms.

{
  "posts": [
    {
      "id": "post_uuid",
      "status": "published",
      "textPreview": "Building in public...",
                      "platforms": ["threads", "instagram"],
      "mediaCount": 1,
      "publishedCount": 2,
      "failedCount": 0,
      "scheduledFor": null,
      "createdAt": "2026-04-30T10:00:00Z",
      "updatedAt": "2026-04-30T10:00:00Z",
      "platformSetId": "set_uuid"
    }
  ],
  "total": 42
}

{
  "post": {
    "id": "post_uuid",
    "userId": "user_xyz",
    "content": { ... },
    "platformPosts": [
      {
        "id": "pp_uuid",
        "platform": "threads",
        "status": "published",
        "publishedUrl": "https://threads.net/user/post/123",
        ...
      }
    ],
    "status": "draft",
    "scheduledFor": null,
    "createdAt": "2026-04-30T10:00:00Z",
    "updatedAt": "2026-04-30T10:00:00Z",
    "platformSetId": "set_uuid"
  }
}

Platforms

Ampost supports 7 social media platforms through a single integration. Connect your accounts in the dashboard, then reference them by platform name in API requests.

YouTube

Ampost's YouTube support is a video-only publishing surface. Requests must include exactly one explicit video object, and the current launch state should be treated as beta unless your Google Cloud project has already cleared YouTube audit requirements for public or unlisted uploads.

{
  "content": {
    "text": "Fallback title for the YouTube upload",
    "media": [
      {
        "url": "https://cdn.example.com/product-demo.mp4",
        "type": "video",
        "filename": "product-demo.mp4",
        "mimeType": "video/mp4",
        "sizeBytes": 18432000,
        "width": 1920,
        "height": 1080,
        "durationSeconds": 45,
        "thumbnailUrl": "https://cdn.example.com/product-demo-thumb.jpg"
      }
    ],
    "linkUrl": null,
    "platformOverrides": {
      "youtube": {
        "settings": {
          "title": "Explicit YouTube title",
          "description": "Launch walkthrough",
          "tags": ["launch", "demo"],
          "categoryId": "28",
          "privacyStatus": "private",
          "notifySubscribers": false,
          "selfDeclaredMadeForKids": false,
          "containsSyntheticMedia": true
        }
      }
    }
  },
  "platforms": ["youtube"],
  "scheduledFor": null,
  "platformSetId": "set_uuid"
}

LinkedIn

Ampost's LinkedIn launch state is member-profile publishing only. The current surface supports text-only posts, image posts, article posts, and one-video posts on behalf of an authenticated member. Organization or Page posting is intentionally gated and is not part of the public launch surface.

Placement

Instagram and Facebook support placement selection to control how content appears. Placements are set via platformOverrides.{platform}.settings.placement and are validated against the media configuration.

Platform Sets

Platform sets group your connected social accounts into named collections. Every post must be scoped to a platform set via platformSetId. Each user can create up to 20 sets.

The public REST surface exposes versioned platform-set endpoints for Bearer API keys. Use them to list sets, create new ones, rename a set, or delete a non-default set. Deleting a set revokes its active platform connections. Dashboard cookie-auth routes remain available separately for the web app.

The canonical public endpoints are /api/v1/platform-sets and /api/v1/platform-sets/:id. The older /api/platforms/sets routes also accept Bearer API keys and dashboard session auth for the same list, create, rename, and delete operations. OAuth connection flows stay outside the public REST and MCP surface: auth URL and callback routes are browser/dashboard entrypoints, while refresh, page selection, and disconnect routes use dashboard session auth rather than Bearer API keys.

{
  "sets": [
    {
      "id": "set_uuid",
      "userId": "user_xyz",
      "name": "My Brand Accounts",
      "isDefault": true,
      "createdAt": "2026-04-30T10:00:00Z",
      "updatedAt": "2026-04-30T10:00:00Z",
      "connectionCount": 3
    }
  ]
}

{
  "set": {
    "id": "set_uuid",
    "userId": "user_xyz",
    "name": "My Brand Accounts",
    "isDefault": false,
    "createdAt": "2026-04-30T10:00:00Z",
    "updatedAt": "2026-04-30T10:00:00Z",
    "connectionCount": 0
  }
}

{
  "set": {
    "id": "set_uuid",
    "userId": "user_xyz",
    "name": "Renamed Set",
    "isDefault": false,
    "createdAt": "2026-04-30T10:00:00Z",
    "updatedAt": "2026-05-01T12:00:00Z"
  }
}

{
  "success": true
}

Accounts

Use the versioned account endpoints to discover connected publishing accounts before creating or debugging posts.

Account responses include scopes, platform set membership, token expiry, derived tokenHealth, and non-secret platformMetadata. For TikTok this metadata includes creator publish options such as available privacy levels, disabled comment/duet/stitch flags, and max video duration. For YouTube it includes channel identifiers plus the stored channel-title and subscriber/video/view count snapshot captured at connect time. For LinkedIn it includes the member's subject identifier, basic OIDC profile snapshot, granted scopes, auth-flow marker, and the organization-posting gate state captured at connect time.

Media Upload

Media files are uploaded inline through the public versioned post creation endpoint. Send a multipart/form-data request to /api/v1/posts with a data field (the same JSON body documented for post creation) and one or more files fields (media files). The legacy /api/posts route remains compatible for existing integrations.

Accepted MIME types: image/jpeg, image/png, image/webp, video/mp4, video/quicktime. Max file size: 200 MB per file.

curl -X POST https://api.ampost.io/api/v1/posts \
  -H "Authorization: Bearer amp_live_YOUR_KEY" \
  -F 'data={
    "content":{
      "text":"TikTok launch post",
      "media":[{
        "url":"https://cdn.example.com/launch.mp4",
        "type":"video",
        "filename":"launch.mp4",
        "mimeType":"video/mp4",
        "sizeBytes":18432000,
        "width":1080,
        "height":1920,
        "durationSeconds":24
      }],
      "linkUrl":null,
      "platformOverrides":{
        "tiktok":{"settings":{"privacyLevel":"SELF_ONLY","disableComment":true}}
      }
    },
    "platforms":["tiktok"],
    "scheduledFor":null,
    "platformSetId":"set_uuid"
  }' \
  -F "files=@launch.mp4"

Scheduled Instagram, Facebook, and YouTube media posts use the same endpoint. Attempts to schedule unsupported platforms such as linkedin, threads, or tiktok return a 400 validation error. For JSON requests, TikTok and YouTube should always be sent as explicit content.media objects. LinkedIn strongly prefers explicit media objects as well and requires them for video. TikTok creator visibility is also launch-state sensitive: if the connected TikTok app is limited to private-only posting during audit or Direct Post review, Ampost exposes only the allowed privacy levels and surfaces provider errors instead of assuming public delivery. YouTube supports exactly one video, does not allow image-only or mixed-media posts, and may keep requested public or unlisted uploads private while Google verification or audit is still pending.

LinkedIn Contract

LinkedIn supports member-auth text-only posts, image posts, article posts, and single-video posts. Use platformOverrides.linkedin.text for a LinkedIn-specific text override and platformOverrides.linkedin.settings for visibility, reshare controls, article metadata, and video title metadata. Organization posting remains intentionally gated, analytics and comment-management APIs are not part of this launch, and LinkedIn scheduling is not supported.

Typed content.media objects are recommended for all LinkedIn media and required for video. Bare mediaUrls stay available only for legacy image posts; video-like legacy URLs are rejected because LinkedIn image and video upload flows differ.

{
  "content": {
    "text": "Shipping the new LinkedIn contract today.",
    "media": [],
    "linkUrl": null,
    "platformOverrides": {
      "linkedin": {
        "settings": {
          "visibility": "PUBLIC",
          "isReshareDisabledByAuthor": true
        }
      }
    }
  },
  "platforms": ["linkedin"],
  "scheduledFor": null,
  "platformSetId": "set_uuid"
}

{
  "content": {
    "text": "LinkedIn image post",
    "media": [
      {
        "id": "media-1",
        "url": "https://cdn.example.com/product-shot.png",
        "type": "image",
        "filename": "product-shot.png",
        "mimeType": "image/png",
        "sizeBytes": 248120,
        "width": 1600,
        "height": 900,
        "altText": "Product dashboard with the LinkedIn publish flow open."
      }
    ],
    "linkUrl": null,
    "platformOverrides": {
      "linkedin": {
        "settings": {
          "visibility": "CONNECTIONS"
        }
      }
    }
  },
  "platforms": ["linkedin"],
  "scheduledFor": null,
  "platformSetId": "set_uuid"
}

{
  "content": {
    "text": "LinkedIn demo clip",
    "media": [
      {
        "id": "media-1",
        "url": "https://cdn.example.com/demo.mp4",
        "type": "video",
        "filename": "demo.mp4",
        "mimeType": "video/mp4",
        "sizeBytes": 18432000,
        "width": 1920,
        "height": 1080,
        "durationSeconds": 38,
        "thumbnailUrl": "https://cdn.example.com/demo-thumb.jpg"
      }
    ],
    "linkUrl": null,
    "platformOverrides": {
      "linkedin": {
        "settings": {
          "visibility": "PUBLIC",
          "videoTitle": "Ampost LinkedIn demo"
        }
      }
    }
  },
  "platforms": ["linkedin"],
  "scheduledFor": null,
  "platformSetId": "set_uuid"
}

{
  "text": "This will be rejected",
  "platforms": ["linkedin"],
  "scheduledFor": null,
  "platformSetId": "set_uuid",
  "mediaUrls": ["https://cdn.example.com/demo.mp4"]
}

The invalid legacy example returns a 400 validation error because LinkedIn video posts must use explicit media metadata.

Rate Limits

Ampost enforces tier-based rate limiting to ensure fair usage. Rate limits vary by operation and plan. Exceeding a rate limit returns a 429 Too Many Requests response.

Rate limit operations

Quota types

In addition to rate limits, Ampost enforces monthly quotas depending on your plan:

Error Codes

The API returns standard HTTP status codes with JSON error bodies. Post-engine errors include a machine-readable code.