The File API allows you to manage files in your account. You can upload, download, list, and delete files.

After you upload a file, you can use it to perform actions such as attaching it to a Knowledge Graph or using it as an input in a no-code agent.

This guide shows you how to perform the following actions:

You need an API key to access the Writer API. Get an API key by following the steps in the API quickstart.

We recommend setting the API key as an environment variable in a .env file with the name WRITER_API_KEY.

​
Upload a file

Endpoint: POST /v1/files

A file persists in your account until you delete it.
curl --location --request POST "https://api.writer.com/v1/files" \
  --header "Content-Type: text/plain" \
  --header "Content-Disposition: attachment; filename=test.txt" \
  --header "Authorization: Bearer $WRITER_API_KEY" \
  --data-binary "@/path/to/test.txt"

​
Request body

ParameterTypeDescription
contentstringThe content of the file. See the Python SDK and the JavaScript SDK for more details about how to pass the file contents.
content_dispositionstringThe content disposition of the file.
content_typestringThe MIME type of the file. The file upload supports txt, doc, docx, ppt, pptx, jpg, png, eml, html, pdf, srt, csv, xls, and xlsx file extensions.

​
Response format

FieldTypeDescription
idstringThe ID of the file.
created_atstringThe date and time the file was created in ISO 8601 format.
namestringThe name of the file.
graph_idsarray[string]The IDs of the Knowledge Graphs the file is attached to.
statusstringThe processing status of the file.
{
  "id": "1862f090-a281-48f3-8838-26c1e78b605e",
  "created_at": "2024-06-24T12:34:56Z",
  "name": "test.txt",
  "graph_ids": [],
  "status": "in_progress"
}

​
List all files

Endpoint: GET /v1/files

curl --location --request GET "https://api.writer.com/v1/files" \
  --header "Authorization: Bearer $WRITER_API_KEY"

​
Query parameters

In addition to the pagination parameters, this endpoint supports the following query parameters:

ParameterTypeDescription
graph_idstringFilter files by the graph they are attached to.
statusstringFilter files by status.
file_typesstringFilter files by extension type. Separate multiple values by commas. For example, txt,pdf,docx.

The file_types parameter is not yet available in the Python and Node SDKs. It will be available in version 2.3.0.

​
Response format

The response has the following structure:

FieldTypeDescription
dataarray[object]An array of file objects.
data[].idstringThe ID of the file.
data[].created_atstringThe date and time the file was created in ISO 8601 format.
data[].namestringThe name of the file.
data[].graph_idsarray[string]The IDs of the Knowledge Graphs the file is attached to.
data[].statusstringThe status of the file.
has_morebooleanWhether there are more files to fetch.
first_idstringThe ID of the first file in the response.
last_idstringThe ID of the last file in the response.
{
  "data": [
    {
      "id": "f1234-abcd-1234",
      "created_at": "2025-03-07T23:20:50.978908Z",
      "name": "my_file.pdf",
      "graph_ids": [],
      "status": "completed"
    },
    {
      "id": "1234-abcd-5678",
      "created_at": "2025-03-07T23:20:44.047604Z",
      "name": "my_second_file.pdf",
      "graph_ids": [],
      "status": "completed"
    }
  ],
  "has_more": false,
  "first_id": "f1234-abcd-1234",
  "last_id": "1234-abcd-5678"
}

​
Get a file

Endpoint: GET /v1/files/{fileId}

curl --location --request GET "https://api.writer.com/v1/files/<fileId>" \
  --header "Authorization: Bearer $WRITER_API_KEY"

​
Path parameters

ParameterDescription
fileIdThe ID of the file to get.

​
Response format

{
  "id": "f1234-abcd-1234",
  "created_at": "2025-03-07T23:20:50.978908Z",
  "name": "test.txt",
  "graph_ids": [],
  "status": "completed"
}

​
Delete a file

Endpoint: DELETE /v1/files/{fileId}

curl --location --request DELETE "https://api.writer.com/v1/files/<fileId>" \
  --header "Authorization: Bearer $WRITER_API_KEY"

​
Path parameters

ParameterDescription
fileIdThe ID of the file to delete.

​
Response format

The response has the following structure:

{
  "id": "f1234-abcd-1234",
  "deleted": true
}