ydb-qdrant-tech Agent API

openapi: 3.2.0
info:
  title: Gravity AI UI Agent API
  version: 1.0.0
  description: API, MCP, and discovery surfaces for Gravity AI UI, an agent-ready generator for validated A2UI and Gravity UI product interfaces.
  contact:
    name: Gravity AI UI
    url: https://gravity-ai.ydb-qdrant.tech/docs
  license:
    name: Apache-2.0
servers:
- url: https://gravity-ai.ydb-qdrant.tech
tags:
- name: Agent
  description: Interface generation and refinement.
paths:
  /api/agent:
    post:
      operationId: streamGravityInterface
      tags:
      - Agent
      summary: Stream generated Gravity UI interface events
      parameters:
      - $ref: '#/components/parameters/ApiVersionHeader'
      description: Accepts a prompt or action request and returns Server-Sent Events with status, A2UI messages, composed payload snapshots, errors, and a final done event.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentRequest'
            examples:
              prompt:
                value:
                  kind: prompt
                  conversationId: demo-conversation
                  prompt: Build a deployment review dashboard
      responses:
        '200':
          description: SSE stream of agent events. Generator configuration errors are emitted as SSE error events.
          content:
            text/event-stream:
              schema:
                type: string
          headers:
            RateLimit-Limit:
              schema:
                type: integer
              description: Documented request budget for agent clients.
            RateLimit-Remaining:
              schema:
                type: integer
              description: Remaining requests in the current window when enforced.
            RateLimit-Reset:
              schema:
                type: integer
              description: Seconds until the current window resets when enforced.
            API-Version:
              schema:
                type: string
                enum:
                - '1'
              description: Current public API version.
        '400':
          description: Invalid agent request.
          headers:
            RateLimit-Limit:
              schema:
                type: integer
              description: Documented request budget for agent clients.
            RateLimit-Remaining:
              schema:
                type: integer
              description: Remaining requests in the current window when enforced.
            RateLimit-Reset:
              schema:
                type: integer
              description: Seconds until the current window resets when enforced.
            API-Version:
              schema:
                type: string
                enum:
                - '1'
              description: Current public API version.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    PromptAgentRequest:
      type: object
      additionalProperties: false
      required:
      - kind
      - conversationId
      - prompt
      properties:
        kind:
          type: string
          const: prompt
        conversationId:
          type: string
          minLength: 1
          maxLength: 120
        prompt:
          type: string
          minLength: 1
          maxLength: 6000
        conversationContext:
          $ref: '#/components/schemas/ConversationContext'
    ProblemDetails:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
            message:
              type: string
            docs:
              type: string
              format: uri
            issues: {}
    ActionAgentRequest:
      type: object
      additionalProperties: false
      required:
      - kind
      - conversationId
      - surfaceId
      - action
      properties:
        kind:
          type: string
          const: action
        conversationId:
          type: string
          minLength: 1
          maxLength: 120
        surfaceId:
          type: string
          minLength: 1
          maxLength: 80
        action: {}
        context: {}
        dataModel: {}
        conversationContext:
          $ref: '#/components/schemas/ConversationContext'
    ComposedInterfacePayload:
      type: object
      additionalProperties: false
      required:
      - sequence
      - surfaceId
      - root
      - nodes
      properties:
        sequence:
          type: integer
          minimum: 0
          maximum: 10000
        surfaceId:
          type: string
          minLength: 1
          maxLength: 80
        dataModel: {}
        root:
          type: object
          required:
          - component
          properties:
            component:
              type: string
              enum:
              - Column
              - Row
            props:
              type: object
        nodes:
          type: array
          maxItems: 120
          items:
            type: object
            required:
            - id
            - component
            properties:
              id:
                type: string
              parentId:
                type:
                - string
                - 'null'
              order:
                type: integer
                minimum: 0
              component:
                type: string
              props:
                type: object
    AgentRequest:
      oneOf:
      - $ref: '#/components/schemas/PromptAgentRequest'
      - $ref: '#/components/schemas/ActionAgentRequest'
    ConversationHistoryItem:
      type: object
      additionalProperties: false
      required:
      - role
      - text
      properties:
        role:
          type: string
          enum:
          - user
          - assistant
        text:
          type: string
          minLength: 1
          maxLength: 2000
        surfaceId:
          type: string
          minLength: 1
          maxLength: 80
    ConversationContext:
      type: object
      additionalProperties: false
      properties:
        history:
          type: array
          maxItems: 12
          items:
            $ref: '#/components/schemas/ConversationHistoryItem'
        latestSurfaceId:
          type: string
          minLength: 1
          maxLength: 80
        latestPayload:
          $ref: '#/components/schemas/ComposedInterfacePayload'
        latestDataModel: {}
  parameters:
    ApiVersionHeader:
      name: API-Version
      in: header
      required: false
      schema:
        type: string
        enum:
        - '1'
        default: '1'
      description: 'Optional API version selector. The current public API version is 1 and responses echo API-Version: 1.'
  securitySchemes:
    OAuth2Metadata:
      type: oauth2
      description: Discovery metadata is published for agent compatibility. Token issuance is disabled in the current public demo.
      flows:
        authorizationCode:
          authorizationUrl: https://gravity-ai.ydb-qdrant.tech/oauth/authorize
          tokenUrl: https://gravity-ai.ydb-qdrant.tech/oauth/token
          scopes:
            interface:generate: Generate and refine interfaces.
            interface:read: Read public gallery interfaces.