Post to Instagram from an AI Agent

Updated September 2026

How do you post to Instagram from an AI agent?

Connect an Instagram account to Chirpie, then have your agent call POST /api/v1/posts with an account_id, text, and at least one public image URL in media_urls. Instagram is the one platform in Chirpie that requires media — a text-only call is rejected — so the agent's job is always "write the caption, attach the image(s), send." Two to ten images in a single call publish as a carousel.

What do you need before you start?

1. A Chirpie account and an API key (chirpie_sk_…) from the dashboard.
2. An Instagram account connected through Instagram Login.
3. Image URLs that are publicly reachable — Chirpie downloads them server-side, so localhost URLs and signed URLs that expire in seconds will not work.

Connect the account from the dashboard, or start the OAuth flow programmatically:

curl -X POST https://chirpie.ai/api/v1/accounts \
  -H "Authorization: Bearer chirpie_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "platform": "instagram" }'

The response contains an authorization_url. Open it, authorize, and the account appears in GET /api/v1/accounts.

How does the agent find the account ID?

Every post is addressed by Chirpie's own account UUID, not by an Instagram handle. Let the agent list accounts first and pick the Instagram one:

curl https://chirpie.ai/api/v1/accounts \
  -H "Authorization: Bearer chirpie_sk_YOUR_KEY"

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "platform": "instagram",
      "username": "yourbrand",
      "display_name": "Your Brand",
      "max_post_length": 2200,
      "is_active": true
    }
  ]
}

Cache that UUID in the agent's config or environment. It does not change.

How do you publish a single image post?

curl -X POST https://chirpie.ai/api/v1/posts \
  -H "Authorization: Bearer chirpie_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "550e8400-e29b-41d4-a716-446655440000",
    "text": "Behind the scenes of this week of building.",
    "media_urls": ["https://cdn.example.com/bts.jpg"]
  }'

import { ChirpieClient } from "@chirpie/sdk";

const chirpie = new ChirpieClient({ apiKey: process.env.CHIRPIE_API_KEY! });

const post = await chirpie.createPost({
  account_id: process.env.INSTAGRAM_ACCOUNT_ID!,
  text: "Behind the scenes of this week of building.",
  media_urls: ["https://cdn.example.com/bts.jpg"],
});

console.log(post.id, post.status);

chirpie post "Behind the scenes of this week of building." \
  -a 550e8400-e29b-41d4-a716-446655440000 \
  -m https://cdn.example.com/bts.jpg

Chirpie downloads each URL, validates format and size, uploads it to Instagram, and publishes. The response is a post object that carries a platform_post_id once it lands.

How do you publish a carousel?

Pass between 2 and 10 image URLs. Array order is carousel order.

await chirpie.createPost({
  account_id: process.env.INSTAGRAM_ACCOUNT_ID!,
  text: "Five charts from this quarter's report. Swipe through.",
  media_urls: [
    "https://cdn.example.com/chart-1.png",
    "https://cdn.example.com/chart-2.png",
    "https://cdn.example.com/chart-3.png",
    "https://cdn.example.com/chart-4.png",
    "https://cdn.example.com/chart-5.png",
  ],
});

What are the Instagram limits?

How do you schedule an Instagram post?

Add schedule_at with a future ISO 8601 timestamp in UTC:

await chirpie.createPost({
  account_id: process.env.INSTAGRAM_ACCOUNT_ID!,
  text: "New drop, 9am sharp.",
  media_urls: ["https://cdn.example.com/drop.jpg"],
  schedule_at: "2026-10-01T09:00:00Z",
});

Scheduled posts publish within about five minutes of the target time. Media is downloaded and stored the moment you schedule, so a URL that expires later still publishes correctly. Scheduled posts for the same account must be at least five minutes apart.

How do you let Claude or Cursor do this directly?

Add the Chirpie MCP server and the agent gets an Instagram-capable tool without any glue code:

npm install -g chirpie
chirpie login
claude mcp add chirpie -- npx @chirpie/mcp

Then ask: "Post this image to Instagram with a caption about our new pricing." The agent calls chirpie_post with account_id, text, and media_urls.

Prompt patterns that work well

• "Post to Instagram with https://cdn.example.com/launch.png and a caption under 200 characters."
• "Make a 5-image carousel from these URLs with a caption summarising the report."
• "Schedule the Instagram post for 9am UTC tomorrow."

Give the agent the account UUID and at least one image URL in the same instruction — those are the two things it cannot invent.

FAQ

Can an AI agent post text-only to Instagram? No. Instagram's publishing API requires media on every post. Attach at least one image.

Does Chirpie support Instagram video or Reels? Not currently. Images and carousels are supported.

What image hosting works? Any publicly accessible HTTPS URL. S3 objects with public read, a CDN, or your own static host all work. Private or very short-lived signed URLs may fail.

How many images can go in one carousel? Up to 10.

Can I delete an Instagram post through Chirpie? Yes — DELETE /api/v1/posts/:id removes it from Chirpie and from Instagram.

Where do I see engagement? GET /api/v1/analytics/posts/:id returns metrics for a published post.

Next steps

• Posts API reference
• Scheduling
• TypeScript SDK