# Group API Reference

OpenAPI source: https://api.are.na/v3/openapi.json

## POST /v3/groups/{id}/invitations

- Label: Add or invite a group member
- Docs: https://www.are.na/developers/explore/group/post-invitations
- Markdown: https://www.are.na/developers/explore/group/post-invitations.md
- Requires resource id: yes
- Response content type: application/json

Resolves a `user_id` or `email` into one of four outcomes and returns
which outcome occurred via the `outcome` field. HTTP status mirrors the
outcome: `201` when something was created (`added`, `invited`), `200`
when no work was needed (`already_member`, `invitation_pending`).

Resolution rules:

- `added`: The request targeted a `user_id` and that user already
  follows the caller. A group membership is created immediately. The
  "must follow caller" signal is treated as opt-in, so no invite/accept
  round trip is required.
- `invited`: A new pending invitation was created and an email was sent.
- `invitation_pending`: An open invitation for this user or email
  already exists; the existing invitation is returned unchanged.
- `already_member`: The user is already a member; no action is taken.

When invited by `email` and no user with that email exists, the caller
must have permission to invite new users.

**Authentication required.**

Path parameters:
- id: string (required) — Resource ID or slug

Request body schema:
```json
{
  "type": "oneOf",
  "variants": [
    {
      "type": "object",
      "required": [
        "user_id"
      ],
      "properties": {
        "user_id": {
          "type": "integer",
          "nullable": false,
          "description": "User ID to add or invite",
          "example": 12345
        }
      }
    },
    {
      "type": "object",
      "required": [
        "email"
      ],
      "properties": {
        "email": {
          "type": "string",
          "nullable": false,
          "description": "Email address to invite",
          "format": "email",
          "example": "invitee@example.com"
        }
      }
    }
  ]
}
```

Response schema:
```json
{
  "type": "object",
  "description": "Result of `POST /v3/groups/{id}/invitations`. Inspect `outcome` to\ndetermine what happened; HTTP status mirrors it (`201` for created outcomes,\n`200` for no-op outcomes).\n",
  "required": [
    "outcome",
    "user",
    "invitation"
  ],
  "properties": {
    "outcome": {
      "type": "string",
      "nullable": false,
      "description": "Discriminator for the result of `POST /v3/groups/{id}/invitations`.\n\n- `added`: A new group membership was created (the invitee already\n  follows the caller, so the invite/accept round trip was skipped).\n- `invited`: A new pending invitation was created and an email was sent.\n- `invitation_pending`: An open invitation for this user/email already\n  existed; that invitation is returned unchanged.\n- `already_member`: The user is already a group member; no action was\n  taken.\n",
      "enum": [
        "added",
        "invited",
        "invitation_pending",
        "already_member"
      ],
      "refName": "GroupMemberInviteOutcome"
    },
    "user": {
      "type": "oneOf",
      "description": "The user that this request resolved to, when known. Null only when\nan invitation was issued by email and no matching user exists yet.\n",
      "variants": [
        {
          "type": "object",
          "description": "Embedded user representation (used when user is nested in other resources)",
          "required": [
            "id",
            "type",
            "name",
            "slug",
            "avatar",
            "initials"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "nullable": false,
              "description": "Unique identifier for the user",
              "example": 12345
            },
            "type": {
              "type": "string",
              "nullable": false,
              "description": "User type",
              "enum": [
                "User"
              ],
              "example": "User"
            },
            "name": {
              "type": "string",
              "nullable": false,
              "description": "User's display name",
              "example": "John Doe"
            },
            "slug": {
              "type": "string",
              "nullable": false,
              "description": "URL-safe identifier (use this in API paths)",
              "example": "john-doe"
            },
            "avatar": {
              "type": "string",
              "nullable": true,
              "description": "URL to user's avatar image",
              "format": "uri",
              "example": "https://d2w9rnfcy7mm78.cloudfront.net/12345/avatar.jpg"
            },
            "initials": {
              "type": "string",
              "nullable": false,
              "description": "User's initials",
              "example": "JD"
            }
          },
          "refName": "EmbeddedUser"
        },
        {
          "type": "unknown",
          "nullable": true
        }
      ]
    },
    "invitation": {
      "type": "oneOf",
      "description": "The invitation associated with this request, for `invited` and\n`invitation_pending` outcomes.\n",
      "variants": [
        {
          "type": "object",
          "description": "Pending invitation for a user to join a group.\n\nInvitee acceptance and decline currently happen through the Are.na web\nUI using tokenized invitation links sent by email. The web UI uses the\nGraphQL `acceptMembershipInvitation` and `declineMembershipInvitation`\nmutations; this REST surface only exposes group-manager list and revoke\noperations.\n",
          "required": [
            "id",
            "type",
            "target",
            "invitee",
            "invitee_email",
            "invited_by",
            "state",
            "accepted_at",
            "created_at",
            "updated_at",
            "_links"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "nullable": false,
              "description": "Unique identifier for the invitation",
              "example": 12345
            },
            "type": {
              "type": "string",
              "nullable": false,
              "enum": [
                "MembershipInvitation"
              ],
              "example": "MembershipInvitation"
            },
            "target": {
              "type": "object",
              "description": "Embedded group representation (used when group is nested in other resources)",
              "required": [
                "id",
                "type",
                "name",
                "slug",
                "avatar",
                "initials"
              ],
              "properties": {
                "id": {
                  "type": "integer",
                  "nullable": false,
                  "description": "Unique identifier for the group",
                  "example": 67890
                },
                "type": {
                  "type": "string",
                  "nullable": false,
                  "description": "Group type",
                  "enum": [
                    "Group"
                  ],
                  "example": "Group"
                },
                "name": {
                  "type": "string",
                  "nullable": false,
                  "description": "Group's name",
                  "example": "Design Team"
                },
                "slug": {
                  "type": "string",
                  "nullable": false,
                  "description": "Group's URL slug",
                  "example": "design-team-abc123"
                },
                "avatar": {
                  "type": "string",
                  "nullable": true,
                  "description": "URL to group's avatar image",
                  "format": "uri",
                  "example": "https://d2w9rnfcy7mm78.cloudfront.net/groups/67890/avatar.jpg"
                },
                "initials": {
                  "type": "string",
                  "nullable": false,
                  "description": "Group's initials",
                  "example": "DT"
                }
              },
              "refName": "EmbeddedGroup"
            },
            "invitee": {
              "type": "oneOf",
              "description": "User being invited, when available",
              "variants": [
                {
                  "type": "object",
                  "description": "Embedded user representation (used when user is nested in other resources)",
                  "…": "see OpenAPI spec for full schema"
                },
                {
                  "type": "unknown",
                  "nullable": true
                }
              ]
            },
            "invitee_email": {
              "type": "string",
              "nullable": true,
              "description": "Email address being invited, visible to users who can manage invitations",
              "format": "email",
              "example": "invitee@example.com"
            },
            "invited_by": {
              "type": "object",
              "description": "Embedded user representation (used when user is nested in other resources)",
              "required": [
                "id",
                "type",
                "name",
                "slug",
                "avatar",
                "initials"
              ],
              "properties": {
                "id": {
                  "type": "integer",
                  "nullable": false,
                  "description": "Unique identifier for the user",
                  "example": 12345
                },
                "type": {
                  "type": "string",
                  "nullable": false,
                  "description": "User type",
                  "enum": [
                    "User"
                  ],
                  "example": "User"
                },
                "name": {
                  "type": "string",
                  "nullable": false,
                  "description": "User's display name",
                  "example": "John Doe"
                },
                "slug": {
                  "type": "string",
                  "nullable": false,
                  "description": "URL-safe identifier (use this in API paths)",
                  "example": "john-doe"
                },
                "avatar": {
                  "type": "string",
                  "nullable": true,
                  "description": "URL to user's avatar image",
                  "format": "uri",
                  "example": "https://d2w9rnfcy7mm78.cloudfront.net/12345/avatar.jpg"
                },
                "initials": {
                  "type": "string",
                  "nullable": false,
                  "description": "User's initials",
                  "example": "JD"
                }
              },
              "refName": "EmbeddedUser"
            },
            "state": {
              "type": "string",
              "nullable": false,
              "enum": [
                "pending",
                "accepted",
                "declined",
                "revoked"
              ],
              "example": "pending"
            },
            "accepted_at": {
              "type": "string",
              "nullable": true,
              "description": "When the invitation was accepted",
              "format": "date-time",
              "example": null
            },
            "created_at": {
              "type": "string",
              "nullable": false,
              "description": "When the invitation was created",
              "format": "date-time",
              "example": "2023-01-15T10:30:00Z"
            },
            "updated_at": {
              "type": "string",
              "nullable": false,
              "description": "When the invitation was last updated",
              "format": "date-time",
              "example": "2023-01-15T10:30:00Z"
            },
            "_links": {
              "type": "object",
              "description": "Links for navigation. Empty today because no public endpoint\naddresses an invitation directly; reserved for future use.\n",
              "required": [],
              "properties": {}
            }
          },
          "refName": "MembershipInvitation"
        },
        {
          "type": "unknown",
          "nullable": true
        }
      ]
    }
  },
  "refName": "GroupMemberInviteResponse"
}
```