# File ## Create a file upload session `client.File.New(ctx, body) (*FileCreateResponse, error)` **post** `/v1/files` Creates a new file upload session and returns an upload URL. After uploading the file bytes to `uploadUrl`, call `POST /v1/files/{id}/complete` to finalize the upload. Optionally pass `purpose` to validate MIME type and size constraints at creation time. See [File uploads](/using-the-api/file-uploads/) for the full upload flow, supported purposes, and size limits. If you are uploading a meeting transcript, see [Uploading meeting transcripts](/using-the-api/uploading-meeting-transcripts/) for the follow-up meeting attachment flow. **[Required scope](/using-the-api/scopes/):** `files:create` **[Rate limit category](/using-the-api/rate-limits/):** Write ### Parameters - `body FileNewParams` - `Filename param.Field[string]` Original filename. - `MimeType param.Field[string]` MIME type of the file. Must be allowed for the given purpose (if specified). - `SizeBytes param.Field[int64]` Expected file size in bytes. Maximum 512 MB. - `Purpose param.Field[FileNewParamsPurpose]` Optional validation hint. When provided, the server enforces purpose-specific MIME type and file size constraints. Use `meeting_transcript` for files that will be attached to a meeting as its transcript. Use `knowledge_user` or `knowledge_workspace` to add the file to the authenticated user's or workspace's Knowledge, making it available to the AI assistant. Not persisted or returned in responses. - `const FileNewParamsPurposeMeetingTranscript FileNewParamsPurpose = "meeting_transcript"` - `const FileNewParamsPurposeKnowledgeUser FileNewParamsPurpose = "knowledge_user"` - `const FileNewParamsPurposeKnowledgeWorkspace FileNewParamsPurpose = "knowledge_workspace"` ### Returns - `type FileCreateResponse struct{…}` - `ID string` Unique identifier for the file. - `CompletedAt string` When the file upload was completed. - `CreatedAt string` When the file upload session was created. - `ExpiresAt string` When the upload session expires. Null once completed, cancelled, or expired. - `Filename string` Original filename. - `MimeType string` MIME type of the file. - `SizeBytes int64` File size in bytes. - `Status FileCreateResponseStatus` Current upload status of the file. - `const FileCreateResponseStatusPending FileCreateResponseStatus = "PENDING"` - `const FileCreateResponseStatusCompleted FileCreateResponseStatus = "COMPLETED"` - `const FileCreateResponseStatusCancelled FileCreateResponseStatus = "CANCELLED"` - `const FileCreateResponseStatusExpired FileCreateResponseStatus = "EXPIRED"` - `UploadHeaders map[string, string]` Headers to include in the upload request. - `UploadURL string` Upload URL. Upload the file bytes directly to this URL. ### Example ```go package main import ( "context" "fmt" "github.com/Lightfld/lightfield-go" "github.com/Lightfld/lightfield-go/option" ) func main() { client := githubcomlightfldlightfieldgo.NewClient( option.WithAPIKey("My API Key"), ) fileCreateResponse, err := client.File.New(context.TODO(), githubcomlightfldlightfieldgo.FileNewParams{ Filename: "x", MimeType: "mimeType", SizeBytes: 1, }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", fileCreateResponse.ID) } ``` #### Response ```json { "id": "id", "completedAt": "completedAt", "createdAt": "createdAt", "expiresAt": "expiresAt", "filename": "filename", "mimeType": "mimeType", "sizeBytes": -9007199254740991, "status": "PENDING", "uploadHeaders": { "foo": "string" }, "uploadUrl": "uploadUrl" } ``` ## Complete a file upload `client.File.Complete(ctx, id, body) (*FileCompleteResponse, error)` **post** `/v1/files/{id}/complete` Finalizes an upload after the file bytes have been uploaded. If an optional `md5` hex digest is provided, the server validates the checksum before marking the file as completed. **[Required scope](/using-the-api/scopes/):** `files:create` **[Rate limit category](/using-the-api/rate-limits/):** Write ### Parameters - `id string` Unique identifier of the file to complete. - `body FileCompleteParams` - `Md5 param.Field[string]` Optional MD5 hex digest of the uploaded file for checksum verification. ### Returns - `type FileCompleteResponse struct{…}` - `ID string` Unique identifier for the file. - `CompletedAt string` When the file upload was completed. - `CreatedAt string` When the file upload session was created. - `ExpiresAt string` When the upload session expires. Null once completed, cancelled, or expired. - `Filename string` Original filename. - `MimeType string` MIME type of the file. - `SizeBytes int64` File size in bytes. - `Status FileCompleteResponseStatus` Current upload status of the file. - `const FileCompleteResponseStatusPending FileCompleteResponseStatus = "PENDING"` - `const FileCompleteResponseStatusCompleted FileCompleteResponseStatus = "COMPLETED"` - `const FileCompleteResponseStatusCancelled FileCompleteResponseStatus = "CANCELLED"` - `const FileCompleteResponseStatusExpired FileCompleteResponseStatus = "EXPIRED"` ### Example ```go package main import ( "context" "fmt" "github.com/Lightfld/lightfield-go" "github.com/Lightfld/lightfield-go/option" ) func main() { client := githubcomlightfldlightfieldgo.NewClient( option.WithAPIKey("My API Key"), ) fileCompleteResponse, err := client.File.Complete( context.TODO(), "id", githubcomlightfldlightfieldgo.FileCompleteParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", fileCompleteResponse.ID) } ``` #### Response ```json { "id": "id", "completedAt": "completedAt", "createdAt": "createdAt", "expiresAt": "expiresAt", "filename": "filename", "mimeType": "mimeType", "sizeBytes": -9007199254740991, "status": "PENDING" } ``` ## Retrieve a file `client.File.Get(ctx, id) (*FileRetrieveResponse, error)` **get** `/v1/files/{id}` Retrieves a single file by its ID. **[Required scope](/using-the-api/scopes/):** `files:read` **[Rate limit category](/using-the-api/rate-limits/):** Read ### Parameters - `id string` Unique identifier of the file to retrieve. ### Returns - `type FileRetrieveResponse struct{…}` - `ID string` Unique identifier for the file. - `CompletedAt string` When the file upload was completed. - `CreatedAt string` When the file upload session was created. - `ExpiresAt string` When the upload session expires. Null once completed, cancelled, or expired. - `Filename string` Original filename. - `MimeType string` MIME type of the file. - `SizeBytes int64` File size in bytes. - `Status FileRetrieveResponseStatus` Current upload status of the file. - `const FileRetrieveResponseStatusPending FileRetrieveResponseStatus = "PENDING"` - `const FileRetrieveResponseStatusCompleted FileRetrieveResponseStatus = "COMPLETED"` - `const FileRetrieveResponseStatusCancelled FileRetrieveResponseStatus = "CANCELLED"` - `const FileRetrieveResponseStatusExpired FileRetrieveResponseStatus = "EXPIRED"` ### Example ```go package main import ( "context" "fmt" "github.com/Lightfld/lightfield-go" "github.com/Lightfld/lightfield-go/option" ) func main() { client := githubcomlightfldlightfieldgo.NewClient( option.WithAPIKey("My API Key"), ) fileRetrieveResponse, err := client.File.Get(context.TODO(), "id") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", fileRetrieveResponse.ID) } ``` #### Response ```json { "id": "id", "completedAt": "completedAt", "createdAt": "createdAt", "expiresAt": "expiresAt", "filename": "filename", "mimeType": "mimeType", "sizeBytes": -9007199254740991, "status": "PENDING" } ``` ## List files `client.File.List(ctx, query) (*FileListResponse, error)` **get** `/v1/files` Returns a paginated list of files in your workspace. Use `offset` and `limit` to paginate through results. See [List endpoints](/using-the-api/list-endpoints/) for more information about pagination. **[Required scope](/using-the-api/scopes/):** `files:read` **[Rate limit category](/using-the-api/rate-limits/):** Search ### Parameters - `query FileListParams` - `Limit param.Field[int64]` Maximum number of records to return. Defaults to 25, maximum 25. - `Offset param.Field[int64]` Number of records to skip for pagination. Defaults to 0. ### Returns - `type FileListResponse struct{…}` - `Data []FileListResponseData` Array of file objects for the current page. - `ID string` Unique identifier for the file. - `CompletedAt string` When the file upload was completed. - `CreatedAt string` When the file upload session was created. - `ExpiresAt string` When the upload session expires. Null once completed, cancelled, or expired. - `Filename string` Original filename. - `MimeType string` MIME type of the file. - `SizeBytes int64` File size in bytes. - `Status string` Current upload status of the file. - `const FileListResponseDataStatusPending FileListResponseDataStatus = "PENDING"` - `const FileListResponseDataStatusCompleted FileListResponseDataStatus = "COMPLETED"` - `const FileListResponseDataStatusCancelled FileListResponseDataStatus = "CANCELLED"` - `const FileListResponseDataStatusExpired FileListResponseDataStatus = "EXPIRED"` - `Object string` The object type, always `"list"`. - `TotalCount int64` Total number of matching files. ### Example ```go package main import ( "context" "fmt" "github.com/Lightfld/lightfield-go" "github.com/Lightfld/lightfield-go/option" ) func main() { client := githubcomlightfldlightfieldgo.NewClient( option.WithAPIKey("My API Key"), ) fileListResponse, err := client.File.List(context.TODO(), githubcomlightfldlightfieldgo.FileListParams{ }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", fileListResponse.Data) } ``` #### Response ```json { "data": [ { "id": "id", "completedAt": "completedAt", "createdAt": "createdAt", "expiresAt": "expiresAt", "filename": "filename", "mimeType": "mimeType", "sizeBytes": -9007199254740991, "status": "PENDING" } ], "object": "object", "totalCount": 0 } ``` ## Get a file download URL `client.File.URL(ctx, id) (*FileURLResponse, error)` **get** `/v1/files/{id}/url` Returns a temporary download URL for the file. Only available for files in `COMPLETED` status. **[Required scope](/using-the-api/scopes/):** `files:read` **[Rate limit category](/using-the-api/rate-limits/):** Read ### Parameters - `id string` Unique identifier of the file to download. ### Returns - `type FileURLResponse struct{…}` - `ExpiresAt string` When the download URL expires. - `URL string` Temporary download URL for the file. ### Example ```go package main import ( "context" "fmt" "github.com/Lightfld/lightfield-go" "github.com/Lightfld/lightfield-go/option" ) func main() { client := githubcomlightfldlightfieldgo.NewClient( option.WithAPIKey("My API Key"), ) fileURLResponse, err := client.File.URL(context.TODO(), "id") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", fileURLResponse.ExpiresAt) } ``` #### Response ```json { "expiresAt": "expiresAt", "url": "url" } ``` ## Cancel a file upload `client.File.Cancel(ctx, id, body) (*FileCancelResponse, error)` **post** `/v1/files/{id}/cancel` Cancels a pending upload by transitioning the file to `CANCELLED`. Only files in `PENDING` status can be cancelled. **[Required scope](/using-the-api/scopes/):** `files:create` **[Rate limit category](/using-the-api/rate-limits/):** Write ### Parameters - `id string` Unique identifier of the file to cancel. - `body FileCancelParams` - `Body param.Field[FileCancelParamsBody]` ### Returns - `type FileCancelResponse struct{…}` - `ID string` Unique identifier for the file. - `CompletedAt string` When the file upload was completed. - `CreatedAt string` When the file upload session was created. - `ExpiresAt string` When the upload session expires. Null once completed, cancelled, or expired. - `Filename string` Original filename. - `MimeType string` MIME type of the file. - `SizeBytes int64` File size in bytes. - `Status FileCancelResponseStatus` Current upload status of the file. - `const FileCancelResponseStatusPending FileCancelResponseStatus = "PENDING"` - `const FileCancelResponseStatusCompleted FileCancelResponseStatus = "COMPLETED"` - `const FileCancelResponseStatusCancelled FileCancelResponseStatus = "CANCELLED"` - `const FileCancelResponseStatusExpired FileCancelResponseStatus = "EXPIRED"` ### Example ```go package main import ( "context" "fmt" "github.com/Lightfld/lightfield-go" "github.com/Lightfld/lightfield-go/option" ) func main() { client := githubcomlightfldlightfieldgo.NewClient( option.WithAPIKey("My API Key"), ) fileCancelResponse, err := client.File.Cancel( context.TODO(), "id", githubcomlightfldlightfieldgo.FileCancelParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", fileCancelResponse.ID) } ``` #### Response ```json { "id": "id", "completedAt": "completedAt", "createdAt": "createdAt", "expiresAt": "expiresAt", "filename": "filename", "mimeType": "mimeType", "sizeBytes": -9007199254740991, "status": "PENDING" } ``` ## Domain Types ### File Cancel Response - `type FileCancelResponse struct{…}` - `ID string` Unique identifier for the file. - `CompletedAt string` When the file upload was completed. - `CreatedAt string` When the file upload session was created. - `ExpiresAt string` When the upload session expires. Null once completed, cancelled, or expired. - `Filename string` Original filename. - `MimeType string` MIME type of the file. - `SizeBytes int64` File size in bytes. - `Status FileCancelResponseStatus` Current upload status of the file. - `const FileCancelResponseStatusPending FileCancelResponseStatus = "PENDING"` - `const FileCancelResponseStatusCompleted FileCancelResponseStatus = "COMPLETED"` - `const FileCancelResponseStatusCancelled FileCancelResponseStatus = "CANCELLED"` - `const FileCancelResponseStatusExpired FileCancelResponseStatus = "EXPIRED"` ### File Complete Response - `type FileCompleteResponse struct{…}` - `ID string` Unique identifier for the file. - `CompletedAt string` When the file upload was completed. - `CreatedAt string` When the file upload session was created. - `ExpiresAt string` When the upload session expires. Null once completed, cancelled, or expired. - `Filename string` Original filename. - `MimeType string` MIME type of the file. - `SizeBytes int64` File size in bytes. - `Status FileCompleteResponseStatus` Current upload status of the file. - `const FileCompleteResponseStatusPending FileCompleteResponseStatus = "PENDING"` - `const FileCompleteResponseStatusCompleted FileCompleteResponseStatus = "COMPLETED"` - `const FileCompleteResponseStatusCancelled FileCompleteResponseStatus = "CANCELLED"` - `const FileCompleteResponseStatusExpired FileCompleteResponseStatus = "EXPIRED"` ### File Create Response - `type FileCreateResponse struct{…}` - `ID string` Unique identifier for the file. - `CompletedAt string` When the file upload was completed. - `CreatedAt string` When the file upload session was created. - `ExpiresAt string` When the upload session expires. Null once completed, cancelled, or expired. - `Filename string` Original filename. - `MimeType string` MIME type of the file. - `SizeBytes int64` File size in bytes. - `Status FileCreateResponseStatus` Current upload status of the file. - `const FileCreateResponseStatusPending FileCreateResponseStatus = "PENDING"` - `const FileCreateResponseStatusCompleted FileCreateResponseStatus = "COMPLETED"` - `const FileCreateResponseStatusCancelled FileCreateResponseStatus = "CANCELLED"` - `const FileCreateResponseStatusExpired FileCreateResponseStatus = "EXPIRED"` - `UploadHeaders map[string, string]` Headers to include in the upload request. - `UploadURL string` Upload URL. Upload the file bytes directly to this URL. ### File List Response - `type FileListResponse struct{…}` - `Data []FileListResponseData` Array of file objects for the current page. - `ID string` Unique identifier for the file. - `CompletedAt string` When the file upload was completed. - `CreatedAt string` When the file upload session was created. - `ExpiresAt string` When the upload session expires. Null once completed, cancelled, or expired. - `Filename string` Original filename. - `MimeType string` MIME type of the file. - `SizeBytes int64` File size in bytes. - `Status string` Current upload status of the file. - `const FileListResponseDataStatusPending FileListResponseDataStatus = "PENDING"` - `const FileListResponseDataStatusCompleted FileListResponseDataStatus = "COMPLETED"` - `const FileListResponseDataStatusCancelled FileListResponseDataStatus = "CANCELLED"` - `const FileListResponseDataStatusExpired FileListResponseDataStatus = "EXPIRED"` - `Object string` The object type, always `"list"`. - `TotalCount int64` Total number of matching files. ### File Retrieve Response - `type FileRetrieveResponse struct{…}` - `ID string` Unique identifier for the file. - `CompletedAt string` When the file upload was completed. - `CreatedAt string` When the file upload session was created. - `ExpiresAt string` When the upload session expires. Null once completed, cancelled, or expired. - `Filename string` Original filename. - `MimeType string` MIME type of the file. - `SizeBytes int64` File size in bytes. - `Status FileRetrieveResponseStatus` Current upload status of the file. - `const FileRetrieveResponseStatusPending FileRetrieveResponseStatus = "PENDING"` - `const FileRetrieveResponseStatusCompleted FileRetrieveResponseStatus = "COMPLETED"` - `const FileRetrieveResponseStatusCancelled FileRetrieveResponseStatus = "CANCELLED"` - `const FileRetrieveResponseStatusExpired FileRetrieveResponseStatus = "EXPIRED"` ### File URL Response - `type FileURLResponse struct{…}` - `ExpiresAt string` When the download URL expires. - `URL string` Temporary download URL for the file.