openapi: 3.1.0
info:
  title: Devin External Attachments Secrets 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: Secrets
  description: Operations for managing secrets and credentials
paths:
  /v1/secrets:
    get:
      tags:
      - Secrets
      summary: List all secrets metadata
      description: 'Get a list of all secrets metadata. This endpoint only returns non-sensitive

        information about the secrets, not the secret values themselves.

        '
      responses:
        '200':
          description: List of secrets metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  secrets:
                    type: array
                    items:
                      $ref: '#/components/schemas/SecretMetadata'
                required:
                - secrets
              examples:
                list-secrets-response:
                  summary: Example response listing secrets
                  value:
                    secrets:
                    - secret_id: sec_xxx
                      secret_type: key-value
                      secret_name: API Access Token
                      created_at: '2024-01-01T00:00:00Z'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags:
      - Secrets
      summary: Create a new secret
      description: 'Create a new secret in your organization. The secret value will be encrypted and stored securely.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSecretRequest'
            examples:
              create-secret-example:
                summary: Example creating a new secret
                value:
                  type: key-value
                  key: API_TOKEN
                  value: sk-1234567890abcdef
                  sensitive: true
                  note: Production API token for external service
      responses:
        '201':
          description: Secret created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The unique identifier of the created secret
                required:
                - id
              examples:
                create-secret-response:
                  summary: Example response for creating a secret
                  value:
                    id: sec_abc123def456
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          description: Conflict - Secret name already exists
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: Secret name is not unique
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/secrets/{secret_id}:
    delete:
      tags:
      - Secrets
      summary: Delete a secret
      description: 'Permanently delete a secret by its ID. This action cannot be undone.

        '
      parameters:
      - name: secret_id
        in: path
        required: true
        description: The ID of the secret to delete
        schema:
          type: string
      responses:
        '204':
          description: Secret successfully deleted
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  responses:
    NotFoundError:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: string
                example: The requested resource does not exist
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: string
                example: Something went wrong
    BadRequestError:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: string
                example: Invalid input or request
    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:
    CreateSecretRequest:
      type: object
      properties:
        type:
          type: string
          description: Type of secret
          enum:
          - cookie
          - key-value
          - totp
        key:
          type: string
          description: User-defined name for the secret
        value:
          type: string
          description: The secret value to store
        sensitive:
          type: boolean
          description: Whether the secret should be treated as sensitive
        note:
          type: string
          description: Optional note about the secret
      required:
      - type
      - key
      - value
      - sensitive
      - note
      description: Request body for creating a new secret
    SecretMetadata:
      type: object
      properties:
        secret_id:
          type: string
          description: Unique identifier for the secret
        secret_type:
          type: string
          description: Type of secret
          enum:
          - cookie
          - key-value
          - dictionary
          - totp
        secret_name:
          type: string
          description: User-defined name for the secret
        created_at:
          type: string
          format: date-time
          description: Creation timestamp (ISO 8601)
      required:
      - secret_id
      - secret_type
      - secret_name
      - created_at
      description: Metadata about a stored secret
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
externalDocs:
  description: Visit Devin's documentation page for more info
  url: https://docs.devin.ai