Mission Personas

Posting identities attached to a mission.

6 actions. Each is callable by the agent as a tool, over HTTP via /api/invoke, and (usually) from a UI page.

`mission_personas.list`

GET

List posting personas attached to a mission — the identities (subjects of type=person or brand) that post on this mission's behalf. Distinct from mission.subjectId (the thing being promoted).

AI tool: mission_personas_list
API: GET /api/invoke/mission_personas.list

Input

Field	Type	Required	Description
`missionId`	string	yes
`activeOnly`	boolean	—

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "missionId": {
      "type": "string",
      "minLength": 1
    },
    "activeOnly": {
      "type": "boolean"
    }
  },
  "required": [
    "missionId"
  ]
}

`mission_personas.attach`

POST · mutating

Attach a subject as a posting persona to a mission. The subject is typically type=person or type=brand — the identity doing the posting. Set role (primary/amplifier/support), weight (relative posting share), and platforms (empty=all). Multiple personas per mission is the norm for multi-account campaigns.

When the agent calls it: When the user says "post on @alex and @juke about my game", create the mission with the GAME as subjectId, then attach Alex + Juke as personas via this action. Each persona is a separate subjects row (find or create them via subjects.search / subjects.create). Pick role thoughtfully: the most-amplified account is "primary" (weight 2x baseline), regular contributors are "amplifier" (1x), occasional cross-posts are "support" (0.5x). User-set weight multiplies on top. platforms restricts a persona to specific channels (e.g. ["twitter","devto"] for a developer account that doesn't post on Instagram). Empty array = all platforms allowed. Use limits to enforce posting cadence per persona: { maxPostsPerDay: 3, maxPostsPerHour: 1, quietHours: { from: "22:00", to: "07:00", tz: "America/Los_Angeles" }, bannedTopics: [] }. The picker skips a persona at-or-over limit and falls through to the next eligible one.

AI tool: mission_personas_attach
API: POST /api/invoke/mission_personas.attach

Input

Field	Type	Required
`missionId`	string	yes
`subjectId`	string	yes
`role`	"primary" \| "amplifier" \| "support"	—
`weight`	integer	—
`platforms`	string[]	—
`active`	boolean	—
`limits`	object	—
`notes`	string	—

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "missionId": {
      "type": "string",
      "minLength": 1
    },
    "subjectId": {
      "type": "string",
      "minLength": 1
    },
    "role": {
      "type": "string",
      "enum": [
        "primary",
        "amplifier",
        "support"
      ]
    },
    "weight": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "platforms": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "active": {
      "type": "boolean"
    },
    "limits": {
      "type": "object",
      "properties": {
        "maxPostsPerDay": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "maxPostsPerHour": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "quietHours": {
          "type": "object",
          "properties": {
            "from": {
              "type": "string"
            },
            "to": {
              "type": "string"
            },
            "tz": {
              "type": "string"
            }
          },
          "required": [
            "from",
            "to"
          ]
        },
        "bannedTopics": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "notes": {
      "type": "string"
    }
  },
  "required": [
    "missionId",
    "subjectId"
  ]
}

`mission_personas.attach_many`

POST · mutating

Attach multiple posting personas to a mission in one call. Idempotent on (missionId, subjectId) — re-attaching updates the row instead of duplicating. Use this when a user describes the whole posting roster upfront ("post on X, Y, and Z about my game") to avoid N round-trips.

When the agent calls it: Prefer this over multiple mission_personas.attach calls when the user lists 2+ posting accounts in one breath. Common shape: { missionId, personas: [{ subjectId: alex, role: "amplifier" }, { subjectId: juke_brand, role: "primary" }] }.

AI tool: mission_personas_attach_many
API: POST /api/invoke/mission_personas.attach_many

Input

Field	Type	Required	Description
`missionId`	string	yes
`personas`	object[]	yes

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "missionId": {
      "type": "string",
      "minLength": 1
    },
    "personas": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "subjectId": {
            "type": "string",
            "minLength": 1
          },
          "role": {
            "type": "string",
            "enum": [
              "primary",
              "amplifier",
              "support"
            ]
          },
          "weight": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "platforms": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "active": {
            "type": "boolean"
          },
          "limits": {
            "type": "object",
            "properties": {
              "maxPostsPerDay": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "maxPostsPerHour": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "quietHours": {
                "type": "object",
                "properties": {
                  "from": {
                    "type": "string"
                  },
                  "to": {
                    "type": "string"
                  },
                  "tz": {
                    "type": "string"
                  }
                },
                "required": [
                  "from",
                  "to"
                ]
              },
              "bannedTopics": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "notes": {
            "type": "string"
          }
        },
        "required": [
          "subjectId"
        ]
      }
    }
  },
  "required": [
    "missionId",
    "personas"
  ]
}

`mission_personas.update`

PATCH · mutating

Update a persona's weight, role, platforms, active flag, or notes.

AI tool: mission_personas_update
API: PATCH /api/invoke/mission_personas.update

Input

Field	Type	Required	Description
`id`	string	yes
`patch`	object	yes

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "patch": {
      "type": "object",
      "properties": {
        "role": {
          "type": "string",
          "enum": [
            "primary",
            "amplifier",
            "support"
          ]
        },
        "weight": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "platforms": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "active": {
          "type": "boolean"
        },
        "limits": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "maxPostsPerDay": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 9007199254740991
                },
                "maxPostsPerHour": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 9007199254740991
                },
                "quietHours": {
                  "type": "object",
                  "properties": {
                    "from": {
                      "type": "string"
                    },
                    "to": {
                      "type": "string"
                    },
                    "tz": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "from",
                    "to"
                  ]
                },
                "bannedTopics": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            },
            {
              "type": "null"
            }
          ]
        },
        "notes": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "id",
    "patch"
  ]
}

`mission_personas.detach`

DELETE · mutating

Remove a persona from a mission. Does not delete the subject — just drops the association.

AI tool: mission_personas_detach
API: DELETE /api/invoke/mission_personas.detach

Input

Field	Type	Required	Description
`id`	string	yes

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "id"
  ]
}

`mission_personas.pick`

POST

Weighted random pick of a persona for an upcoming draft. Filters to active personas whose platforms list is empty OR contains the target platform. Use when you need to attribute a new draft to a persona but the user didn't specify one — this enforces the cadence weights the user set up.

AI tool: mission_personas_pick
API: POST /api/invoke/mission_personas.pick

Input

Field	Type	Required	Description
`missionId`	string	yes
`platform`	string	yes

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "missionId": {
      "type": "string",
      "minLength": 1
    },
    "platform": {
      "type": "string"
    }
  },
  "required": [
    "missionId",
    "platform"
  ]
}