# Group API Reference

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

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

- Label: List pending group invitations
- Docs: https://www.are.na/developers/explore/group/invitations
- Markdown: https://www.are.na/developers/explore/group/invitations.md
- Requires resource id: yes
- Response content type: application/json

Returns a paginated list of open (pending) membership invitations for
the group, newest first. Only users who can manage invitations on the
group — typically the owner and existing members — may list them.

Use `POST /v3/groups/{id}/invitations` to create an invitation; that
endpoint chooses between direct add and invitation automatically based
on the follow relationship.

### Invitation acceptance flow

Invitees receive an email with a tokenized URL that opens the Are.na web
UI. Accept and decline actions are handled there via GraphQL
(`acceptMembershipInvitation` and `declineMembershipInvitation`), not
through this REST API. There is no REST endpoint for invitees to list
their own pending invitations today; invitation discovery is email-link
based.

**Authentication required.**

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

Query parameters:
- page: number (optional) — Page number for pagination
- per: number (optional) — Number of items per page (max 100)

Response schema:
```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "description": "Array of pending membership invitations",
      "items": {
        "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"
      }
    },
    "meta": {
      "type": "object",
      "description": "Pagination metadata",
      "required": [
        "current_page",
        "per_page",
        "total_pages",
        "total_count",
        "has_more_pages"
      ],
      "properties": {
        "current_page": {
          "type": "integer",
          "nullable": false,
          "description": "Current page number",
          "example": 1
        },
        "next_page": {
          "type": "integer",
          "nullable": true,
          "description": "Next page number (null if last page)",
          "example": 2
        },
        "prev_page": {
          "type": "integer",
          "nullable": true,
          "description": "Previous page number (null if first page)"
        },
        "per_page": {
          "type": "integer",
          "nullable": false,
          "description": "Number of items per page",
          "example": 25
        },
        "total_pages": {
          "type": "integer",
          "nullable": false,
          "description": "Total number of pages available",
          "example": 5
        },
        "total_count": {
          "type": "integer",
          "nullable": false,
          "description": "Total number of items available",
          "example": 120
        },
        "has_more_pages": {
          "type": "boolean",
          "nullable": false,
          "description": "Whether there are more pages available",
          "example": true
        }
      },
      "refName": "PaginationMeta"
    }
  },
  "required": [
    "data",
    "data",
    "meta"
  ],
  "description": "Paginated list of pending membership invitations",
  "refName": "MembershipInvitationListResponse"
}
```