# Group API Reference

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

## POST /v3/groups

- Label: Create a group
- Docs: https://www.are.na/developers/explore/group/post-group
- Markdown: https://www.are.na/developers/explore/group/post-group.md
- Requires resource id: no
- Response content type: application/json

Creates a new group owned by the authenticated user.

**Authentication required.**

Request body schema:
```json
{
  "type": "object",
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string",
      "nullable": false,
      "description": "Group name",
      "example": "Research Studio"
    },
    "description": {
      "type": "string",
      "nullable": false,
      "description": "Group description (supports markdown)",
      "example": "Shared research notes and channels"
    },
    "avatar_url": {
      "type": "string",
      "nullable": false,
      "description": "URL of an avatar image to fetch asynchronously.",
      "format": "uri",
      "example": "https://example.com/avatar.jpg"
    }
  }
}
```

Response schema:
```json
{
  "type": "object",
  "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"
    },
    "description": {
      "type": "oneOf",
      "description": "Group description with markdown, HTML, and plain text renderings",
      "variants": [
        {
          "type": "object",
          "description": "Markdown content with multiple renderings",
          "required": [
            "markdown",
            "html",
            "plain"
          ],
          "properties": {
            "markdown": {
              "type": "string",
              "nullable": false,
              "description": "Original markdown value",
              "example": "This is **only** a [test](https://example.com)."
            },
            "html": {
              "type": "string",
              "nullable": false,
              "description": "HTML rendering of the markdown",
              "example": "<p>This is <strong>only</strong> a <a href=\"https://example.com\" target=\"_blank\" rel=\"nofollow noopener\">test</a>.</p>"
            },
            "plain": {
              "type": "string",
              "nullable": false,
              "description": "Plain text rendering of the markdown",
              "example": "This is only a test (https://example.com)."
            }
          },
          "refName": "MarkdownContent"
        },
        {
          "type": "unknown",
          "nullable": true
        }
      ]
    },
    "created_at": {
      "type": "string",
      "nullable": false,
      "description": "When the group was created",
      "format": "date-time",
      "example": "2023-01-15T10:30:00Z"
    },
    "updated_at": {
      "type": "string",
      "nullable": false,
      "description": "When the group was last updated",
      "format": "date-time",
      "example": "2023-06-20T14:45:00Z"
    },
    "user": {
      "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"
    },
    "counts": {
      "type": "object",
      "description": "Counts of various items for the group",
      "required": [
        "channels",
        "users"
      ],
      "properties": {
        "channels": {
          "type": "integer",
          "nullable": false,
          "description": "Number of channels owned by the group",
          "example": 12
        },
        "users": {
          "type": "integer",
          "nullable": false,
          "description": "Number of users in the group",
          "example": 5
        }
      },
      "refName": "GroupCounts"
    },
    "can": {
      "type": "object",
      "description": "Actions the current user can perform on the group",
      "required": [
        "update",
        "destroy",
        "manage_members",
        "manage_invitations"
      ],
      "properties": {
        "update": {
          "type": "boolean",
          "nullable": false,
          "description": "Whether the user can update this group",
          "example": false
        },
        "destroy": {
          "type": "boolean",
          "nullable": false,
          "description": "Whether the user can delete this group",
          "example": false
        },
        "manage_members": {
          "type": "boolean",
          "nullable": false,
          "description": "Whether the user can add/remove group members",
          "example": false
        },
        "manage_invitations": {
          "type": "boolean",
          "nullable": false,
          "description": "Whether the user can create/revoke group invitations",
          "example": false
        }
      },
      "refName": "GroupAbilities"
    },
    "_links": {
      "type": "object",
      "description": "HATEOAS links for navigation and discovery.\nFollows HAL (Hypertext Application Language) format where link relationships \nare expressed as object keys (e.g., \"self\", \"user\", \"channels\").\n",
      "required": [
        "self"
      ],
      "properties": {
        "self": {
          "type": "object",
          "description": "A hypermedia link containing the URL of a linked resource.\nThe relationship type is expressed by the key in the parent _links object.\n",
          "required": [
            "href"
          ],
          "properties": {
            "href": {
              "type": "string",
              "nullable": false,
              "description": "The URL of the linked resource",
              "format": "uri",
              "example": "https://api.are.na/v3/blocks/12345"
            }
          },
          "refName": "Link"
        }
      },
      "additionalProperties": {
        "type": "object",
        "description": "A hypermedia link containing the URL of a linked resource.\nThe relationship type is expressed by the key in the parent _links object.\n",
        "required": [
          "href"
        ],
        "properties": {
          "href": {
            "type": "string",
            "nullable": false,
            "description": "The URL of the linked resource",
            "format": "uri",
            "example": "https://api.are.na/v3/blocks/12345"
          }
        },
        "refName": "Link"
      },
      "refName": "Links"
    }
  },
  "required": [
    "id",
    "type",
    "name",
    "slug",
    "avatar",
    "initials",
    "created_at",
    "updated_at",
    "user",
    "counts",
    "can",
    "_links"
  ],
  "description": "Full group representation",
  "refName": "Group"
}
```