|
| 1 | +syntax = "proto3"; |
| 2 | + |
| 3 | +package xai_api; |
| 4 | + |
| 5 | +import "google/protobuf/timestamp.proto"; |
| 6 | + |
| 7 | +// Service for uploading, listing, retrieving, and deleting files. |
| 8 | +// |
| 9 | +// Files are referenced by the `id` returned on upload (e.g. when attaching |
| 10 | +// to chat completions). Maximum file size is 512 MB. |
| 11 | +service Files { |
| 12 | + // Upload a file. The first stream message MUST set `chunk = init` |
| 13 | + // (filename + optional TTL); subsequent messages MUST set `chunk = data` |
| 14 | + // with file bytes in order. Recommended chunk size up to 5 MB; total |
| 15 | + // size capped at 512 MB. Returns the new file's metadata. |
| 16 | + // |
| 17 | + // Errors: INVALID_ARGUMENT (missing/misplaced init, bad filename, bad |
| 18 | + // TTL), RESOURCE_EXHAUSTED (over 512 MB). |
| 19 | + rpc UploadFile(stream UploadFileChunk) returns (File) {} |
| 20 | + |
| 21 | + // List file metadata, paginated and sorted. Returns metadata only — use |
| 22 | + // `RetrieveFileContent` to download bytes. |
| 23 | + rpc ListFiles(ListFilesRequest) returns (ListFilesResponse) {} |
| 24 | + |
| 25 | + // Get metadata for one file. Returns metadata only — use |
| 26 | + // `RetrieveFileContent` to download bytes. Errors NOT_FOUND if no |
| 27 | + // accessible file with that id (including already-deleted). |
| 28 | + rpc RetrieveFile(RetrieveFileRequest) returns (File) {} |
| 29 | + |
| 30 | + // Delete a file. After success it stops appearing in `ListFiles` / |
| 31 | + // `RetrieveFile` and is no longer downloadable. Errors NOT_FOUND if no |
| 32 | + // accessible file with that id (including already-deleted). |
| 33 | + rpc DeleteFile(DeleteFileRequest) returns (DeleteFileResponse) {} |
| 34 | + |
| 35 | + // Stream the file's contents in chunks of up to 5 MB, in order. |
| 36 | + // Concatenate `data` from every chunk to reconstruct the file. |
| 37 | + rpc RetrieveFileContent(RetrieveFileContentRequest) returns (stream FileContentChunk) {} |
| 38 | +} |
| 39 | + |
| 40 | +// First stream message of an `UploadFile` call. Sent exactly once, before |
| 41 | +// any data chunks. |
| 42 | +message UploadFileInit { |
| 43 | + // Filename (max 255 Unicode chars). Must not contain ASCII control |
| 44 | + // chars, line terminators (CR/LF/NEL/U+2028/U+2029), null bytes, `"`, |
| 45 | + // `;`, or `\` — these would break `Content-Disposition` headers. |
| 46 | + string name = 1; |
| 47 | + |
| 48 | + // Optional TTL in seconds, measured from upload time. Must be in |
| 49 | + // [3600, 2592000] (1h to 30d) inclusive — 0 and out-of-range values are |
| 50 | + // rejected. Unset means no expiration. |
| 51 | + optional int64 expires_after = 2; |
| 52 | +} |
| 53 | + |
| 54 | +// One message in an `UploadFile` stream: either `init` (required first) or |
| 55 | +// a `data` chunk. |
| 56 | +message UploadFileChunk { |
| 57 | + oneof chunk { |
| 58 | + // Information about the file being uploaded. |
| 59 | + UploadFileInit init = 1; |
| 60 | + // Up to ~5 MB per chunk recommended; cumulative size capped at 512 MB. |
| 61 | + bytes data = 2; |
| 62 | + } |
| 63 | +} |
| 64 | + |
| 65 | +// Metadata for an uploaded file. |
| 66 | +message File { |
| 67 | + // Size in bytes. |
| 68 | + int64 size = 1; |
| 69 | + |
| 70 | + // UTC timestamp the file was uploaded. |
| 71 | + google.protobuf.Timestamp created_at = 2; |
| 72 | + |
| 73 | + // UTC timestamp the file will be auto-deleted at. Present only if the |
| 74 | + // upload set `UploadFileInit.expires_after`. |
| 75 | + optional google.protobuf.Timestamp expires_at = 3; |
| 76 | + |
| 77 | + // Filename as supplied at upload. |
| 78 | + string filename = 4; |
| 79 | + |
| 80 | + // Opaque server-assigned ID (e.g. `file_<uuid>`). Use this in |
| 81 | + // `RetrieveFile`, `DeleteFile`, `RetrieveFileContent`, and other xAI |
| 82 | + // APIs that accept a file reference. |
| 83 | + string id = 5; |
| 84 | + |
| 85 | + reserved 6; |
| 86 | +} |
| 87 | + |
| 88 | +// Sort direction for list-style RPCs. |
| 89 | +enum Ordering { |
| 90 | + ASCENDING = 0; |
| 91 | + DESCENDING = 1; |
| 92 | +} |
| 93 | + |
| 94 | +// Field to sort `ListFiles` results by. |
| 95 | +enum FilesSortBy { |
| 96 | + // Default. |
| 97 | + FILES_SORT_BY_CREATED_AT = 0; |
| 98 | + // Case-sensitive lexicographic order. |
| 99 | + FILES_SORT_BY_FILENAME = 1; |
| 100 | + FILES_SORT_BY_SIZE = 2; |
| 101 | +} |
| 102 | + |
| 103 | +// Request message for `Files.ListFiles`. |
| 104 | +message ListFilesRequest { |
| 105 | + // Page size, in [1, 100]. Values <= 0 default to 100; values > 100 are |
| 106 | + // clamped. |
| 107 | + int32 limit = 1; |
| 108 | + |
| 109 | + // Sort direction. Defaults to ASCENDING. |
| 110 | + Ordering order = 2; |
| 111 | + |
| 112 | + // Opaque token from a prior `ListFilesResponse.pagination_token`, used to |
| 113 | + // resume listing where the previous page left off. Omit on the first |
| 114 | + // call. Use the same `order` and `sort_by` as the request that produced |
| 115 | + // the token; otherwise paging behavior is undefined. Treat as opaque; |
| 116 | + // format may change. |
| 117 | + optional string pagination_token = 3; |
| 118 | + |
| 119 | + // Sort field. Defaults to `FILES_SORT_BY_CREATED_AT`. |
| 120 | + optional FilesSortBy sort_by = 4; |
| 121 | +} |
| 122 | + |
| 123 | +// Response message for `Files.ListFiles`. |
| 124 | +message ListFilesResponse { |
| 125 | + // List of file metadata. |
| 126 | + repeated File data = 1; |
| 127 | + |
| 128 | + // Token for the next page; absent on the final page. |
| 129 | + optional string pagination_token = 2; |
| 130 | +} |
| 131 | + |
| 132 | +// Request message for `Files.RetrieveFile`. |
| 133 | +message RetrieveFileRequest { |
| 134 | + // The ID of the file to use for this request. |
| 135 | + string file_id = 1; |
| 136 | +} |
| 137 | + |
| 138 | +// Request message for `Files.DeleteFile`. |
| 139 | +message DeleteFileRequest { |
| 140 | + // The ID of the file to use for this request. |
| 141 | + string file_id = 1; |
| 142 | +} |
| 143 | + |
| 144 | +// Response message for `Files.DeleteFile`. |
| 145 | +message DeleteFileResponse { |
| 146 | + // Echoes the deleted file's id. |
| 147 | + string id = 1; |
| 148 | + |
| 149 | + // Always true on success (failures surface as gRPC errors). |
| 150 | + bool deleted = 2; |
| 151 | +} |
| 152 | + |
| 153 | +// Which representation of a file to download. |
| 154 | +enum DownloadFormat { |
| 155 | + // Treated as `DOWNLOAD_FORMAT_ORIGINAL` (the default when `format` is |
| 156 | + // unset). |
| 157 | + DOWNLOAD_FORMAT_UNKNOWN = 0; |
| 158 | + // Raw bytes as uploaded. |
| 159 | + DOWNLOAD_FORMAT_ORIGINAL = 1; |
| 160 | + // Text extracted from the file (e.g. PDF/DOCX). Only works for file |
| 161 | + // types with a server-side text-extraction pass; fails otherwise. |
| 162 | + DOWNLOAD_FORMAT_TEXT = 2; |
| 163 | +} |
| 164 | + |
| 165 | +// Request message for `Files.RetrieveFileContent`. |
| 166 | +message RetrieveFileContentRequest { |
| 167 | + // The ID of the file to download. |
| 168 | + string file_id = 1; |
| 169 | + |
| 170 | + // Format of the downloaded content. |
| 171 | + // ORIGINAL: raw file bytes (default). |
| 172 | + // TEXT: extracted/converted text content. |
| 173 | + optional DownloadFormat format = 2; |
| 174 | +} |
| 175 | + |
| 176 | +// One chunk of a `RetrieveFileContent` stream. |
| 177 | +message FileContentChunk { |
| 178 | + // Up to 5 MB of file bytes. Final/intermediate chunks may be smaller. |
| 179 | + bytes data = 1; |
| 180 | +} |
0 commit comments