Skip to main content

Entity UI API

Usage​

import { epilot } from '@epilot/sdk'

epilot.authorize(() => '<token>')
const { data } = await epilot.entityUi.putWidgetDefinition(...)

Tree-shakeable import​

import { getClient, authorize } from '@epilot/sdk/entity-ui'

const entityUiClient = getClient()
authorize(entityUiClient, () => '<token>')
const { data } = await entityUiClient.putWidgetDefinition(...)

Operations​

Widget Definitions

Schemas

putWidgetDefinition​

Stores a widget definition and returns its ref.

PUT /v1/entity-ui/widget-definitions

const { data } = await client.putWidgetDefinition(
  null,
  {
    version: 1,
    prompt: 'string',
    manifest: {
      relations: {},
      libs: ['echarts'],
      icons: ['string']
    },
    html: 'string',
    strings: {
      de: {},
      en: {}
    },
    suggestions: {
      de: ['string'],
      en: ['string']
    }
  },
)
Response
{
  "ref": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
}

getWidgetDefinition​

Returns a stored widget definition in its canonical form.

GET /v1/entity-ui/widget-definitions/{ref}

const { data } = await client.getWidgetDefinition({
  ref: 'example',
})
Response
{
  "version": 1,
  "prompt": "string",
  "manifest": {
    "relations": {},
    "libs": ["echarts"],
    "icons": ["string"]
  },
  "html": "string",
  "strings": {
    "de": {},
    "en": {}
  },
  "suggestions": {
    "de": ["string"],
    "en": ["string"]
  }
}

batchGetWidgetDefinitions​

Returns up to 20 stored widget definitions by ref. Refs that are not stored in the organization are listed in missing.

POST /v1/entity-ui/widget-definitions/batch-get

const { data } = await client.batchGetWidgetDefinitions(
  null,
  {
    refs: ['9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08']
  },
)
Response
{
  "definitions": {},
  "missing": ["9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"]
}

Schemas​

WidgetDefinitionRef​

Lowercase hex SHA-256 of the definition's RFC 8785 canonical JSON

type WidgetDefinitionRef = string

WidgetDefinitionRefResponse​

type WidgetDefinitionRefResponse = {
  ref: string
}

WidgetDefinition​

Version 1 of an AI widget definition. Unknown keys are rejected at every level, because any extra key would produce a different ref for an otherwise identical definition.

type WidgetDefinition = {
  version: 1
  prompt: string
  manifest: {
    relations: {
      mode?: { ... }
    } | {
      mode?: { ... }
      schemas?: { ... }
    }
    libs: "echarts"[]
    icons?: string[]
  }
  html: string
  strings: {
    de: Record<string, string>
    en: Record<string, string>
  }
  suggestions?: {
    de: string[]
    en: string[]
  }
}

WidgetManifest​

type WidgetManifest = {
  relations: {
    mode?: "direct" | "reverse" | "both"
  } | {
    mode?: "none"
    schemas?: unknown
  }
  libs: "echarts"[]
  icons?: string[]
}

WidgetRelations​

type WidgetRelations = {
  mode?: "direct" | "reverse" | "both"
} | {
  mode?: "none"
  schemas?: unknown
}

WidgetStrings​

Localized string tables; both include title

type WidgetStrings = {
  de: Record<string, string>
  en: Record<string, string>
}

WidgetStringTable​

String table of one locale. Keys are what the widget passes to t(); both tables include title.

Every key must match ^[a-z0-9_]{1,64}$ (snake_case, at most 64 characters) and may not be __proto__. The server enforces this and answers 400 naming the offending key; OpenAPI 3.0 has no keyword

type WidgetStringTable = Record<string, string>

WidgetSuggestions​

type WidgetSuggestions = {
  de: string[]
  en: string[]
}

BatchGetWidgetDefinitionsRequest​

type BatchGetWidgetDefinitionsRequest = {
  refs: string[]
}

BatchGetWidgetDefinitionsResponse​

type BatchGetWidgetDefinitionsResponse = {
  definitions: Record<string, {
    version: 1
    prompt: string
    manifest: {
      relations: { ... }
      libs: { ... }
      icons?: { ... }
    }
    html: string
    strings: {
      de: { ... }
      en: { ... }
    }
    suggestions?: {
      de: { ... }
      en: { ... }
    }
  }>
  missing: string[]
}

ErrorResponse​

Standard error response format for all API errors

type ErrorResponse = {
  error: string | object[]
  status: number
}