---
updatedAt: 2025-09-11T20:21:58.000Z
agentTools:
  projectIndex: https://docs.gathercontent.com/llms.txt
---

# Get file

Get a file.
#### Optional includes:

 - item_instances: Will include a `item_instances` field that contains an array of item id's that the file is attached via an attachment field.
 - metadata: Will include a `metadata` field that contains an array of any metadata that the file contains.
 - uploader: Will include  `avatar`,`name` & `initials` fields of the user who uploaded the file.

> 📘 File URLs
>
> We provide three different URLs for files:
>
> * **url**: This URL can be used to render the file contents in a browser.
> * **download\_url**: This URL will force the file to be downloaded using the original filename.
> * **optimised\_image\_url**:  This is a version in the file optimized for the web.
>
> **Please note**: For none Image-based files, all URLs will force a download and the content cannot be rendered in the browser.  The current supported renderable images are `jpeg`, `png`, `gif`.

# OpenAPI definition

```json
{
  "openapi": "3.0.2",
  "info": {
    "title": "GatherContent API",
    "description": "This is the documentation for the latest stable version of the GatherContent API Find out more about GatherContent at [https://gathercontent.com](https://gathercontent.com) or get help at [https://help.gathercontent.com](https://help.gathercontent.com)",
    "version": "2.0.0",
    "termsOfService": "https://gathercontent.com/legal/terms-of-service",
    "contact": {
      "email": "development@gathercontent.com"
    }
  },
  "x-samples-languages": [
    "curl",
    "node",
    "ruby",
    "javascript",
    "python"
  ],
  "servers": [
    {
      "url": "https://api.gathercontent.com"
    },
    {
      "url": "https://api.gatherpreview.com"
    },
    {
      "url": "http://api.gathercontent.test"
    }
  ],
  "externalDocs": {
    "description": "GatherContent help docs",
    "url": "https://help.gathercontent.com"
  },
  "paths": {
    "/projects/{project_id}/files/{file_id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/projectId"
        },
        {
          "$ref": "#/components/parameters/fileId"
        }
      ],
      "get": {
        "summary": "Get file",
        "operationId": "getFile",
        "description": "Get a file.\n#### Optional includes:\n\n - item_instances: Will include a `item_instances` field that contains an array of item id's that the file is attached via an attachment field.\n - metadata: Will include a `metadata` field that contains an array of any metadata that the file contains.\n - uploader: Will include  `avatar`,`name` & `initials` fields of the user who uploaded the file.\n",
        "tags": [
          "Files"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "include",
            "description": "comma separated list of extra includes",
            "explode": false,
            "schema": {
              "$ref": "#/components/schemas/fileIncludes"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/vnd.gathercontent.v2+json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/fileDefinition"
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/pagination"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/insufficientRoles"
          },
          "404": {
            "description": "Item or Project not found",
            "content": {
              "application/vnd.gathercontent.v2+json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string",
                          "example": "Project not found"
                        },
                        "code": {
                          "type": "integer",
                          "example": 404
                        }
                      }
                    },
                    {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string",
                          "example": "Item not found"
                        },
                        "code": {
                          "type": "integer",
                          "example": 404
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/tooManyRequests"
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Files",
      "description": "Files can be uploaded to project and then used within asset fields within your content."
    }
  ],
  "components": {
    "parameters": {
      "projectId": {
        "name": "project_id",
        "description": "Project id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "integer"
        }
      },
      "fileId": {
        "name": "file_id",
        "description": "File id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "example": "Mh/6LUSfRbSOY0srrxm"
        }
      }
    },
    "schemas": {
      "datetime": {
        "type": "string",
        "description": "DateTimes are all in UTC - it's up to the client to convert them to an appropriate time zone",
        "pattern": "\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}",
        "example": "2019-04-20T04:20:00.000Z"
      },
      "datetimeNullable": {
        "type": "string",
        "description": "DateTimes are all in UTC - it's up to the client to convert them to an appropriate time zone",
        "pattern": "\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}",
        "example": "2019-04-20T04:20:00.000Z",
        "nullable": true
      },
      "fileDefinition": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The identifier of the file"
          },
          "project_id": {
            "type": "integer"
          },
          "filename": {
            "type": "string",
            "description": "The name of the file"
          },
          "optimised_image_url": {
            "type": "string",
            "description": "The optimised file URL"
          },
          "download_url": {
            "type": "string",
            "description": "The file URL maintaining the original filename"
          },
          "size": {
            "type": "integer",
            "description": "The size of the file in MB?"
          },
          "mime_type": {
            "type": "string",
            "description": "The MIME type of the file"
          },
          "alt_text": {
            "type": "string",
            "nullable": true,
            "description": "The alt text type of the file"
          },
          "uploaded_by": {
            "type": "integer",
            "description": "The id of the user who uploaded the file"
          },
          "created_at": {
            "$ref": "#/components/schemas/datetime"
          },
          "updated_at": {
            "$ref": "#/components/schemas/datetimeNullable"
          }
        }
      },
      "fileIncludes": {
        "type": "array",
        "items": {
          "enum": [
            "item_instances",
            "metadata",
            "uploader"
          ]
        }
      },
      "pagination": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer"
          },
          "count": {
            "type": "integer"
          },
          "per_page": {
            "type": "integer"
          },
          "current_page": {
            "type": "integer"
          },
          "total_pages": {
            "type": "integer"
          },
          "links": {
            "type": "object"
          }
        }
      }
    },
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "scheme": "basic"
      }
    },
    "responses": {
      "insufficientRoles": {
        "description": "Insufficient permission to perform this action",
        "content": {
          "application/vnd.gathercontent.v2+json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string",
                  "example": "Insufficient permission to perform this action"
                },
                "code": {
                  "type": "integer",
                  "example": 403
                }
              }
            }
          }
        }
      },
      "tooManyRequests": {
        "description": "Too many request",
        "content": {
          "application/vnd.gathercontent.v2+json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string",
                  "example": "Too Many Attempts."
                },
                "code": {
                  "type": "integer",
                  "example": 429
                }
              }
            }
          }
        },
        "headers": {
          "X-RateLimit-Limit": {
            "schema": {
              "type": "integer"
            },
            "description": "Request limit."
          },
          "X-RateLimit-Remaining": {
            "schema": {
              "type": "integer"
            },
            "description": "The number of requests left for the time window."
          },
          "X-RateLimit-Reset": {
            "schema": {
              "type": "string"
            },
            "description": "The Unix timestamp at which the current rate limit window resets."
          },
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "The number of seconds before the current rate limit window resets."
          }
        }
      }
    }
  },
  "security": [
    {
      "basicAuth": []
    }
  ],
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  }
}
```