> ## Documentation Index
> Fetch the complete documentation index at: https://mcp.shipcontent.com/llms.txt
> Use this file to discover all available pages before exploring further.

---
title: Instagram
description: Connect, check readiness and prepare owner approval.
section: reference
order: 70
status: implemented
mode: both
generated: true
sourceOfTruth: [src/lib/mcp/agent-tools.ts, src/lib/server/mcp/AgentMcp.ts, src/lib/docs/handoffs.ts, src/lib/docs/channels.ts]
tools: [start_instagram_connection, get_instagram_connection, list_instagram_connections, prepare_instagram_destination, prepare_instagram_readiness, get_instagram_readiness, prepare_instagram_approval, get_instagram_approval, publish_instagram_reel]
---

Instagram tools prepare owner handoffs for connection, destination, readiness and exact approval. Only the signed-in owner can make those decisions. If the owner allows one agent to publish to one account, `publish_instagram_reel` publishes an exact saved Reel without a review for each post. The agent never receives a provider credential or OAuth state. Approval can queue one publication job; read its final state and provider receipt before reporting delivery.

Quoted text is the tool description your client receives from `tools/list`.

## Tools on this page

- [`start_instagram_connection`](#start_instagram_connection)
- [`get_instagram_connection`](#get_instagram_connection)
- [`list_instagram_connections`](#list_instagram_connections)
- [`prepare_instagram_destination`](#prepare_instagram_destination)
- [`prepare_instagram_readiness`](#prepare_instagram_readiness)
- [`get_instagram_readiness`](#get_instagram_readiness)
- [`prepare_instagram_approval`](#prepare_instagram_approval)
- [`get_instagram_approval`](#get_instagram_approval)
- [`publish_instagram_reel`](#publish_instagram_reel)

---

### start_instagram_connection {#start_instagram_connection}

<div class="doc-fact-strip"><dl><dt>Title</dt><dd>Connect Instagram Account <em>as sent in tools/list</em></dd><dt>Transport</dt><dd>Streamable HTTP at <code>/mcp</code></dd><dt>Annotations</dt><dd><span class="doc-chip" data-kind="annotation" data-value="readOnlyHint:false">readOnlyHint false</span> <span class="doc-chip" data-kind="annotation" data-value="destructiveHint:false">destructiveHint false</span> <span class="doc-chip" data-kind="annotation" data-value="idempotentHint:true">idempotentHint true</span> <span class="doc-chip" data-kind="annotation" data-value="openWorldHint:false">openWorldHint false</span> <em>as sent in tools/list</em></dd><dt>Owner handoff</dt><dd>Yes. <code>/connect/instagram</code> from <code>connectionUrl</code></dd><dt>Idempotency key</dt><dd><code>requestId</code></dd><dt>Revision guard</dt><dd>None</dd></dl></div>

> Create a saved owner handoff to connect the owner's professional Instagram account. Reuse requestId after a lost response. This call does not contact Instagram, grant provider access, change a post destination, or approve publication. Only the signed-in owner can continue: connectionUrl (/connect/instagram) sends the owner straight to Instagram and keeps the request bound to this agent. Returns the owner's open request when one exists, whoever started it; the owner can also start from the Connections page. Use get_instagram_connection or list_instagram_connections to resume saved progress.

#### Input

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `workspaceId` | string (UUID) | yes |  |
| `requestId` | string (UUID) | yes |  |

Unknown fields are rejected.

#### Result

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `connection` | object | yes |  |
| `connectionUrl` | string (URL) | yes |  |

The result carries no other fields.

**`connection.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `id` | string (UUID) | yes |  |
| `requestId` | string (UUID) | yes |  |
| `status` | `"pending"` \| `"authorizing"` \| `"exchanging"` \| `"connected"` \| `"denied"` \| `"cancelled"` \| `"failed"` \| `"unknown"` \| `"expired"` | yes |  |
| `connectionId` | string (UUID) | yes |  |
| `createdAt` | string (date-time) | yes |  |
| `expiresAt` | string (date-time) | yes |  |
| `activeUntil` | string (date-time) or null | yes |  |
| `account` | object or null | yes |  |
| `failureCode` | string or null | yes | min length 1; max length 100 |
| `lifecycle` | object or null | yes |  |

The result carries no other fields.

**`connection.account.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `accountId` | string | yes | pattern `^[0-9]{1,200}$` |
| `username` | string | yes | min length 1; max length 100 |
| `accountType` | `"BUSINESS"` \| `"MEDIA_CREATOR"` | yes |  |
| `expiresAt` | string (date-time) | yes |  |
| `verifiedAt` | string (date-time) | yes |  |

The result carries no other fields.

**`connection.lifecycle.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `status` | `"connected"` \| `"refreshing"` \| `"reconnect-required"` \| `"disconnected"` | yes |  |
| `credentialVersion` | string (UUID) or null | yes |  |
| `refreshAvailableAt` | string (date-time) or null | yes |  |
| `lastRefresh` | object or null | yes |  |

The result carries no other fields.

Every successful result is also returned as `structuredContent`.

#### Replay and conflicts

Reuse the same `requestId` with identical input to recover a lost response; the original result is returned. Changed input with the same ID is rejected. A new ID creates a new operation. See [Request IDs, replay and recovery](/docs/contracts/request-ids).

#### Owner handoff

The owner URL is `connectionUrl` for `/connect/instagram`. Give that URL to the owner and stop. The URL grants no access by itself.

- What the owner does: Connect the professional account.
- What the agent reads: `get_instagram_connection`, field `lifecycle.status`.

---

### get_instagram_connection {#get_instagram_connection}

<div class="doc-fact-strip"><dl><dt>Title</dt><dd>Get Instagram Connection <em>as sent in tools/list</em></dd><dt>Transport</dt><dd>Streamable HTTP at <code>/mcp</code></dd><dt>Annotations</dt><dd><span class="doc-chip" data-kind="annotation" data-value="readOnlyHint:true">readOnlyHint true</span> <span class="doc-chip" data-kind="annotation" data-value="destructiveHint:false">destructiveHint false</span> <span class="doc-chip" data-kind="annotation" data-value="idempotentHint:true">idempotentHint true</span> <span class="doc-chip" data-kind="annotation" data-value="openWorldHint:false">openWorldHint false</span> <em>as sent in tools/list</em></dd><dt>Owner handoff</dt><dd>Yes. <code>/connect/instagram</code> from <code>connectionUrl</code></dd><dt>Idempotency key</dt><dd>None</dd><dt>Revision guard</dt><dd>None</dd></dl></div>

> Read a saved Instagram connection request, its current account lifecycle, and protected owner link. For an open request the link goes straight to Instagram; otherwise it opens Connections, where the owner can refresh eligible access or disconnect ShipContent. This tool does not contact Instagram. Use lifecycle.status for current access; operation status records the original consent. A connected identity does not prove media readiness or approve publication. Unknown exchanges or refreshes must not be retried with a new request. Local disconnection does not claim Meta grant revocation. Provider credentials and OAuth state are never returned.

#### Input

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `workspaceId` | string (UUID) | yes |  |
| `operationId` | string (UUID) | yes |  |

Unknown fields are rejected.

#### Result

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `connection` | object | yes |  |
| `connectionUrl` | string (URL) | yes |  |

The result carries no other fields.

**`connection.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `id` | string (UUID) | yes |  |
| `requestId` | string (UUID) | yes |  |
| `status` | `"pending"` \| `"authorizing"` \| `"exchanging"` \| `"connected"` \| `"denied"` \| `"cancelled"` \| `"failed"` \| `"unknown"` \| `"expired"` | yes |  |
| `connectionId` | string (UUID) | yes |  |
| `createdAt` | string (date-time) | yes |  |
| `expiresAt` | string (date-time) | yes |  |
| `activeUntil` | string (date-time) or null | yes |  |
| `account` | object or null | yes |  |
| `failureCode` | string or null | yes | min length 1; max length 100 |
| `lifecycle` | object or null | yes |  |

The result carries no other fields.

**`connection.account.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `accountId` | string | yes | pattern `^[0-9]{1,200}$` |
| `username` | string | yes | min length 1; max length 100 |
| `accountType` | `"BUSINESS"` \| `"MEDIA_CREATOR"` | yes |  |
| `expiresAt` | string (date-time) | yes |  |
| `verifiedAt` | string (date-time) | yes |  |

The result carries no other fields.

**`connection.lifecycle.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `status` | `"connected"` \| `"refreshing"` \| `"reconnect-required"` \| `"disconnected"` | yes |  |
| `credentialVersion` | string (UUID) or null | yes |  |
| `refreshAvailableAt` | string (date-time) or null | yes |  |
| `lastRefresh` | object or null | yes |  |

The result carries no other fields.

Every successful result is also returned as `structuredContent`.

#### Owner handoff

The owner URL is `connectionUrl` for `/connect/instagram`. Give that URL to the owner and stop. The URL grants no access by itself.

- What the owner does: Finish the connection, or open Connections to refresh or disconnect.
- What the agent reads: `get_instagram_connection`, field `lifecycle.status`.

---

### list_instagram_connections {#list_instagram_connections}

<div class="doc-fact-strip"><dl><dt>Title</dt><dd>List Instagram Connections <em>as sent in tools/list</em></dd><dt>Transport</dt><dd>Streamable HTTP at <code>/mcp</code></dd><dt>Annotations</dt><dd><span class="doc-chip" data-kind="annotation" data-value="readOnlyHint:true">readOnlyHint true</span> <span class="doc-chip" data-kind="annotation" data-value="destructiveHint:false">destructiveHint false</span> <span class="doc-chip" data-kind="annotation" data-value="idempotentHint:true">idempotentHint true</span> <span class="doc-chip" data-kind="annotation" data-value="openWorldHint:false">openWorldHint false</span> <em>as sent in tools/list</em></dd><dt>Owner handoff</dt><dd>No</dd><dt>Idempotency key</dt><dd>None</dd><dt>Revision guard</dt><dd>None</dd></dl></div>

> Discover up to 25 saved Instagram connection requests after reconnecting or losing chat history, with current account lifecycle and protected owner links. Resume the existing link for consent, or open Connections for refresh or local disconnection. This reads saved metadata only; it does not contact Instagram or change publication authority.

#### Input

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `workspaceId` | string (UUID) | yes |  |

Unknown fields are rejected.

#### Result

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `connections` | array of object | yes | max items 25 |

The result carries no other fields.

**`connections[]`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `connection` | object | yes |  |
| `connectionUrl` | string (URL) | yes |  |

The result carries no other fields.

**`connections[].connection.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `id` | string (UUID) | yes |  |
| `requestId` | string (UUID) | yes |  |
| `status` | `"pending"` \| `"authorizing"` \| `"exchanging"` \| `"connected"` \| `"denied"` \| `"cancelled"` \| `"failed"` \| `"unknown"` \| `"expired"` | yes |  |
| `connectionId` | string (UUID) | yes |  |
| `createdAt` | string (date-time) | yes |  |
| `expiresAt` | string (date-time) | yes |  |
| `activeUntil` | string (date-time) or null | yes |  |
| `account` | object or null | yes |  |
| `failureCode` | string or null | yes | min length 1; max length 100 |
| `lifecycle` | object or null | yes |  |

The result carries no other fields.

Every successful result is also returned as `structuredContent`.

---

### prepare_instagram_destination {#prepare_instagram_destination}

<div class="doc-fact-strip"><dl><dt>Title</dt><dd>Request Instagram Account Choice <em>as sent in tools/list</em></dd><dt>Transport</dt><dd>Streamable HTTP at <code>/mcp</code></dd><dt>Annotations</dt><dd><span class="doc-chip" data-kind="annotation" data-value="readOnlyHint:true">readOnlyHint true</span> <span class="doc-chip" data-kind="annotation" data-value="destructiveHint:false">destructiveHint false</span> <span class="doc-chip" data-kind="annotation" data-value="idempotentHint:true">idempotentHint true</span> <span class="doc-chip" data-kind="annotation" data-value="openWorldHint:false">openWorldHint false</span> <em>as sent in tools/list</em></dd><dt>Owner handoff</dt><dd>Yes. <code>/posts/review</code> from <code>review.url</code></dd><dt>Idempotency key</dt><dd>None</dd><dt>Revision guard</dt><dd>None</dd></dl></div>

> Prepare an owner-only account-selection link for one saved draft. The owner chooses a connected professional Instagram account in the browser, which sets the post to Instagram and video. Use inspect_post afterward to read the saved account and destinationConnectionId. This read-only call does not select an account, contact Instagram, verify readiness, approve, or publish.

#### Input

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `workspaceId` | string (UUID) | yes |  |
| `postId` | string (UUID) | yes |  |

Unknown fields are rejected.

#### Result

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `postId` | string (UUID) | yes |  |
| `review` | object | yes |  |

The result carries no other fields.

**`review.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `available` | **always** `true` | yes |  |
| `requiresOwner` | **always** `true` | yes |  |
| `url` | string (URL) | yes |  |

The result carries no other fields.

Every successful result is also returned as `structuredContent`.

#### Owner handoff

The owner URL is `review.url` for `/posts/review`. Give that URL to the owner and stop. The URL grants no access by itself.

- What the owner does: Confirm the destination account for the post.
- What the agent reads: `inspect_post`, the saved account and `destinationConnectionId` inside `postReview`.

---

### prepare_instagram_readiness {#prepare_instagram_readiness}

<div class="doc-fact-strip"><dl><dt>Title</dt><dd>Request Instagram Readiness Check <em>as sent in tools/list</em></dd><dt>Transport</dt><dd>Streamable HTTP at <code>/mcp</code></dd><dt>Annotations</dt><dd><span class="doc-chip" data-kind="annotation" data-value="readOnlyHint:true">readOnlyHint true</span> <span class="doc-chip" data-kind="annotation" data-value="destructiveHint:false">destructiveHint false</span> <span class="doc-chip" data-kind="annotation" data-value="idempotentHint:true">idempotentHint true</span> <span class="doc-chip" data-kind="annotation" data-value="openWorldHint:false">openWorldHint false</span> <em>as sent in tools/list</em></dd><dt>Owner handoff</dt><dd>Yes. <code>/posts/review</code> from <code>review.url</code></dd><dt>Idempotency key</dt><dd>None</dd><dt>Revision guard</dt><dd>None</dd></dl></div>

> Prepare a protected owner handoff to check this exact Instagram video draft. This read-only tool makes no provider calls and creates no check. The signed-in owner starts one durable check in the review page. Use get_instagram_readiness to read its current result after reload or response loss. Checks cover measured video properties and current account access; Instagram processing, approval and publication remain unverified.

#### Input

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `workspaceId` | string (UUID) | yes |  |
| `postId` | string (UUID) | yes |  |

Unknown fields are rejected.

#### Result

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `postId` | string (UUID) | yes |  |
| `review` | object | yes |  |

The result carries no other fields.

**`review.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `available` | **always** `true` | yes |  |
| `requiresOwner` | **always** `true` | yes |  |
| `url` | string (URL) | yes |  |

The result carries no other fields.

Every successful result is also returned as `structuredContent`.

#### Owner handoff

The owner URL is `review.url` for `/posts/review`. Give that URL to the owner and stop. The URL grants no access by itself.

- What the owner does: Open the readiness result for the post.
- What the agent reads: `get_instagram_readiness`.

---

### get_instagram_readiness {#get_instagram_readiness}

<div class="doc-fact-strip"><dl><dt>Title</dt><dd>Get Instagram Readiness <em>as sent in tools/list</em></dd><dt>Transport</dt><dd>Streamable HTTP at <code>/mcp</code></dd><dt>Annotations</dt><dd><span class="doc-chip" data-kind="annotation" data-value="readOnlyHint:true">readOnlyHint true</span> <span class="doc-chip" data-kind="annotation" data-value="destructiveHint:false">destructiveHint false</span> <span class="doc-chip" data-kind="annotation" data-value="idempotentHint:true">idempotentHint true</span> <span class="doc-chip" data-kind="annotation" data-value="openWorldHint:false">openWorldHint false</span> <em>as sent in tools/list</em></dd><dt>Owner handoff</dt><dd>No</dd><dt>Lookup key</dt><dd><code>requestId</code> selects a saved request. It is not an idempotency key.</dd><dt>Revision guard</dt><dd>None</dd></dl></div>

> Read the latest exact-post Instagram preflight, or a saved requestId, without repeating private-media or provider work. A result becomes stale after a change to the caption, media, channel or account, a credential or authority change, or when validity expires. mediaIssue reports the failed video rule, measured value, required value and export action when inspection fails. Passed preflight does not approve publication, reserve quota or prove provider processing. Null means no check is saved; unknown is not success.

**When to call it**

Read the saved video and account check after the owner selects **Publish**, or after a response is lost. Supply the same `requestId` to read that exact result. This read does not inspect again or publish.

A failed video check includes `readiness.mediaIssue` with the failed `rule`, a plain `message`, the measured `actual` value when available, and the `expected` value. For example, a frame-rate failure can report `rule: "frame_rate"`, `actual: 12`, and `expected: "23 to 60 fps"`. The field is `null` when no video inspection failure was recorded. It contains no file paths, process output or credentials. Explain the saved failure and its action instead of asking for approval again.

#### Input

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `workspaceId` | string (UUID) | yes |  |
| `postId` | string (UUID) | yes |  |
| `requestId` | string (UUID) | no |  |

Unknown fields are rejected.

#### Result

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `readiness` | object or null | yes |  |

The result carries no other fields.

**`readiness.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `id` | string (UUID) | yes |  |
| `requestId` | string (UUID) | yes |  |
| `postId` | string (UUID) | yes |  |
| `connectionId` | string (UUID) | yes |  |
| `accountId` | string | yes | pattern `^[0-9]{1,200}$` |
| `credentialVersion` | string (UUID) | yes |  |
| `asset` | object | yes |  |
| `format` | `"image"` \| `"carousel"` \| `"video"` \| `"story"` | no |  |
| `placement` | `"default"` \| `"reel"` | no |  |
| `assets` | array of object or null | no | min items 1; max items 10 |
| `status` | `"checking"` \| `"passed"` \| `"blocked"` \| `"unknown"` \| `"stale"` | yes |  |
| `resultStatus` | `"passed"` \| `"blocked"` \| `"unknown"` or null | yes |  |
| `createdAt` | string (date-time) | yes |  |
| `activeUntil` | string (date-time) | yes |  |
| `checkedAt` | string (date-time) or null | yes |  |
| `validUntil` | string (date-time) or null | yes |  |
| `mediaStatus` | `"passed"` \| `"blocked"` \| `"unknown"` \| `"not_checked"` | yes |  |
| `mediaIssue` | object or null | yes | default `null` |
| `providerStatus` | `"passed"` \| `"blocked"` \| `"unknown"` \| `"not_checked"` | yes |  |
| `blockers` | array of `"INSTAGRAM_ACCOUNT_MISMATCH"` \| `"INSTAGRAM_ACCESS_DENIED"` \| `"INSTAGRAM_QUOTA_EXHAUSTED"` \| `"INSTAGRAM_PROVIDER_UNAVAILABLE"` \| `"INSTAGRAM_MEDIA_INVALID"` \| `"INSTAGRAM_STORY_ACCOUNT_UNSUPPORTED"` \| `"INSTAGRAM_REEL_MEDIA_INVALID"` \| `"INSTAGRAM_REEL_INSPECTION_UNAVAILABLE"` \| `"MEDIA_CHANGED"` \| `"MEDIA_UNAVAILABLE"` \| `"CREDENTIAL_UNAVAILABLE"` \| `"CHECK_CANCELLED"` \| `"CHECK_UNAVAILABLE"` | yes | max items 10 |

The result carries no other fields.

**`readiness.asset.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `id` | string (UUID) | yes |  |
| `size` | integer | yes | max 9007199254740991 |

The result carries no other fields.

**`readiness.assets[]`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `id` | string (UUID) | yes |  |
| `size` | integer | yes | max 9007199254740991 |
| `kind` | `"image"` \| `"video"` | yes |  |
| `sha256` | string or null | no | pattern `^[a-f0-9]{64}$` |

The result carries no other fields.

**`readiness.mediaIssue.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `rule` | string | yes | pattern `^[a-z][a-z0-9_]{0,63}$` |
| `message` | string | yes | min length 1; max length 500 |
| `actual` | number or string or boolean or null | yes |  |
| `expected` | string | yes | min length 1; max length 120 |

The result carries no other fields.

Every successful result is also returned as `structuredContent`.

#### Errors

- `AUTH_REQUIRED`
- `AUTH_NOT_CONFIGURED`
- `FORBIDDEN`
- `INVALID_INPUT`
- `NOT_FOUND`
- `READINESS_STORAGE_UNAVAILABLE`
- `DATABASE_UNAVAILABLE`

Errors return `isError: true` and `{ code, error }` in `structuredContent`. See [Error codes](/docs/contracts/errors).

#### Related

- [Instagram](/docs/channels/instagram)

---

### prepare_instagram_approval {#prepare_instagram_approval}

<div class="doc-fact-strip"><dl><dt>Title</dt><dd>Request Instagram Reel Approval <em>as sent in tools/list</em></dd><dt>Transport</dt><dd>Streamable HTTP at <code>/mcp</code></dd><dt>Annotations</dt><dd><span class="doc-chip" data-kind="annotation" data-value="readOnlyHint:true">readOnlyHint true</span> <span class="doc-chip" data-kind="annotation" data-value="destructiveHint:false">destructiveHint false</span> <span class="doc-chip" data-kind="annotation" data-value="idempotentHint:true">idempotentHint true</span> <span class="doc-chip" data-kind="annotation" data-value="openWorldHint:false">openWorldHint false</span> <em>as sent in tools/list</em></dd><dt>Owner handoff</dt><dd>Yes. <code>/posts/review</code> from <code>review.url</code></dd><dt>Idempotency key</dt><dd>None</dd><dt>Revision guard</dt><dd>None</dd></dl></div>

> Prepare an owner approval handoff for a saved Reel and passed readiness request. Returns the caption, asset ID, account, publish-now policy, and a manifest hash for the review text. Only the signed-in owner can confirm the reviewed manifest.

**When to call it**

Call this as the last agent step for a Reel, after a passed readiness check for
the current post. Send that check's `readinessRequestId`. The tool is
read-only: it approves nothing, it contacts no Instagram API and it publishes
nothing.

#### Input

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `postId` | string (UUID) | yes |  |
| `readinessRequestId` | string (UUID) | yes |  |
| `workspaceId` | string (UUID) | yes |  |

Unknown fields are rejected.

#### Result

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `manifest` | object (2 shapes) | yes |  |
| `manifestSha256` | string | yes | pattern `^[a-f0-9]{64}$` |
| `review` | object | yes |  |
| `executionAvailable` | **always** `true` | yes |  |

The result carries no other fields.

**`manifest.*`, shape 1**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `version` | **always** `1` | yes |  |
| `workspaceId` | string (UUID) | yes |  |
| `ownerId` | string (UUID) | yes |  |
| `postId` | string (UUID) | yes |  |
| `channel` | **always** `"instagram"` | yes |  |
| `format` | **always** `"video"` | yes |  |
| `caption` | string | yes | max length 2200 |
| `account` | object | yes |  |
| `asset` | object | yes |  |
| `readiness` | object | yes |  |
| `timing` | object | yes |  |
| `trialReel` | `"manual"` \| `"performance"` | no |  |

The result carries no other fields.

**`manifest.account.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `connectionId` | string (UUID) | yes |  |
| `accountId` | string | yes | pattern `^[0-9]{1,200}$` |
| `username` | string | yes | min length 1; max length 100 |
| `accountType` | `"BUSINESS"` \| `"MEDIA_CREATOR"` | yes |  |

The result carries no other fields.

**`manifest.asset.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `id` | string (UUID) | yes |  |
| `size` | integer | yes | min 1; max 52428800 |

The result carries no other fields.

**`manifest.readiness.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `id` | string (UUID) | yes |  |
| `requestId` | string (UUID) | yes |  |
| `credentialVersion` | string (UUID) | yes |  |
| `checkedAt` | string (date-time) | yes |  |
| `validUntil` | string (date-time) | yes |  |

The result carries no other fields.

**`manifest.timing.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `mode` | **always** `"immediate"` | yes |  |
| `maximumDelaySeconds` | **always** `600` | yes |  |

The result carries no other fields.

**`manifest.*`, shape 2**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `version` | **always** `2` | yes |  |
| `workspaceId` | string (UUID) | yes |  |
| `ownerId` | string (UUID) | yes |  |
| `postId` | string (UUID) | yes |  |
| `channel` | **always** `"instagram"` | yes |  |
| `format` | `"image"` \| `"carousel"` \| `"video"` \| `"story"` | yes |  |
| `caption` | string | yes | max length 2200 |
| `account` | object | yes |  |
| `asset` | object | yes |  |
| `readiness` | object | yes |  |
| `timing` | object | yes |  |
| `trialReel` | `"manual"` \| `"performance"` | no |  |
| `placement` | `"default"` \| `"reel"` | yes |  |
| `assets` | array of object | yes | min items 1; max items 10 |

The result carries no other fields.

**`manifest.account.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `connectionId` | string (UUID) | yes |  |
| `accountId` | string | yes | pattern `^[0-9]{1,200}$` |
| `username` | string | yes | min length 1; max length 100 |
| `accountType` | `"BUSINESS"` \| `"MEDIA_CREATOR"` | yes |  |

The result carries no other fields.

**`manifest.asset.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `id` | string (UUID) | yes |  |
| `size` | integer | yes | min 1; max 52428800 |

The result carries no other fields.

**`manifest.readiness.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `id` | string (UUID) | yes |  |
| `requestId` | string (UUID) | yes |  |
| `credentialVersion` | string (UUID) | yes |  |
| `checkedAt` | string (date-time) | yes |  |
| `validUntil` | string (date-time) | yes |  |

The result carries no other fields.

**`manifest.timing.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `mode` | **always** `"immediate"` | yes |  |
| `maximumDelaySeconds` | **always** `600` | yes |  |

The result carries no other fields.

**`manifest.assets[]`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `id` | string (UUID) | yes |  |
| `size` | integer | yes | min 1; max 52428800 |
| `sha256` | string | yes | pattern `^[a-f0-9]{64}$` |
| `kind` | `"image"` \| `"video"` | yes |  |

The result carries no other fields.

**`review.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `available` | **always** `true` | yes |  |
| `requiresOwner` | **always** `true` | yes |  |
| `url` | string (URL) | yes |  |

The result carries no other fields.

Every successful result is also returned as `structuredContent`.

#### Example call

```json
{
  "name": "prepare_instagram_approval",
  "arguments": {
    "workspaceId": "00000000-0000-4000-8000-000000000001",
    "postId": "00000000-0000-4000-8000-000000000007",
    "readinessRequestId": "00000000-0000-4000-8000-000000000018"
  }
}
```

#### Example result

```json
{
  "manifest": {
    "version": 1,
    "workspaceId": "00000000-0000-4000-8000-000000000001",
    "ownerId": "00000000-0000-4000-8000-000000000010",
    "postId": "00000000-0000-4000-8000-000000000007",
    "channel": "instagram",
    "format": "video",
    "caption": "Release health in one screen. Start a 14 day trial.",
    "account": {
      "connectionId": "00000000-0000-4000-8000-000000000019",
      "accountId": "17841400000000000",
      "username": "northstar.analytics",
      "accountType": "BUSINESS"
    },
    "asset": {
      "id": "00000000-0000-4000-8000-000000000012",
      "sha256": "9f2c1a7b4d6e8f0a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f607182",
      "size": 8388608
    },
    "readiness": {
      "id": "00000000-0000-4000-8000-000000000020",
      "requestId": "00000000-0000-4000-8000-000000000018",
      "credentialVersion": "00000000-0000-4000-8000-000000000021",
      "checkedAt": "2026-09-21T09:20:00Z",
      "validUntil": "2026-09-21T09:25:00Z"
    },
    "timing": {
      "mode": "immediate",
      "maximumDelaySeconds": 600
    }
  },
  "manifestSha256": "1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f809",
  "review": {
    "available": true,
    "requiresOwner": true,
    "url": "https://shipcontent.example.com/posts/review?workspaceId=00000000-0000-4000-8000-000000000001&postId=00000000-0000-4000-8000-000000000007&expectedReadinessRequestId=00000000-0000-4000-8000-000000000018&expectedApprovalManifestSha256=1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f809"
  },
  "executionAvailable": true
}
```

#### Errors

- `AUTH_REQUIRED`
- `AUTH_NOT_CONFIGURED`
- `FORBIDDEN`
- `INVALID_INPUT`
- `NOT_FOUND`
- `DRAFT_LOCKED`
- `INSTAGRAM_DESTINATION_UNAVAILABLE`
- `INSTAGRAM_VIDEO_REQUIRED`
- `READINESS_REQUIRED`
- `READINESS_STALE`
- `APPROVAL_STORAGE_UNAVAILABLE`
- `DATABASE_UNAVAILABLE`

Errors return `isError: true` and `{ code, error }` in `structuredContent`. See [Error codes](/docs/contracts/errors).

#### Owner handoff

The owner URL is `review.url` for `/posts/review`. Give that URL to the owner and stop. The URL grants no access by itself.

- What the owner does: Review the current Reel in Marketing → Posts and select Publish.
- What the agent reads: `get_instagram_approval`, field `status`.

Give `review.url` to the owner and read the caption, account and video back to
them first. Their confirmation starts a fixed ten-minute window and locks the
draft. The owner confirmation queues one publication job. Read the final job state and provider receipt; approval alone is not delivery.

#### Related

- [Instagram](/docs/channels/instagram)
- [Approval model](/docs/contracts/approval-model)

---

### get_instagram_approval {#get_instagram_approval}

<div class="doc-fact-strip"><dl><dt>Title</dt><dd>Get Instagram Approval <em>as sent in tools/list</em></dd><dt>Transport</dt><dd>Streamable HTTP at <code>/mcp</code></dd><dt>Annotations</dt><dd><span class="doc-chip" data-kind="annotation" data-value="readOnlyHint:true">readOnlyHint true</span> <span class="doc-chip" data-kind="annotation" data-value="destructiveHint:false">destructiveHint false</span> <span class="doc-chip" data-kind="annotation" data-value="idempotentHint:true">idempotentHint true</span> <span class="doc-chip" data-kind="annotation" data-value="openWorldHint:false">openWorldHint false</span> <em>as sent in tools/list</em></dd><dt>Owner handoff</dt><dd>No</dd><dt>Lookup key</dt><dd><code>requestId</code> selects a saved request. It is not an idempotency key.</dd><dt>Revision guard</dt><dd>None</dd></dl></div>

> Read the latest exact-post owner approval or one saved approve/withdraw requestId. Returns the immutable reviewed manifest, original deadline and current status without repeating an owner action. Owner approval queues one publication job; the worker publishes the exact Reel once within 10 minutes. job.status reports queued, running, published, failed or unknown. Withdrawal revokes authority; it does not prove an in-flight post was cancelled. Historical readiness in the manifest is not a new preflight pass. Any approval history keeps this post locked for draft edits.

#### Input

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `workspaceId` | string (UUID) | yes |  |
| `postId` | string (UUID) | yes |  |
| `requestId` | string (UUID) | no |  |

Unknown fields are rejected.

#### Result

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `approval` | object or null | yes |  |
| `request` | object or null | yes |  |
| `executionAvailable` | **always** `true` | yes |  |

The result carries no other fields.

**`approval.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `id` | string (UUID) | yes |  |
| `requestId` | string (UUID) | yes |  |
| `manifest` | object (2 shapes) | yes |  |
| `manifestSha256` | string | yes | pattern `^[a-f0-9]{64}$` |
| `status` | `"approved"` \| `"withdrawn"` \| `"expired"` \| `"stale"` | yes |  |
| `approvedBy` | `"owner"` \| `"agent_publish"` | yes |  |
| `clientId` | string or null | yes |  |
| `approvedAt` | string (date-time) | yes |  |
| `publishBefore` | string (date-time) | yes |  |
| `revokedAt` | string (date-time) or null | yes |  |
| `job` | object or null | yes |  |

The result carries no other fields.

**`approval.manifest.*`, shape 1**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `version` | **always** `1` | yes |  |
| `workspaceId` | string (UUID) | yes |  |
| `ownerId` | string (UUID) | yes |  |
| `postId` | string (UUID) | yes |  |
| `channel` | **always** `"instagram"` | yes |  |
| `format` | **always** `"video"` | yes |  |
| `caption` | string | yes | max length 2200 |
| `account` | object | yes |  |
| `asset` | object | yes |  |
| `readiness` | object | yes |  |
| `timing` | object | yes |  |
| `trialReel` | `"manual"` \| `"performance"` | no |  |

The result carries no other fields.

**`approval.manifest.*`, shape 2**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `version` | **always** `2` | yes |  |
| `workspaceId` | string (UUID) | yes |  |
| `ownerId` | string (UUID) | yes |  |
| `postId` | string (UUID) | yes |  |
| `channel` | **always** `"instagram"` | yes |  |
| `format` | `"image"` \| `"carousel"` \| `"video"` \| `"story"` | yes |  |
| `caption` | string | yes | max length 2200 |
| `account` | object | yes |  |
| `asset` | object | yes |  |
| `readiness` | object | yes |  |
| `timing` | object | yes |  |
| `trialReel` | `"manual"` \| `"performance"` | no |  |
| `placement` | `"default"` \| `"reel"` | yes |  |
| `assets` | array of object | yes | min items 1; max items 10 |

The result carries no other fields.

**`approval.job.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `id` | string (UUID) | yes |  |
| `status` | `"queued"` \| `"running"` \| `"published"` \| `"failed"` \| `"unknown"` \| `"cancelled"` | yes |  |
| `phase` | string | yes | min length 1; max length 100 |

The result carries no other fields.

**`request.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `requestId` | string (UUID) | yes |  |
| `action` | `"approve"` \| `"withdraw"` | yes |  |
| `approvalId` | string (UUID) | yes |  |
| `createdAt` | string (date-time) | yes |  |

The result carries no other fields.

Every successful result is also returned as `structuredContent`.

---

### publish_instagram_reel {#publish_instagram_reel}

<div class="doc-fact-strip"><dl><dt>Title</dt><dd>Publish an Instagram Reel <em>as sent in tools/list</em></dd><dt>Transport</dt><dd>Streamable HTTP at <code>/mcp</code></dd><dt>Annotations</dt><dd><span class="doc-chip" data-kind="annotation" data-value="readOnlyHint:false">readOnlyHint false</span> <span class="doc-chip" data-kind="annotation" data-value="destructiveHint:true">destructiveHint true</span> <span class="doc-chip" data-kind="annotation" data-value="idempotentHint:true">idempotentHint true</span> <span class="doc-chip" data-kind="annotation" data-value="openWorldHint:true">openWorldHint true</span> <em>as sent in tools/list</em></dd><dt>Owner handoff</dt><dd>When mode is owner_review; an automatic post with Publish queues without owner review. <code>/posts/review</code> from <code>review.url</code></dd><dt>Idempotency key</dt><dd><code>requestId</code></dd><dt>Revision guard</dt><dd>None</dd></dl></div>

> Publish one exact saved Instagram Reel when the post's publishMode is automatic and this agent has Publish (list_workspaces access.canPublish). With Publish, this call runs one exact-post readiness check, saves an agent_publish approval with the manifest hash, and queues one job. The worker publishes the Reel once within 10 minutes; read job.status with get_instagram_approval. Otherwise nothing is saved: mode is owner_review, reason is post_requires_review or publish_off, and review.url lets the owner approve this post. The Reel uses the one connected Instagram account of the workspace; the owner does not select it for each post. DESTINATION_REQUIRED means that the post is not an Instagram Reel, that no connected account is ready, or that the post names a different Instagram account. Reuse requestId after a lost response: a replay returns the original result and never starts a second check, approval or job. Do not use a new requestId to hide an unknown result.

**When to call it**

Call this when a saved Reel has one video,
and `list_workspaces.access.canPublish` is true and the post is `automatic`.
The Reel uses the one connected Instagram account of the workspace; the owner
does not select it for each post. `DESTINATION_REQUIRED` means that the post
is not an Instagram Reel, that no connected account is ready, or that the post
names a different Instagram account. Send
the `postId` and a new `requestId`. With the owner's
permission, one call checks readiness, saves an `agent_publish` approval and
queues one job. Read `get_instagram_approval` for `job.status`. Without the
permission, `mode` is `owner_review` and nothing is saved.

A draft with `trialReel` publishes as a [trial Reel](/docs/channels/instagram#trial-reels). The approval manifest then has `trialReel`.

After a lost response, send the same `requestId` and identical input. The
replay returns the original result. It never runs a second check or queues a
second job.

#### Input

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| `postId` | string (UUID) | yes |  |
| `requestId` | string (UUID) | yes |  |
| `workspaceId` | string (UUID) | yes |  |

Unknown fields are rejected.

#### Result

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `mode` | `"auto_publish"` \| `"owner_review"` | yes |  |
| `reason` | `"publish_off"` \| `"post_requires_review"` or null | yes |  |
| `approval` | object or null | yes |  |
| `request` | object or null | yes |  |
| `review` | object or null | yes |  |

The result carries no other fields.

**`approval.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `id` | string (UUID) | yes |  |
| `requestId` | string (UUID) | yes |  |
| `manifest` | object (2 shapes) | yes |  |
| `manifestSha256` | string | yes | pattern `^[a-f0-9]{64}$` |
| `status` | `"approved"` \| `"withdrawn"` \| `"expired"` \| `"stale"` | yes |  |
| `approvedBy` | `"owner"` \| `"agent_publish"` | yes |  |
| `clientId` | string or null | yes |  |
| `approvedAt` | string (date-time) | yes |  |
| `publishBefore` | string (date-time) | yes |  |
| `revokedAt` | string (date-time) or null | yes |  |
| `job` | object or null | yes |  |

The result carries no other fields.

**`approval.manifest.*`, shape 1**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `version` | **always** `1` | yes |  |
| `workspaceId` | string (UUID) | yes |  |
| `ownerId` | string (UUID) | yes |  |
| `postId` | string (UUID) | yes |  |
| `channel` | **always** `"instagram"` | yes |  |
| `format` | **always** `"video"` | yes |  |
| `caption` | string | yes | max length 2200 |
| `account` | object | yes |  |
| `asset` | object | yes |  |
| `readiness` | object | yes |  |
| `timing` | object | yes |  |
| `trialReel` | `"manual"` \| `"performance"` | no |  |

The result carries no other fields.

**`approval.manifest.*`, shape 2**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `version` | **always** `2` | yes |  |
| `workspaceId` | string (UUID) | yes |  |
| `ownerId` | string (UUID) | yes |  |
| `postId` | string (UUID) | yes |  |
| `channel` | **always** `"instagram"` | yes |  |
| `format` | `"image"` \| `"carousel"` \| `"video"` \| `"story"` | yes |  |
| `caption` | string | yes | max length 2200 |
| `account` | object | yes |  |
| `asset` | object | yes |  |
| `readiness` | object | yes |  |
| `timing` | object | yes |  |
| `trialReel` | `"manual"` \| `"performance"` | no |  |
| `placement` | `"default"` \| `"reel"` | yes |  |
| `assets` | array of object | yes | min items 1; max items 10 |

The result carries no other fields.

**`approval.job.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `id` | string (UUID) | yes |  |
| `status` | `"queued"` \| `"running"` \| `"published"` \| `"failed"` \| `"unknown"` \| `"cancelled"` | yes |  |
| `phase` | string | yes | min length 1; max length 100 |

The result carries no other fields.

**`request.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `requestId` | string (UUID) | yes |  |
| `action` | `"approve"` \| `"withdraw"` | yes |  |
| `approvalId` | string (UUID) | yes |  |
| `createdAt` | string (date-time) | yes |  |

The result carries no other fields.

**`review.*`**

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `available` | **always** `true` | yes |  |
| `requiresOwner` | **always** `true` | yes |  |
| `url` | string (URL) | yes |  |

The result carries no other fields.

Every successful result is also returned as `structuredContent`.

#### Example call

```json
{
  "name": "publish_instagram_reel",
  "arguments": {
    "workspaceId": "00000000-0000-4000-8000-000000000001",
    "postId": "00000000-0000-4000-8000-000000000007",
    "requestId": "00000000-0000-4000-8000-000000000030"
  }
}
```

#### Example result

```json
{
  "mode": "auto_publish",
  "reason": null,
  "approval": {
    "id": "00000000-0000-4000-8000-000000000031",
    "requestId": "00000000-0000-4000-8000-000000000030",
    "manifest": {
      "version": 1,
      "workspaceId": "00000000-0000-4000-8000-000000000001",
      "ownerId": "00000000-0000-4000-8000-000000000010",
      "postId": "00000000-0000-4000-8000-000000000007",
      "channel": "instagram",
      "format": "video",
      "caption": "Release health in one screen. Start a 14 day trial.",
      "account": {
        "connectionId": "00000000-0000-4000-8000-000000000019",
        "accountId": "17841400000000000",
        "username": "northstar.analytics",
        "accountType": "BUSINESS"
      },
      "asset": {
        "id": "00000000-0000-4000-8000-000000000012",
        "size": 8388608
      },
      "readiness": {
        "id": "00000000-0000-4000-8000-000000000020",
        "requestId": "00000000-0000-4000-8000-000000000032",
        "credentialVersion": "00000000-0000-4000-8000-000000000021",
        "checkedAt": "2026-09-25T09:20:00.000Z",
        "validUntil": "2026-09-25T09:25:00.000Z"
      },
      "timing": {
        "mode": "immediate",
        "maximumDelaySeconds": 600
      }
    },
    "manifestSha256": "1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f809",
    "status": "approved",
    "approvedBy": "agent_publish",
    "clientId": "northstar-agent",
    "approvedAt": "2026-09-25T09:20:05.000Z",
    "publishBefore": "2026-09-25T09:30:05.000Z",
    "revokedAt": null,
    "job": {
      "id": "00000000-0000-4000-8000-000000000034",
      "status": "queued",
      "phase": "queued"
    }
  },
  "request": {
    "requestId": "00000000-0000-4000-8000-000000000030",
    "action": "approve",
    "approvalId": "00000000-0000-4000-8000-000000000031",
    "createdAt": "2026-09-25T09:20:05.000Z"
  },
  "review": null
}
```

#### Errors

- `AUTH_REQUIRED`
- `AUTH_NOT_CONFIGURED`
- `FORBIDDEN`
- `INVALID_INPUT`
- `POST_NOT_FOUND`
- `READINESS_NOT_PASSED`
- `READINESS_BUSY`
- `READINESS_STALE`
- `DRAFT_LOCKED`
- `DESTINATION_REQUIRED`
- `INSTAGRAM_DESTINATION_UNAVAILABLE`
- `INSTAGRAM_VIDEO_REQUIRED`
- `INSTAGRAM_OAUTH_NOT_CONFIGURED`
- `IDEMPOTENCY_CONFLICT`
- `AUTHORITY_CHANGED`
- `DATABASE_UNAVAILABLE`

Errors return `isError: true` and `{ code, error }` in `structuredContent`. See [Error codes](/docs/contracts/errors).

#### Replay and conflicts

Reuse the same `requestId` with identical input to recover a lost response; the original result is returned. Changed input with the same ID is rejected. A new ID creates a new operation. See [Request IDs, replay and recovery](/docs/contracts/request-ids).

#### Owner handoff

When mode is owner_review; an automatic post with Publish queues without owner review, use the owner handoff if returned. The owner URL is `review.url` for `/posts/review`. Give that URL to the owner and stop. The URL grants no access by itself.

- What the owner does: Review the post in Marketing → Posts and select Publish for Instagram.
- What the agent reads: `get_instagram_approval`, field `status`.

With `mode: "owner_review"`, give `review.url` to the owner. The owner can
approve this exact post there. Enable Publish separately in Agents with typed confirmation `allow agent`. Read `get_instagram_approval` after the owner acts. A
queued job is not a provider receipt.

#### Related

- [Instagram](/docs/channels/instagram)
- [Agent access](/docs/contracts/grants)

---

The schemas on this page are generated from the repository at build time. The guidance was last reviewed on 2026-09-30.
