List files

http
GET /projects/{project_reference}/files

List the files. Requires project.read.

Servers

json
[
  {
    "url": "https://api.veryfront.com"
  }
]

Authentication

json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyAuth": []
  }
]
json
{
  "bearerAuth": {
    "type": "http",
    "scheme": "bearer",
    "bearerFormat": "JWT or API Key",
    "description": "Use a JWT bearer token or a Veryfront API key in the `Authorization` header."
  },
  "apiKeyAuth": {
    "type": "apiKey",
    "in": "header",
    "name": "X-API-Key",
    "description": "Alternative API key header for `vf_<prefix>_<secret>` tokens."
  }
}

Parameters

NameLocationRequiredDescription
project_referencepathYesProject slug, UUID, or domain that identifies the project.
refqueryNo
branchqueryNo
branch_idqueryNo
patternqueryNoFile pattern filter (for example, *.tsx).
cursorqueryNoOpaque cursor pointing at the next page. Omit it to read the first page.
limitqueryNoFiles per page. At most 100 when the listing includes content, and at most 1000 when fields excludes content.
sort_byqueryNo
sort_orderqueryNo
fieldsqueryNo

Parameter contracts

json
[
  {
    "schema": {
      "$ref": "#/components/schemas/ProjectReference"
    },
    "required": true,
    "description": "Project slug, UUID, or domain that identifies the project.",
    "name": "project_reference",
    "in": "path"
  },
  {
    "schema": {
      "type": "string",
      "description": "Content to address: `main`, `branch:<name-or-id>`, `release:<version>` or `env:<name>`. Canonical replacement for `branch` and `branch_id`.",
      "example": "branch:feature-x"
    },
    "required": false,
    "name": "ref",
    "in": "query"
  },
  {
    "schema": {
      "type": "string",
      "description": "Branch name or ID. Legacy alias for `ref=branch:<value>`.",
      "example": "feature-x"
    },
    "required": false,
    "name": "branch",
    "in": "query"
  },
  {
    "schema": {
      "type": "string",
      "format": "uuid",
      "description": "Branch ID. Legacy alias for `ref=branch:<uuid>`."
    },
    "required": false,
    "name": "branch_id",
    "in": "query"
  },
  {
    "schema": {
      "type": "string",
      "maxLength": 1024,
      "description": "File pattern filter (for example, *.tsx)."
    },
    "required": false,
    "description": "File pattern filter (for example, *.tsx).",
    "name": "pattern",
    "in": "query"
  },
  {
    "schema": {
      "$ref": "#/components/schemas/PaginationCursor"
    },
    "required": false,
    "description": "Opaque cursor pointing at the next page. Omit it to read the first page.",
    "name": "cursor",
    "in": "query"
  },
  {
    "schema": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000,
      "default": 20,
      "description": "Files per page. At most 100 when the listing includes content, and at most 1000 when `fields` excludes content.",
      "example": 20
    },
    "required": false,
    "description": "Files per page. At most 100 when the listing includes content, and at most 1000 when `fields` excludes content.",
    "name": "limit",
    "in": "query"
  },
  {
    "schema": {
      "type": "string",
      "enum": [
        "path",
        "updated_at"
      ],
      "default": "updated_at",
      "description": "Sort by path or last update time (default updated_at)."
    },
    "required": false,
    "name": "sort_by",
    "in": "query"
  },
  {
    "schema": {
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ],
      "default": "desc",
      "description": "Sort order."
    },
    "required": false,
    "name": "sort_order",
    "in": "query"
  },
  {
    "schema": {
      "type": "string",
      "pattern": "^!?\\([^)]*\\)$",
      "description": "Response fields to include or exclude. Examples: `(id,name)`, `(id,files(path))`, and `!(content)`.",
      "example": "(id,path,type,size)"
    },
    "required": false,
    "name": "fields",
    "in": "query"
  }
]

Responses

200

Paginated list of files with selectable response fields.

json
{
  "description": "Paginated list of files with selectable response fields.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "version_id": {
                  "type": "string"
                },
                "path": {
                  "type": "string"
                },
                "content": {
                  "type": "string"
                },
                "size": {
                  "type": "number",
                  "description": "Size of the file content encoded as UTF-8, in bytes."
                },
                "type": {
                  "type": "string",
                  "enum": [
                    "page",
                    "function",
                    "component",
                    "file"
                  ]
                },
                "updated_at": {
                  "type": "string"
                },
                "binary": {
                  "type": "object",
                  "properties": {
                    "content_hash": {
                      "type": "string",
                      "pattern": "^[a-f0-9]{64}$"
                    },
                    "byte_size": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 8388608
                    },
                    "content_type": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 200,
                      "pattern": "^[\\x20-\\x7e]+$"
                    }
                  },
                  "required": [
                    "content_hash",
                    "byte_size",
                    "content_type"
                  ],
                  "additionalProperties": false
                },
                "checksum": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "size_bytes": {
                  "type": "number",
                  "description": "Size of the file content encoded as UTF-8, in bytes."
                },
                "_links": {
                  "type": "object",
                  "properties": {
                    "self": {
                      "type": "object",
                      "properties": {
                        "href": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "href"
                      ]
                    }
                  },
                  "required": [
                    "self"
                  ]
                }
              },
              "required": [
                "path",
                "content",
                "size",
                "type",
                "updated_at",
                "size_bytes"
              ]
            }
          },
          "page_info": {
            "$ref": "#/components/schemas/PageInfo"
          },
          "_links": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "href": {
                  "type": "string",
                  "description": "URL of the linked resource"
                },
                "method": {
                  "type": "string",
                  "description": "HTTP method for this link (default: GET)"
                },
                "title": {
                  "type": "string",
                  "description": "Human-readable description of the link"
                }
              },
              "required": [
                "href"
              ]
            },
            "description": "Hypermedia links for resource navigation"
          }
        },
        "required": [
          "data",
          "page_info",
          "_links"
        ]
      }
    }
  }
}

400

Bad request

json
{
  "description": "Bad request",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

401

Unauthorized

json
{
  "description": "Unauthorized",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

403

Forbidden - insufficient permissions

json
{
  "description": "Forbidden - insufficient permissions",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

404

Not found

json
{
  "description": "Not found",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

500

Server error

json
{
  "description": "Server error",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      }
    }
  }
}

Referenced contracts

components/parameters/ProjectReference

json
{
  "schema": {
    "$ref": "#/components/schemas/ProjectReference"
  },
  "required": true,
  "description": "Project slug, UUID, or domain that identifies the project.",
  "name": "project_reference",
  "in": "path"
}

components/schemas/ProjectReference

json
{
  "type": "string"
}

components/parameters/PaginationCursor

json
{
  "schema": {
    "$ref": "#/components/schemas/PaginationCursor"
  },
  "required": false,
  "description": "Opaque cursor pointing at the next page. Omit it to read the first page.",
  "name": "cursor",
  "in": "query"
}

components/schemas/PaginationCursor

json
{
  "type": "string",
  "description": "Opaque cursor pointing at the next page. Omit it to read the first page."
}

components/schemas/PageInfo

json
{
  "type": "object",
  "properties": {
    "self": {
      "type": [
        "string",
        "null"
      ],
      "description": "Cursor pointing to the current page"
    },
    "first": {
      "type": "null",
      "description": "First page cursor (always null for cursor-based pagination)"
    },
    "next": {
      "type": [
        "string",
        "null"
      ],
      "description": "Cursor for the next page (null if no more pages)"
    },
    "prev": {
      "type": [
        "string",
        "null"
      ],
      "description": "Cursor for the previous page (null if on first page)"
    }
  },
  "required": [
    "self",
    "first",
    "next",
    "prev"
  ]
}

components/schemas/Problem

json
{
  "type": "object",
  "properties": {
    "cause": {
      "type": "string",
      "enum": [
        "schedule_concurrency_forbidden",
        "schedule_fire_in_progress",
        "schedule_run_limit_reached"
      ],
      "description": "Schedule admission refusal."
    },
    "idempotency": {
      "type": "object",
      "properties": {
        "state": {
          "type": "string",
          "enum": [
            "in_progress",
            "payload_mismatch",
            "outcome_unknown"
          ]
        },
        "operation": {
          "type": "string",
          "minLength": 1
        },
        "retryable": {
          "type": "boolean"
        },
        "retry_after_seconds": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0
        },
        "expires_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "recovery": {
          "type": "object",
          "properties": {
            "available": {
              "type": "boolean"
            },
            "description": {
              "type": "string"
            },
            "resource_url": {
              "type": "string"
            }
          },
          "required": [
            "available",
            "description"
          ]
        }
      },
      "required": [
        "state",
        "operation",
        "retryable",
        "retry_after_seconds",
        "expires_at"
      ],
      "description": "Replay status, retry timing, and recovery lookup."
    },
    "type": {
      "type": "string",
      "description": "URI reference identifying the problem type",
      "example": "https://api.veryfront.com/errors/validation-failed"
    },
    "title": {
      "type": "string",
      "description": "Short human-readable summary of the problem",
      "example": "Validation Failed"
    },
    "status": {
      "type": "integer",
      "minimum": 100,
      "maximum": 599,
      "description": "HTTP status code",
      "example": 400
    },
    "code": {
      "type": "string",
      "description": "Stable machine-readable error code",
      "example": "RUN_INVALID_INPUT"
    },
    "detail": {
      "type": "string",
      "description": "Human-readable explanation specific to this occurrence",
      "example": "The 'email' field must be a valid email address"
    },
    "instance": {
      "type": "string",
      "description": "URI reference identifying the specific occurrence",
      "example": "/projects/my-project/members"
    },
    "slug": {
      "type": "string",
      "description": "Stable identifier for the problem type",
      "example": "validation-failed"
    },
    "category": {
      "type": "string",
      "enum": [
        "AUTH",
        "RESOURCE",
        "VALIDATION",
        "DATABASE",
        "SUBSCRIPTION",
        "INTEGRATION",
        "INTERNAL"
      ],
      "description": "API error category",
      "example": "VALIDATION"
    },
    "suggestion": {
      "type": "string",
      "description": "Suggested action to resolve the problem",
      "example": "Check the request body and query parameters against the API documentation."
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string",
            "description": "Field path that caused the error",
            "example": "email"
          },
          "message": {
            "type": "string",
            "description": "Error message for this field",
            "example": "Invalid email format"
          },
          "code": {
            "type": "string",
            "description": "Error code for this field",
            "example": "INVALID_FORMAT"
          }
        },
        "required": [
          "field",
          "message"
        ]
      },
      "description": "Detailed field-level errors for validation failures"
    }
  },
  "required": [
    "type",
    "title",
    "status"
  ]
}

Operation contract

json
{
  "operationId": "listFiles",
  "tags": [
    "projects/Files/Files"
  ],
  "summary": "List files",
  "description": "List the files. Requires project.read.",
  "parameters": [
    {
      "$ref": "#/components/parameters/ProjectReference"
    },
    {
      "schema": {
        "type": "string",
        "description": "Content to address: `main`, `branch:<name-or-id>`, `release:<version>` or `env:<name>`. Canonical replacement for `branch` and `branch_id`.",
        "example": "branch:feature-x"
      },
      "required": false,
      "name": "ref",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "description": "Branch name or ID. Legacy alias for `ref=branch:<value>`.",
        "example": "feature-x"
      },
      "required": false,
      "name": "branch",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "format": "uuid",
        "description": "Branch ID. Legacy alias for `ref=branch:<uuid>`."
      },
      "required": false,
      "name": "branch_id",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "maxLength": 1024,
        "description": "File pattern filter (for example, *.tsx)."
      },
      "required": false,
      "description": "File pattern filter (for example, *.tsx).",
      "name": "pattern",
      "in": "query"
    },
    {
      "$ref": "#/components/parameters/PaginationCursor"
    },
    {
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 1000,
        "default": 20,
        "description": "Files per page. At most 100 when the listing includes content, and at most 1000 when `fields` excludes content.",
        "example": 20
      },
      "required": false,
      "description": "Files per page. At most 100 when the listing includes content, and at most 1000 when `fields` excludes content.",
      "name": "limit",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "enum": [
          "path",
          "updated_at"
        ],
        "default": "updated_at",
        "description": "Sort by path or last update time (default updated_at)."
      },
      "required": false,
      "name": "sort_by",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "enum": [
          "asc",
          "desc"
        ],
        "default": "desc",
        "description": "Sort order."
      },
      "required": false,
      "name": "sort_order",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "pattern": "^!?\\([^)]*\\)$",
        "description": "Response fields to include or exclude. Examples: `(id,name)`, `(id,files(path))`, and `!(content)`.",
        "example": "(id,path,type,size)"
      },
      "required": false,
      "name": "fields",
      "in": "query"
    }
  ],
  "responses": {
    "200": {
      "description": "Paginated list of files with selectable response fields.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "version_id": {
                      "type": "string"
                    },
                    "path": {
                      "type": "string"
                    },
                    "content": {
                      "type": "string"
                    },
                    "size": {
                      "type": "number",
                      "description": "Size of the file content encoded as UTF-8, in bytes."
                    },
                    "type": {
                      "type": "string",
                      "enum": [
                        "page",
                        "function",
                        "component",
                        "file"
                      ]
                    },
                    "updated_at": {
                      "type": "string"
                    },
                    "binary": {
                      "type": "object",
                      "properties": {
                        "content_hash": {
                          "type": "string",
                          "pattern": "^[a-f0-9]{64}$"
                        },
                        "byte_size": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 8388608
                        },
                        "content_type": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "pattern": "^[\\x20-\\x7e]+$"
                        }
                      },
                      "required": [
                        "content_hash",
                        "byte_size",
                        "content_type"
                      ],
                      "additionalProperties": false
                    },
                    "checksum": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "size_bytes": {
                      "type": "number",
                      "description": "Size of the file content encoded as UTF-8, in bytes."
                    },
                    "_links": {
                      "type": "object",
                      "properties": {
                        "self": {
                          "type": "object",
                          "properties": {
                            "href": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "href"
                          ]
                        }
                      },
                      "required": [
                        "self"
                      ]
                    }
                  },
                  "required": [
                    "path",
                    "content",
                    "size",
                    "type",
                    "updated_at",
                    "size_bytes"
                  ]
                }
              },
              "page_info": {
                "$ref": "#/components/schemas/PageInfo"
              },
              "_links": {
                "type": "object",
                "additionalProperties": {
                  "type": "object",
                  "properties": {
                    "href": {
                      "type": "string",
                      "description": "URL of the linked resource"
                    },
                    "method": {
                      "type": "string",
                      "description": "HTTP method for this link (default: GET)"
                    },
                    "title": {
                      "type": "string",
                      "description": "Human-readable description of the link"
                    }
                  },
                  "required": [
                    "href"
                  ]
                },
                "description": "Hypermedia links for resource navigation"
              }
            },
            "required": [
              "data",
              "page_info",
              "_links"
            ]
          }
        }
      }
    },
    "400": {
      "description": "Bad request",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden - insufficient permissions",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "404": {
      "description": "Not found",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    },
    "500": {
      "description": "Server error",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    }
  },
  "x-documentation-source-tag": "Project Files",
  "x-canonical-documentation": {
    "domain": "projects",
    "resource": "Files",
    "subgroup": "Files",
    "name": "List files",
    "description": "List the files. Requires project.read.",
    "operationId": "listFiles"
  },
  "x-mint": {
    "href": "/cloud/rest/api-reference/projects-files-files/list-files"
  }
}