Assistants Admin 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. For staging: https://<account>.staging.deepdesk.com/api/v2/docs.

---

OpenAPI 3.0 spec

openapi: 3.0.2
info:
  title: Deepdesk Assistants Admin API
  version: 1.0.0
  description: ''
  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:
  /apis/admin/assistants/apis/:
    get:
      operationId: listApis
      description: ''
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Api'
          description: ''
      tags:
        - Assistants
    post:
      operationId: createApi
      description: ''
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Api'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Api'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Api'
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api'
          description: ''
      tags:
        - Assistants
  /apis/admin/assistants/apis/{code}/:
    get:
      operationId: retrieveApi
      parameters:
        - name: code
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api'
      tags:
        - Assistants
    put:
      operationId: updateApi
      parameters:
        - name: code
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Api'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api'
      tags:
        - Assistants
    patch:
      operationId: partialUpdateApi
      parameters:
        - name: code
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Api'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api'
      tags:
        - Assistants
    delete:
      operationId: destroyApi
      parameters:
        - name: code
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: ''
      tags:
        - Assistants
  /apis/admin/assistants/tools/:
    get:
      operationId: listAssistantTools
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AssistantTool'
      tags:
        - Assistants
  /apis/admin/assistants/tools/{id}/:
    get:
      operationId: retrieveAssistantTool
      parameters:
        - name: id
          in: path
          required: true
          description: A unique integer value identifying this assistant tool.
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantTool'
      tags:
        - Assistants
  /apis/admin/assistants/:
    get:
      operationId: listassistants
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AssistantViewSet'
      tags:
        - Assistants
    post:
      operationId: createassistants
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssistantViewSet'
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantViewSet'
      tags:
        - Assistants
  /apis/admin/assistants/{code}/:
    get:
      operationId: retrieveassistants
      parameters:
        - name: code
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantViewSet'
      tags:
        - Assistants
    put:
      operationId: updateassistants
      parameters:
        - name: code
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssistantViewSet'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantViewSet'
      tags:
        - Assistants
    patch:
      operationId: partialUpdateassistants
      parameters:
        - name: code
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssistantViewSet'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantViewSet'
      tags:
        - Assistants
    delete:
      operationId: destroyassistants
      parameters:
        - name: code
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: ''
      tags:
        - Assistants
  /apis/admin/assistants/{assistant_code}/routes/:
    get:
      operationId: listAssistantRoutes
      parameters:
        - name: assistant_code
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AssistantRoute'
      tags:
        - Assistants
    post:
      operationId: createAssistantRoute
      parameters:
        - name: assistant_code
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssistantRoute'
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantRoute'
      tags:
        - Assistants
  /apis/admin/assistants/{assistant_code}/routes/{id}/:
    get:
      operationId: retrieveAssistantRoute
      parameters:
        - name: assistant_code
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          description: A unique integer value identifying this assistant route.
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantRoute'
      tags:
        - Assistants
    put:
      operationId: updateAssistantRoute
      parameters:
        - name: assistant_code
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssistantRoute'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantRoute'
      tags:
        - Assistants
    patch:
      operationId: partialUpdateAssistantRoute
      parameters:
        - name: assistant_code
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssistantRoute'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantRoute'
      tags:
        - Assistants
    delete:
      operationId: destroyAssistantRoute
      parameters:
        - name: assistant_code
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: ''
      tags:
        - Assistants
  /apis/admin/assistants/{assistant_code}/threads/:
    get:
      operationId: listAssistantThreads
      parameters:
        - name: assistant_code
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AssistantThread'
      tags:
        - Assistants
    post:
      operationId: createAssistantThread
      parameters:
        - name: assistant_code
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssistantThread'
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantThread'
      tags:
        - Assistants
  /apis/admin/assistants/{assistant_code}/threads/{id}/:
    get:
      operationId: retrieveAssistantThread
      parameters:
        - name: assistant_code
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          description: A unique integer value identifying this assistant thread.
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantThread'
      tags:
        - Assistants
    put:
      operationId: updateAssistantThread
      parameters:
        - name: assistant_code
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssistantThread'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantThread'
      tags:
        - Assistants
    patch:
      operationId: partialUpdateAssistantThread
      parameters:
        - name: assistant_code
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssistantThread'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantThread'
      tags:
        - Assistants
    delete:
      operationId: destroyAssistantThread
      parameters:
        - name: assistant_code
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: ''
      tags:
        - Assistants
  /apis/admin/assistants/{assistant_code}/threads/{id}/messages/:
    get:
      operationId: listAssistantThreadMessages
      parameters:
        - name: assistant_code
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items: {}
      tags:
        - Assistants
    post:
      operationId: createAssistantThreadMessage
      parameters:
        - name: assistant_code
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema: {}
      responses:
        '201':
          content:
            application/json:
              schema: {}
      tags:
        - Assistants
components:
  schemas:
    Api:
      type: object
      required:
        - url
        - headers
      properties:
        id:
          type: integer
          readOnly: true
        url:
          type: string
          format: uri
          maxLength: 200
        headers:
          type: string
    AssistantViewSet:
      type: object
      required:
        - code
        - name
        - instructions
        - tools
      properties:
        id:
          type: integer
          readOnly: true
        code:
          type: string
          pattern: '^[a-z0-9-]+$'
          maxLength: 255
          minLength: 3
        name:
          type: string
          maxLength: 255
        instructions:
          type: string
        model:
          type: string
          enum:
            - gpt-35-turbo
            - gpt-35-turbo-16k
            - gpt-4
            - gpt-4o
        response_format_json:
          type: boolean
        temperature:
          type: string
          format: decimal
          multipleOf: 0.01
          maximum: 1
          minimum: 0
        top_p:
          type: string
          format: decimal
          multipleOf: 0.01
          maximum: 1
          minimum: 0
        tools:
          type: array
          items:
            type: integer
        tools_json:
          type: string
          readOnly: true
        include_conversation_transcript:
          type: boolean
        include_conversation_metadata:
          type: boolean
    AssistantRoute:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        assistant:
          type: string
          readOnly: true
        tags:
          type: object
    AssistantTool:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        data:
          type: object
          readOnly: true
        source_assistant:
          type: string
          readOnly: true
    AssistantThread:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        assistant:
          type: string
          readOnly: true
        user_id:
          type: string
          nullable: true
          maxLength: 255
        content:
          type: object
  securitySchemes:
    OAuth2ClientCredentialFlow:
      type: oauth2
      flows:
        clientCredentials:
          scopes:
            assistants:read: Read access to assistants
            assistants:write: Write access to assistants
          tokenUrl: /oauth/token/
    bearerAuth:
      type: http
      scheme: bearer
security:
  - bearerAuth: []
  - OAuth2ClientCredentialFlow: []

---

Summary

Resource	Endpoints
APIs	GET/POST /apis/admin/assistants/apis/, GET/PUT/PATCH/DELETE .../apis/{code}/
Tools	GET /apis/admin/assistants/tools/, GET .../tools/{id}/
Assistants	GET/POST /apis/admin/assistants/, GET/PUT/PATCH/DELETE .../assistants/{code}/
Routes	GET/POST .../assistants/{assistant_code}/routes/, GET/PUT/PATCH/DELETE .../routes/{id}/
Threads	GET/POST .../assistants/{assistant_code}/threads/, GET/PUT/PATCH/DELETE .../threads/{id}/
Thread messages	GET/POST .../threads/{id}/messages/

Auth: OAuth2 client credentials (assistants:read, assistants:write) or Bearer token. See API and Evaluation Guide.

See also

• Assistants Evaluation API (OpenAPI) — Evaluate endpoint spec
• API and Evaluation Guide — Authentication and examples
• Assistants — Assistant concepts and configuration