Skip to main content
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.
You can optionally provide a graphId query parameter to associate the uploaded file with a Knowledge Graph during upload. 
curl --location --request POST "https://api.writer.com/v1/files?graphId=<GRAPH_ID>" \
  --header "Content-Type: text/plain" \
  --header "Content-Disposition: attachment; filename=<FILE_NAME>" \
  --header "Authorization: Bearer $WRITER_API_KEY" \
  --data-binary "@<FILE_PATH>"

# Example:
#   <FILE_NAME> = test.txt
#   <FILE_PATH> = /path/to/test.txt
#   <GRAPH_ID> = 6029b226-1ee0-4239-a1b0-cdeebfa3ad5a (optional)

​
Query parameters

ParameterTypeDescription
graphIdstringOptional. The UUID of the Knowledge Graph to associate the uploaded file with.

​
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.
If you provide a graphId during upload, the file is associated with that Knowledge Graph. However, the graph_ids field in the upload response is an empty list. The association is visible in the graph_ids list when you retrieve the file using the Get a file endpoint.
{
  "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/<FILE_ID>" \
  --header "Authorization: Bearer $WRITER_API_KEY"

​
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/<FILE_ID>" \
  --header "Authorization: Bearer $WRITER_API_KEY"

​
Response format

The response has the following structure: 
{
  "id": "f1234-abcd-1234",
  "deleted": true
}