> ## Documentation Index > Fetch the complete documentation index at: https://traceroot.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create a dashboard widget > Create a widget on a dashboard the authenticated user can write to. Requires MEMBER role or higher in the project's workspace (the write service decides). Strict create — never idempotent, ``created`` is always ``true`` on success. Args: request (Request): Incoming request (rate-limit plumbing). response (Response): Outgoing response (rate-limit plumbing). auth (AccountStampedAuth): Account-scope user auth (session token or CLI access JWT); its resolved ``user_id`` becomes the actor. payload (CreateWidgetRequest): The widget to create. _live (None): Write-path liveness gate (blocks a revoked JWT session). Returns: CreateWidgetResponse: The created widget. ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/public/widgets openapi: 3.1.0 info: title: TraceRoot Public API version: 0.1.0 servers: - description: TraceRoot Cloud url: https://app.traceroot.ai - description: Self-hosted url: '{baseUrl}' variables: baseUrl: default: http://localhost:8000 description: Your TraceRoot backend URL security: [] paths: /api/v1/public/widgets: post: tags: - Widgets summary: Create a dashboard widget description: >- Create a widget on a dashboard the authenticated user can write to. Requires MEMBER role or higher in the project's workspace (the write service decides). Strict create — never idempotent, ``created`` is always ``true`` on success. Args: request (Request): Incoming request (rate-limit plumbing). response (Response): Outgoing response (rate-limit plumbing). auth (AccountStampedAuth): Account-scope user auth (session token or CLI access JWT); its resolved ``user_id`` becomes the actor. payload (CreateWidgetRequest): The widget to create. _live (None): Write-path liveness gate (blocks a revoked JWT session). Returns: CreateWidgetResponse: The created widget. operationId: create_widget requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateWidgetRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/CreateWidgetResponse' description: Successful Response '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Invalid request '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Authentication failed or session revoked '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Insufficient role or wrong credential kind '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Not found '422': content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' description: Validation Error '503': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Write service unavailable security: - BearerAuth: [] components: schemas: CreateWidgetRequest: description: >- Body for creating a widget on a dashboard. Unlike the other create bodies, ``spec`` is deep-validated here: it is a structured contract the agent/CLI must compose (a wrong shape only surfaces at render time otherwise), and the union below is what generated tool schemas show the model. properties: dashboard_id: title: Dashboard Id type: string display_config: anyOf: - additionalProperties: true type: object - type: 'null' title: Display Config project_id: title: Project Id type: string spec: anyOf: - additionalProperties: false description: >- Chart spec over the "spans" view; the enums below are the complete field vocabulary for this view. properties: breakdown: enum: - name - span_kind - error_type - model_name - environment - null title: Breakdown type: - string - 'null' display: additionalProperties: false description: Controls how the query result is rendered on the dashboard. properties: type: enum: - line - area - bar - pie - number - table - histogram title: Type type: string required: - type title: WidgetDisplay type: object filters: items: additionalProperties: false description: A single filter predicate applied to a widget query. properties: field: enum: - name - span_kind - status - error_type - model_name - environment - is_root - duration_ms - cost - input_tokens - output_tokens - cache_read_tokens - cache_write_tokens - total_tokens - metadata title: Field type: string key: title: Key type: string op: enum: - '=' - contains - in - '>' - '>=' - < - <= title: Op type: string value: anyOf: - minLength: 1 type: string - type: number - items: minLength: 1 type: string maxItems: 100 minItems: 1 type: array title: Value type: - string - number - array required: - field - op - value title: WidgetFilter type: object title: Filters type: array metric: additionalProperties: false description: >- The measure and aggregation function that define the widget's y-axis. properties: agg: enum: - count - sum - avg - min - max - p50 - p75 - p90 - p95 - p99 - uniq title: Agg type: string measure: enum: - duration_ms - cost - input_tokens - output_tokens - cache_read_tokens - cache_write_tokens - total_tokens - tokens_per_second - trace_id - count title: Measure type: string required: - measure - agg title: WidgetMetric type: object view: const: spans title: View type: string required: - view - metric - display title: WidgetSpec (spans) type: object - additionalProperties: false description: >- Chart spec over the "traces" view; the enums below are the complete field vocabulary for this view. properties: breakdown: enum: - name - user_id - session_id - environment - null title: Breakdown type: - string - 'null' display: additionalProperties: false description: Controls how the query result is rendered on the dashboard. properties: type: enum: - line - area - bar - pie - number - table - histogram title: Type type: string required: - type title: WidgetDisplay type: object filters: items: additionalProperties: false description: A single filter predicate applied to a widget query. properties: field: enum: - name - user_id - session_id - environment - duration_ms - cost - input_tokens - output_tokens - cache_read_tokens - cache_write_tokens - total_tokens - error_count title: Field type: string key: title: Key type: string op: enum: - '=' - contains - in - '>' - '>=' - < - <= title: Op type: string value: anyOf: - minLength: 1 type: string - type: number - items: minLength: 1 type: string maxItems: 100 minItems: 1 type: array title: Value type: - string - number - array required: - field - op - value title: WidgetFilter type: object title: Filters type: array metric: additionalProperties: false description: >- The measure and aggregation function that define the widget's y-axis. properties: agg: enum: - count - sum - avg - min - max - p50 - p75 - p90 - p95 - p99 - uniq title: Agg type: string measure: enum: - duration_ms - cost - input_tokens - output_tokens - cache_read_tokens - cache_write_tokens - total_tokens - count - error_count title: Measure type: string required: - measure - agg title: WidgetMetric type: object view: const: traces title: View type: string required: - view - metric - display title: WidgetSpec (traces) type: object - $ref: '#/components/schemas/TraceFeedSpec' description: >- The widget's content. For type "query": a chart spec (view/filters/metric/breakdown/display). For type "trace_feed": a trace-list feed spec (predicate filters + row limit). title: Spec title: title: Title type: string type: title: Type type: string required: - project_id - dashboard_id - title - type - spec title: CreateWidgetRequest type: object CreateWidgetResponse: description: The created widget (widget creation is strict, never idempotent). properties: created: title: Created type: boolean dashboard_id: title: Dashboard Id type: string id: title: Id type: string title: title: Title type: string type: title: Type type: string required: - id - dashboard_id - title - type - created title: CreateWidgetResponse type: object ErrorResponse: description: >- The canonical public error envelope (matches the gateway's normalized shape). properties: detail: title: Detail type: string required: - detail title: ErrorResponse type: object HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' title: Detail type: array title: HTTPValidationError type: object TraceFeedSpec: additionalProperties: false description: >- Spec for a ``trace_feed`` widget: a filtered live list of recent traces. Mirrors the trace-list predicate wire format (canonical shape: what ``isValidPredicate`` in frontend/ui/src/features/filters/predicate.ts accepts and the dashboard seed produces). ``limit`` carries the trace-list page-size bound; it defaults to 10 rows in the renderer when omitted. properties: filters: items: anyOf: - $ref: '#/components/schemas/TraceFeedInPredicate' - $ref: '#/components/schemas/TraceFeedNumericPredicate' - $ref: '#/components/schemas/TraceFeedTextPredicate' maxItems: 20 title: Filters type: array limit: maximum: 200 minimum: 1 title: Limit type: integer title: TraceFeedSpec type: object ValidationError: properties: ctx: title: Context type: object input: title: Input loc: items: anyOf: - type: string - type: integer title: Location type: array msg: title: Message type: string type: title: Error Type type: string required: - loc - msg - type title: ValidationError type: object TraceFeedInPredicate: additionalProperties: false description: 'Membership predicate: the field''s value is one of the listed strings.' properties: field: title: Field type: string key: maxLength: 256 minLength: 1 title: Key type: string op: const: in title: Op type: string value: items: maxLength: 1024 type: string minItems: 1 title: Value type: array required: - field - op - value title: TraceFeedInPredicate type: object TraceFeedNumericPredicate: additionalProperties: false description: Numeric comparison predicate (equality or ordering) on a finite number. properties: field: title: Field type: string key: maxLength: 256 minLength: 1 title: Key type: string op: enum: - eq - gt - gte - lt - lte title: Op type: string value: title: Value type: number required: - field - op - value title: TraceFeedNumericPredicate type: object TraceFeedTextPredicate: additionalProperties: false description: 'Text predicate: exact match or substring containment.' properties: field: title: Field type: string key: maxLength: 256 minLength: 1 title: Key type: string op: enum: - eq - contains title: Op type: string value: maxLength: 1024 minLength: 1 title: Value type: string required: - field - op - value title: TraceFeedTextPredicate type: object securitySchemes: BearerAuth: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.