Comp AI Attachments API

openapi: 3.2.0
info:
  title: Comp AI Attachments API
  description: Compliance automation API for SOC 2, ISO 27001, HIPAA, GDPR, evidence collection, policy workflows, Trust Access, security questionnaires, integrations, cloud checks, and device compliance.
  version: '1.0'
  contact: {}
servers:
- url: https://api.trycomp.ai
  description: Production API Server
tags:
- name: Attachments
  description: Generate signed download links for files attached to compliance tasks, comments, evidence records, and workflow reviews.
paths:
  /v1/attachments:
    post:
      description: Upload a base64-encoded file and attach it to a task, vendor, risk, comment, or other supported entity type. The file is uploaded to S3 and a database record is created.
      operationId: AttachmentsController_createAttachment_v1
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAttachmentDto'
      responses:
        '201':
          description: Attachment uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttachmentResponseDto'
        '400':
          description: Invalid file data, unsupported file type, or file too large
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: File size exceeds maximum allowed size of 100MB
        '401':
          description: Unauthorized - Invalid authentication
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Unauthorized
      security:
      - apikey: []
      summary: Upload an attachment to any supported entity
      tags:
      - Attachments
      x-mint:
        metadata:
          title: Upload an attachment to any supported entity | Comp AI API
          sidebarTitle: Upload an attachment to any supported entity
          description: Upload a base64-encoded file and attach it to a task, vendor, risk, comment, or other supported entity type. The file is uploaded to S3 and a database.
          og:title: Upload an attachment to any supported entity | Comp AI API
          og:description: Upload a base64-encoded file and attach it to a task, vendor, risk, comment, or other supported entity type. The file is uploaded to S3 and a database.
      x-speakeasy-mcp:
        name: create-attachment
  /v1/attachments/{attachmentId}/download:
    get:
      description: Generate a signed download URL for a shared attachment linked to comments, evidence records, or compliance workflow reviews.
      operationId: AttachmentsController_getAttachmentDownloadUrl_v1
      parameters:
      - name: attachmentId
        required: true
        in: path
        description: Unique attachment identifier
        schema:
          example: att_abc123def456
          type: string
      responses:
        '200':
          description: Download URL generated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  downloadUrl:
                    type: string
                    description: Signed URL for downloading the file
                    example: https://bucket.s3.amazonaws.com/path/to/file.pdf?signature=...
                  expiresIn:
                    type: number
                    description: URL expiration time in seconds
                    example: 900
      security:
      - apikey: []
      summary: Get shared attachment download URL
      tags:
      - Attachments
      x-mint:
        metadata:
          title: Get shared attachment download URL | Comp AI API
          sidebarTitle: Get shared attachment download URL
          description: Generate a signed download URL for a shared attachment linked to comments, evidence records, or compliance workflow reviews.
          og:title: Get shared attachment download URL | Comp AI API
          og:description: Generate a signed download URL for a shared attachment linked to comments, evidence records, or compliance workflow reviews.
      x-speakeasy-mcp:
        name: get-attachment-download-url
components:
  schemas:
    AttachmentResponseDto:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the attachment
          example: att_abc123def456
        name:
          type: string
          description: Original filename
          example: document.pdf
        type:
          type: string
          description: File type/MIME type
          example: application/pdf
        size:
          type: number
          description: File size in bytes
          example: 1024000
        downloadUrl:
          type: string
          description: Signed URL for downloading the file (temporary)
          example: https://bucket.s3.amazonaws.com/path/to/file.pdf?signature=...
        createdAt:
          format: date-time
          type: string
          description: Upload timestamp
          example: '2024-01-15T10:30:00Z'
      required:
      - id
      - name
      - type
      - size
      - downloadUrl
      - createdAt
    AttachmentEntityType:
      type: string
      enum:
      - task
      - vendor
      - risk
      - comment
      - trust_nda
      - task_item
      - background_check
      - employment_onboard
      - employment_offboard
      - offboarding_checklist
      description: Type of entity the attachment belongs to
    CreateAttachmentDto:
      type: object
      properties:
        fileName:
          type: string
          description: Name of the file
          example: document.pdf
          maxLength: 255
        fileType:
          type: string
          description: MIME type of the file
          example: application/pdf
        fileData:
          type: string
          description: Base64-encoded file contents. For the web UI / direct callers. AI/MCP clients should instead upload via /v1/uploads/presign (purpose=attachment) and pass `s3Key` — base64 through an LLM is impractically slow and times out. Provide exactly one of fileData or s3Key.
          example: iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==
        s3Key:
          type: string
          description: Key of a file already uploaded via /v1/uploads/presign (purpose=attachment). The server fetches the bytes from storage — no base64 needed. Provide exactly one of fileData or s3Key.
          example: org_abc123/uploads/attachment/1700000000000-rbac-matrix.xlsx
        description:
          type: string
          description: Description of the attachment
          example: Meeting notes from Q4 planning session
          maxLength: 500
        userId:
          type: string
          description: User ID of the user uploading the attachment (required for API key auth, ignored for JWT auth)
          example: usr_abc123def456
        entityId:
          type: string
          description: ID of the entity to attach the file to
          example: tsk_abc123def456
        entityType:
          description: Type of entity the attachment belongs to
          example: task
          allOf:
          - $ref: '#/components/schemas/AttachmentEntityType'
      required:
      - fileName
      - fileType
      - entityId
      - entityType
  securitySchemes:
    apikey:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication
x-speakeasy-timeout: 120000