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, linkedin, tiktok, 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, reconnect, refresh, and disconnect do not accept Bearer API keys. New account connections can be initiated with a Bearer key through the hosted connect endpoints below; social consent still happens in the user's browser.

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 5 social media platforms through a single integration. Connect your accounts in the dashboard, then reference them by platform name in API requests.

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 any set, or delete a set when at least one other set remains. 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. The public hosted-connect API can create and poll new browser-assisted connections. Existing dashboard reconnect, refresh, disconnect, and dashboard Facebook Page-selection routes remain session-only.

{
  "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 start a browser-assisted connection or discover connected publishing accounts before creating and 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 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.

{
  "connectRequest": {
    "id": "11111111-1111-4111-8111-111111111111",
    "platform": "instagram",
    "platformSetId": "22222222-2222-4222-8222-222222222222",
    "status": "pending",
    "connectUrl": "https://ampost.io/connect/11111111-1111-4111-8111-111111111111#token=<one-time-token>",
    "createdAt": "2026-07-14T12:00:00.000Z",
    "expiresAt": "2026-07-14T12:10:00.000Z"
  }
}

{
  "connectRequest": {
    "id": "11111111-1111-4111-8111-111111111111",
    "platform": "instagram",
    "platformSetId": "22222222-2222-4222-8222-222222222222",
    "status": "connected",
    "connectionId": "33333333-3333-4333-8333-333333333333",
    "error": null,
    "createdAt": "2026-07-14T12:00:00.000Z",
    "expiresAt": "2026-07-14T12:10:00.000Z",
    "completedAt": "2026-07-14T12:02:14.000Z",
    "updatedAt": "2026-07-14T12:02:14.000Z"
  }
}

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, Threads, TikTok, and LinkedIn media posts use the same endpoint. For JSON requests, TikTok 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.

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, and analytics and comment-management APIs are not part of this launch.

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.