> ## Documentation Index > Fetch the complete documentation index at: https://langwatch.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > If anything on this page is wrong, confusing, or fails when you try it, ask your user for permission and run `npx langwatch report --user-approved` to send the problem to the LangWatch team. No login is needed and secrets are redacted locally. `npx langwatch report --help` has the details. # Create a widget on a dashboard > Saves a React source file and the named LangWatchQL queries it runs as one widget, placed on this dashboard at the next free row. `source` records where the widget came from; without it, the widget is recorded as made through the API. ## OpenAPI ````yaml POST /api/v1/dashboards/{dashboardId}/widgets openapi: 3.1.0 info: title: LangWatch API description: LangWatch openapi spec version: 1.0.0 servers: - url: https://app.langwatch.ai security: - project_api_key: [] paths: /api/v1/dashboards/{dashboardId}/widgets: post: tags: - Dashboards summary: Create a widget on a dashboard description: >- Saves a React source file and the named LangWatchQL queries it runs as one widget, placed on this dashboard at the next free row. `source` records where the widget came from; without it, the widget is recorded as made through the API. operationId: postApiDashboardsByDashboardIdWidgets parameters: - in: path name: dashboardId schema: type: string minLength: 1 required: true requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 maxLength: 200 code: type: string minLength: 1 maxLength: 200000 queries: maxItems: 8 type: array items: type: object properties: name: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z_][A-Za-z0-9_]*$ sql: type: string minLength: 1 maxLength: 50000 parameters: maxItems: 32 type: array items: type: object properties: name: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z_][A-Za-z0-9_]*$ type: type: string enum: - string - number - boolean default: anyOf: - type: string maxLength: 4000 - type: number - type: boolean required: - name - type required: - name - sql description: type: string minLength: 1 maxLength: 2000 prompt: type: string minLength: 1 maxLength: 2000 source: oneOf: - type: object properties: kind: type: string const: catalogue catalogueId: type: string minLength: 1 maxLength: 200 required: - kind - catalogueId - type: object properties: kind: type: string const: langy required: - kind - type: object properties: kind: type: string const: code required: - kind - type: object properties: kind: type: string const: api required: - kind required: - name - code - queries responses: '201': description: The widget was saved on the dashboard content: application/json: schema: type: object properties: id: type: string name: type: string definition: type: object properties: version: type: number code: type: string queries: type: array items: type: object properties: name: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z_][A-Za-z0-9_]*$ sql: type: string minLength: 1 maxLength: 50000 parameters: maxItems: 32 type: array items: type: object properties: name: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z_][A-Za-z0-9_]*$ type: type: string enum: - string - number - boolean default: anyOf: - type: string maxLength: 4000 - type: number - type: boolean required: - name - type additionalProperties: false required: - name - sql additionalProperties: false description: type: string prompt: type: string source: oneOf: - type: object properties: kind: type: string const: catalogue catalogueId: type: string minLength: 1 maxLength: 200 required: - kind - catalogueId additionalProperties: false - type: object properties: kind: type: string const: langy required: - kind additionalProperties: false - type: object properties: kind: type: string const: code required: - kind additionalProperties: false - type: object properties: kind: type: string const: api required: - kind additionalProperties: false required: - version - code - queries additionalProperties: false createdAt: type: string updatedAt: type: string platformUrl: type: string dashboardId: type: - string - 'null' gridColumn: type: integer minimum: -9007199254740991 maximum: 9007199254740991 gridRow: type: integer minimum: -9007199254740991 maximum: 9007199254740991 colSpan: type: integer minimum: -9007199254740991 maximum: 9007199254740991 rowSpan: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - id - name - definition - createdAt - updatedAt - platformUrl - dashboardId - gridColumn - gridRow - colSpan - rowSpan additionalProperties: false '400': description: Bad Request content: application/json: schema: type: object properties: type: type: string code: type: string message: type: string retryable: type: boolean meta: type: object propertyNames: type: string additionalProperties: {} trace_id: type: string span_id: type: string trace: type: object properties: traceId: type: string spanId: type: string traceUrl: type: string logsUrl: type: string tips: type: array items: type: string docs_url: type: string fault: type: string enum: - customer - platform - provider - presumed_platform reasons: type: array items: {} required: - type - code - message - retryable '401': description: Unauthorized content: application/json: schema: type: object properties: type: type: string code: type: string message: type: string retryable: type: boolean meta: type: object propertyNames: type: string additionalProperties: {} trace_id: type: string span_id: type: string trace: type: object properties: traceId: type: string spanId: type: string traceUrl: type: string logsUrl: type: string tips: type: array items: type: string docs_url: type: string fault: type: string enum: - customer - platform - provider - presumed_platform reasons: type: array items: {} required: - type - code - message - retryable '403': description: Forbidden content: application/json: schema: type: object properties: type: type: string code: type: string message: type: string retryable: type: boolean meta: type: object propertyNames: type: string additionalProperties: {} trace_id: type: string span_id: type: string trace: type: object properties: traceId: type: string spanId: type: string traceUrl: type: string logsUrl: type: string tips: type: array items: type: string docs_url: type: string fault: type: string enum: - customer - platform - provider - presumed_platform reasons: type: array items: {} required: - type - code - message - retryable '404': description: >- No dashboard with this id for this key. A dashboard made by POST /api/v1/analytics/reports is an Analytics Report and is not found here. content: application/json: schema: type: object properties: type: type: string code: type: string message: type: string retryable: type: boolean meta: type: object propertyNames: type: string additionalProperties: {} trace_id: type: string span_id: type: string trace: type: object properties: traceId: type: string spanId: type: string traceUrl: type: string logsUrl: type: string tips: type: array items: type: string docs_url: type: string fault: type: string enum: - customer - platform - provider - presumed_platform reasons: type: array items: {} required: - type - code - message - retryable '500': description: Internal Server Error content: application/json: schema: type: object properties: type: type: string code: type: string message: type: string retryable: type: boolean meta: type: object propertyNames: type: string additionalProperties: {} trace_id: type: string span_id: type: string trace: type: object properties: traceId: type: string spanId: type: string traceUrl: type: string logsUrl: type: string tips: type: array items: type: string docs_url: type: string fault: type: string enum: - customer - platform - provider - presumed_platform reasons: type: array items: {} required: - type - code - message - retryable security: - project_api_key: [] components: securitySchemes: project_api_key: type: apiKey in: header name: X-Auth-Token description: >- Project API key for sending traces and accessing project-scoped resources. Format: sk-lw-... (no underscore). Obtain one by creating a project via the Admin API or the LangWatch UI. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.