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

# Upsert a dashboard card (CLI metrics sync)

> Creates or updates a dashboard card by (agent_id, event_name). Idempotent — safe to call on every deploy.



## OpenAPI

````yaml /api-reference/openapi.json post /api/v1/runtime/observability/dashboard-cards
openapi: 3.0.0
info:
  title: Runflow Runtime API
  description: >-
    Programmatic surface for the Runflow platform — used by the SDK, the CLI,
    the execution engine, and any server-to-server caller. Authenticate with an
    `x-api-key` header (or `Authorization: Bearer ...`).
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.runflow.ai
    description: Production
  - url: http://localhost:3000
    description: Local development
security: []
tags: []
paths:
  /api/v1/runtime/observability/dashboard-cards:
    post:
      tags:
        - Runtime API - Dashboard Cards
      summary: Upsert a dashboard card (CLI metrics sync)
      description: >-
        Creates or updates a dashboard card by (agent_id, event_name).
        Idempotent — safe to call on every deploy.
      operationId: RuntimeDashboardCardsController_upsertDashboardCard
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - agentId
                - title
                - cardType
                - config
              properties:
                agentId:
                  type: string
                  description: Agent UUID
                title:
                  type: string
                cardType:
                  type: string
                  enum:
                    - number
                    - rate
                    - line
                    - bar
                    - pie
                    - table
                    - funnel
                    - gauge
                  description: >-
                    Card visualization type. All 8 types supported: number,
                    rate, line, bar, pie, table, funnel, gauge.
                config:
                  type: object
                  description: >-
                    Card-type-specific config. Polymorphic shape — see
                    @runflow/shared dashboard-cards types for the per-type
                    required fields.
                tabId:
                  type: string
                  description: Optional dashboard tab (UUID).
                gridLayout:
                  type: object
                  description: Optional grid position (x, y, w, h). Stored in config.
                  properties:
                    x:
                      type: integer
                    'y':
                      type: integer
                    w:
                      type: integer
                    h:
                      type: integer
                sortOrder:
                  type: number
                idempotencyKey:
                  type: string
                  description: Optional caller-supplied key.
      responses:
        '200':
          description: Card upserted successfully.
        '400':
          description: Invalid request body.
      security:
        - bearer: []
components: {}

````