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

# Upload workspace files

> Upload files to use. 

You can assign metadata to your files to limit searches to specific files by file metadata. There is no bulk upload method; files must be loaded one at a time.

* **Max number of files:** No limit. The playground limits bulk uploads to 50 files per request.
* **Max total library size:** 1 GB.
* **Max file size:** 5 MB.
* **Supported file types:** PDF, DocX, HTML, TXT, Markdown.

## Request body fields

<ParamField body="file" type="string" required>
  Raw file bytes. Every uploaded file must have a unique file name. Specifying file  labels will find only files with *both* the specified name and label.
</ParamField>

<ParamField body="labels" type="string[]">
  Arbitrary string labels that describe the contents of this file. Labels are case-sensitive. Specifying labels or labels + name will return only files with both any of the specified labels and the specified name.
</ParamField>

<ParamField body="publicUrl" type="string">
  A public URL associated with the file, if any. Only used as metadata, to indicate the location of the source file. For example, if implementing a search engine against a website, specifying a URL for each uploaded file is a simple way to present the link to the file in the search results presented to the user.
</ParamField>

## Responses

### Response 200

A unique identifier for the uploaded file. Use this later to request, modify, or delete the file. You don't need to store the value though, as it is returned along with all file information in a GET /files request. **Type:** UUID. Example: da13301a-14e4-4487-aa2f-cc6048e73cdc // file-uuid

### Error: Unsupported document type 422

Error message:

```json theme={"system"}
{
    "detail": "Invalid file type: image/png. Supported file types are: text/plain, text/html, application/docx, application/pdf"
}
```

<ResponseExample>
  ```json 200 theme={"system"}
  {
    "id": "da13301a-14e4-4487-aa2f-cc6048e73cdc",
  }
  ```

  ```json 422 Unsupported document type theme={"system"}
  {
    "detail": "Invalid file type: image/png. Supported file types are: text/plain, text/html, application/docx, application/pdf"
  }
  ```
</ResponseExample>

<RequestExample>
  ```python Python theme={"system"}
  rom ai21 import AI21Client

  client = AI21Client()

  # Option 1: Upload a local file
  file_from_disk = client.library.files.create(
      labels=["label1", "label2"],
  )

  # Option 2: Upload a file from a public URL
  file_from_url = client.library.files.create(
      public_url="https://www.example.com/file.pdf",
      labels=["label1", "label2"],
  )

  # Retrieve uploaded file metadata (example)
  uploaded_file = client.library.files.get(file_from_disk.id)
  ```

  ```javascript JavaScript theme={"system"}
  const payload = {
    path: "docs/file-from-url.pdf",
    labels: ["label1", "label2"],
    publicUrl: "https://www.example.com/file.pdf"
  };

  fetch("https://api.ai21.com/studio/v1/library/files", {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify(payload)
  })
    .then(response => response.json())
    .then(response => console.log(response))
    .catch(error => console.error(error));
  ```

  ```php PHP theme={"system"}
  <?php

  $payload = json_encode([
    "path" => "docs/file-from-url.pdf",
    "labels" => ["label1", "label2"],
    "publicUrl" => "https://www.example.com/file.pdf"
  ]);

  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.ai21.com/studio/v1/library/files",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_HTTPHEADER => [
      "Authorization: Bearer YOUR_API_KEY",
      "Content-Type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```go Go theme={"system"}
  package main

  import (
          "bytes"
          "encoding/json"
          "fmt"
          "io/ioutil"
          "net/http"
  )

  func main() {
          url := "https://api.ai21.com/studio/v1/library/files"

          payload := map[string]interface{}{
                  "path":      "docs/file-from-url.pdf",
                  "labels":    []string{"label1", "label2"},
                  "publicUrl": "https://www.example.com/file.pdf",
          }

          jsonData, err := json.Marshal(payload)
          if err != nil {
                  panic(err)
          }

          req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
          if err != nil {
                  panic(err)
          }

          req.Header.Add("Content-Type", "application/json")
          req.Header.Add("Authorization", "Bearer YOUR_API_KEY")

          client := &http.Client{}
          res, err := client.Do(req)
          if err != nil {
                  panic(err)
          }
          defer res.Body.Close()

          body, err := ioutil.ReadAll(res.Body)
          if err != nil {
                  panic(err)
  ```

  ```bash cURI theme={"system"}
  curl --request POST \
    --url https://api.ai21.com/studio/v1/library/files \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --data '{
      "path": "docs/file-from-url.pdf",
      "labels": ["label1", "label2"],
      "publicUrl": "https://www.example.com/file.pdf"
    }'
  ```

  ```java Java theme={"system"}
  HttpResponse<String> response = Unirest.post("https://api.ai21.com/studio/v1/library/files")
    .header("Content-Type", "application/json")
    .header("Authorization", "Bearer YOUR_API_KEY")
    .body("{"
        + "\"path\": \"docs/file-from-url.pdf\","
        + "\"labels\": [\"label1\", \"label2\"],"
        + "\"publicUrl\": \"https://www.example.com/file.pdf\""
        + "}")
    .asString();
  ```
</RequestExample>