@igpapi/ios

Instagram private API client for iOS. Covers device signals, request signatures, session handling, and a large chunk of the mobile API surface.

Installation

yarn add @igpapi/ios
Copy

Quick start

import { createIosIgpapi, IosPreLoginFlow, IosPostLoginFlow } from '@igpapi/ios';

const ig = await createIosIgpapi({
  seed: 'any-stable-string', // deterministic device generation
});

// 1. Simulate what the real app does before login
//    (QE sync, launcher sync, etc.)
await ig.run(IosPreLoginFlow({ username: 'your_username' }));

// 2. Authenticate (bloks-based — same flow the app uses)
const login = await ig.loginBloks({ username: 'your_username', password: 'your_password' });
const user = login.logged_in_user;

// 3. Simulate what the real app does after login
//    (timeline warmup, inbox sync, pigeon, etc.)
await ig.run(IosPostLoginFlow());

console.log(`Logged in as ${user.username} (${user.pk_id})`);

// Now use the API
const info = await ig.users.info({ id: user.pk_id });
Copy

ig.loginBloks is the login flow the real Instagram app uses. There's also ig.loginNative which calls the legacy /accounts/login/ endpoint — kept for reference only, don't use in production.

⚠️ Do not skip pre-login and post-login flows. Instagram fingerprints client behavior. Accounts that authenticate without the surrounding traffic tend to get flagged and checkpointed — sometimes within hours. These flows approximate the requests the app makes around login to reduce that risk.

Persisting sessions

// First run — save snapshot after login
const ig = await createIosIgpapi({ seed: 'my-account' });
await ig.run(IosPreLoginFlow({ username }));
await ig.loginBloks({ username, password });
await ig.run(IosPostLoginFlow());
const snapshot = ig.export();
await fs.writeFile('session.json', JSON.stringify(snapshot));

// Later — restore from snapshot, no re-login
const saved = JSON.parse(await fs.readFile('session.json', 'utf8'));
const ig2 = await createIosIgpapi({ snapshot: saved });
Copy

Start here

createIosIgpapi — the only entry point you need. It returns a runtime object whose type documents every available facade and method. Hover/click through the returned type in the reference to see the full API surface without digging through files.

What's exported

createIosIgpapi returns a runtime with facades for every API surface:

• ig.loginBloks — authentication (recommended); ig.loginNative — legacy, reference only
• ig.users, ig.friendships, ig.account — profile & social graph
• ig.activity, ig.news, ig.live, ig.clips, ig.highlights — feeds
• ig.collections, ig.creatives, ig.restrict, ig.graphqlWww — other endpoints
• ig.run(effect) — escape hatch for composing Effect workflows directly

Requirements

• Node.js ≥ 22
• IGPAPI_LICENSE_TOKEN environment variable

Related packages

• @igpapi/android — Android variant
• @igpapi/core — core types and HTTP infrastructure