Assistants Evaluation OpenAPI Spec

Preview the spec in Swagger Editor by copying the YAML below. The live API documentation for your account is at:

https://<account>.deepdesk.com/api/v2/docs

Replace <account> with your Deepdesk account code (e.g. acme, staging). For staging, use https://<account>.staging.deepdesk.com/api/v2/docs.

---

OpenAPI 3.0 spec

openapi: 3.0.0
info:
  title: Deepdesk Assistants Evaluation API
  version: 2.0.0
  termsOfService: https://deepdesk.com/general-terms
  license:
    name: License
    url: https://deepdesk.com
  contact:
    name: Technical Support
    email: support@deepdesk.com
servers:
  - url: https://<account>.staging.deepdesk.com
    description: Staging
  - url: https://<account>.deepdesk.com
    description: Production
paths:
  /api/v2/assistants/{assistant_code}/evaluate:
    post:
      tags:
        - Assistants
      summary: Evaluate
      operationId: evaluate_api_assistants__assistant_code__evaluate_post
      security:
        - OAuth2ClientCredentialFlow: []
        - HTTPBearer: []
      parameters:
        - name: assistant_code
          in: path
          required: true
          schema:
            type: string
            title: Assistant Code
        - name: conversation_id
          in: query
          required: false
          schema:
            type: string
            description: The CX platform conversation ID
            title: Conversation Id
          description: The CX platform conversation ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EvaluationInput'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvaluationOutput'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'

components:
  schemas:
    EvaluationInput:
      type: object
      required:
        - input
      title: EvaluationInput
      properties:
        input:
          type: object
          title: Input
    EvaluationOutput:
      type: object
      required:
        - output
      title: EvaluationOutput
      properties:
        output:
          type: string
          title: Output
    HTTPValidationError:
      type: object
      title: HTTPValidationError
      properties:
        detail:
          type: array
          title: Detail
          items:
            $ref: '#/components/schemas/ValidationError'
    ValidationError:
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
      properties:
        loc:
          type: array
          title: Location
          items:
            anyOf:
              - type: string
              - type: integer
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
  securitySchemes:
    OAuth2ClientCredentialFlow:
      type: oauth2
      flows:
        clientCredentials:
          scopes:
            assistants:read: Read permission
            assistants:write: Write permission
          tokenUrl: /oauth/token/
    HTTPBearer:
      type: http
      scheme: bearer

---

Summary

Item	Description
Endpoint	POST /api/v2/assistants/{assistant_code}/evaluate
Query	conversation_id (optional) — CX platform conversation ID
Body	EvaluationInput: { "input": { ... } } — optional parameters included in the assistant prompt
Response	EvaluationOutput: { "output": "<string>" } — LLM response text
Auth	OAuth2 client credentials (assistants:read for evaluate) or HTTP Bearer token

See also

• API and Evaluation Guide — Authentication, examples, and Python code
• Assistants Admin API (OpenAPI) — Admin CRUD spec (assistants, APIs, tools, routes, threads)
• Assistants — Assistant configuration and concepts