post/channels/{channel_id}/invites

Create channel invite

Creates a new invite for the specified channel with optional parameters such as maximum age, maximum uses, and temporary membership settings. The authenticated user must have permission to create invites for the channel. Returns the created invite with full metadata including usage statistics.

create_channel_invite

Parameters

Name	In	Type	Description
channel_id*	path	SnowflakeType	The ID of the channel

Request body

application/json

json

{
  "type": "object",
  "properties": {
    "max_uses": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 0,
          "maximum": 100,
          "format": "int32"
        },
        {
          "type": "null"
        }
      ],
      "description": "Maximum number of times this invite can be used (0 for unlimited)"
    },
    "max_age": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 0,
          "maximum": 604800,
          "format": "int32"
        },
        {
          "type": "null"
        }
      ],
      "description": "Duration in seconds before the invite expires (0 for never)"
    },
    "unique": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "description": "Whether to create a new unique invite or reuse an existing one"
    },
    "temporary": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "description": "Whether members that joined via this invite should be kicked after disconnecting"
    }
  }
}

Responses

200

Success

json

{
  "oneOf": [
    {
      "$ref": "#/components/schemas/GuildInviteMetadataResponse"
    },
    {
      "$ref": "#/components/schemas/GroupDmInviteMetadataResponse"
    },
    {
      "$ref": "#/components/schemas/PackInviteMetadataResponse"
    }
  ]
}

400

Bad Request - The request was malformed or contained invalid data

json

{
  "type": "object",
  "properties": {
    "code": {
      "$ref": "#/components/schemas/APIErrorCode"
    },
    "message": {
      "type": "string",
      "description": "Human-readable error message"
    },
    "errors": {
      "type": "array",
      "description": "Field-specific validation errors",
      "items": {
        "$ref": "#/components/schemas/ValidationErrorItem"
      }
    }
  },
  "required": [
    "code",
    "message"
  ]
}

401

Unauthorized - Authentication is required or the token is invalid

json

{
  "type": "object",
  "properties": {
    "code": {
      "$ref": "#/components/schemas/APIErrorCode"
    },
    "message": {
      "type": "string",
      "description": "Human-readable error message"
    },
    "errors": {
      "type": "array",
      "description": "Field-specific validation errors",
      "items": {
        "$ref": "#/components/schemas/ValidationErrorItem"
      }
    }
  },
  "required": [
    "code",
    "message"
  ]
}

403

Forbidden - You do not have permission to perform this action

json

{
  "type": "object",
  "properties": {
    "code": {
      "$ref": "#/components/schemas/APIErrorCode"
    },
    "message": {
      "type": "string",
      "description": "Human-readable error message"
    },
    "errors": {
      "type": "array",
      "description": "Field-specific validation errors",
      "items": {
        "$ref": "#/components/schemas/ValidationErrorItem"
      }
    }
  },
  "required": [
    "code",
    "message"
  ]
}

429

Too Many Requests - You are being rate limited

json

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "enum": [
        "RATE_LIMITED"
      ]
    },
    "message": {
      "type": "string"
    },
    "retry_after": {
      "type": "number",
      "description": "Seconds to wait before retrying"
    },
    "global": {
      "type": "boolean",
      "description": "Whether this is a global rate limit"
    }
  },
  "required": [
    "code",
    "message",
    "retry_after"
  ]
}

500

Internal Server Error - An unexpected error occurred

json

{
  "type": "object",
  "properties": {
    "code": {
      "$ref": "#/components/schemas/APIErrorCode"
    },
    "message": {
      "type": "string",
      "description": "Human-readable error message"
    },
    "errors": {
      "type": "array",
      "description": "Field-specific validation errors",
      "items": {
        "$ref": "#/components/schemas/ValidationErrorItem"
      }
    }
  },
  "required": [
    "code",
    "message"
  ]
}