---
updatedAt: 2026-06-12T20:00:32.000Z
agentTools:
  projectIndex: https://layer-api.readme.io/llms.txt
---

# Create a File

Create a File in a Project by uploading multipart data or importing a hosted image URL

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "termsOfService": "https://layer.team/terms-of-service",
    "title": "Layer API",
    "version": "0.3.0",
    "x-logo": {
      "altText": "Layer logo",
      "url": "https://layer.team/wp-content/themes/lessis/images/assets/layer-logo-footer.png"
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "bearerFormat": "JWT",
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "paths": {
    "/projects/{projectId}/files": {
      "post": {
        "operationId": "createFile",
        "summary": "Create a File",
        "tags": [
          "Files"
        ],
        "description": "Create a File in a Project by uploading multipart data or importing a hosted image URL",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "description": "The required info to add a file to a project, either as multipart file data or a hosted image source URL",
                "title": "File Create Request",
                "oneOf": [
                  {
                    "description": "Create a file by uploading multipart file data.",
                    "title": "Multipart File Upload",
                    "type": "object",
                    "required": [
                      "file"
                    ],
                    "properties": {
                      "caption": {
                        "description": "Caption for the file",
                        "type": "string"
                      },
                      "elementId": {
                        "description": "ID for the element to associate this file with",
                        "type": "string"
                      },
                      "fieldId": {
                        "description": "ID for the field to associate this file with",
                        "type": "string"
                      },
                      "file": {
                        "additionalProperties": true,
                        "description": "An un-encoded file object. Max size: 25",
                        "type": "object",
                        "required": [
                          "buffer",
                          "encoding",
                          "filename",
                          "mimetype",
                          "size",
                          "truncated"
                        ],
                        "properties": {
                          "buffer": {},
                          "encoding": {
                            "type": "string"
                          },
                          "filename": {
                            "type": "string"
                          },
                          "mimetype": {
                            "type": "string"
                          },
                          "size": {
                            "type": "number"
                          },
                          "truncated": {
                            "type": "boolean"
                          }
                        }
                      }
                    }
                  },
                  {
                    "description": "Create a file by importing an image from a hosted URL.",
                    "title": "Source URL File Import",
                    "type": "object",
                    "required": [
                      "sourceUrl"
                    ],
                    "properties": {
                      "caption": {
                        "description": "Caption for the file",
                        "type": "string"
                      },
                      "elementId": {
                        "description": "ID for the element to associate this file with",
                        "type": "string"
                      },
                      "fieldId": {
                        "description": "ID for the field to associate this file with",
                        "type": "string"
                      },
                      "sourceUrl": {
                        "description": "Public HTTP(S) image URL for the API to fetch and copy into Google Cloud Storage",
                        "format": "uri",
                        "type": "string"
                      }
                    }
                  }
                ]
              }
            },
            "multipart/mixed": {
              "schema": {
                "description": "The required info to add a file to a project, either as multipart file data or a hosted image source URL",
                "title": "File Create Request",
                "oneOf": [
                  {
                    "description": "Create a file by uploading multipart file data.",
                    "title": "Multipart File Upload",
                    "type": "object",
                    "required": [
                      "file"
                    ],
                    "properties": {
                      "caption": {
                        "description": "Caption for the file",
                        "type": "string"
                      },
                      "elementId": {
                        "description": "ID for the element to associate this file with",
                        "type": "string"
                      },
                      "fieldId": {
                        "description": "ID for the field to associate this file with",
                        "type": "string"
                      },
                      "file": {
                        "additionalProperties": true,
                        "description": "An un-encoded file object. Max size: 25",
                        "type": "object",
                        "required": [
                          "buffer",
                          "encoding",
                          "filename",
                          "mimetype",
                          "size",
                          "truncated"
                        ],
                        "properties": {
                          "buffer": {},
                          "encoding": {
                            "type": "string"
                          },
                          "filename": {
                            "type": "string"
                          },
                          "mimetype": {
                            "type": "string"
                          },
                          "size": {
                            "type": "number"
                          },
                          "truncated": {
                            "type": "boolean"
                          }
                        }
                      }
                    }
                  },
                  {
                    "description": "Create a file by importing an image from a hosted URL.",
                    "title": "Source URL File Import",
                    "type": "object",
                    "required": [
                      "sourceUrl"
                    ],
                    "properties": {
                      "caption": {
                        "description": "Caption for the file",
                        "type": "string"
                      },
                      "elementId": {
                        "description": "ID for the element to associate this file with",
                        "type": "string"
                      },
                      "fieldId": {
                        "description": "ID for the field to associate this file with",
                        "type": "string"
                      },
                      "sourceUrl": {
                        "description": "Public HTTP(S) image URL for the API to fetch and copy into Google Cloud Storage",
                        "format": "uri",
                        "type": "string"
                      }
                    }
                  }
                ]
              }
            },
            "multipart/form-data": {
              "schema": {
                "description": "The required info to add a file to a project, either as multipart file data or a hosted image source URL",
                "title": "File Create Request",
                "oneOf": [
                  {
                    "description": "Create a file by uploading multipart file data.",
                    "title": "Multipart File Upload",
                    "type": "object",
                    "required": [
                      "file"
                    ],
                    "properties": {
                      "caption": {
                        "description": "Caption for the file",
                        "type": "string"
                      },
                      "elementId": {
                        "description": "ID for the element to associate this file with",
                        "type": "string"
                      },
                      "fieldId": {
                        "description": "ID for the field to associate this file with",
                        "type": "string"
                      },
                      "file": {
                        "additionalProperties": true,
                        "description": "An un-encoded file object. Max size: 25",
                        "type": "object",
                        "required": [
                          "buffer",
                          "encoding",
                          "filename",
                          "mimetype",
                          "size",
                          "truncated"
                        ],
                        "properties": {
                          "buffer": {},
                          "encoding": {
                            "type": "string"
                          },
                          "filename": {
                            "type": "string"
                          },
                          "mimetype": {
                            "type": "string"
                          },
                          "size": {
                            "type": "number"
                          },
                          "truncated": {
                            "type": "boolean"
                          }
                        }
                      }
                    }
                  },
                  {
                    "description": "Create a file by importing an image from a hosted URL.",
                    "title": "Source URL File Import",
                    "type": "object",
                    "required": [
                      "sourceUrl"
                    ],
                    "properties": {
                      "caption": {
                        "description": "Caption for the file",
                        "type": "string"
                      },
                      "elementId": {
                        "description": "ID for the element to associate this file with",
                        "type": "string"
                      },
                      "fieldId": {
                        "description": "ID for the field to associate this file with",
                        "type": "string"
                      },
                      "sourceUrl": {
                        "description": "Public HTTP(S) image URL for the API to fetch and copy into Google Cloud Storage",
                        "format": "uri",
                        "type": "string"
                      }
                    }
                  }
                ]
              }
            }
          },
          "description": "The required info to add a file to a project, either as multipart file data or a hosted image source URL"
        },
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "projectId",
            "required": true,
            "description": "Project ID"
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "File successfully created",
            "content": {
              "application/json": {
                "schema": {
                  "description": "File successfully created",
                  "type": "object",
                  "required": [
                    "file"
                  ],
                  "properties": {
                    "errors": {
                      "description": "If any validation errors occurred with the file configuration values, those will be shown here",
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "message"
                        ],
                        "properties": {
                          "code": {
                            "type": "string"
                          },
                          "key": {
                            "type": "string"
                          },
                          "message": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "file": {
                      "type": "object",
                      "required": [
                        "createdAt",
                        "createdBy",
                        "drawingViewFile",
                        "element",
                        "field",
                        "fileType",
                        "id",
                        "metadata",
                        "name",
                        "stage",
                        "status",
                        "updatedAt",
                        "updatedBy",
                        "urls"
                      ],
                      "properties": {
                        "caption": {
                          "description": "File caption",
                          "type": "string"
                        },
                        "createdAt": {
                          "description": "Date the file was created",
                          "format": "date-time",
                          "type": "string"
                        },
                        "createdBy": {
                          "description": "Name of the user who created the file",
                          "type": "string"
                        },
                        "drawingViewFile": {
                          "description": "Boolean value indicating that the file is being use as a drawing view file",
                          "type": "boolean"
                        },
                        "element": {
                          "nullable": true,
                          "type": "object",
                          "required": [
                            "id",
                            "name"
                          ],
                          "properties": {
                            "id": {
                              "description": "Element ID",
                              "type": "string"
                            },
                            "name": {
                              "description": "Element name",
                              "type": "string"
                            }
                          }
                        },
                        "field": {
                          "nullable": true,
                          "type": "object",
                          "required": [
                            "id",
                            "name"
                          ],
                          "properties": {
                            "id": {
                              "description": "Field ID",
                              "type": "string"
                            },
                            "name": {
                              "description": "Field name",
                              "type": "string"
                            }
                          }
                        },
                        "fileSize": {
                          "description": "Size of the file in KB",
                          "type": "number"
                        },
                        "fileType": {
                          "description": "Type of the file from the extension",
                          "type": "string"
                        },
                        "id": {
                          "type": "string"
                        },
                        "isMobileOptimized": {
                          "description": "Boolean value indicating that a mobile-optimized PDF is enabled for this file",
                          "type": "boolean"
                        },
                        "metadata": {
                          "description": "Additional file data.",
                          "type": "object",
                          "required": [
                            "UsePanoramaViewer"
                          ],
                          "properties": {
                            "UsePanoramaViewer": {
                              "description": "Flag to determine use of the 360 panorama viewer in Layer",
                              "type": "boolean"
                            }
                          }
                        },
                        "name": {
                          "description": "Name of the file",
                          "type": "string"
                        },
                        "optimizedFullUrl": {
                          "description": "URL to the mobile-optimized full-size PDF",
                          "type": "string"
                        },
                        "stage": {
                          "description": "Indicates the current processing stage of the file",
                          "enum": [
                            [
                              "COMPLETE",
                              "ERROR",
                              "LOCAL",
                              "processed",
                              "PROCESSING",
                              "UPLOADING"
                            ]
                          ],
                          "type": "string"
                        },
                        "status": {
                          "description": "File status",
                          "enum": [
                            "active",
                            "archived"
                          ],
                          "type": "string"
                        },
                        "updatedAt": {
                          "description": "Date & time the file was last updated",
                          "format": "date-time",
                          "type": "string"
                        },
                        "updatedBy": {
                          "description": "Name of the user who last updated the file",
                          "type": "string"
                        },
                        "urls": {
                          "description": "Set of storage URLs where the original file and generated thumbnails reside. Only available once the file's status has moved from PROCESSING to COMPLETE",
                          "type": "object",
                          "properties": {
                            "full": {
                              "description": "URL to the full size file",
                              "type": "string"
                            },
                            "thumb256": {
                              "description": "URL to a 256px thumbnail for the file",
                              "type": "string"
                            },
                            "thumb512": {
                              "description": "URL to a 512px thumbnail for the file",
                              "type": "string"
                            },
                            "thumb64": {
                              "description": "URL to a 64px thumbnail for the file",
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "Response payload exceeded the configured size limit for this API.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Response payload exceeded the configured size limit for this API.",
                  "properties": {
                    "code": {
                      "description": "Stable machine-readable error code.",
                      "type": "string"
                    },
                    "error": {
                      "description": "Human-readable error message.",
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "error"
                  ],
                  "type": "object"
                }
              }
            }
          },
          "500": {
            "description": "Default error response.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Default error response.",
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "description": "Human-readable error message.",
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "4XX": {
            "description": "Default error response.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Default error response.",
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "description": "Human-readable error message.",
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://api.layer.team"
    }
  ],
  "x-readme": {
    "samples-languages": [
      "curl"
    ]
  }
}
```