# Send Invitation

`POST /v1/invitations`

Invite someone by email to the organization, or to one workspace with
``project_id``, at a role. Needs ``members:write``, and the authority to
give that role there (never above the creator's own). Someone already in
the organization is given a role with ``PUT /v1/members/{user_id}``
instead (400).

- Base URL: `https://junction-api.qualiastudios.dev`
- Authentication: an API key in the `X-API-Key` header, or `Authorization: Bearer …`

## Parameters

- `project_id` (query, string | null (uuid)): A workspace of the organization; omit it for the organization itself. A workspace key names its own workspace.

## Request body

Required: `application/json` `InvitationRequest`

## Responses

- `201` The invitation, sent: `application/json` `Invitation`
- `400` Refused by the role rules: `application/json` `ErrorResponse`
- `401` Invalid or missing API key: `application/json` `ErrorResponse`
- `403` The key lacks members:write, or its creator may not give or take this role here (nobody grants above their own role): `application/json` `ErrorResponse`
- `404` Not found or not readable: `application/json` `ErrorResponse`
- `409` The organization's last owner stays: `application/json` `ErrorResponse`
- `422` Validation Error: `application/json` `HTTPValidationError`

## Schemas

```yaml
InvitationRequest:
  properties:
    email:
      type: string
      maxLength: 320
      pattern: ^[^@\s]+@[^@\s]+$
    role:
      type: string
      enum:
        - viewer
        - contributor
        - admin
        - owner
  additionalProperties: false
  type: object
  required:
    - email
    - role
  title: InvitationRequest
  description: |-
    ``POST /v1/invitations``: invite someone by email at a role (to the
    workspace the query's ``project_id`` names, as a guest, else to the
    organization).
Invitation:
  properties:
    invitation_id:
      type: string
      format: uuid
    email:
      type: string
    space_id:
      description: The space it grants a role on
      format: uuid
      type:
        - string
        - "null"
    space_role:
      description: The role it grants there
      nullable: true
      type: string
      enum:
        - viewer
        - contributor
        - admin
        - owner
    space_name:
      type:
        - string
        - "null"
    space_kind:
      nullable: true
      type: string
      enum:
        - organization
        - workspace
    invited_by:
      format: uuid
      type:
        - string
        - "null"
    created_at:
      format: date-time
      type:
        - string
        - "null"
    expires_at:
      format: date-time
      type:
        - string
        - "null"
  type: object
  required:
    - invitation_id
    - email
  title: Invitation
  description: A pending invitation.
ErrorResponse:
  properties:
    detail:
      type: string
      description: Error message describing what went wrong
  type: object
  required:
    - detail
  title: ErrorResponse
  description: Standard error response.
HTTPValidationError:
  properties:
    detail:
      items:
        $ref: "#/components/schemas/ValidationError"
      type: array
  type: object
  title: HTTPValidationError
ValidationError:
  properties:
    loc:
      items:
        type:
          - string
          - integer
      type: array
      title: Location
    msg:
      type: string
      title: Message
    type:
      type: string
      title: Error Type
    input: {}
    ctx:
      type: object
      title: Context
  type: object
  required:
    - loc
    - msg
    - type
  title: ValidationError
```