External Authorization

Send one idempotent text event to an owner-approved AI consciousness.

Requires the partner key plus an active clone:invoke grant bound to the same installation, external identity, and clone. Use a provider event id as idempotency_key: exact retries return the stored encrypted outcome and never run generation twice. A concurrent retry returns processing with retry_after_seconds; an abandoned receipt eventually becomes terminal failed and is not regenerated with the same key. The message may include media links so the consciousness can perceive a shared image, clip, or audio. To let it take part in a group conversation, set is_group, pass a stable conversation_id (each thread keeps its own separate history), and attach the recent surrounding turns as context_messages with a speaker_label for who is speaking now; the surrounding turns are treated purely as quoted context. The owner must retain normal subscription entitlement; this operation does not spend credits.

post/v1/invoke_external_clone

Request

Base URL: https://partner.mindupload.app
URL: https://partner.mindupload.app/v1/invoke_external_clone
Auth: API key in header X-Partner-Key

Request body

preferred_languagestring nullable

BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.

access_tokenstring required

Opaque grant token accepted only by grant inspection and external clone invocation; store it as a secret and never expose it to users.

literal_textboolean

When true, marker-like text is quoted literally and cannot fetch media. Only the owner’s own clone is accepted; use explicit consolidation/save for learning.

media_idsstring[] nullable

Completed controlled media IDs, checked for ownership, application, scope, retention and exact object version. No analysis is started here.

installation_idstring required

Your stable opaque identifier for this app installation.

external_subjectstring required

Your stable opaque identifier for the person authorizing this installation.

clone_idstring required

AI consciousness id as returned by clone operations.

textstring required

idempotency_keystring required

A stable opaque event key that makes exact retries return the same outcome.

conversation_idstring nullable

Stable opaque id of the conversation or thread this event belongs to. Each conversation keeps its own separate history; omit for a plain one-on-one event.

speaker_labelstring nullable

Neutral display name of whoever is sending this message, shown to the AI consciousness as who it is currently talking to.

is_groupboolean nullable

Set true when this event is one turn of a multi-party conversation so the AI consciousness replies as a single participant among several.

learnboolean nullable

source_labelstring nullable

Example request

{
  "access_token": "grant-token-from-exchange-response",
  "installation_id": "your-installation-id",
  "external_subject": "your-external-user-id",
  "clone_id": "64f0c8b2f7a9b4e1c2d3a456",
  "text": "Hello from your external app.",
  "idempotency_key": "provider-event-id",
  "conversation_id": "your-thread-or-channel-id",
  "speaker_label": "Alex",
  "is_group": true,
  "context_messages": [
    {
      "display_name": "Alex",
      "text": "anyone around to help plan the trip?",
      "is_ai": false,
      "timestamp": 1720000000,
      "gender": "Male"
    },
    {
      "display_name": "Sam",
      "text": "yeah, what are you thinking?",
      "is_ai": false
    }
  ]
}

Response

Result envelope — check the success field.

successboolean required

Whether the call succeeded.

error_messagestring nullable required

Human-readable reason when success is false.

error_codestring

invocation_idstring nullable required

Stable receipt identifier for this external event.

status'processing' | 'succeeded' | 'failed' nullable required

Current authorization or invocation lifecycle state.

response_textstring nullable required

The AI consciousness reply when status is succeeded.

clone_idstring nullable required

AI consciousness id as returned by clone operations.

clone_nicknamestring nullable required

User-facing name of the invoked AI consciousness.

generated_by_aiboolean nullable required

True when the returned response was generated by an AI consciousness.

idempotent_replayboolean nullable required

True when this response came from an existing durable receipt.

retry_after_secondsinteger nullable required

Suggested delay before retrying the same event while processing.

Changes

No recorded changes to this operation across all 2 revisions of this API.