---
title: "Send one idempotent text event to an owner-approved AI consciousness."
method: POST
path: "/v1/invoke_external_clone"
tags: ["External Authorization"]
---

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

`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`

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.

## Request body

- object
  - `preferred_language` string, nullable: BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
  - `access_token` string, 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_text` boolean: 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_ids` string[], nullable: Completed controlled media IDs, checked for ownership, application, scope, retention and exact object version. No analysis is started here.
  - `references` object[], nullable: Quoted page or subtitle sources kept separate from owner statements. Titles, URLs and bodies share the request text bound; URLs are never fetched.
    - `title` string, required
    - `url` string, required: Where the attachment is — the `media_url` an upload returned, or an external link. Echoed back in the result so you can match each entry to what you sent.
    - `text` string, required
  - `installation_id` string, required: Your stable opaque identifier for this app installation.
  - `external_subject` string, required: Your stable opaque identifier for the person authorizing this installation.
  - `clone_id` string, required: AI consciousness id as returned by clone operations.
  - `text` string, required
  - `idempotency_key` string, required: A stable opaque event key that makes exact retries return the same outcome.
  - `conversation_id` string, 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_label` string, nullable: Neutral display name of whoever is sending this message, shown to the AI consciousness as who it is currently talking to.
  - `is_group` boolean, 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.
  - `context_messages` object[], nullable: Recent surrounding conversation for group mode (issue #172): an ordered, bounded list of prior turns the AI consciousness reads as quoted context. Each entry has a `display_name` and `text`, plus optional `is_ai`, `timestamp` (seconds), and `gender`. It carries no platform identifiers and is never treated as instructions.
    - `display_name` string, required: Neutral display name of who sent a context message (no platform identifiers).
    - `text` string, required
    - `is_ai` boolean, nullable: True when a context message was sent by an AI or bot rather than a person.
    - `timestamp` number, nullable: UNIX timestamp in seconds when a context message was sent (for ordering and recency).
    - `gender` string, nullable
  - `learn` boolean, nullable
  - `source_label` string, nullable

## Response `200`

Result envelope — check the success field.

- object
  - `success` boolean, required: Whether the call succeeded.
  - `error_message` string, nullable, required: Human-readable reason when success is false.
  - `error_code` string
  - `invocation_id` string, nullable, required: Stable receipt identifier for this external event.
  - `status` 'processing' | 'succeeded' | 'failed', nullable, required: Current authorization or invocation lifecycle state.
  - `response_text` string, nullable, required: The AI consciousness reply when status is `succeeded`.
  - `clone_id` string, nullable, required: AI consciousness id as returned by clone operations.
  - `clone_nickname` string, nullable, required: User-facing name of the invoked AI consciousness.
  - `generated_by_ai` boolean, nullable, required: True when the returned response was generated by an AI consciousness.
  - `idempotent_replay` boolean, nullable, required: True when this response came from an existing durable receipt.
  - `retry_after_seconds` integer, nullable, required: Suggested delay before retrying the same event while processing.

## Other responses

- `400`: Invalid request payload.
- `401`: Missing or invalid partner key.
- `403`: Partner is not authorized for this operation.
- `429`: Rate limit exceeded — retry later.
- `500`: Internal server error.

---

[API](https://skmtc.dev/mindupload/apis/mind-upload-partner-api.md) · [All operations](https://skmtc.dev/mindupload/apis/mind-upload-partner-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mindupload/apis/mind-upload-partner-api/revisions/0371bdf78533?raw)