> ## Documentation Index
> Fetch the complete documentation index at: https://docs.transparencyhubnetwork.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Drive Document

> Create a document from text, Markdown, CSV or a prepared file.

Create a file in Drive in one request. Supply `content` for text, Markdown or CSV, or `content_base64` for a prepared file such as a PDF or Word document. Supply exactly one of these fields.

**Required scope:** `drive:write`

> [!NOTE]
>
> These endpoints require the Drive document creation API to be deployed to the selected environment. Existing read or download keys do not gain write access automatically; create a key with `drive:write` when it is available.

## Choose a format

| File extension | `content_type` | Content field |
| - | - | - |
| `.txt` | `text/plain` | `content` |
| `.md` | `text/markdown` | `content` |
| `.csv` | `text/csv` | `content` |
| `.pdf` | `application/pdf` | `content_base64` |
| `.docx` | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` | `content_base64` |

`content` is stored as UTF-8. `content_base64` must contain strict base64-encoded file bytes without a data URL prefix. Other supported Drive file formats can also use `content_base64`, with a matching extension and MIME type. This endpoint stores the supplied format; it does not convert text into Word or PDF.

Omit `parent_id` or set it to `null` for the Drive root. Otherwise, supply the destination folder's ID. Association-wide keys must also specify `chapter_id`; chapter-bound keys may omit it.

The key owner must have Drive view permission and permission to create at the root or contribute to the selected folder. File type, signature, size and storage quota checks apply. Successful creation is recorded in the chapter's activity log.

```json Markdown document theme={null}
{
  "file_name": "Committee minutes.md",
  "content_type": "text/markdown",
  "content": "# Committee minutes\n\nThe meeting opened at 10:00."
}
```

```json Prepared text file as base64 theme={null}
{
  "file_name": "Welcome.txt",
  "content_type": "text/plain",
  "content_base64": "SGVsbG8h"
}
```

```json 201 theme={null}
{
  "status": "success",
  "data": {
    "id": 501,
    "parent_id": 1,
    "is_root": false,
    "item_type": "file",
    "name": "Welcome.txt",
    "file_size": 6,
    "content_type": "text/plain",
    "content_version": 0,
    "createdby": 7,
    "createddate": "2026-10-24T10:00:00Z",
    "lastmodifieddate": null
  }
}
```

The response contains file metadata. Use its `id` with [Download a Drive File](https://docs.transparencyhubnetwork.ai/api-reference/drive/download.md) when you need the bytes; downloads require the separate `drive:download` scope.

## Size limits and retries

The configured Drive upload limit applies to decoded bytes (100 MiB by default). Base64 adds request overhead, and HTTP request limits may be lower. Use [Start a Drive Upload](https://docs.transparencyhubnetwork.ai/api-reference/drive/upload-session.md) for larger files.

An existing file with the same name in the selected folder causes `409`; it is never overwritten. Requests are not idempotent. After an uncertain response, check [List Drive Items](https://docs.transparencyhubnetwork.ai/api-reference/drive/items.md) before retrying (requires `drive:read`).

| Status | Meaning |
| - | - |
| `400` | Invalid content, unsupported format, invalid file signature or quota exceeded |
| `403` | Missing scope, forbidden chapter or insufficient Drive permissions |
| `404` | Destination folder is unavailable to the key owner |
| `409` | A file with this name already exists in the folder |
| `503` | Drive is disabled |


## OpenAPI

````yaml POST /v1/drive/documents
openapi: 3.0.3
info:
  title: Transparency Hub Public API
  version: 1.7.0
  description: Key-authenticated REST API for association and chapter integrations.
servers:
  - url: https://api.transparencyhubnetwork.ai/api
  - url: https://testapi.transparencyhubnetwork.ai/api
    description: Test
security:
  - ApiKeyAuth: []
  - BearerAuth: []
paths:
  /v1/drive/documents:
    post:
      summary: Create a Drive document
      description: >-
        Requires drive:write and the key owner's Drive permissions. Creates a
        file from exactly one of content (UTF-8 text, Markdown, CSV) or
        content_base64 (prepared file bytes, including PDF and Office formats).
        Uses the app upload validation, quota, inherited permissions, and audit
        logging. Does not convert text into Word/PDF. For larger files use
        upload-session and commit. A repeated successful request does not
        overwrite a file; a duplicate name returns 409.
      parameters:
        - $ref: '#/components/parameters/chapterId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDriveDocument'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - success
                  data:
                    $ref: '#/components/schemas/DriveItem'
        '400':
          description: >-
            Invalid input, unsupported file type, invalid file signature, size
            mismatch, or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            Missing drive:write scope, forbidden chapter, or insufficient Drive
            permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Parent folder or upload session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: File name conflict or upload session already finalized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Drive is disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    chapterId:
      name: chapter_id
      in: query
      schema:
        type: integer
      description: >-
        Required for association-wide keys; must match the key's chapter for
        chapter-bound keys.
  schemas:
    CreateDriveDocument:
      type: object
      required:
        - file_name
        - content_type
      properties:
        chapter_id:
          type: integer
          minimum: 1
          description: >-
            Required for association-wide keys; otherwise the key chapter is
            used.
        parent_id:
          type: integer
          minimum: 1
          nullable: true
          description: Omit or use null for the Drive root.
        file_name:
          type: string
          minLength: 1
          maxLength: 255
        content_type:
          type: string
          description: A supported Drive MIME type matching file_name.
        content:
          type: string
          minLength: 1
          description: UTF-8 content for text/plain, text/markdown, or text/csv.
        content_base64:
          type: string
          format: byte
          minLength: 1
          description: Strict base64-encoded file bytes, without a data URL prefix.
      oneOf:
        - required:
            - content
          not:
            required:
              - content_base64
        - required:
            - content_base64
          not:
            required:
              - content
    DriveItem:
      type: object
      properties:
        id:
          type: integer
          nullable: true
        parent_id:
          type: integer
          nullable: true
        is_root:
          type: boolean
          nullable: true
        item_type:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
        file_size:
          type: integer
          nullable: true
        content_type:
          type: string
          nullable: true
        content_version:
          type: integer
          nullable: true
        createdby:
          type: integer
          nullable: true
        createddate:
          type: string
          format: date-time
          nullable: true
        lastmodifieddate:
          type: string
          format: date-time
          nullable: true
    Error:
      type: object
      required:
        - status
        - code
        - message
      properties:
        status:
          type: string
          enum:
            - error
        code:
          type: string
        message:
          type: string
        details:
          type: object
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    BearerAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.