You can drive your Inrō account from your own code with the Private API (a REST API, meaning you talk to it over normal web requests that return JSON). Read and update contacts, trigger scenarios, manage campaigns and folders, configure your AI agent, and more. Most of what you do in the dashboard, you can also do here.

This article is the home base for the API: how to authenticate, where the docs are, and the limits to design around. Each resource has its own how-to (linked at the end).

Before you start

The API needs a Pro or Trial subscription. Free accounts can't call it (you'll get a 403).
Everything is scoped to one organization (one Instagram account = one Inrō organization). Your token only ever touches that account's data.

Get your API token

The Private API and the MCP Server both live in the same place.

Open the account menu (bottom-left) and go to Integrations & API.
Find the Private API card. Your token is shown there.
Click to copy it.

Integrations & API page showing the Private API token card and the MCP Server card

Private API card showing the token field with a copy button and a regenerate option

Send the token as a Bearer token in the Authorization header on every request:

Authorization: Bearer YOUR_API_TOKEN

⚠️ Keep your token private. Anyone who has it can act on your whole account. If it leaks, regenerate it from the same card. The old token stops working the moment you regenerate.

The base URL

The API lives on the api. subdomain, and every path is under /api/v1:

https://api.inro.social/api/v1

So the contacts list, for example, is https://api.inro.social/api/v1/contacts.

Make your first request

Here's how to look up a single contact by username:

curl -X GET \  -H "Authorization: Bearer YOUR_API_TOKEN" \  -H "Content-Type: application/json" \  "https://api.inro.social/api/v1/contact?username=jane_example"

The API returns JSON. The /contact (singular) endpoint finds one contact by exactly one of id, username, or email. Use /contacts (plural) for the paginated list and search.

Find the full reference

Every endpoint, parameter, and response shape is documented in the interactive API docs:

api.inro.social/api_doc.html renders the live API reference, so it always matches what the API actually accepts.

The how-to articles in this collection cover the common tasks: updating contacts in bulk, building scenarios and campaigns from JSON, configuring your AI agent, sending rich messages, and more.

What you can build

A few common patterns:

Sync Inrō contacts with an external database or CRM on a schedule.
Trigger a scenario for a contact from your own backend, and pass custom data into it.
Update properties or folder assignments for thousands of contacts at once.
Build a custom dashboard that pulls live data from your account.

One thing the API does not do: it can't browse your inbox or pull past conversation history. The public API sends messages and manages your CRM and automations; reading message threads stays in the app.

Rate limits

The API is rate limited per organization. The production limits are:

Window	Limit
Per second	20
Per minute	1,000
Per hour	10,000
Per day	100,000

When you go over, you get a 429 Too Many Requests response with a Retry-After header (seconds to wait) and X-RateLimit-* headers. If you're building a high-volume sync, space out your requests and retry on 429 after the Retry-After delay.

Rate limiting applies to Private API token requests on the /api/v1/ paths. (The MCP Server is a separate surface, covered in its own article.)

Pagination

List endpoints return a bare JSON array and put the page details in response headers: X-Total, X-Total-Pages, X-Page, and X-Per-Page. Use the page and per_page query parameters to walk through results. per_page defaults to 20 and goes up to 1,000.

Authentication beyond the token

The token above is the simplest way in and is right for your own scripts and servers. If you're building an app that connects on behalf of other Inrō users, or connecting an AI agent like Claude or ChatGPT, Inrō also supports OAuth 2.1 (with PKCE) and automatic discovery. The AI-agent path is covered end to end in Connect Your AI Agent to Inrō with the MCP Server.

🐾 Netsuke's Tips

Store your token as an environment variable, not hardcoded in your scripts. That way rotating it doesn't mean editing every file.
There's no sandbox. The API works on your live data, so test writes (triggering scenarios, updating contacts) against a test contact or a throwaway scenario first.
If you're not a developer but want to pull data or take actions, the MCP Server is often the faster path: describe what you want to Claude or ChatGPT and let it call the API for you.