Creates a participant and optionally binds it to a set of agents atomically.

Creates the participant together with its channels and any initial agent bindings supplied in the request — all in one transaction, so a participant is never persisted half-bound. `Kind` is fixed at creation: switching a participant between Person, Group, and AI Agent requires recreating it.

Authorization

Bearer

AuthorizationBearer <token>

JWT Authorization header using the Bearer scheme. Enter 'Bearer' [space] and then your token.

In: header

Path Parameters

tenant*string

The tenant identifier

Request Body

kind?string

What sort of entity a Fruxon.Model.Participants.Participant represents. The Agent Network treats all three uniformly — they're the "things that talk to agents" — but the kind disambiguates UX and downstream routing rules.

Value in"UNSPECIFIED" | "PERSON" | "GROUP" | "AI_AGENT"

audience?string

Trust boundary a Fruxon.Model.Participants.Participant sits on (design participant-audience-and-roles.md §1) — a platform-owned, security-relevant axis distinct from Fruxon.Model.Participants.ParticipantTier (how it was admitted) and the tenant's own Segment directory. A customer and a support operator are both Fruxon.Model.Participants.ParticipantTier.Curated; only Audience separates them.

Gates the operator-eligibility predicate (only an Fruxon.Model.Participants.ParticipantAudience.Internal + Fruxon.Model.Participants.ParticipantTier.CuratedFruxon.Model.Participants.ParticipantKind.Person may be an escalation operator), which fixes "a customer can be selected as an operator." Defaults Fruxon.Model.Participants.ParticipantAudience.Unknown on existing rows so eligibility is fail-closed; the I4 backfill promotes participants already wired as operators to Fruxon.Model.Participants.ParticipantAudience.Internal so live escalation is not stranded.

Value in"UNSPECIFIED" | "UNKNOWN" | "INTERNAL" | "EXTERNAL"

displayName*string

Length1 <= length <= 150

email?string|null

Lengthlength <= 4000

relatedAgentId?string|null

avatarFileId?string|null

Operator-uploaded avatar file id (in platform storage). Optional; AI-agent participants without one fall back to the backing agent's avatar at projection time.

addresses?|null

Identity addresses (provider + address) the participant can be reached at. The bot/app is derived from the bound agents' endpoints, not picked here.

agentIds?|null

Agents to bind to this participant on creation. May be empty.

consultAllowed?boolean

Whether the initial bindings also place this participant on each agent's consult roster. Defaults false so binding a customer for conversation access does not inject peer-network tools. Advisor creation must opt in explicitly.

description?string|null

Consult advisor identity (PLAN-consult-roster): a free-text description of what this participant can help with, plus the capability names they carry (the expertise the consult resolver matches).

Lengthlength <= 4000

expertise?|null

area?string|null

Profile (PLAN-identity-normalization, Phase 0): area of work (or role), a longer bio, and working-preference tags — distinct from the consult Fruxon.Model.Participants.CreateParticipantRequest.Description/Fruxon.Model.Participants.CreateParticipantRequest.Expertise above.

Lengthlength <= 150

bio?string|null

Lengthlength <= 4000

preferredLanguage?string|null

Optional preferred language (ISO 639-1, e.g. "en", "he") for platform-authored notices sent to this participant — set on an operator so bridge notices render in their language, not the customer's.

Lengthlength <= 16

preferences?|null

environmentId?string|null

Optional environment (served end-customer / account) this contact belongs to — the unified grouping (docs/design/environments-directory-unification.md). A logical reference (no FK, partition-friendly), null = unaffiliated. Set at onboarding by the per-provider environment resolver, or by an operator picking one on approve.

Formatuuid

accounts?|null

Non-routing external account links (github, jira, gitlab, …) — correlation keys, never routed. Kept separate from Fruxon.Model.Participants.CreateParticipantRequest.Addresses on purpose.

[key: string]?never

Response Body

curl -X POST "https://api.fruxon.com/v1/tenants/string/participants" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "string"
  }'

curl -X POST "https://api.fruxon.com/v1/tenants/string/participants" \  -H "Content-Type: application/json" \  -d '{    "displayName": "string"  }'

{
  "id": "00000000-0000-0000-0000-000000000000",
  "kind": "PERSON",
  "tier": "CURATED",
  "audience": "UNKNOWN",
  "displayName": "string",
  "email": "string",
  "relatedAgentId": "string",
  "description": "string",
  "expertise": [
    "string"
  ],
  "area": "string",
  "bio": "string",
  "preferredLanguage": "string",
  "environmentId": "00000000-0000-0000-0000-000000000000",
  "preferences": [
    "string"
  ],
  "accounts": [
    {
      "provider": "string",
      "identifier": "string",
      "handle": "string",
      "profileUrl": "string",
      "source": "MANUAL",
      "verifiedAt": 0
    }
  ],
  "addresses": [
    {
      "provider": "string",
      "address": "string",
      "priority": 0,
      "label": "string",
      "disabled": false
    }
  ],
  "isDebugOnly": false,
  "agentIds": [
    "string"
  ],
  "disabledAt": 0,
  "health": {
    "reachable": false,
    "channels": [
      {
        "address": "string",
        "reason": null,
        "keyStatus": "UNSPECIFIED",
        "keyPrefix": "string",
        "lastMessageAt": null
      }
    ],
    "reason": "INVALID_FORMAT"
  },
  "channelActivations": [
    {
      "agentId": "string",
      "bindingId": "00000000-0000-0000-0000-000000000000",
      "integrationConfigId": "00000000-0000-0000-0000-000000000000",
      "provider": "string",
      "address": "string",
      "webhookUrl": "string",
      "webhookUrlTemplate": "string",
      "webhookKeyPrefix": "string",
      "scope": "PER_BINDING"
    }
  ],
  "avatarFileId": "string",
  "avatarSource": "UPLOADED",
  "avatarSourceConfigId": "00000000-0000-0000-0000-000000000000",
  "avatarSourceAddress": "string",
  "avatarSyncedAt": 0,
  "avatarAutoSync": {
    "synced": false,
    "provider": "string",
    "address": "string"
  },
  "createdAt": 0,
  "modifiedAt": 0
}

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Empty

Creates a participant and optionally binds it to a set of agents atomically.

Authorization

Path Parameters

Request Body

Response Body

201

400

401

403