> For the complete documentation index, see [llms.txt](https://docs.kognitos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kognitos.com/guides/api-reference/files.md).

# Files

Upload, download, and manage files.

## Upload File

> Upload a file scoped to a specific workspace. The file's lifetime is tied\
> to the organization. This is the preferred endpoint for new file uploads.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Files","description":"Upload, download, and manage files."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1UploadFileResponse":{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/v1FileMetadata"}},"title":"Response after uploading a file\nFor HTTP/REST: Returns JSON with metadata\nHTTP Status: 201 Created with Location header pointing to the created resource"},"v1FileMetadata":{"type":"object","properties":{"name":{"type":"string","title":"The resource name of the file (server-generated)","readOnly":true},"filename":{"type":"string","title":"Filename of the file (e.g., \"document.pdf\")"},"mime_type":{"type":"string","title":"MIME type of the file (server-detected for security)","readOnly":true},"size_bytes":{"type":"string","format":"int64","title":"Size of the file in bytes (server-calculated)","readOnly":true},"create_time":{"type":"string","format":"date-time","title":"Timestamp when the file was created","readOnly":true},"sha256_hash":{"type":"string","description":"SHA-256 hash of the file content, lowercase hex-encoded (64 chars).\nComputed by the server at upload time over the raw bytes.\nFollows the Cloud Storage `md5_hash` / `crc32c` naming pattern\n(see https://cloud.google.com/storage/docs/hashes-etags).","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the file's content was last replaced.\nUnset if the content has never been replaced.","readOnly":true}},"title":"File metadata resource in the Bishop system","required":["filename"]},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"apiHttpBody":{"type":"object","properties":{"content_type":{"type":"string","description":"The HTTP Content-Type header value specifying the content type of the body."},"data":{"type":"string","format":"byte","description":"The HTTP request/response body as raw binary."},"extensions":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"},"description":"Application specific response metadata. Must be set in the first response\nfor streaming APIs."}},"description":"Message that represents an arbitrary HTTP body. It should only be used for\npayload formats that can't be represented as JSON, such as raw binary or\nan HTML page.\n\n\nThis message can be used both in streaming and non-streaming API methods in\nthe request as well as the response.\n\nIt can be used as a top-level request field, which is convenient if one\nwants to extract parameters from either the URL or HTTP template into the\nrequest fields and also want access to the raw HTTP body.\n\nExample:\n\n    message GetResourceRequest {\n      // A unique request id.\n      string request_id = 1;\n\n      // The raw HTTP body is bound to this field.\n      google.api.HttpBody http_body = 2;\n\n    }\n\n    service ResourceService {\n      rpc GetResource(GetResourceRequest)\n        returns (google.api.HttpBody);\n      rpc UpdateResource(google.api.HttpBody)\n        returns (google.protobuf.Empty);\n\n    }\n\nExample with streaming methods:\n\n    service CaldavService {\n      rpc GetCalendar(stream google.api.HttpBody)\n        returns (stream google.api.HttpBody);\n      rpc UpdateCalendar(stream google.api.HttpBody)\n        returns (stream google.api.HttpBody);\n\n    }\n\nUse of this type only changes how the request and response bodies are\nhandled, all other features will continue to work unchanged."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/files:upload":{"post":{"summary":"Upload File","description":"Upload a file scoped to a specific workspace. The file's lifetime is tied\nto the organization. This is the preferred endpoint for new file uploads.","operationId":"UploadFile","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1UploadFileResponse"}}}},"201":{"description":"File uploaded successfully","headers":{"Location":{"description":"URL of the created file resource","schema":{"type":"string"}}},"content":{"application/json":{"schema":{}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/apiHttpBody"}}},"description":"Raw HTTP body containing multipart/form-data","required":true},"tags":["Files"]}}}}
```

## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/files/{file}:download

> Download File

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Files","description":"Upload, download, and manage files."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/files/{file}:download":{"get":{"summary":"Download File","operationId":"DownloadFile","responses":{"200":{"description":"File content","headers":{"Content-Disposition":{"description":"Attachment with filename","schema":{"type":"string"}},"Content-Length":{"description":"File size in bytes","schema":{"type":"string"}},"Content-Type":{"description":"MIME type of the file","schema":{"type":"string"}}},"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"default":{"description":"An unexpected error response.","content":{"application/octet-stream":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"file","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Files"]}}}}
```

## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/files/{file}/metadata

> Get File Metadata

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Files","description":"Upload, download, and manage files."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1FileMetadata":{"type":"object","properties":{"name":{"type":"string","title":"The resource name of the file (server-generated)","readOnly":true},"filename":{"type":"string","title":"Filename of the file (e.g., \"document.pdf\")"},"mime_type":{"type":"string","title":"MIME type of the file (server-detected for security)","readOnly":true},"size_bytes":{"type":"string","format":"int64","title":"Size of the file in bytes (server-calculated)","readOnly":true},"create_time":{"type":"string","format":"date-time","title":"Timestamp when the file was created","readOnly":true},"sha256_hash":{"type":"string","description":"SHA-256 hash of the file content, lowercase hex-encoded (64 chars).\nComputed by the server at upload time over the raw bytes.\nFollows the Cloud Storage `md5_hash` / `crc32c` naming pattern\n(see https://cloud.google.com/storage/docs/hashes-etags).","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the file's content was last replaced.\nUnset if the content has never been replaced.","readOnly":true}},"title":"File metadata resource in the Bishop system","required":["filename"]},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/files/{file}/metadata":{"get":{"summary":"Get File Metadata","operationId":"GetFileMetadata","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1FileMetadata"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"file","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Files"]}}}}
```

## DELETE /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/files/{file}

> Delete File

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Files","description":"Upload, download, and manage files."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/files/{file}":{"delete":{"summary":"Delete File","operationId":"DeleteFile","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"file","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Files"]}}}}
```

## POST /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/files:generateUploadUrl

> Generate Upload Url

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Files","description":"Upload, download, and manage files."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1GenerateUploadUrlResponse":{"type":"object","properties":{"upload_uri":{"type":"string","title":"Presigned upload URI"}},"title":"Response with presigned upload URL"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"GenerateUploadUrlBody":{"type":"object","properties":{"expire_duration":{"type":"string","title":"Optional expiration duration"}},"description":"If no expiration duration is provided, the default is 1 hour.","title":"Request to generate presigned upload URL"}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/files:generateUploadUrl":{"post":{"summary":"Generate Upload Url","operationId":"GenerateUploadUrl","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1GenerateUploadUrlResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateUploadUrlBody"}}},"required":true},"tags":["Files"]}}}}
```

## POST /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/files/{file}:generateDownloadUrl

> Generate Download Url

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Files","description":"Upload, download, and manage files."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1GenerateDownloadUrlResponse":{"type":"object","properties":{"download_uri":{"type":"string","title":"Presigned download URI"}},"title":"Response with presigned download URL"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"GenerateDownloadUrlBody":{"type":"object","properties":{"expire_duration":{"type":"string","title":"Optional expiration duration"},"format":{"$ref":"#/components/schemas/v1DownloadFormat"}},"description":"If no expiration duration is provided, the default is 1 hour.","title":"Request to generate presigned download URL"},"v1DownloadFormat":{"type":"string","enum":["DOWNLOAD_FORMAT_UNSPECIFIED","DOWNLOAD_FORMAT_ARROW","DOWNLOAD_FORMAT_CSV","DOWNLOAD_FORMAT_JSON","DOWNLOAD_FORMAT_TXT"],"default":"DOWNLOAD_FORMAT_UNSPECIFIED","description":"Download format for file content.\nSpecifies the desired serialization format when downloading file content.\n\n - DOWNLOAD_FORMAT_UNSPECIFIED: Unspecified format; server will apply default behavior (Arrow).\n - DOWNLOAD_FORMAT_ARROW: Apache Arrow IPC format.\n - DOWNLOAD_FORMAT_CSV: Comma-separated values format.\n - DOWNLOAD_FORMAT_JSON: JSON format.\n - DOWNLOAD_FORMAT_TXT: Plain text format."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/files/{file}:generateDownloadUrl":{"post":{"summary":"Generate Download Url","operationId":"GenerateDownloadUrl","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1GenerateDownloadUrlResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"file","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateDownloadUrlBody"}}},"required":true},"tags":["Files"]}}}}
```

## Delete File

> Delete file

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Files","description":"Upload, download, and manage files."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/files/{file}":{"delete":{"summary":"Delete File","description":"Delete file","operationId":"DeleteOrganizationFile","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"file","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Files"]}}}}
```

## Get File Metadata

> Get file metadata only

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Files","description":"Upload, download, and manage files."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1FileMetadata":{"type":"object","properties":{"name":{"type":"string","title":"The resource name of the file (server-generated)","readOnly":true},"filename":{"type":"string","title":"Filename of the file (e.g., \"document.pdf\")"},"mime_type":{"type":"string","title":"MIME type of the file (server-detected for security)","readOnly":true},"size_bytes":{"type":"string","format":"int64","title":"Size of the file in bytes (server-calculated)","readOnly":true},"create_time":{"type":"string","format":"date-time","title":"Timestamp when the file was created","readOnly":true},"sha256_hash":{"type":"string","description":"SHA-256 hash of the file content, lowercase hex-encoded (64 chars).\nComputed by the server at upload time over the raw bytes.\nFollows the Cloud Storage `md5_hash` / `crc32c` naming pattern\n(see https://cloud.google.com/storage/docs/hashes-etags).","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the file's content was last replaced.\nUnset if the content has never been replaced.","readOnly":true}},"title":"File metadata resource in the Bishop system","required":["filename"]},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/files/{file}/metadata":{"get":{"summary":"Get File Metadata","description":"Get file metadata only","operationId":"GetOrganizationFileMetadata","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1FileMetadata"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"file","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Files"]}}}}
```

## Download File

> Download file content\
> Direct REST Implementation:\
> \- Binary response with metadata in HTTP headers

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Files","description":"Upload, download, and manage files."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/files/{file}:download":{"get":{"summary":"Download File","description":"Download file content\nDirect REST Implementation:\n- Binary response with metadata in HTTP headers","operationId":"DownloadOrganizationFile","responses":{"200":{"description":"File content","headers":{"Content-Disposition":{"description":"Attachment with filename","schema":{"type":"string"}},"Content-Length":{"description":"File size in bytes","schema":{"type":"string"}},"Content-Type":{"description":"MIME type of the file","schema":{"type":"string"}}},"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"default":{"description":"An unexpected error response.","content":{"application/octet-stream":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"file","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Files"]}}}}
```

## Generate Download Url

> Generate presigned URL for direct download

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Files","description":"Upload, download, and manage files."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1GenerateDownloadUrlResponse":{"type":"object","properties":{"download_uri":{"type":"string","title":"Presigned download URI"}},"title":"Response with presigned download URL"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"FilesServiceGenerateDownloadUrlBody":{"type":"object","properties":{"expire_duration":{"type":"string","title":"Optional expiration duration"},"format":{"$ref":"#/components/schemas/v1DownloadFormat"}},"description":"If no expiration duration is provided, the default is 1 hour.","title":"Request to generate presigned download URL"},"v1DownloadFormat":{"type":"string","enum":["DOWNLOAD_FORMAT_UNSPECIFIED","DOWNLOAD_FORMAT_ARROW","DOWNLOAD_FORMAT_CSV","DOWNLOAD_FORMAT_JSON","DOWNLOAD_FORMAT_TXT"],"default":"DOWNLOAD_FORMAT_UNSPECIFIED","description":"Download format for file content.\nSpecifies the desired serialization format when downloading file content.\n\n - DOWNLOAD_FORMAT_UNSPECIFIED: Unspecified format; server will apply default behavior (Arrow).\n - DOWNLOAD_FORMAT_ARROW: Apache Arrow IPC format.\n - DOWNLOAD_FORMAT_CSV: Comma-separated values format.\n - DOWNLOAD_FORMAT_JSON: JSON format.\n - DOWNLOAD_FORMAT_TXT: Plain text format."}}},"paths":{"/api/v1/organizations/{organization_id}/files/{file}:generateDownloadUrl":{"post":{"summary":"Generate Download Url","description":"Generate presigned URL for direct download","operationId":"GenerateOrganizationDownloadUrl","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1GenerateDownloadUrlResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"file","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilesServiceGenerateDownloadUrlBody"}}},"required":true},"tags":["Files"]}}}}
```

## Generate Upload Url

> Generate presigned URL for direct upload

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Files","description":"Upload, download, and manage files."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1GenerateUploadUrlResponse":{"type":"object","properties":{"upload_uri":{"type":"string","title":"Presigned upload URI"}},"title":"Response with presigned upload URL"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"FilesServiceGenerateUploadUrlBody":{"type":"object","properties":{"expire_duration":{"type":"string","title":"Optional expiration duration"}},"description":"If no expiration duration is provided, the default is 1 hour.","title":"Request to generate presigned upload URL"}}},"paths":{"/api/v1/organizations/{organization_id}/files:generateUploadUrl":{"post":{"summary":"Generate Upload Url","description":"Generate presigned URL for direct upload","operationId":"GenerateOrganizationUploadUrl","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1GenerateUploadUrlResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilesServiceGenerateUploadUrlBody"}}},"required":true},"tags":["Files"]}}}}
```

## Upload File

> Upload file content\
> Direct REST Implementation:\
> \- multipart/form-data with filename and file fields\
> \- Returns complete FileMetadata with server-generated fields\
> \
> The lifetime of the file is the lifetime of the organization, ie,\
> if the organization is deleted, its file will also be deleted.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Files","description":"Upload, download, and manage files."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1UploadFileResponse":{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/v1FileMetadata"}},"title":"Response after uploading a file\nFor HTTP/REST: Returns JSON with metadata\nHTTP Status: 201 Created with Location header pointing to the created resource"},"v1FileMetadata":{"type":"object","properties":{"name":{"type":"string","title":"The resource name of the file (server-generated)","readOnly":true},"filename":{"type":"string","title":"Filename of the file (e.g., \"document.pdf\")"},"mime_type":{"type":"string","title":"MIME type of the file (server-detected for security)","readOnly":true},"size_bytes":{"type":"string","format":"int64","title":"Size of the file in bytes (server-calculated)","readOnly":true},"create_time":{"type":"string","format":"date-time","title":"Timestamp when the file was created","readOnly":true},"sha256_hash":{"type":"string","description":"SHA-256 hash of the file content, lowercase hex-encoded (64 chars).\nComputed by the server at upload time over the raw bytes.\nFollows the Cloud Storage `md5_hash` / `crc32c` naming pattern\n(see https://cloud.google.com/storage/docs/hashes-etags).","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the file's content was last replaced.\nUnset if the content has never been replaced.","readOnly":true}},"title":"File metadata resource in the Bishop system","required":["filename"]},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"apiHttpBody":{"type":"object","properties":{"content_type":{"type":"string","description":"The HTTP Content-Type header value specifying the content type of the body."},"data":{"type":"string","format":"byte","description":"The HTTP request/response body as raw binary."},"extensions":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"},"description":"Application specific response metadata. Must be set in the first response\nfor streaming APIs."}},"description":"Message that represents an arbitrary HTTP body. It should only be used for\npayload formats that can't be represented as JSON, such as raw binary or\nan HTML page.\n\n\nThis message can be used both in streaming and non-streaming API methods in\nthe request as well as the response.\n\nIt can be used as a top-level request field, which is convenient if one\nwants to extract parameters from either the URL or HTTP template into the\nrequest fields and also want access to the raw HTTP body.\n\nExample:\n\n    message GetResourceRequest {\n      // A unique request id.\n      string request_id = 1;\n\n      // The raw HTTP body is bound to this field.\n      google.api.HttpBody http_body = 2;\n\n    }\n\n    service ResourceService {\n      rpc GetResource(GetResourceRequest)\n        returns (google.api.HttpBody);\n      rpc UpdateResource(google.api.HttpBody)\n        returns (google.protobuf.Empty);\n\n    }\n\nExample with streaming methods:\n\n    service CaldavService {\n      rpc GetCalendar(stream google.api.HttpBody)\n        returns (stream google.api.HttpBody);\n      rpc UpdateCalendar(stream google.api.HttpBody)\n        returns (stream google.api.HttpBody);\n\n    }\n\nUse of this type only changes how the request and response bodies are\nhandled, all other features will continue to work unchanged."}}},"paths":{"/api/v1/organizations/{organization_id}/files:upload":{"post":{"summary":"Upload File","description":"Upload file content\nDirect REST Implementation:\n- multipart/form-data with filename and file fields\n- Returns complete FileMetadata with server-generated fields\n\nThe lifetime of the file is the lifetime of the organization, ie,\nif the organization is deleted, its file will also be deleted.","operationId":"UploadOrganizationFile","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1UploadFileResponse"}}}},"201":{"description":"File uploaded successfully","headers":{"Location":{"description":"URL of the created file resource","schema":{"type":"string"}}},"content":{"application/json":{"schema":{}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/apiHttpBody"}}},"description":"Raw HTTP body containing multipart/form-data","required":true},"tags":["Files"]}}}}
```

## Paginate Value Content

> Paginate content from an offloaded value file.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Files","description":"Upload, download, and manage files."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1PaginateValueContentResponse":{"type":"object","properties":{"chunk":{"$ref":"#/components/schemas/commonv1Value"},"next_page_token":{"type":"string","description":"Opaque token for fetching the next page.\nEmpty means there are no additional pages.","readOnly":true},"start_index":{"type":"string","format":"int64","description":"Zero-based start index (or row offset for tables) represented by this chunk.","readOnly":true}},"description":"Response containing a paginated chunk of an offloaded value."},"commonv1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n   day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n   day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n   day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"},"text_value":{"$ref":"#/components/schemas/v1TextValue"},"list_value":{"$ref":"#/components/schemas/commonv1ListValue"},"set_value":{"$ref":"#/components/schemas/v1SetValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"text_value":{"$ref":"#/components/schemas/v1TextValue"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1TextValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote text content via URL or file path"},"inline":{"type":"string","title":"Text content embedded directly in the message"}},"description":"Represents a text value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling text strings in the Jarvis interpreter:\n- Small strings can be embedded directly using the inline option\n- Large strings can be referenced by URL using the remote option\n- The choice depends on string size, network constraints, and access patterns"},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1File"}},"description":"Represents a file value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling files in the Jarvis interpreter:\n- Small files can be embedded directly using the inline option\n- Large files can be referenced by URL/path using the remote option\n- The choice depends on file size, network constraints, and access patterns"},"v1File":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"name":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"Represents a file with its name and binary content.\n\nThis message contains the complete file data including both metadata\n(filename) and the actual file content as raw bytes. It's used for\nembedding files directly within messages when the file size is\nmanageable and immediate access is required.\n\nExamples:\n - Configuration files\n - Small text or binary files\n - Generated reports or documents\n - Temporary files created during execution\n"},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote table via URL or file path (feather-v2 format)"},"inline":{"$ref":"#/components/schemas/v1Table"}},"description":"Represents a table value that can be either stored inline or referenced remotely."},"v1Table":{"type":"object","properties":{"data":{"type":"string","format":"byte","title":"The table data serialized in feather-v2 format"}},"description":"Represents a table with data in feather-v2 format.\n\nThis message contains the complete table data serialized using the\nfeather-v2 format, which provides efficient columnar storage and\nfast serialization/deserialization for tabular data."},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"commonv1ListValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote list data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1List"}},"description":"Represents a list value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large lists:\n- Small lists can be embedded directly using the inline option\n- Large lists can be referenced by URL using the remote option"},"v1SetValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote set data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a set value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large sets:\n- Small sets can be embedded directly using the inline option\n- Large sets can be referenced by URL using the remote option"},"v1DictionaryValue":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to remote dictionary data via URL or file path"},"inline":{"$ref":"#/components/schemas/v1Dictionary"}},"description":"Represents a dictionary value that can be either stored inline or referenced remotely.\n\nThis message provides flexibility for handling large dictionaries:\n- Small dictionaries can be embedded directly using the inline option\n- Large dictionaries can be referenced by URL using the remote option"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/files/{file}:paginateValueContent":{"get":{"summary":"Paginate Value Content","description":"Paginate content from an offloaded value file.","operationId":"PaginateValueContent","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1PaginateValueContentResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"file","in":"path","required":true,"schema":{"type":"string"}},{"name":"value_kind","description":"Value type used to deserialize payload bytes.\n\n - VALUE_KIND_UNSPECIFIED: Default unspecified value kind.\n - VALUE_KIND_TEXT: UTF-8 text payload.\n - VALUE_KIND_LIST: Serialized list payload.\n - VALUE_KIND_DICTIONARY: Serialized dictionary payload.\n - VALUE_KIND_TABLE: Arrow table payload.\n - VALUE_KIND_SET: Offloaded set of hashable values.","in":"query","required":true,"schema":{"type":"string","enum":["VALUE_KIND_UNSPECIFIED","VALUE_KIND_TEXT","VALUE_KIND_LIST","VALUE_KIND_DICTIONARY","VALUE_KIND_TABLE","VALUE_KIND_SET"],"default":"VALUE_KIND_UNSPECIFIED"}},{"name":"page_size","description":"Maximum number of elements/rows/chars to return in this page.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"Opaque token for fetching the next page.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Files"]}}}}
```

## Replace File Content

> Replace an existing file's content, preserving its identity.\
> The resource name and create\_time are unchanged, so existing references\
> to the file stay valid.\
> Direct REST Implementation:\
> \- multipart/form-data with a single content field\
> \- Returns the updated FileMetadata

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Files","description":"Upload, download, and manage files."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ReplaceFileContentResponse":{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/v1FileMetadata"}},"title":"Response after replacing a file's content\nFor HTTP/REST: Returns JSON with metadata\nHTTP Status: 200 OK"},"v1FileMetadata":{"type":"object","properties":{"name":{"type":"string","title":"The resource name of the file (server-generated)","readOnly":true},"filename":{"type":"string","title":"Filename of the file (e.g., \"document.pdf\")"},"mime_type":{"type":"string","title":"MIME type of the file (server-detected for security)","readOnly":true},"size_bytes":{"type":"string","format":"int64","title":"Size of the file in bytes (server-calculated)","readOnly":true},"create_time":{"type":"string","format":"date-time","title":"Timestamp when the file was created","readOnly":true},"sha256_hash":{"type":"string","description":"SHA-256 hash of the file content, lowercase hex-encoded (64 chars).\nComputed by the server at upload time over the raw bytes.\nFollows the Cloud Storage `md5_hash` / `crc32c` naming pattern\n(see https://cloud.google.com/storage/docs/hashes-etags).","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the file's content was last replaced.\nUnset if the content has never been replaced.","readOnly":true}},"title":"File metadata resource in the Bishop system","required":["filename"]},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"apiHttpBody":{"type":"object","properties":{"content_type":{"type":"string","description":"The HTTP Content-Type header value specifying the content type of the body."},"data":{"type":"string","format":"byte","description":"The HTTP request/response body as raw binary."},"extensions":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"},"description":"Application specific response metadata. Must be set in the first response\nfor streaming APIs."}},"description":"Message that represents an arbitrary HTTP body. It should only be used for\npayload formats that can't be represented as JSON, such as raw binary or\nan HTML page.\n\n\nThis message can be used both in streaming and non-streaming API methods in\nthe request as well as the response.\n\nIt can be used as a top-level request field, which is convenient if one\nwants to extract parameters from either the URL or HTTP template into the\nrequest fields and also want access to the raw HTTP body.\n\nExample:\n\n    message GetResourceRequest {\n      // A unique request id.\n      string request_id = 1;\n\n      // The raw HTTP body is bound to this field.\n      google.api.HttpBody http_body = 2;\n\n    }\n\n    service ResourceService {\n      rpc GetResource(GetResourceRequest)\n        returns (google.api.HttpBody);\n      rpc UpdateResource(google.api.HttpBody)\n        returns (google.protobuf.Empty);\n\n    }\n\nExample with streaming methods:\n\n    service CaldavService {\n      rpc GetCalendar(stream google.api.HttpBody)\n        returns (stream google.api.HttpBody);\n      rpc UpdateCalendar(stream google.api.HttpBody)\n        returns (stream google.api.HttpBody);\n\n    }\n\nUse of this type only changes how the request and response bodies are\nhandled, all other features will continue to work unchanged."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/files/{file}:replaceContent":{"post":{"summary":"Replace File Content","description":"Replace an existing file's content, preserving its identity.\nThe resource name and create_time are unchanged, so existing references\nto the file stay valid.\nDirect REST Implementation:\n- multipart/form-data with a single content field\n- Returns the updated FileMetadata","operationId":"ReplaceFileContent","responses":{"200":{"description":"File content replaced successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ReplaceFileContentResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"file","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/apiHttpBody"}}},"description":"Raw HTTP body containing multipart/form-data with a single `content` field.\nThe file keeps its original filename.","required":true},"tags":["Files"]}}}}
```
