fireblocks Tags API

openapi: 3.2.0
info:
  title: Fireblocks Tags API
  description: 'Fireblocks provides a suite of applications to manage digital asset operations and a complete development platform to build your business on the blockchain.


    - Visit our website for more information: Fireblocks Website

    - Visit our developer docs: Fireblocks DevPortal'
  version: 1.6.2
  contact:
    email: developers@fireblocks.com
servers:
- url: https://api.fireblocks.io/v1
  description: Fireblocks Production Environment Base URL
- url: https://sandbox-api.fireblocks.io/v1
  description: Fireblocks Sandbox Environment Base URL
tags:
- name: Tags
paths:
  /tags:
    post:
      operationId: createTag
      summary: Create a new tag
      description: 'Create a new tag.

        Endpoint Permissions: For protected tags: ADMIN,NON_SIGNING_ADMIN,OWNER. For non protected tags: ADMIN,NON_SIGNING_ADMIN,OWNER,SIGNER,EDITOR,APPROVER.'
      tags:
      - Tags
      x-rate-limit-category: write
      parameters:
      - $ref: '#/components/parameters/X-Idempotency-Key'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTagRequest'
      responses:
        '201':
          description: Tag created successfully
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag'
      x-readme:
        code-samples:
        - language: typescript
          code: 'const response: Promise<FireblocksResponse<Tag>> = fireblocks.tags.createTag(tagsApiCreateTagRequest);'
          name: Fireblocks SDK TypeScript example
        - language: java
          code: CompletableFuture<ApiResponse<Tag>> response = fireblocks.tags().createTag(createTagRequest, idempotencyKey);
          name: Fireblocks SDK Java example
        - language: python
          code: response = fireblocks.tags.create_tag(create_tag_request, idempotency_key);
          name: Fireblocks SDK Python example
      x-codeSamples:
      - lang: TypeScript
        source: 'const response: Promise<FireblocksResponse<Tag>> = fireblocks.tags.createTag(tagsApiCreateTagRequest);'
      - lang: Java
        source: CompletableFuture<ApiResponse<Tag>> response = fireblocks.tags().createTag(createTagRequest, idempotencyKey);
      - lang: Python
        source: response = fireblocks.tags.create_tag(create_tag_request, idempotency_key);
    get:
      operationId: getTags
      summary: Get list of tags
      description: Retrieve a paged list of all tags according to filters.
      tags:
      - Tags
      x-rate-limit-category: query
      parameters:
      - in: query
        name: pageCursor
        description: Page cursor to get the next page.
        example: MjAyMy0xMi0xMyAyMDozNjowOC4zMDI=:MTEwMA==
        required: false
        schema:
          type: string
      - in: query
        name: pageSize
        description: Maximum number of items in the page
        required: false
        schema:
          type: number
          minimum: 1
          maximum: 100
          default: 100
      - in: query
        name: label
        description: Label prefix to filter by.
        example: VIP
        required: false
        schema:
          type: string
      - in: query
        name: tagIds
        description: List of tag IDs to filter by.
        required: false
        schema:
          type: array
          maxItems: 100
          items:
            type: string
            format: uuid
      - in: query
        name: includePendingApprovalsInfo
        description: Whether to include pending approval requests info.
        required: false
        schema:
          type: boolean
          default: false
      - in: query
        name: isProtected
        required: false
        schema:
          type: boolean
      - in: query
        name: type
        description: Filter by tag type
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/TagType'
      - in: query
        name: allowedEntityType
        description: 'Filter tags whose allow-list contains this entity type. Known values: vault_account, contact.'
        example: contact
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Tags fetched successfully
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagsPagedResponse'
      x-readme:
        code-samples:
        - language: typescript
          code: 'const response: Promise<FireblocksResponse<TagsPagedResponse>> = fireblocks.tags.getTags(tagsApiGetTagsRequest);'
          name: Fireblocks SDK TypeScript example
        - language: java
          code: CompletableFuture<ApiResponse<TagsPagedResponse>> response = fireblocks.tags().getTags(pageCursor, pageSize, label, tagIds, includePendingApprovalsInfo, isProtected, type, allowedEntityType);
          name: Fireblocks SDK Java example
        - language: python
          code: response = fireblocks.tags.get_tags(page_cursor, page_size, label, tag_ids, include_pending_approvals_info, is_protected, type, allowed_entity_type);
          name: Fireblocks SDK Python example
      x-codeSamples:
      - lang: TypeScript
        source: 'const response: Promise<FireblocksResponse<TagsPagedResponse>> = fireblocks.tags.getTags(tagsApiGetTagsRequest);'
      - lang: Java
        source: CompletableFuture<ApiResponse<TagsPagedResponse>> response = fireblocks.tags().getTags(pageCursor, pageSize, label, tagIds, includePendingApprovalsInfo, isProtected, type, allowedEntityType);
      - lang: Python
        source: response = fireblocks.tags.get_tags(page_cursor, page_size, label, tag_ids, include_pending_approvals_info, is_protected, type, allowed_entity_type);
  /tags/{tagId}:
    get:
      summary: Get a tag
      description: Retrieve an existing tag by ID.
      tags:
      - Tags
      x-rate-limit-category: read
      parameters:
      - in: path
        name: tagId
        required: true
        description: The ID of the tag to retrieve
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: A tag object
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag'
      operationId: getTag
      x-readme:
        code-samples:
        - language: typescript
          code: 'const response: Promise<FireblocksResponse<Tag>> = fireblocks.tags.getTag(tagsApiGetTagRequest);'
          name: Fireblocks SDK TypeScript example
        - language: java
          code: CompletableFuture<ApiResponse<Tag>> response = fireblocks.tags().getTag(tagId);
          name: Fireblocks SDK Java example
        - language: python
          code: response = fireblocks.tags.get_tag(tag_id);
          name: Fireblocks SDK Python example
      x-codeSamples:
      - lang: TypeScript
        source: 'const response: Promise<FireblocksResponse<Tag>> = fireblocks.tags.getTag(tagsApiGetTagRequest);'
      - lang: Java
        source: CompletableFuture<ApiResponse<Tag>> response = fireblocks.tags().getTag(tagId);
      - lang: Python
        source: response = fireblocks.tags.get_tag(tag_id);
    patch:
      summary: Update a tag
      description: 'Update an existing specified tag.

        Endpoint Permission: For protected tags: Owner, Admin, Non-Signing Admin. For non protected tags: Owner, Admin, Non-Signing Admin, Signer, Editor, Approver.'
      tags:
      - Tags
      x-rate-limit-category: write
      parameters:
      - in: path
        name: tagId
        required: true
        description: The ID of the tag to update
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/X-Idempotency-Key'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTagRequest'
      responses:
        '200':
          description: A tag object
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag'
      operationId: updateTag
      x-readme:
        code-samples:
        - language: typescript
          code: 'const response: Promise<FireblocksResponse<Tag>> = fireblocks.tags.updateTag(tagsApiUpdateTagRequest);'
          name: Fireblocks SDK TypeScript example
        - language: java
          code: CompletableFuture<ApiResponse<Tag>> response = fireblocks.tags().updateTag(updateTagRequest, tagId, idempotencyKey);
          name: Fireblocks SDK Java example
        - language: python
          code: response = fireblocks.tags.update_tag(update_tag_request, tag_id, idempotency_key);
          name: Fireblocks SDK Python example
      x-codeSamples:
      - lang: TypeScript
        source: 'const response: Promise<FireblocksResponse<Tag>> = fireblocks.tags.updateTag(tagsApiUpdateTagRequest);'
      - lang: Java
        source: CompletableFuture<ApiResponse<Tag>> response = fireblocks.tags().updateTag(updateTagRequest, tagId, idempotencyKey);
      - lang: Python
        source: response = fireblocks.tags.update_tag(update_tag_request, tag_id, idempotency_key);
    delete:
      summary: Delete a tag
      description: 'Delete the specified tag.

        Endpoint Permission: For protected tags: Owner, Admin, Non-Signing Admin. For non protected tags: Owner, Admin, Non-Signing Admin, Signer, Editor, Approver.'
      tags:
      - Tags
      x-rate-limit-category: write
      parameters:
      - in: path
        name: tagId
        required: true
        description: The ID of the tag to retrieve
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Tag was deleted successfully
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
      operationId: deleteTag
      x-readme:
        code-samples:
        - language: typescript
          code: 'const response: Promise<FireblocksResponse<void>> = fireblocks.tags.deleteTag(tagsApiDeleteTagRequest);'
          name: Fireblocks SDK TypeScript example
        - language: java
          code: CompletableFuture<ApiResponse<Void>> response = fireblocks.tags().deleteTag(tagId);
          name: Fireblocks SDK Java example
        - language: python
          code: response = fireblocks.tags.delete_tag(tag_id);
          name: Fireblocks SDK Python example
      x-codeSamples:
      - lang: TypeScript
        source: 'const response: Promise<FireblocksResponse<void>> = fireblocks.tags.deleteTag(tagsApiDeleteTagRequest);'
      - lang: Java
        source: CompletableFuture<ApiResponse<Void>> response = fireblocks.tags().deleteTag(tagId);
      - lang: Python
        source: response = fireblocks.tags.delete_tag(tag_id);
  /tags/approval_requests/{id}:
    get:
      summary: Get an approval request by id
      tags:
      - Tags
      x-rate-limit-category: read
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: numeric
          example: '12345'
      responses:
        '200':
          description: Approval request fetched successfully
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApprovalRequest'
        '401':
          description: Unauthorized
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Approval request not found
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          $ref: '#/components/responses/Error'
      operationId: getApprovalRequest
      x-readme:
        code-samples:
        - language: typescript
          code: 'const response: Promise<FireblocksResponse<ApprovalRequest>> = fireblocks.tags.getApprovalRequest(tagsApiGetApprovalRequestRequest);'
          name: Fireblocks SDK TypeScript example
        - language: java
          code: CompletableFuture<ApiResponse<ApprovalRequest>> response = fireblocks.tags().getApprovalRequest(id);
          name: Fireblocks SDK Java example
        - language: python
          code: response = fireblocks.tags.get_approval_request(id);
          name: Fireblocks SDK Python example
      x-codeSamples:
      - lang: TypeScript
        source: 'const response: Promise<FireblocksResponse<ApprovalRequest>> = fireblocks.tags.getApprovalRequest(tagsApiGetApprovalRequestRequest);'
      - lang: Java
        source: CompletableFuture<ApiResponse<ApprovalRequest>> response = fireblocks.tags().getApprovalRequest(id);
      - lang: Python
        source: response = fireblocks.tags.get_approval_request(id);
components:
  schemas:
    UpdateTagRequest:
      type: object
      properties:
        label:
          type: string
          description: The tag label
          example: VIP
        description:
          type: string
          description: Description for the tag
          example: Tag for VIP customers
        color:
          type: string
          description: The tag color in hex format
          example: '#FF5733'
    CreateTagRequest:
      type: object
      properties:
        label:
          type: string
          description: The tag label
          minLength: 2
          maxLength: 30
          example: VIP
        description:
          type: string
          description: Description for the tag
          maxLength: 250
          example: Tag for VIP customers
        color:
          type: string
          description: The tag color in hex format
          example: '#FF5733'
        isProtected:
          type: boolean
          description: Indication if the tag is protected tag
          default: false
        type:
          $ref: '#/components/schemas/TagType'
        allowedEntityTypes:
          type: array
          description: 'Allow-list of entity types this tag may be attached to. Soft-defaults to [''vault_account''] when omitted, and is immutable after creation. Known values: vault_account (default), contact.'
          default:
          - vault_account
          minItems: 1
          items:
            type: string
          example:
          - vault_account
      required:
      - label
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
              - INTERNAL
              - AUTHENTICATION
              - AUTHORIZATION
              - VALIDATION
              - NOT_FOUND
              - UNPROCESSABLE_ENTITY
              - FORBIDDEN
            message:
              type: string
          required:
          - type
          - message
      required:
      - error
    TagsPagedResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
        next:
          type:
          - string
          - 'null'
          description: Cursor to the next page
          example: MjAyNS0wNy0wOSAxMDo1MzoxMy40NTI=:NA==
      required:
      - data
      - next
    Tag:
      type: object
      properties:
        id:
          description: The unique identifier of the tag
          type: string
          format: uuid
          example: df4c0987-30da-4976-8dcf-bc2dd41ae331
        label:
          type: string
          description: The tag label
          example: VIP
        description:
          type: string
          description: Description for the tag
          example: Tag for VIP customers
        color:
          type: string
          description: The tag color in hex format
          example: '#FF5733'
        isProtected:
          type: boolean
          description: Indication if the tag is a protected tag
          default: false
        updatedAt:
          type: number
          description: The date and time the tag was last updated
          example: 1717084800000
        type:
          $ref: '#/components/schemas/TagType'
        allowedEntityTypes:
          type: array
          description: 'The entity types this tag may be attached to. Tags created before this field was introduced read back as [''vault_account'']. Known values: vault_account (default), contact.'
          minItems: 1
          items:
            type: string
          example:
          - vault_account
        pendingApprovalRequest:
          $ref: '#/components/schemas/ApprovalRequest'
      required:
      - id
      - label
      - isProtected
      - updatedAt
    ApprovalRequest:
      type: object
      description: Approval request details
      properties:
        id:
          type: string
          format: numeric
          description: The approval request identifier
          example: '12345'
        type:
          type: string
          description: The approval request type
          enum:
          - TAG_UPDATE
          - TAG_DELETE
          - TAG_ATTACH_DETACH
        state:
          type: string
          description: The approval request state
          enum:
          - PENDING
          - APPROVED
          - REJECTED
          - FAILED
          - CANCELLED
          - EXPIRED
      required:
      - id
      - type
      - state
    ErrorSchema:
      type: object
      properties:
        message:
          type: string
        code:
          type: number
    TagType:
      type: string
      description: The tag type, indicating the domain that owns the tag
      enum:
      - WALLET_POOL
  responses:
    Error:
      description: Error Response
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorSchema'
  parameters:
    X-Idempotency-Key:
      name: Idempotency-Key
      in: header
      description: A unique identifier for the request. If the request is sent multiple times with the same idempotency key, the server will return the same response as the first request. The idempotency key is valid for 24 hours.
      required: false
      schema:
        type: string
  headers:
    X-Request-ID:
      schema:
        type: string
      description: Unique ID correlated to the API request. Please provide it in any support ticket you create or on Github issues related to Fireblocks SDKs
  securitySchemes:
    bearerTokenAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
x-readme:
  explorer-enabled: false
  samples-languages:
  - curl
  - javascript
  - python
x-provenance:
  method: harvested
  publisher: Fireblocks
  source: https://swagger.fireblocks.com/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)