openapi: 3.1.0
info:
  title: Devin External Attachments Knowledge API
  version: 1.0.0
  description: 'The Devin External API enables you to programmatically create and interact with Devin sessions. This RESTful API allows you to integrate Devin into your own applications, automate workflows, and build powerful tools on top of Devin.

    **Note**: The External API is currently in alpha. While we strive to maintain backward compatibility, some endpoints may change as we improve the API.

    '
servers:
- url: https://api.devin.ai
  description: Devin Production Server
security:
- bearerAuth: []
tags:
- name: Knowledge
  description: Operations for managing knowledge
paths:
  /v1/knowledge:
    get:
      tags:
      - Knowledge
      summary: List knowledge
      description: 'Gets all knowledge and folders in your current organization. This endpoint will not return system knowledge (repo indexes or built-in knowledge) managed by Cognition.

        '
      responses:
        '200':
          description: List of all knowledge and folders
          content:
            application/json:
              schema:
                type: object
                properties:
                  knowledge:
                    type: array
                    items:
                      $ref: '#/components/schemas/KnowledgeResponse'
                  folders:
                    type: array
                    items:
                      $ref: '#/components/schemas/KnowledgeFolderResponse'
                required:
                - knowledge
                - folders
              examples:
                list-knowledge-response:
                  summary: Example response listing knowledge and folders
                  value:
                    knowledge:
                    - $ref: '#/components/examples/knowledge-response/value'
                    folders:
                    - id: folder-xxx
                      name: Fetching data
                      description: Knowledge related to what websites or APIs Devin should use to complete certain tasks
                      created_at: '2024-01-01T00:00:00Z'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
    post:
      tags:
      - Knowledge
      summary: Create knowledge
      description: 'Create a new piece of knowledge.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KnowledgeRequest'
      responses:
        '200':
          description: Knowledge created. Returns the newly created knowledge.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeResponse'
              examples:
                create-knowledge-response:
                  summary: Example response for creating a knowledge
                  value:
                    $ref: '#/components/examples/knowledge-response/value'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
  /v1/knowledge/{note_id}:
    delete:
      tags:
      - Knowledge
      summary: Delete knowledge
      description: 'Permanently delete a piece of knowledge by its ID. This action cannot be undone.

        '
      parameters:
      - name: note_id
        in: path
        required: true
        description: The ID of the knowledge to delete
        schema:
          type: string
      responses:
        '204':
          description: Knowledge successfully deleted
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
    put:
      tags:
      - Knowledge
      summary: Update knowledge
      description: 'Update the name, body, or trigger of a piece of knowledge.

        '
      parameters:
      - name: note_id
        in: path
        required: true
        description: The ID of the knowledge to update
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KnowledgeRequest'
        required: true
      responses:
        '200':
          description: Knowledge successfully updated. Returns the updated knowledge.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeResponse'
              examples:
                update-knowledge-response:
                  summary: Example response for updating a knowledge
                  value:
                    $ref: '#/components/examples/knowledge-response/value'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
components:
  responses:
    NotFoundError:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: string
                example: The requested resource does not exist
    ForbiddenError:
      description: Forbidden - User does not have permission to access the resource
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: string
                example: You do not have permission to access this resource
    UnauthorizedError:
      description: Unauthorized - Invalid or missing API key
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: string
                example: Missing or invalid Authorization header
  schemas:
    KnowledgeFolderResponse:
      type: object
      description: Information about a knowledge folder
      properties:
        id:
          type: string
          description: The id of the folder
        name:
          type: string
          description: The name of the folder
        description:
          type: string
          description: The description of the folder, assists the auto-organization of knowledge
        created_at:
          type: string
          format: date-time
          description: Creation timestamp (ISO 8601)
    KnowledgeResponse:
      description: Information about a piece of knowledge
      allOf:
      - $ref: '#/components/schemas/KnowledgeRequest'
      - type: object
        properties:
          id:
            type: string
            description: The id of the knowledge
          created_at:
            type: string
            format: date-time
            description: Creation timestamp (ISO 8601)
        required:
        - id
        - created_at
    KnowledgeRequest:
      type: object
      description: Information about a piece of knowledge
      properties:
        body:
          type: string
          description: The content of the knowledge. Devin will read this when the knowledge gets triggered
        name:
          title: Name
          description: The name of the knowledge, used only for displaying the knowledge on the knowledge page
        parent_folder_id:
          type: string
          nullabe: true
          description: The id of the folder that this knowledge is located in. Null if the knowledge is not located in any folder
        trigger_description:
          type: string
          description: The description of when this knowledge should be used by Devin
        pinned_repo:
          type: string
          nullable: true
          description: "Pin knowledge to specific repositories. Valid values:\n- null: No pinning (default)\n- \"all\": Pin to all repositories  \n- \"owner/repo\": Pin to specific repository\n"
          example: all
      required:
      - name
      - body
      - trigger_description
  examples:
    knowledge-response:
      value:
        id: note-xxx
        name: Getting the weather
        body: Navigate to weather.com
        trigger_description: When the user asks about the weather
        parent_folder_id: folder-xxx
        created_at: '2024-01-01T00:00:00Z'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
externalDocs:
  description: Visit Devin's documentation page for more info
  url: https://docs.devin.ai