---
title: "Create a user invite"
method: POST
path: "/api/v1/users/{user}/invites"
---

# Create a user invite

`POST /api/v1/users/{user}/invites`

Creates a new invite for the authenticated user. The invite can optionally be
scoped to a specific thread, a persona, or carry arbitrary metadata. The
caller receives the new invite object at HTTP 201.

The invite key is always generated server-side (192-bit URL-safe random
string) and cannot be supplied by the caller.

The path `:user` must match the authenticated user. If a `thread_id` is
provided, the authenticated user must have permission to invite others to that
thread; team threads are not supported and return an error. Supplying a
`thread_id` that does not exist or that belongs to a different user returns
an error. If a key collision occurs during creation the call returns a 409
conflict — simply retry to generate a new key.

## Path parameters

- `user` string, required

## Request body

- object
  - `invite` object, required — Parameters for the new invite. See the UserInviteCreateParams schema for field details.
    - `metadata` object — Arbitrary key-value metadata to attach to the invite. Returned as-is on the resulting invite object.
    - `persona_id` string — ID of the persona to associate with this invite (`per_...`). `null` if the invite is not bound to a persona.
    - `thread_id` string — ID of the thread to associate with this invite (`thr_...`). `null` if the invite is not bound to a thread.

## Response `201`

Successful response

- UserInvite — A shareable invite created by a user, optionally scoped to a thread. Recipients can use the invite key to join or start a conversation.
  - `created_at` string, date-time — When this invite was created (ISO 8601).
  - `id` string, required — Invite ID (`uin_...`).
  - `key` string — Secret bearer token used to accept this invite. Treat this value like a password — do not log or expose it publicly.
  - `metadata` object — Arbitrary key-value metadata attached to the invite at creation time. Defaults to an empty object.
  - `thread` string — ID of the thread this invite is scoped to (`thr_...`). `null` if the invite is not bound to a thread.
  - `user` InviteCreator — A minimal, public-safe projection of the user who sent an invite, exposed to unauthenticated recipients so they can render a join screen. Only identity fields are included; sensitive fields such as email address and organization membership are omitted.
    - `id` string, required — User ID of the inviter (`usr_...`).
    - `name` string — Display name of the inviter. `null` when the inviter has not set a name on their account.
    - `profile_picture` ImageSource — Resolved metadata for an image, including its delivery URL, dimensions, and optional references to the underlying storage file or media record.
      - `file` string — ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.
      - `height` integer — Height of the image in pixels. `null` if not known.
      - `media` string — ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.
      - `mime_type` string — MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.
      - `refresh_url` string — Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing.
      - `url` string — Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires.
      - `width` integer — Width of the image in pixels. `null` if not known.

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `404` — Thread not found
- `409` — Resource already exists
- `422` — Validation failed; Invites cannot be created for team threads; Invalid thread id; User context is required

---

[API](https://skmtc.net/archastro/apis/archastro-platform-api.md) · [All operations](https://skmtc.net/archastro/apis/archastro-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/archastro/archastro-platform-api/versions/a8772b442f86/schema)