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

# Upload Folder Document

> Upload a guideline, glossary, or character list to a folder as a file, without hosting it yourself

Attaches a folder-level document by sending the file itself as `multipart/form-data`. Use this when you have the file locally and do not want to host it or generate a pre-signed URL first.

This is the same operation as [Attach Folder Document](/apis/ollang-api-reference/attach-folder-document); only the way you supply the file differs. The document is applied to every project that already exists in the folder **and** to projects created in it afterwards, including projects created through [Direct File Upload](/apis/ollang-api-reference/direct-file-upload).

<Note>
  Send the file in a form field named `file`. The file must be smaller than
  50 MiB (52,428,800 bytes). Files at or above this limit return `413`.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api-integration.ollang.com/integration/folder/60b8d6f1e1b9b1d8c6c0d8e1/docs/upload" \
    -H "X-Api-Key: <your-api-key>" \
    -H "Content-Type: multipart/form-data" \
    -F "file=@/path/to/brand-guideline-v3.pdf" \
    -F "type=guideline" \
    -F "name=Brand guideline v3" \
    -F "language=en"
  ```

  ```javascript JavaScript theme={null}
  const folderId = "60b8d6f1e1b9b1d8c6c0d8e1";

  const formData = new FormData();
  formData.append("file", guidelineFile);
  formData.append("type", "guideline");
  formData.append("name", "Brand guideline v3");
  formData.append("language", "en");

  const response = await fetch(
    `https://api-integration.ollang.com/integration/folder/${folderId}/docs/upload`,
    {
      method: "POST",
      headers: {
        "X-Api-Key": "<your-api-key>",
      },
      body: formData,
    },
  );

  const doc = await response.json();
  console.log("Attached document:", doc.id);
  ```

  ```python Python theme={null}
  import requests

  folder_id = "60b8d6f1e1b9b1d8c6c0d8e1"

  files = {'file': open('brand-guideline-v3.pdf', 'rb')}
  data = {
      'type': 'guideline',
      'name': 'Brand guideline v3',
      'language': 'en',
  }
  headers = {'X-Api-Key': '<your-api-key>'}

  response = requests.post(
      f'https://api-integration.ollang.com/integration/folder/{folder_id}/docs/upload',
      files=files,
      data=data,
      headers=headers,
  )

  doc = response.json()
  print("Attached document:", doc["id"])
  ```

  ```php PHP theme={null}
  $folderId = '60b8d6f1e1b9b1d8c6c0d8e1';

  $curl = curl_init();

  curl_setopt_array($curl, array(
      CURLOPT_URL => "https://api-integration.ollang.com/integration/folder/{$folderId}/docs/upload",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_POST => true,
      CURLOPT_POSTFIELDS => array(
          'file' => new CURLFile('/path/to/brand-guideline-v3.pdf'),
          'type' => 'guideline',
          'name' => 'Brand guideline v3',
          'language' => 'en',
      ),
      CURLOPT_HTTPHEADER => array(
          'X-Api-Key: <your-api-key>'
      ),
  ));

  $response = curl_exec($curl);
  $doc = json_decode($response, true);
  curl_close($curl);

  echo "Attached document: " . $doc['id'];
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "fmt"
      "io"
      "mime/multipart"
      "net/http"
      "os"
  )

  func main() {
      folderID := "60b8d6f1e1b9b1d8c6c0d8e1"
      url := "https://api-integration.ollang.com/integration/folder/" + folderID + "/docs/upload"

      body := &bytes.Buffer{}
      writer := multipart.NewWriter(body)

      file, _ := os.Open("brand-guideline-v3.pdf")
      defer file.Close()

      part, _ := writer.CreateFormFile("file", "brand-guideline-v3.pdf")
      io.Copy(part, file)

      writer.WriteField("type", "guideline")
      writer.WriteField("name", "Brand guideline v3")
      writer.WriteField("language", "en")
      writer.Close()

      req, _ := http.NewRequest("POST", url, body)
      req.Header.Set("X-Api-Key", "<your-api-key>")
      req.Header.Set("Content-Type", writer.FormDataContentType())

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      respBody, _ := io.ReadAll(resp.Body)

      var doc map[string]interface{}
      json.Unmarshal(respBody, &doc)

      fmt.Println("Attached document:", doc["id"])
  }
  ```

  ```java Java theme={null}
  String folderId = "60b8d6f1e1b9b1d8c6c0d8e1";

  HttpResponse<String> response = Unirest
    .post("https://api-integration.ollang.com/integration/folder/" + folderId + "/docs/upload")
    .header("X-Api-Key", "<your-api-key>")
    .field("file", new File("brand-guideline-v3.pdf"))
    .field("type", "guideline")
    .field("name", "Brand guideline v3")
    .field("language", "en")
    .asString();

  JSONObject doc = new JSONObject(response.getBody());
  System.out.println("Attached document: " + doc.getString("id"));
  ```
</RequestExample>

## Authorizations

This endpoint requires API key authentication. Include your API key in the request header:

* **Header name**: `X-Api-Key`
* **Header value**: Your API key from the Ollang dashboard
* **Format**: `X-Api-Key: your-api-key-here`

The API key user needs write access to the folder. Keys without a folder-write role receive a `403`.

## Path Parameters

<ParamField path="folderId" type="string" required>
  The unique identifier of the folder to attach the document to. Retrieve
  folder IDs with [Retrieve All
  Folders](/apis/ollang-api-reference/retrieve-all-folders).
</ParamField>

## Body Parameters

Send the request as `multipart/form-data`.

<ParamField body="file" type="file" required>
  The document to upload, smaller than 50 MiB (52,428,800 bytes).
</ParamField>

<ParamField body="type" type="string" required>
  The kind of folder document. One of:

  * `guideline` — style and tone guidance
  * `guideline_glossary` — terminology list
  * `character_list` — character names and notes
</ParamField>

<ParamField body="name" type="string">
  Display name of the document. Defaults to the uploaded file's own name.
</ParamField>

<ParamField body="language" type="string">
  BCP-47 language tag of the document (e.g. `en`). When omitted, each project
  copy uses that project's source language.
</ParamField>

## Response

Returns the created folder document, identical to [Attach Folder
Document](/apis/ollang-api-reference/attach-folder-document).

<ResponseField name="id" type="string">
  Unique identifier of the folder document. Pass this to [Remove Folder
  Document](/apis/ollang-api-reference/delete-folder-document).
</ResponseField>

<ResponseField name="name" type="string">
  Display name of the document.
</ResponseField>

<ResponseField name="type" type="string">
  One of `guideline`, `guideline_glossary`, or `character_list`.
</ResponseField>

<ResponseField name="url" type="string">
  Location of the stored copy Ollang created.
</ResponseField>

<ResponseField name="size" type="number">
  Size of the stored document in bytes.
</ResponseField>

<ResponseField name="sourceLanguage" type="string">
  The `language` supplied with the request, or `null`.
</ResponseField>

<ResponseField name="folderId" type="string">
  Identifier of the folder the document is attached to.
</ResponseField>

<ResponseField name="createdAt" type="string">
  When the document was attached, in ISO 8601 format.
</ResponseField>

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "60b8d6f1e1b9b1d8c6c0d8f1",
    "name": "Brand guideline v3",
    "type": "guideline",
    "url": "https://ollang-docs.s3.eu-central-1.amazonaws.com/60b8d6f1e1b9b1d8c6c0d8e5/brand-guideline-v3.pdf",
    "size": 481203,
    "sourceLanguage": "en",
    "folderId": "60b8d6f1e1b9b1d8c6c0d8e1",
    "clientId": "60b8d6f1e1b9b1d8c6c0d8e5",
    "createdAt": "2026-09-04T09:11:02.310Z",
    "updatedAt": "2026-09-04T09:11:02.310Z"
  }
  ```

  ```json 413 theme={null}
  {
    "code": -1,
    "error": "UnknownError",
    "message": "unknown error",
    "detail": "File too large"
  }
  ```

  ```json 401 theme={null}
  {
    "error": "Unauthorized",
    "message": "Invalid or missing API key",
    "code": "UNAUTHORIZED"
  }
  ```

  ```json 403 theme={null}
  {
    "statusCode": 403,
    "message": "You do not have permission to modify this folder",
    "error": "Forbidden"
  }
  ```

  ```json 404 theme={null}
  {
    "statusCode": 404,
    "message": "Folder not found",
    "error": "Not Found"
  }
  ```
</ResponseExample>