Message API/docs/components/symbol-management/symbols

Symbols

Upload payloads and symbol record contracts for the Symbol Management module.

Routes

Use these routes to manage symbol records within a folder.

List by folder: load all symbol records for a folder ID.
Create: add a new symbol under the active folder.
Get by ID: open detailed symbol information.
Patch: update metadata, content, or move the symbol to another folder.
Delete: remove the symbol record.
Auth header: include `x-api-key` on every symbols request. If you need to issue or manage that client key, see API Key Management Overview.

GET    /symbol/folders/:folderId/symbols
POST   /symbol/folders/:folderId/symbols
GET    /symbol/symbols/:id
PATCH  /symbol/symbols/:id
DELETE /symbol/symbols/:id

Routes

Request Contracts

The module stores uploaded file information inside the `data` field as a JSON string containing file metadata and base64 content.

For readability, document the inner `data` object separately and then show the final payload using `JSON.stringify(...)`.

Serialized Data Structure

{
  name: 'valve.png',
  type: 'image/png',
  content: '<base64>',
  width: 120,
  height: 80,
}

Create Symbol Payload

{
  name: 'Valve',
  type: 'image/png',
  data: JSON.stringify({
    name: 'valve.png',
    type: 'image/png',
    content: '<base64>',
    width: 120,
    height: 80,
  }),
}

Update Symbol Payload

{
  name: 'Valve Updated',
  type: 'image/png',
  data: JSON.stringify({
    name: 'valve.png',
    type: 'image/png',
    content: '<base64>',
    width: 120,
    height: 80,
  }),
  folderId: 3,
}

Upload Note

The user selects a file from the computer, the frontend reads it, extracts base64 content, measures the image dimensions, and serializes that data into the `data` string.

Use the file name without extension for the symbol `name`, and use the uploaded MIME type for `type`.

Preview source: a client can generate a local data URL before save if preview support is needed.
Stored contract: the backend receives the serialized JSON string, not the raw data URL.
Protected uploads: the same `x-api-key` header is required for list, create, update, and delete requests.
Folder refresh: after create, update, move, or delete, reload the active folder symbols list.

Example API Calls

These examples show request functions you can call from a client application after a file is prepared for upload.

Shared Types

const API_BASE_URL = 'http://localhost:5203/api'

type SymbolFileData = {
  name: string
  type: string
  content: string
  width: number
  height: number
}

type SymbolRecord = {
  id: number
  name: string
  type: string
  data: string
  folderId: number
}

Get Symbols

async function getSymbols(folderId: number): Promise<SymbolRecord[]> {
  const response = await fetch(`${API_BASE_URL}/symbol/folders/${folderId}/symbols`, {
    headers: {
      'x-api-key': CLIENT_API_KEY,
    },
  })

  if (!response.ok) {
    throw new Error(await response.text())
  }

  return response.json()
}

Create Symbol

async function createSymbol(
  folderId: number,
  payload: {
    name: string
    type: string
    data: SymbolFileData
  }
): Promise<SymbolRecord> {
  const response = await fetch(`${API_BASE_URL}/symbol/folders/${folderId}/symbols`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': CLIENT_API_KEY,
    },
    body: JSON.stringify({
      name: payload.name,
      type: payload.type,
      data: JSON.stringify(payload.data),
    }),
  })

  if (!response.ok) {
    throw new Error(await response.text())
  }

  return response.json()
}

Update Symbol

async function updateSymbol(
  id: number,
  payload: {
    name: string
    type: string
    data: SymbolFileData
    folderId: number
  }
): Promise<SymbolRecord> {
  const response = await fetch(`${API_BASE_URL}/symbol/symbols/${id}`, {
    method: 'PATCH',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': CLIENT_API_KEY,
    },
    body: JSON.stringify({
      name: payload.name,
      type: payload.type,
      data: JSON.stringify(payload.data),
      folderId: payload.folderId,
    }),
  })

  if (!response.ok) {
    throw new Error(await response.text())
  }

  return response.json()
}

Delete Symbol

async function deleteSymbol(id: number): Promise<void> {
  const response = await fetch(`${API_BASE_URL}/symbol/symbols/${id}`, {
    method: 'DELETE',
    headers: {
      'x-api-key': CLIENT_API_KEY,
    },
  })

  if (!response.ok) {
    throw new Error(await response.text())
  }
}