openapi: 3.0.3
info:
  title: File API API
  version: '1.0'
servers:
- url: https://api.writer.com
security:
- bearerAuth: []
tags:
- name: File API
paths:
  /v1/files/{file_id}:
    get:
      security:
      - bearerAuth: []
      summary: Retrieve file
      description: Retrieve detailed information about a specific file, including its metadata, status, and associated graphs.
      tags:
      - File API
      operationId: gatewayGetFile
      parameters:
      - name: file_id
        in: path
        required: true
        schema:
          type: string
        description: The unique identifier of the file.
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/file_response'
              example:
                id: 7c36a365-392f-43ba-840d-8f3103b42572
                created_at: '2024-07-10T13:34:28.301201Z'
                name: example.pdf
                graph_ids:
                - 704ffd94-de04-4de2-9f8b-f9fc04831edd
                status: completed
      x-codeSamples:
      - lang: cURL
        source: "curl --location --request GET https://api.writer.com/v1/files/{file_id} \\\n --header \"Authorization: Bearer <token>\""
      - lang: JavaScript
        source: "import Writer from 'writer-sdk';\n\nconst client = new Writer({\n  apiKey: process.env['WRITER_API_KEY'], // This is the default and can be omitted\n});\n\nasync function main() {\n  const file = await client.files.retrieve('file_id');\n\n  console.log(file.id);\n}\n\nmain();"
      - lang: Python
        source: "import os\nfrom writerai import Writer\n\nclient = Writer(\n    # This is the default and can be omitted\n    api_key=os.environ.get(\"WRITER_API_KEY\"),\n)\nfile = client.files.retrieve(\n    \"file_id\",\n)\nprint(file.id)"
    delete:
      security:
      - bearerAuth: []
      summary: Delete file
      description: Permanently delete a file from the system. This action cannot be undone.
      tags:
      - File API
      operationId: gatewayDeleteFile
      parameters:
      - name: file_id
        in: path
        required: true
        schema:
          type: string
        description: The unique identifier of the file.
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/delete_file_response'
              example:
                id: 7c36a365-392f-43ba-840d-8f3103b42572
                deleted: true
      x-codeSamples:
      - lang: cURL
        source: "curl --location --request DELETE https://api.writer.com/v1/files/{file_id} \\\n --header \"Authorization: Bearer <token>\""
      - lang: JavaScript
        source: "import Writer from 'writer-sdk';\n\nconst client = new Writer({\n  apiKey: process.env['WRITER_API_KEY'], // This is the default and can be omitted\n});\n\nasync function main() {\n  const file = await client.files.delete('file_id');\n\n  console.log(file.id);\n}\n\nmain();"
      - lang: Python
        source: "import os\nfrom writerai import Writer\n\nclient = Writer(\n    # This is the default and can be omitted\n    api_key=os.environ.get(\"WRITER_API_KEY\"),\n)\nfile = client.files.delete(\n    \"file_id\",\n)\nprint(file.id)"
  /v1/files:
    get:
      security:
      - bearerAuth: []
      summary: List files
      description: Retrieve a paginated list of files with optional filtering by status, graph association, and file type.
      tags:
      - File API
      operationId: gatewayGetFiles
      parameters:
      - name: before
        in: query
        required: false
        schema:
          type: string
        description: The ID of the first object in the previous page. This parameter instructs the API to return the previous page of results.
      - name: after
        in: query
        required: false
        schema:
          type: string
        description: The ID of the last object in the previous page. This parameter instructs the API to return the next page of results.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          format: int32
          default: 50
        description: Specifies the maximum number of objects returned in a page. The default value is 50. The minimum value is 1, and the maximum value is 100.
      - name: order
        in: query
        required: false
        schema:
          type: string
          default: desc
          enum:
          - asc
          - desc
        description: Specifies the order of the results. Valid values are asc for ascending and desc for descending.
      - name: graph_id
        in: query
        required: false
        schema:
          type: string
          format: uuid
        description: The unique identifier of the graph to which the files belong.
      - name: status
        in: query
        required: false
        schema:
          enum:
          - in_progress
          - completed
          - failed
        description: Specifies the status of the files to retrieve. Valid values are in_progress, completed or failed.
      - name: file_types
        in: query
        required: false
        schema:
          type: string
        description: 'The extensions of the files to retrieve. Separate multiple extensions with a comma. For example: `pdf,jpg,docx`.'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/files_response'
              example:
                data:
                - id: 7c36a365-392f-43ba-840d-8f3103b42572
                  name: example.pdf
                  created_at: '2024-07-10T12:00:00Z'
                  graph_ids:
                  - 31a8b75a-9a90-432f-8861-942229125333
                  status: in_progress
                - id: 4bbe6207-737e-486f-a287-c5e95536984a
                  name: image.jpg
                  created_at: '2024-07-09T15:30:00Z'
                  graph_ids:
                  - 31a8b75a-9a90-432f-8861-942229125333
                  status: completed
                - id: efc86bb4-30a4-40c9-a52a-ecee0d7e071f
                  name: document.txt
                  created_at: '2024-07-08T16:00:00Z'
                  graph_ids:
                  - 31a8b75a-9a90-432f-8861-942229125333
                  status: failed
                has_more: false
                first_id: 7c36a365-392f-43ba-840d-8f3103b42572
                last_id: efc86bb4-30a4-40c9-a52a-ecee0d7e071f
      x-codeSamples:
      - lang: cURL
        source: "curl --location --request GET https://api.writer.com/v1/files \\\n --header \"Authorization: Bearer <token>\""
      - lang: JavaScript
        source: "import Writer from 'writer-sdk';\n\nconst client = new Writer({\n  apiKey: process.env['WRITER_API_KEY'], // This is the default and can be omitted\n});\n\nasync function main() {\n  // Automatically fetches more pages as needed.\n  for await (const file of client.files.list()) {\n    console.log(file.id);\n  }\n}\n\nmain();"
      - lang: Python
        source: "import os\nfrom writerai import Writer\n\nclient = Writer(\n    # This is the default and can be omitted\n    api_key=os.environ.get(\"WRITER_API_KEY\"),\n)\npage = client.files.list()\npage = page.data[0]\nprint(page.id)"
    post:
      security:
      - bearerAuth: []
      summary: Upload file
      description: Upload a new file to the system. Supports various file formats including PDF, DOC, DOCX, PPT, PPTX, JPG, PNG, EML, HTML, SRT, CSV, XLS, and XLSX.
      tags:
      - File API
      operationId: gatewayUploadFile
      parameters:
      - name: Content-Disposition
        in: header
        required: true
        schema:
          type: string
        description: 'The disposition type of the file, typically used to indicate the form-data name. Use `attachment` with the filename parameter to specify the name of the file, for example: `attachment; filename=example.pdf`.'
      - name: Content-Type
        in: header
        required: true
        schema:
          type: string
        description: The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/MIME_types/Common_types) of the file being uploaded. Supports `txt`, `doc`, `docx`, `ppt`, `pptx`, `jpg`, `png`, `eml`, `html`, `pdf`, `srt`, `csv`, `xls`, `xlsx`, `mp3`, and `mp4` file extensions.
      - name: Content-Length
        in: header
        required: true
        schema:
          type: integer
          format: int64
        description: The size of the file in bytes.
      - name: graphId
        in: query
        required: false
        schema:
          type: string
          format: uuid
        description: 'The unique identifier of the Knowledge Graph to associate the uploaded file with.


          Note: The response from the upload endpoint does not include the `graphId` field, but the association will be visible when you retrieve the file using the file retrieval endpoint.'
      requestBody:
        content:
          text/plain:
            schema:
              type: string
              format: binary
          application/msword:
            schema:
              type: string
              format: binary
          application/vnd.openxmlformats-officedocument.wordprocessingml.document:
            schema:
              type: string
              format: binary
          application/vnd.ms-powerpoint:
            schema:
              type: string
              format: binary
          application/vnd.openxmlformats-officedocument.presentationml.presentation:
            schema:
              type: string
              format: binary
          image/jpeg:
            schema:
              type: string
              format: binary
          image/png:
            schema:
              type: string
              format: binary
          message/rfc822:
            schema:
              type: string
              format: binary
          text/html:
            schema:
              type: string
              format: binary
          application/pdf:
            schema:
              type: string
              format: binary
          application/x-subrip:
            schema:
              type: string
              format: binary
          text/csv:
            schema:
              type: string
              format: binary
          application/vnd.ms-excel:
            schema:
              type: string
              format: binary
          application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
            schema:
              type: string
              format: binary
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/file_response'
              example:
                id: 7c36a365-392f-43ba-840d-8f3103b42572
                name: example.pdf
                created_at: '2024-07-10T14:30:00Z'
                graph_id: []
                status: in_progress
      x-codeSamples:
      - lang: cURL
        source: "curl --location --request POST https://api.writer.com/v1/files \\\n --header \"Authorization: Bearer <token>\"\n --header \"Accept: */*\" \\\n --header \"Content-Disposition: attachment; filename=descriptions.pdf\" \\\n --header \"Content-Length: size_in_bytes\" \\\n --header \"Content-Type: application/pdf\" \\\n --data-binary \"@descriptions.pdf\""
      - lang: JavaScript
        source: "import fs from 'fs';\nimport Writer from 'writer-sdk';\n\nconst client = new Writer({\n  apiKey: process.env['WRITER_API_KEY'], // This is the default and can be omitted\n});\n\nasync function main() {\n  const file = await client.files.upload({\n    content: fs.createReadStream('path/to/file/descriptions.pdf'),\n    'Content-Disposition': 'attachment; filename=descriptions.pdf',\n    'Content-Type': 'application/pdf',\n  });\n\n  console.log(file.id);\n}\n\nmain();"
      - lang: Python
        source: "import os\nfrom pathlib import Path\nfrom writerai import Writer\n\nclient = Writer(\n    # This is the default and can be omitted\n    api_key=os.environ.get(\"WRITER_API_KEY\"),\n)\nfile = client.files.upload(\n    content=Path('/path/to/file/descriptions.pdf'),\n    content_disposition=\"attachment; filename=descriptions.pdf\",\n    content_type=\"application/pdf\"\n)\nprint(file.id)"
  /v1/files/{file_id}/download:
    get:
      security:
      - bearerAuth: []
      tags:
      - File API
      summary: Download file
      description: Download the binary content of a file. The response will contain the file data in the appropriate MIME type.
      operationId: gatewayDownloadFile
      parameters:
      - name: file_id
        in: path
        required: true
        schema:
          type: string
        description: The unique identifier of the file.
      responses:
        '200':
          description: File download successful
          headers:
            Content-Type:
              description: The MIME type of the file being downloaded
              required: true
              schema:
                type: object
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
              examples:
                fileDownloadExample:
                  summary: Example binary file download
                  value: File contents
      x-codeSamples:
      - lang: cURL
        source: "curl --location --request GET https://api.writer.com/v1/files/{file_id}/download \\\n --header \"Authorization: Bearer <token>\""
      - lang: JavaScript
        source: "import Writer from 'writer-sdk';\n\nconst client = new Writer({\n  apiKey: process.env['WRITER_API_KEY'], // This is the default and can be omitted\n});\n\nasync function main() {\n  const response = await client.files.download('file_id');\n\n  console.log(response);\n\n  const content = await response.blob();\n  console.log(content);\n}\n\nmain();"
      - lang: Python
        source: "import os\nfrom writerai import Writer\n\nclient = Writer(\n    # This is the default and can be omitted\n    api_key=os.environ.get(\"WRITER_API_KEY\"),\n)\nresponse = client.files.download(\n    \"file_id\",\n)\nprint(response)\ncontent = response.read()\nprint(content)"
  /v1/files/retry:
    post:
      security:
      - bearerAuth: []
      tags:
      - File API
      summary: Retry failed files
      description: Retry processing of files that previously failed to process. This will re-attempt the processing of the specified files.
      operationId: gatewayRetryFailedFiles
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/retry_files_request'
        required: true
      responses:
        '200':
          description: The retry request is being processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retry_files_response'
              example:
                success: true
      x-codeSamples:
      - lang: cURL
        source: "curl --location --request POST https://api.writer.com/v1/files/retry \\\n --header \"Authorization: Bearer <token>\" \\\n --header \"Content-Type: application/json\" \\\n --data-raw '{\"file_ids\":[\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\", \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\", \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\"]}'"
      - lang: JavaScript
        source: "import Writer from 'writer-sdk';\n\nconst client = new Writer({\n  apiKey: process.env['WRITER_API_KEY'], // This is the default and can be omitted\n});\n\nasync function main() {\n  const response = await client.files.retry({\n    file_ids: [\n      '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',\n      '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',\n      '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',\n    ],\n  });\n\n  console.log(response.success);\n}\n\nmain();"
      - lang: Python
        source: "import os\nfrom writerai import Writer\n\nclient = Writer(\n    # This is the default and can be omitted\n    api_key=os.environ.get(\"WRITER_API_KEY\"),\n)\nresponse = client.files.retry(\n    file_ids=[\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\", \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\", \"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\"],\n)\nprint(response.success)"
components:
  schemas:
    retry_files_response:
      title: retry_files_response
      type: object
      properties:
        success:
          type: boolean
          description: Indicates whether the retry operation was successful.
    retry_files_request:
      title: retry_files_request
      required:
      - file_ids
      type: object
      properties:
        file_ids:
          type: array
          items:
            type: string
            format: uuid
          description: The unique identifier of the files to retry.
    files_response:
      title: files_response
      required:
      - data
      - has_more
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/file_response'
        has_more:
          type: boolean
          description: Indicates if there are more files available beyond the current page.
        first_id:
          type: string
          description: The ID of the first file in the current response.
        last_id:
          type: string
          description: The ID of the last file in the current response.
    file_response:
      title: file_response
      required:
      - id
      - created_at
      - name
      - graph_ids
      - status
      type: object
      properties:
        id:
          type: string
          description: A unique identifier of the file.
        created_at:
          type: string
          format: date-time
          description: The timestamp when the file was uploaded.
        name:
          type: string
          description: The name of the file.
        graph_ids:
          type: array
          items:
            type: string
            format: uuid
          description: 'A list of Knowledge Graph IDs that the file is associated with.


            If you provided 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 will be visible in the `graph_ids` list when you retrieve the file using the file retrieval endpoint.'
        status:
          type: string
          description: The processing status of the file.
    delete_file_response:
      title: delete_file_response
      required:
      - id
      - deleted
      type: object
      properties:
        id:
          type: string
          description: A unique identifier of the deleted file.
        deleted:
          type: boolean
          description: Indicates whether the file was successfully deleted.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer authentication header of the form `Bearer <token>`, where `<token>` is your [Writer API key](https://dev.writer.com/api-reference/api-keys).
x-mint:
  mcp:
    enabled: true