Visuals API

Overview

The Visuals API allows you to create, retrieve, update, delete, and duplicate visuals (cards/frames) programmatically.

Base path:

https://semaphor.cloud/api/management/v1/visuals

All endpoints require authentication and permission checks.

Endpoints

List Visuals

GET /visuals

Lists visuals accessible to the authenticated user.
Supports search, pagination, and returns permission metadata.

Query Parameters:

projectId (string, optional)
tenantId (string, optional)
search (string, optional)
limit (integer, default: 500)
offset (integer, default: 0)

Example Request:

curl -X GET "https://semaphor.cloud/api/management/v1/visuals?search=bar&limit=10" -H "Authorization: Bearer <token>"

Example Response:

{
  "visuals": [
    {
      "id": "visual_abc123",
      "title": "Bar Chart",
      "description": "A bar chart visual",
      "permissions": {
        "canEdit": true,
        "canShare": true,
        "canDelete": false
      },
      "ownership": {
        /* ... */
      }
    }
  ],
  "total": 1
}

Create Visual

POST /visuals

Creates a new visual.

Request Body:

{
  "title": "Bar Chart",
  "description": "A bar chart visual",
  "frameObject": {
    /* visual configuration object */
  },
  "tenantId": "tenant_123"
}

frameObject: This is a JSON representation of a visual frame. If omitted, an empty frame will be created. You can use the frameObject from an existing visual as a template.

Sample frameObject:

{
  "id": "74a0f4a3-f18b-4fe3-9e30-dbbfd2305485",
  "cards": [
    {
      "id": "7369f283-3b52-4b6a-b507-e79c1d205000",
      "title": "Title",
      "description": "Description",
      "preferences": {},
      "type": "bar",
      "sql": "",
      "data": [],
      "dataSource": {
        "connectionId": "c_75e24958-4470-4b13-8fef-a2de1d9fab98",
        "connectionType": "API",
        "mode": "database",
        "selectedEntities": [
          {
            "connectionId": "c_75e24958-4470-4b13-8fef-a2de1d9fab98",
            "connectionType": "API",
            "type": "table",
            "database": "",
            "schema": "",
            "name": "api",
            "dialect": "duckdb"
          }
        ],
        "dbSelection": {
          "database": "",
          "schema": "",
          "entityType": "table"
        }
      },
      "connectionId": "c_75e24958-4470-4b13-8fef-a2de1d9fab98",
      "lastSelectedDatabase": "",
      "lastSelectedSchema": "",
      "datamodelId": "",
      "lastSelectedTable": "api",
      "config": {
        "metricColumns": [
          {
            "id": "metrics-api-order_id-1753119318387",
            "name": "order_id",
            "dataType": "VARCHAR",
            "label": "Count of Order Id",
            "qualifiedEntityName": "api",
            "entityId": "api",
            "entityName": "api",
            "entityType": "table",
            "role": "metric",
            "aggregate": "COUNT"
          }
        ],
        "groupByColumns": [
          {
            "id": "groupBy-api-ship_mode-1753119320338",
            "name": "ship_mode",
            "dataType": "VARCHAR",
            "label": "Ship Mode",
            "qualifiedEntityName": "api",
            "entityId": "api",
            "entityName": "api",
            "entityType": "table",
            "role": "groupby"
          }
        ]
      },
      "lastSelectedDatamodelId": "",
      "customCfg": null
    }
  ],
  "activeCardId": "7369f283-3b52-4b6a-b507-e79c1d205000"
}

Example Request:

curl -X POST https://semaphor.cloud/api/management/v1/visuals \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Bar Chart", "description": "A bar chart visual", "frameObject": { /* ...see above... */ } }'

Example Response:

{
  "id": "visual_xyz789",
  "title": "Bar Chart",
  "description": "A bar chart visual",
  "frameObject": {
    /* ... */
  },
  "projectId": "project_abc",
  "createdByOrgUser": null,
  "createdByTenantUser": "user_123",
  "tenantId": "tenant_123"
}

Duplicate Visual

POST /visuals/:id/duplicate

Duplicates an existing visual, including its frameObject and properties.
The new visual will have a new ID, and you can optionally override the title and description.

Request Body (optional):

{
  "title": "Bar Chart (Copy)",
  "description": "A duplicate of my bar chart."
}

If no body is provided, the duplicate will have the original title with "(Copy)" appended and the same description.

Example Request:

curl -X POST https://semaphor.cloud/api/management/v1/visuals/visual_xyz789/duplicate \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Bar Chart (Copy)" }'

Example Response:

{
  "message": "Visual duplicated successfully",
  "original": {
    "id": "visual_xyz789",
    "title": "Bar Chart"
  },
  "duplicate": {
    "id": "visual_newid123",
    "title": "Bar Chart (Copy)",
    "description": "A duplicate of my bar chart.",
    "frameObject": {
      /* ... */
    },
    "permissions": {
      "canEdit": true,
      "canShare": true,
      "canDelete": true
    }
    /* ...other fields... */
  }
}

Get Visual by ID

GET /visuals/:id

Returns details for a specific visual, including permissions.

Example Request:

curl -X GET https://semaphor.cloud/api/management/v1/visuals/visual_xyz789 \
  -H "Authorization: Bearer <token>"

Example Response:

{
  "id": "visual_xyz789",
  "title": "Bar Chart",
  "description": "A bar chart visual",
  "frameObject": {
    /* ... */
  },
  "permissions": {
    "canEdit": true,
    "canShare": true,
    "canDelete": true
  }
  /* ...other fields... */
}

Update Visual

PUT /visuals/:id

Updates visual fields (title, description, frameObject, isPrivate, tenantId).

Request Body:

{
  "title": "Updated Bar Chart",
  "description": "Updated description"
}

Example Request:

curl -X PUT https://semaphor.cloud/api/management/v1/visuals/visual_xyz789 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Updated Bar Chart" }'

Example Response:

{
  "id": "visual_xyz789",
  "title": "Updated Bar Chart",
  "description": "Updated description",
  "permissions": {
    /* ... */
  }
}

Delete Visual

DELETE /visuals/:id

Deletes a visual by ID.

Example Request:

curl -X DELETE https://semaphor.cloud/api/management/v1/visuals/visual_xyz789 \
  -H "Authorization: Bearer <token>"

Example Response:

{
  "message": "Visual deleted successfully",
  "deletedVisual": {
    "id": "visual_xyz789",
    "title": "Bar Chart",
    "projectId": "project_abc",
    "tenantId": "tenant_123"
  }
}

Error Handling

All endpoints return standard error responses with appropriate HTTP status codes (400, 401, 403, 404, 409, 500, etc.).
Validation errors return details in the response body.

Notes

All endpoints require authentication (Bearer token).
Permission checks are enforced for all operations.

Visuals API

On this page