# Tags API

Source: https://frameleaf.app/docs/api/reference/tags/

Use your own server and its scoped API keys.

## Retrieve tags

GET /api/tags

Retrieve a list of all tags.

```json
{
  "description": "Retrieve a list of all tags.",
  "operationId": "getAllTags",
  "parameters": [],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "items": {
              "$ref": "#/components/schemas/TagResponseDto"
            },
            "type": "array"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Retrieve tags",
  "tags": [
    "Tags"
  ],
  "x-frameleaf-permission": "tag.read"
}
```

## Create a tag

POST /api/tags

Create a new tag by providing a name and optional color.

```json
{
  "description": "Create a new tag by providing a name and optional color.",
  "operationId": "createTag",
  "parameters": [],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/TagCreateDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "201": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/TagResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Create a tag",
  "tags": [
    "Tags"
  ],
  "x-frameleaf-permission": "tag.create"
}
```

## Upsert tags

PUT /api/tags

Create or update multiple tags in a single request.

```json
{
  "description": "Create or update multiple tags in a single request.",
  "operationId": "upsertTags",
  "parameters": [],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/TagUpsertDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "items": {
              "$ref": "#/components/schemas/TagResponseDto"
            },
            "type": "array"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Upsert tags",
  "tags": [
    "Tags"
  ],
  "x-frameleaf-permission": "tag.create"
}
```

## Tag assets

PUT /api/tags/assets

Add multiple tags to multiple assets in a single request.

```json
{
  "description": "Add multiple tags to multiple assets in a single request.",
  "operationId": "bulkTagAssets",
  "parameters": [],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/TagBulkAssetsDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/TagBulkAssetsResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Tag assets",
  "tags": [
    "Tags"
  ],
  "x-frameleaf-permission": "tag.asset"
}
```

## Retrieve tag statistics

GET /api/tags/statistics

Count the Timeline items that carry each tag: exactly that tag, and that tag or any tag nested under it. Archived, Locked and hidden items are never counted, and tags the session may not see are left out.

```json
{
  "description": "Count the Timeline items that carry each tag: exactly that tag, and that tag or any tag nested under it. Archived, Locked and hidden items are never counted, and tags the session may not see are left out.",
  "operationId": "getTagStatistics",
  "parameters": [],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "items": {
              "$ref": "#/components/schemas/TagStatisticsResponseDto"
            },
            "type": "array"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Retrieve tag statistics",
  "tags": [
    "Tags"
  ],
  "x-frameleaf-permission": "tag.read"
}
```

## Delete a tag

DELETE /api/tags/{id}

Delete a specific tag by its ID.

```json
{
  "description": "Delete a specific tag by its ID.",
  "operationId": "deleteTag",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "responses": {
    "204": {
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Delete a tag",
  "tags": [
    "Tags"
  ],
  "x-frameleaf-permission": "tag.delete"
}
```

## Retrieve a tag

GET /api/tags/{id}

Retrieve a specific tag by its ID.

```json
{
  "description": "Retrieve a specific tag by its ID.",
  "operationId": "getTagById",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/TagResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Retrieve a tag",
  "tags": [
    "Tags"
  ],
  "x-frameleaf-permission": "tag.read"
}
```

## Update a tag

PUT /api/tags/{id}

Update an existing tag identified by its ID.

```json
{
  "deprecated": true,
  "description": "Update an existing tag identified by its ID.",
  "operationId": "updateTag",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/TagUpdateDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/TagResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Update a tag",
  "tags": [
    "Tags",
    "Deprecated"
  ],
  "x-frameleaf-permission": "tag.update"
}
```

## Untag assets

DELETE /api/tags/{id}/assets

Remove a tag from all the specified assets.

```json
{
  "description": "Remove a tag from all the specified assets.",
  "operationId": "untagAssets",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/BulkIdsDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "items": {
              "$ref": "#/components/schemas/BulkIdResponseDto"
            },
            "type": "array"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Untag assets",
  "tags": [
    "Tags"
  ],
  "x-frameleaf-permission": "tag.asset"
}
```

## Tag assets

PUT /api/tags/{id}/assets

Add a tag to all the specified assets.

```json
{
  "description": "Add a tag to all the specified assets.",
  "operationId": "tagAssets",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/BulkIdsDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "items": {
              "$ref": "#/components/schemas/BulkIdResponseDto"
            },
            "type": "array"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Tag assets",
  "tags": [
    "Tags"
  ],
  "x-frameleaf-permission": "tag.asset"
}
```