> ## 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.

# Attach Folder Document

> Attach a guideline, glossary, or character list to a folder so every project in it inherits the document

Attaches a folder-level document to a folder. 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).

This is the API equivalent of uploading a guideline in the folder's **Guidelines** panel in the dashboard. See [Memory, Guidelines, and Custom Instructions](/memory-guidelines-custom-instructions) for how folder-level guidelines interact with project-level guidelines and global custom instructions.

<Note>
  Ollang fetches the document from the URL you supply and stores its own copy,
  so a short-lived pre-signed URL is fine. The URL only needs to be readable at
  the moment of the call, and the document stays available to later orders after
  the signature expires.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api-integration.ollang.com/integration/folder/60b8d6f1e1b9b1d8c6c0d8e1/docs" \
    -H "X-Api-Key: <your-api-key>" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://your-bucket.s3.amazonaws.com/brand-guideline-v3.pdf?X-Amz-Signature=...",
      "type": "guideline",
      "name": "Brand guideline v3",
      "size": 481203,
      "language": "en"
    }'
  ```

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

  const response = await fetch(
    `https://api-integration.ollang.com/integration/folder/${folderId}/docs`,
    {
      method: "POST",
      headers: {
        "X-Api-Key": "<your-api-key>",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        url: "https://your-bucket.s3.amazonaws.com/brand-guideline-v3.pdf?X-Amz-Signature=...",
        type: "guideline",
        name: "Brand guideline v3",
        language: "en",
      }),
    },
  );

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

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

  folder_id = "60b8d6f1e1b9b1d8c6c0d8e1"

  response = requests.post(
      f"https://api-integration.ollang.com/integration/folder/{folder_id}/docs",
      headers={
          "X-Api-Key": "<your-api-key>",
          "Content-Type": "application/json",
      },
      json={
          "url": "https://your-bucket.s3.amazonaws.com/brand-guideline-v3.pdf?X-Amz-Signature=...",
          "type": "guideline",
          "name": "Brand guideline v3",
          "language": "en",
      },
  )

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

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

  $payload = json_encode([
      'url' => 'https://your-bucket.s3.amazonaws.com/brand-guideline-v3.pdf?X-Amz-Signature=...',
      'type' => 'guideline',
      'name' => 'Brand guideline v3',
      'language' => 'en',
  ]);

  $curl = curl_init();

  curl_setopt_array($curl, array(
      CURLOPT_URL => "https://api-integration.ollang.com/integration/folder/{$folderId}/docs",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_POST => true,
      CURLOPT_POSTFIELDS => $payload,
      CURLOPT_HTTPHEADER => array(
          'X-Api-Key: <your-api-key>',
          'Content-Type: application/json'
      ),
  ));

  $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"
      "net/http"
  )

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

      payload, _ := json.Marshal(map[string]interface{}{
          "url":      "https://your-bucket.s3.amazonaws.com/brand-guideline-v3.pdf?X-Amz-Signature=...",
          "type":     "guideline",
          "name":     "Brand guideline v3",
          "language": "en",
      })

      req, _ := http.NewRequest("POST", url, bytes.NewBuffer(payload))
      req.Header.Set("X-Api-Key", "<your-api-key>")
      req.Header.Set("Content-Type", "application/json")

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

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

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

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

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

  JSONObject payload = new JSONObject()
    .put("url", "https://your-bucket.s3.amazonaws.com/brand-guideline-v3.pdf?X-Amz-Signature=...")
    .put("type", "guideline")
    .put("name", "Brand guideline v3")
    .put("language", "en");

  HttpResponse<String> response = Unirest
    .post("https://api-integration.ollang.com/integration/folder/" + folderId + "/docs")
    .header("X-Api-Key", "<your-api-key>")
    .header("Content-Type", "application/json")
    .body(payload.toString())
    .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.
</ParamField>

## Body Parameters

<ParamField body="url" type="string" required>
  A URL Ollang can read the document from, such as a pre-signed S3 URL. Must be
  `http` or `https`, must resolve to a public address, and must return the file
  without a redirect. The document must be 50 MB or smaller.
</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 `<folder name>_folder_document`.
</ParamField>

<ParamField body="size" type="number">
  Size of the document in bytes. Ollang records the size of the file it actually
  fetched, so this value is informational.
</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.

<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-02T10:14:22.511Z",
    "updatedAt": "2026-09-02T10:14:22.511Z"
  }
  ```

  ```json 400 theme={null}
  {
    "statusCode": 400,
    "message": "Could not fetch the document from the provided URL. Make sure it is publicly readable and under 50 MB.",
    "error": "Bad Request"
  }
  ```

  ```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>