Vanta Documents API

openapi: 3.2.0
info:
  title: Vanta Documents API
  description: The Vanta REST API enables organizations to programmatically manage their security compliance posture. The API supports personnel management, vulnerability monitoring, resource scoping, document and test management, control oversight, vendor management, and custom integrations. Vanta helps automate compliance for SOC 2, ISO 27001, HIPAA, PCI DSS, and GDPR frameworks.
  version: v1
  contact:
    name: Vanta Developer Hub
    url: https://developer.vanta.com
  termsOfService: https://www.vanta.com/terms
  license:
    name: Proprietary
    url: https://www.vanta.com/terms
servers:
- url: https://api.vanta.com
  description: Vanta API
security:
- OAuth2: []
tags:
- name: Documents
  description: Compliance evidence document management
paths:
  /v1/documents:
    get:
      operationId: listDocuments
      summary: List Documents
      description: Retrieve compliance evidence documents uploaded to Vanta.
      tags:
      - Documents
      parameters:
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/pageCursor'
      responses:
        '200':
          description: Paginated list of documents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      operationId: uploadDocument
      summary: Upload Document
      description: Upload a compliance evidence document to Vanta.
      tags:
      - Documents
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: The document file to upload
                name:
                  type: string
                  description: Name of the document
                description:
                  type: string
                  description: Description of the document
              required:
              - file
              - name
      responses:
        '201':
          description: Document uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  parameters:
    pageSize:
      name: pageSize
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
      description: Number of items to return per page (1-100)
    pageCursor:
      name: pageCursor
      in: query
      schema:
        type: string
      description: Cursor for pagination — start from the item following this cursor
  responses:
    RateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request — invalid parameters or request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized — missing or invalid access token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    PageInfo:
      type: object
      properties:
        pageSize:
          type: integer
          description: Number of items returned
        nextPageCursor:
          type: string
          nullable: true
          description: Cursor for the next page of results
        hasNextPage:
          type: boolean
          description: Whether there are more items after this page
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error code
        message:
          type: string
          description: Human-readable error description
        details:
          type: array
          items:
            type: string
          description: Additional error details
    DocumentListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Document'
        pageInfo:
          $ref: '#/components/schemas/PageInfo'
    Document:
      type: object
      properties:
        id:
          type: string
          description: Unique document identifier
        name:
          type: string
          description: Document name
        description:
          type: string
          nullable: true
          description: Document description
        mimeType:
          type: string
          description: Document MIME type
        sizeBytes:
          type: integer
          description: Document size in bytes
        uploadedAt:
          type: string
          format: date-time
          description: When the document was uploaded
        uploadedBy:
          type: string
          description: User ID who uploaded the document
        downloadUrl:
          type: string
          format: uri
          description: Temporary URL to download the document
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.vanta.com/oauth/token
          scopes:
            vanta.read: Read access to Vanta data
            vanta.write: Write access to Vanta data
            connectors.self:read-resource: Read connector resources
            connectors.self:write-resource: Write connector resources
            auditor-api.audit:read: Read audit data
            auditor-api.auditor:read: Read auditor data