Skip to content

Instagram

Implemented

Connect, check readiness and prepare owner approval.

Open as Markdown

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#

Title
Connect Instagram Account as sent in tools/list
Transport
Streamable HTTP at /mcp
Annotations
readOnlyHint false destructiveHint false idempotentHint true openWorldHint false as sent in tools/list
Owner handoff
Yes. /connect/instagram from connectionUrl
Idempotency key
requestId
Revision guard
None

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#

Table: Field, Type, Required, Constraints
FieldTypeRequiredConstraints
workspaceIdstring (UUID)yes
requestIdstring (UUID)yes

Unknown fields are rejected.

Result#

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
connectionobjectyes
connectionUrlstring (URL)yes

The result carries no other fields.

connection.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
idstring (UUID)yes
requestIdstring (UUID)yes
status"pending" | "authorizing" | "exchanging" | "connected" | "denied" | "cancelled" | "failed" | "unknown" | "expired"yes
connectionIdstring (UUID)yes
createdAtstring (date-time)yes
expiresAtstring (date-time)yes
activeUntilstring (date-time) or nullyes
accountobject or nullyes
failureCodestring or nullyesmin length 1; max length 100
lifecycleobject or nullyes

The result carries no other fields.

connection.account.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
accountIdstringyespattern ^[0-9]{1,200}$
usernamestringyesmin length 1; max length 100
accountType"BUSINESS" | "MEDIA_CREATOR"yes
expiresAtstring (date-time)yes
verifiedAtstring (date-time)yes

The result carries no other fields.

connection.lifecycle.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
status"connected" | "refreshing" | "reconnect-required" | "disconnected"yes
credentialVersionstring (UUID) or nullyes
refreshAvailableAtstring (date-time) or nullyes
lastRefreshobject or nullyes

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.

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#

Title
Get Instagram Connection as sent in tools/list
Transport
Streamable HTTP at /mcp
Annotations
readOnlyHint true destructiveHint false idempotentHint true openWorldHint false as sent in tools/list
Owner handoff
Yes. /connect/instagram from connectionUrl
Idempotency key
None
Revision guard
None

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#

Table: Field, Type, Required, Constraints
FieldTypeRequiredConstraints
workspaceIdstring (UUID)yes
operationIdstring (UUID)yes

Unknown fields are rejected.

Result#

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
connectionobjectyes
connectionUrlstring (URL)yes

The result carries no other fields.

connection.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
idstring (UUID)yes
requestIdstring (UUID)yes
status"pending" | "authorizing" | "exchanging" | "connected" | "denied" | "cancelled" | "failed" | "unknown" | "expired"yes
connectionIdstring (UUID)yes
createdAtstring (date-time)yes
expiresAtstring (date-time)yes
activeUntilstring (date-time) or nullyes
accountobject or nullyes
failureCodestring or nullyesmin length 1; max length 100
lifecycleobject or nullyes

The result carries no other fields.

connection.account.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
accountIdstringyespattern ^[0-9]{1,200}$
usernamestringyesmin length 1; max length 100
accountType"BUSINESS" | "MEDIA_CREATOR"yes
expiresAtstring (date-time)yes
verifiedAtstring (date-time)yes

The result carries no other fields.

connection.lifecycle.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
status"connected" | "refreshing" | "reconnect-required" | "disconnected"yes
credentialVersionstring (UUID) or nullyes
refreshAvailableAtstring (date-time) or nullyes
lastRefreshobject or nullyes

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#

Title
List Instagram Connections as sent in tools/list
Transport
Streamable HTTP at /mcp
Annotations
readOnlyHint true destructiveHint false idempotentHint true openWorldHint false as sent in tools/list
Owner handoff
No
Idempotency key
None
Revision guard
None

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#

Table: Field, Type, Required, Constraints
FieldTypeRequiredConstraints
workspaceIdstring (UUID)yes

Unknown fields are rejected.

Result#

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
connectionsarray of objectyesmax items 25

The result carries no other fields.

connections[]

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
connectionobjectyes
connectionUrlstring (URL)yes

The result carries no other fields.

connections[].connection.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
idstring (UUID)yes
requestIdstring (UUID)yes
status"pending" | "authorizing" | "exchanging" | "connected" | "denied" | "cancelled" | "failed" | "unknown" | "expired"yes
connectionIdstring (UUID)yes
createdAtstring (date-time)yes
expiresAtstring (date-time)yes
activeUntilstring (date-time) or nullyes
accountobject or nullyes
failureCodestring or nullyesmin length 1; max length 100
lifecycleobject or nullyes

The result carries no other fields.

Every successful result is also returned as structuredContent.


prepare_instagram_destination#

Title
Request Instagram Account Choice as sent in tools/list
Transport
Streamable HTTP at /mcp
Annotations
readOnlyHint true destructiveHint false idempotentHint true openWorldHint false as sent in tools/list
Owner handoff
Yes. /posts/review from review.url
Idempotency key
None
Revision guard
None

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#

Table: Field, Type, Required, Constraints
FieldTypeRequiredConstraints
workspaceIdstring (UUID)yes
postIdstring (UUID)yes

Unknown fields are rejected.

Result#

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
postIdstring (UUID)yes
reviewobjectyes

The result carries no other fields.

review.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
availablealways trueyes
requiresOwneralways trueyes
urlstring (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#

Title
Request Instagram Readiness Check as sent in tools/list
Transport
Streamable HTTP at /mcp
Annotations
readOnlyHint true destructiveHint false idempotentHint true openWorldHint false as sent in tools/list
Owner handoff
Yes. /posts/review from review.url
Idempotency key
None
Revision guard
None

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#

Table: Field, Type, Required, Constraints
FieldTypeRequiredConstraints
workspaceIdstring (UUID)yes
postIdstring (UUID)yes

Unknown fields are rejected.

Result#

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
postIdstring (UUID)yes
reviewobjectyes

The result carries no other fields.

review.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
availablealways trueyes
requiresOwneralways trueyes
urlstring (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.


get_instagram_readiness#

Title
Get Instagram Readiness as sent in tools/list
Transport
Streamable HTTP at /mcp
Annotations
readOnlyHint true destructiveHint false idempotentHint true openWorldHint false as sent in tools/list
Owner handoff
No
Lookup key
requestId selects a saved request. It is not an idempotency key.
Revision guard
None

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#

Table: Field, Type, Required, Constraints
FieldTypeRequiredConstraints
workspaceIdstring (UUID)yes
postIdstring (UUID)yes
requestIdstring (UUID)no

Unknown fields are rejected.

Result#

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
readinessobject or nullyes

The result carries no other fields.

readiness.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
idstring (UUID)yes
requestIdstring (UUID)yes
postIdstring (UUID)yes
connectionIdstring (UUID)yes
accountIdstringyespattern ^[0-9]{1,200}$
credentialVersionstring (UUID)yes
assetobjectyes
format"image" | "carousel" | "video" | "story"no
placement"default" | "reel"no
assetsarray of object or nullnomin items 1; max items 10
status"checking" | "passed" | "blocked" | "unknown" | "stale"yes
resultStatus"passed" | "blocked" | "unknown" or nullyes
createdAtstring (date-time)yes
activeUntilstring (date-time)yes
checkedAtstring (date-time) or nullyes
validUntilstring (date-time) or nullyes
mediaStatus"passed" | "blocked" | "unknown" | "not_checked"yes
mediaIssueobject or nullyesdefault null
providerStatus"passed" | "blocked" | "unknown" | "not_checked"yes
blockersarray 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"yesmax items 10

The result carries no other fields.

readiness.asset.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
idstring (UUID)yes
sizeintegeryesmax 9007199254740991

The result carries no other fields.

readiness.assets[]

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
idstring (UUID)yes
sizeintegeryesmax 9007199254740991
kind"image" | "video"yes
sha256string or nullnopattern ^[a-f0-9]{64}$

The result carries no other fields.

readiness.mediaIssue.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
rulestringyespattern ^[a-z][a-z0-9_]{0,63}$
messagestringyesmin length 1; max length 500
actualnumber or string or boolean or nullyes
expectedstringyesmin 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.


prepare_instagram_approval#

Title
Request Instagram Reel Approval as sent in tools/list
Transport
Streamable HTTP at /mcp
Annotations
readOnlyHint true destructiveHint false idempotentHint true openWorldHint false as sent in tools/list
Owner handoff
Yes. /posts/review from review.url
Idempotency key
None
Revision guard
None

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#

Table: Field, Type, Required, Constraints
FieldTypeRequiredConstraints
postIdstring (UUID)yes
readinessRequestIdstring (UUID)yes
workspaceIdstring (UUID)yes

Unknown fields are rejected.

Result#

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
manifestobject (2 shapes)yes
manifestSha256stringyespattern ^[a-f0-9]{64}$
reviewobjectyes
executionAvailablealways trueyes

The result carries no other fields.

manifest.*, shape 1

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
versionalways 1yes
workspaceIdstring (UUID)yes
ownerIdstring (UUID)yes
postIdstring (UUID)yes
channelalways "instagram"yes
formatalways "video"yes
captionstringyesmax length 2200
accountobjectyes
assetobjectyes
readinessobjectyes
timingobjectyes
trialReel"manual" | "performance"no

The result carries no other fields.

manifest.account.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
connectionIdstring (UUID)yes
accountIdstringyespattern ^[0-9]{1,200}$
usernamestringyesmin length 1; max length 100
accountType"BUSINESS" | "MEDIA_CREATOR"yes

The result carries no other fields.

manifest.asset.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
idstring (UUID)yes
sizeintegeryesmin 1; max 52428800

The result carries no other fields.

manifest.readiness.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
idstring (UUID)yes
requestIdstring (UUID)yes
credentialVersionstring (UUID)yes
checkedAtstring (date-time)yes
validUntilstring (date-time)yes

The result carries no other fields.

manifest.timing.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
modealways "immediate"yes
maximumDelaySecondsalways 600yes

The result carries no other fields.

manifest.*, shape 2

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
versionalways 2yes
workspaceIdstring (UUID)yes
ownerIdstring (UUID)yes
postIdstring (UUID)yes
channelalways "instagram"yes
format"image" | "carousel" | "video" | "story"yes
captionstringyesmax length 2200
accountobjectyes
assetobjectyes
readinessobjectyes
timingobjectyes
trialReel"manual" | "performance"no
placement"default" | "reel"yes
assetsarray of objectyesmin items 1; max items 10

The result carries no other fields.

manifest.account.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
connectionIdstring (UUID)yes
accountIdstringyespattern ^[0-9]{1,200}$
usernamestringyesmin length 1; max length 100
accountType"BUSINESS" | "MEDIA_CREATOR"yes

The result carries no other fields.

manifest.asset.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
idstring (UUID)yes
sizeintegeryesmin 1; max 52428800

The result carries no other fields.

manifest.readiness.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
idstring (UUID)yes
requestIdstring (UUID)yes
credentialVersionstring (UUID)yes
checkedAtstring (date-time)yes
validUntilstring (date-time)yes

The result carries no other fields.

manifest.timing.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
modealways "immediate"yes
maximumDelaySecondsalways 600yes

The result carries no other fields.

manifest.assets[]

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
idstring (UUID)yes
sizeintegeryesmin 1; max 52428800
sha256stringyespattern ^[a-f0-9]{64}$
kind"image" | "video"yes

The result carries no other fields.

review.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
availablealways trueyes
requiresOwneralways trueyes
urlstring (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.

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.


get_instagram_approval#

Title
Get Instagram Approval as sent in tools/list
Transport
Streamable HTTP at /mcp
Annotations
readOnlyHint true destructiveHint false idempotentHint true openWorldHint false as sent in tools/list
Owner handoff
No
Lookup key
requestId selects a saved request. It is not an idempotency key.
Revision guard
None

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#

Table: Field, Type, Required, Constraints
FieldTypeRequiredConstraints
workspaceIdstring (UUID)yes
postIdstring (UUID)yes
requestIdstring (UUID)no

Unknown fields are rejected.

Result#

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
approvalobject or nullyes
requestobject or nullyes
executionAvailablealways trueyes

The result carries no other fields.

approval.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
idstring (UUID)yes
requestIdstring (UUID)yes
manifestobject (2 shapes)yes
manifestSha256stringyespattern ^[a-f0-9]{64}$
status"approved" | "withdrawn" | "expired" | "stale"yes
approvedBy"owner" | "agent_publish"yes
clientIdstring or nullyes
approvedAtstring (date-time)yes
publishBeforestring (date-time)yes
revokedAtstring (date-time) or nullyes
jobobject or nullyes

The result carries no other fields.

approval.manifest.*, shape 1

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
versionalways 1yes
workspaceIdstring (UUID)yes
ownerIdstring (UUID)yes
postIdstring (UUID)yes
channelalways "instagram"yes
formatalways "video"yes
captionstringyesmax length 2200
accountobjectyes
assetobjectyes
readinessobjectyes
timingobjectyes
trialReel"manual" | "performance"no

The result carries no other fields.

approval.manifest.*, shape 2

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
versionalways 2yes
workspaceIdstring (UUID)yes
ownerIdstring (UUID)yes
postIdstring (UUID)yes
channelalways "instagram"yes
format"image" | "carousel" | "video" | "story"yes
captionstringyesmax length 2200
accountobjectyes
assetobjectyes
readinessobjectyes
timingobjectyes
trialReel"manual" | "performance"no
placement"default" | "reel"yes
assetsarray of objectyesmin items 1; max items 10

The result carries no other fields.

approval.job.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
idstring (UUID)yes
status"queued" | "running" | "published" | "failed" | "unknown" | "cancelled"yes
phasestringyesmin length 1; max length 100

The result carries no other fields.

request.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
requestIdstring (UUID)yes
action"approve" | "withdraw"yes
approvalIdstring (UUID)yes
createdAtstring (date-time)yes

The result carries no other fields.

Every successful result is also returned as structuredContent.


publish_instagram_reel#

Title
Publish an Instagram Reel as sent in tools/list
Transport
Streamable HTTP at /mcp
Annotations
readOnlyHint false destructiveHint true idempotentHint true openWorldHint true as sent in tools/list
Owner handoff
When mode is owner_review; an automatic post with Publish queues without owner review. /posts/review from review.url
Idempotency key
requestId
Revision guard
None

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. 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#

Table: Field, Type, Required, Constraints
FieldTypeRequiredConstraints
postIdstring (UUID)yes
requestIdstring (UUID)yes
workspaceIdstring (UUID)yes

Unknown fields are rejected.

Result#

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
mode"auto_publish" | "owner_review"yes
reason"publish_off" | "post_requires_review" or nullyes
approvalobject or nullyes
requestobject or nullyes
reviewobject or nullyes

The result carries no other fields.

approval.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
idstring (UUID)yes
requestIdstring (UUID)yes
manifestobject (2 shapes)yes
manifestSha256stringyespattern ^[a-f0-9]{64}$
status"approved" | "withdrawn" | "expired" | "stale"yes
approvedBy"owner" | "agent_publish"yes
clientIdstring or nullyes
approvedAtstring (date-time)yes
publishBeforestring (date-time)yes
revokedAtstring (date-time) or nullyes
jobobject or nullyes

The result carries no other fields.

approval.manifest.*, shape 1

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
versionalways 1yes
workspaceIdstring (UUID)yes
ownerIdstring (UUID)yes
postIdstring (UUID)yes
channelalways "instagram"yes
formatalways "video"yes
captionstringyesmax length 2200
accountobjectyes
assetobjectyes
readinessobjectyes
timingobjectyes
trialReel"manual" | "performance"no

The result carries no other fields.

approval.manifest.*, shape 2

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
versionalways 2yes
workspaceIdstring (UUID)yes
ownerIdstring (UUID)yes
postIdstring (UUID)yes
channelalways "instagram"yes
format"image" | "carousel" | "video" | "story"yes
captionstringyesmax length 2200
accountobjectyes
assetobjectyes
readinessobjectyes
timingobjectyes
trialReel"manual" | "performance"no
placement"default" | "reel"yes
assetsarray of objectyesmin items 1; max items 10

The result carries no other fields.

approval.job.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
idstring (UUID)yes
status"queued" | "running" | "published" | "failed" | "unknown" | "cancelled"yes
phasestringyesmin length 1; max length 100

The result carries no other fields.

request.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
requestIdstring (UUID)yes
action"approve" | "withdraw"yes
approvalIdstring (UUID)yes
createdAtstring (date-time)yes

The result carries no other fields.

review.*

Table: Field, Type, Always present, Notes
FieldTypeAlways presentNotes
availablealways trueyes
requiresOwneralways trueyes
urlstring (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.

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.

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.


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

Status: Implemented · Generated from src/lib/mcp/agent-tools.ts, src/lib/server/mcp/AgentMcp.ts, src/lib/docs/handoffs.ts, src/lib/docs/channels.ts

Open as Markdown