Tags API

Ask about this page View Markdown

Base URL: https://YOUR-SERVER/api. Send your API key in x-api-key where authentication is required. A key also needs the listed permission; your account's access rules still apply.

API guide · All endpoints · OpenAPI JSON

GET /tags — Retrieve tags
POST /tags — Create a tag
PUT /tags — Upsert tags
PUT /tags/assets — Tag assets
GET /tags/statistics — Retrieve tag statistics
DELETE /tags/{id} — Delete a tag
GET /tags/{id} — Retrieve a tag
PUT /tags/{id} — Update a tag
DELETE /tags/{id}/assets — Untag assets
PUT /tags/{id}/assets — Tag assets

Retrieve tags

GET /api/tags

Retrieve a list of all tags.

Authentication: API key. Permission: tag.read.

Responses

Field definitions: TagResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/TagResponseDto"
          },
          "type": "array"
        }
      }
    },
    "description": ""
  }
}

Create a tag

POST /api/tags

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

Authentication: API key. Permission: tag.create.

Request body

Required.

Field definitions: TagCreateDto

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/TagCreateDto"
    }
  }
}

Responses

Field definitions: TagResponseDto

{
  "201": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/TagResponseDto"
        }
      }
    },
    "description": ""
  }
}

Upsert tags

PUT /api/tags

Create or update multiple tags in a single request.

Authentication: API key. Permission: tag.create.

Request body

Required.

Field definitions: TagUpsertDto

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/TagUpsertDto"
    }
  }
}

Responses

Field definitions: TagResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/TagResponseDto"
          },
          "type": "array"
        }
      }
    },
    "description": ""
  }
}

Tag assets

PUT /api/tags/assets

Add multiple tags to multiple assets in a single request.

Authentication: API key. Permission: tag.asset.

Request body

Required.

Field definitions: TagBulkAssetsDto

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/TagBulkAssetsDto"
    }
  }
}

Responses

Field definitions: TagBulkAssetsResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/TagBulkAssetsResponseDto"
        }
      }
    },
    "description": ""
  }
}

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.

Authentication: API key. Permission: tag.read.

Responses

Field definitions: TagStatisticsResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/TagStatisticsResponseDto"
          },
          "type": "array"
        }
      }
    },
    "description": ""
  }
}

Delete a tag

DELETE /api/tags/{id}

Delete a specific tag by its ID.

Authentication: API key. Permission: tag.delete.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "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": ""
  }
}

Retrieve a tag

GET /api/tags/{id}

Retrieve a specific tag by its ID.

Authentication: API key. Permission: tag.read.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "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

Field definitions: TagResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/TagResponseDto"
        }
      }
    },
    "description": ""
  }
}

Update a tag

PUT /api/tags/{id}

Update an existing tag identified by its ID.

Deprecated. Avoid this operation in new integrations; use the replacement supported by your server release.

Authentication: API key. Permission: tag.update.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "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"
    }
  }
]

Request body

Required.

Field definitions: TagUpdateDto

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/TagUpdateDto"
    }
  }
}

Responses

Field definitions: TagResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/TagResponseDto"
        }
      }
    },
    "description": ""
  }
}

Untag assets

DELETE /api/tags/{id}/assets

Remove a tag from all the specified assets.

Authentication: API key. Permission: tag.asset.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "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"
    }
  }
]

Request body

Required.

Field definitions: BulkIdsDto

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/BulkIdsDto"
    }
  }
}

Responses

Field definitions: BulkIdResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/BulkIdResponseDto"
          },
          "type": "array"
        }
      }
    },
    "description": ""
  }
}

Tag assets

PUT /api/tags/{id}/assets

Add a tag to all the specified assets.

Authentication: API key. Permission: tag.asset.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "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"
    }
  }
]

Request body

Required.

Field definitions: BulkIdsDto

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/BulkIdsDto"
    }
  }
}

Responses

Field definitions: BulkIdResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/BulkIdResponseDto"
          },
          "type": "array"
        }
      }
    },
    "description": ""
  }
}

Frameleaf and the Frameleaf logo are Trademarks of Frameleaf Inc.