> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frayme.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Add a tag

> Apply a tag to a case. Requires the **`tags:write`** scope.

The tag must be an enabled option in your tenant's managed tag
vocabulary (configured under Settings → Tags in the portal); an
arbitrary label is rejected with `400`, so the console's chips, colours,
and filters stay consistent. The applier is recorded as your API key,
never a client-supplied `createdBy`.

Idempotent: applying a tag the case already carries returns `200 OK`
with the originally stored `createdBy` / `createdAt`, not `201`.




## OpenAPI

````yaml /api-reference/openapi.yaml post /cases/{caseId}/tags
openapi: 3.1.0
info:
  title: Frayme Case API
  version: 1.0.0
  description: >
    The partner-facing HTTP API for the Frayme fraud-analysis platform. Submit

    **cases** (KYC, KYB, or Transaction), poll their status, act on paused

    workflow nodes, and deliver external callbacks.


    All requests authenticate with a tenant-scoped API key sent in the

    `X-API-Key` header. Each key carries one or more **scopes** — the required

    scope is listed on every operation below.


    | Scope | Grants |

    | --- | --- |

    | `cases:write` | Submit new cases (`POST /cases`) |

    | `cases:read` | Read a case, list paused nodes, list durable actions |

    | `cases:callback` | Deliver an external callback, or invoke a pending /
    durable action |

    | `tags:read` | List a case's tags (`GET /cases/{caseId}/tags`) |

    | `tags:write` | Add or remove a case's tags (`POST` / `DELETE
    /cases/{caseId}/tags`) |


    Your tenant is derived from the API key — never send `tenantId` in a request

    body; it is ignored. The base URL and your webhook configuration are

    provisioned for you by Frayme.
servers:
  - url: https://core.us.api.frayme.io
    description: Production.
  - url: https://core.us.api.stg.frayme.io
    description: Staging.
security:
  - apiKeyAuth: []
tags:
  - name: Cases
    description: Submit and read cases.
  - name: Pending actions
    description: Act on a workflow node that is paused awaiting an external system.
  - name: Durable actions
    description: Invoke a broker action on a case after it has been decided.
  - name: Callbacks
    description: Deliver the result of an external callback back to a paused node.
  - name: Tags
    description: Read and manage the labels applied to a case.
paths:
  /cases/{caseId}/tags:
    post:
      tags:
        - Tags
      summary: Add a tag
      description: |
        Apply a tag to a case. Requires the **`tags:write`** scope.

        The tag must be an enabled option in your tenant's managed tag
        vocabulary (configured under Settings → Tags in the portal); an
        arbitrary label is rejected with `400`, so the console's chips, colours,
        and filters stay consistent. The applier is recorded as your API key,
        never a client-supplied `createdBy`.

        Idempotent: applying a tag the case already carries returns `200 OK`
        with the originally stored `createdBy` / `createdAt`, not `201`.
      operationId: addCaseTag
      parameters:
        - $ref: '#/components/parameters/CaseId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddTagRequest'
            example:
              tag: high-risk
      responses:
        '200':
          description: The case already carried the tag (idempotent re-apply).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CaseTag'
        '201':
          description: The tag was newly applied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CaseTag'
              example:
                tag: high-risk
                createdBy: apikey:key_01HABCXYZ
                createdAt: '2026-07-09T12:34:56Z'
        '400':
          description: >-
            The tag is empty, exceeds 64 characters, or is not an enabled option
            in the tenant's managed vocabulary.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No API key was supplied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The API key is missing the `tags:write` scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: The tag vocabulary could not be resolved right now; retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    CaseId:
      name: caseId
      in: path
      required: true
      description: The case identifier returned by `POST /cases`.
      schema:
        type: string
  schemas:
    AddTagRequest:
      type: object
      required:
        - tag
      properties:
        tag:
          type: string
          maxLength: 64
          description: >-
            The tag to apply. Must be an enabled option in the tenant's managed
            tag vocabulary.
    CaseTag:
      type: object
      properties:
        tag:
          type: string
          description: The tag label.
        createdBy:
          type: string
          description: >-
            Who applied the tag. For tags added via the API this is the API key
            (`apikey:<keyId>`); for tags added by an analyst it is their user
            id.
        createdAt:
          type: string
          format: date-time
          description: When the tag was applied (RFC 3339).
    Error:
      type: object
      properties:
        error:
          type: string
          description: A human-readable error message.
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: A tenant-scoped API key provisioned by Frayme.

````