> ## Documentation Index > Fetch the complete documentation index at: https://docs.member.dev/llms.txt > Use this file to discover all available pages before exploring further. # Merge Tags > Merge a tag into another, retaining target identity and assignment provenance. Human owner JWT only; full-access API keys can read tags but cannot merge. LIVE references refuse the merge. At most 10,000 source assignments, including inactive contacts, can be merged synchronously. Returns one aggregate audit. No Idempotency-Key: a retry after a successful merge returns 404 tag_not_found because the source tag has been soft-deleted. ## OpenAPI ````yaml /openapi/mio-openapi.json post /api/v1/teams/{team_id}/tags/{source_tag_id}/merge openapi: 3.1.0 info: description: >- Production API reference for Membership.io. Use the authored guides for workflows and the generated endpoint pages for exact parameters and schemas. title: Membership.io API version: 0.1.0 servers: - description: Production url: https://api.member.dev security: - bearerAuth: [] paths: /api/v1/teams/{team_id}/tags/{source_tag_id}/merge: post: tags: - tags-admin summary: Merge Tags description: >- Merge a tag into another, retaining target identity and assignment provenance. Human owner JWT only; full-access API keys can read tags but cannot merge. LIVE references refuse the merge. At most 10,000 source assignments, including inactive contacts, can be merged synchronously. Returns one aggregate audit. No Idempotency-Key: a retry after a successful merge returns 404 tag_not_found because the source tag has been soft-deleted. operationId: >- tags_admin.post_tags_admin_post_teams_by_team_id_tags_by_source_tag_id_merge parameters: - in: path name: team_id required: true schema: title: Team Id type: string - in: path name: source_tag_id required: true schema: title: Source Tag Id type: string requestBody: content: application/vnd.api+json: schema: $ref: '#/components/schemas/TagMergeEnvelope' required: true responses: '200': content: application/vnd.api+json: schema: $ref: '#/components/schemas/TagMergeResponse' description: Successful Response '400': content: application/vnd.api+json: schema: $ref: '#/components/schemas/JsonApiErrorResponse' description: Validation error '401': content: application/vnd.api+json: schema: $ref: '#/components/schemas/JsonApiErrorResponse' description: Owner user JWT required '403': content: application/vnd.api+json: schema: $ref: '#/components/schemas/JsonApiErrorResponse' description: >- Owner JWT only. This operation requires user (JWT) authentication, not an API key. '404': content: application/vnd.api+json: schema: $ref: '#/components/schemas/JsonApiErrorResponse' description: >- Missing, deleted or foreign source/target; retries after success return tag_not_found '409': content: application/vnd.api+json: schema: $ref: '#/components/schemas/JsonApiErrorResponse' description: LIVE references, over 10,000 source assignments, or lock contention headers: Retry-After: description: 1 on merge_busy schema: type: string '415': content: application/vnd.api+json: schema: $ref: '#/components/schemas/JsonApiErrorResponse' description: Unsupported media type (requires application/vnd.api+json) '422': content: application/vnd.api+json: schema: $ref: '#/components/schemas/JsonApiErrorResponse' description: Strict tag_merges request or self merge '429': content: application/vnd.api+json: schema: $ref: '#/components/schemas/JsonApiErrorResponse' description: 'Merge limit: 60/hour; Retry-After header' headers: Retry-After: schema: type: string security: - HTTPBearer: [] components: schemas: TagMergeEnvelope: additionalProperties: false properties: data: $ref: '#/components/schemas/TagMergeResource' required: - data title: TagMergeEnvelope type: object TagMergeResponse: properties: data: $ref: '#/components/schemas/TagResource' meta: additionalProperties: type: integer title: Meta type: object required: - data - meta title: TagMergeResponse type: object JsonApiErrorResponse: description: Error JSON:API response. properties: errors: items: $ref: '#/components/schemas/JsonApiError' title: Errors type: array meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta required: - errors title: JsonApiErrorResponse type: object TagMergeResource: additionalProperties: false properties: attributes: $ref: '#/components/schemas/TagMergeAttributes' type: const: tag_merges title: Type type: string required: - type - attributes title: TagMergeResource type: object TagResource: additionalProperties: false properties: attributes: $ref: '#/components/schemas/TagAttributes' id: title: Id type: string links: anyOf: - $ref: '#/components/schemas/JsonApiLinks' - type: 'null' type: const: tags default: tags title: Type type: string required: - id - attributes title: TagResource type: object JsonApiError: properties: code: anyOf: - type: string - type: 'null' title: Code detail: anyOf: - type: string - type: 'null' title: Detail id: anyOf: - type: string - type: 'null' title: Id meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta source: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Source status: title: Status type: string title: title: Title type: string required: - status - title title: JsonApiError type: object TagMergeAttributes: additionalProperties: false properties: target_tag_id: maxLength: 36 minLength: 1 title: Target Tag Id type: string required: - target_tag_id title: TagMergeAttributes type: object TagAttributes: additionalProperties: false properties: color: anyOf: - type: string - type: 'null' title: Color contact_count: anyOf: - minimum: 0 type: integer - type: 'null' readOnly: true title: Contact Count created_at: format: date-time title: Created At type: string created_by: anyOf: - type: string - type: 'null' title: Created By deleted_at: anyOf: - format: date-time type: string - type: 'null' title: Deleted At description: anyOf: - type: string - type: 'null' title: Description last_assigned_at: anyOf: - format: date-time type: string - type: 'null' readOnly: true title: Last Assigned At last_assigned_by_user_id: anyOf: - type: string - type: 'null' readOnly: true title: Last Assigned By User Id name: title: Name type: string slug: title: Slug type: string team_id: title: Team Id type: string updated_at: format: date-time title: Updated At type: string required: - team_id - name - slug - color - description - created_by - created_at - updated_at - deleted_at title: TagAttributes type: object JsonApiLinks: properties: self: anyOf: - type: string - type: 'null' title: Self title: JsonApiLinks type: object securitySchemes: bearerAuth: bearerFormat: JWT or mio_sk API key description: >- Send platform JWTs, contact JWTs, or team API keys as `Authorization: Bearer `. scheme: bearer type: http HTTPBearer: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.