You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
client =WeTransfer::Client.new(api_key:'YOUR PRIVATE API KEY GOES HERE')
31
31
32
-
board = client.create_board_and_upload_items(name:'Kittens') do |builder|
32
+
board = client.create_board_and_upload_items(name:'Little kittens') do |builder|
33
33
builder.add_file(
34
34
name:'bobis.jpg',
35
35
io:File.open('/path/to/kitty.jpg', 'rb')
@@ -75,11 +75,15 @@ puts "The board can be viewed on #{board.url}"
75
75
}
76
76
```
77
77
78
-
<asideclass="warning"><strong>Note:</strong> The <code>url</code> in the response is the URL you will use to access the board you create! It is not returned at the end of the upload flow, rather right now when you create the empty board.</aside>
78
+
<asideclass="warning">**Note**: The `url` in the response is the URL you will use to access the board you created. It is not returned at the end of the upload flow, rather only right now when you create the (empty) board.</aside>
79
+
80
+
Later you'll want to interact with your board. Add files and links to it. In order to do that, make sure to note the value of the `id` property.
79
81
80
82
## Add links to a board
81
83
82
-
Once a board has been created you can add links like so:
84
+
A board can hold files *and* URLs. Lets have a look at how you can add URLs to your board. For that you need the `id` of the board you created earlier, unless your SDK will handle that for you.
85
+
86
+
Once a board has been created you can add links like below:
83
87
84
88
```shell
85
89
curl -i -X POST "https://dev.wetransfer.com/v2/boards/{board_id}/links" \
The endpoint will return an object for each file you want to add to the board. Each file must be split into chunks, and uploaded to a pre-signed S3 URL, provided by the following endpoint.
210
+
The endpoint will return an object for each file you want to add to the board. The data returned is helpful in the next step when we want to request a place where we can upload our file.
211
+
212
+
The important parts in the response are the `id` of the file, the `id` of the multipart object, together with its `part_numbers`.
207
213
208
214
**Important**
209
215
210
-
Board chunks _must_ be 6 megabytes in size, except for the very last chunk, which can be smaller. Sending too much or too little data will result in a 400 Bad Request error when you finalise the file.
216
+
Board chunks _must_ be 6 megabytes (or more precisely 6291456 bytes) in size, except for the very last chunk, which can be smaller. Sending too much or too little data will result in a `400 Bad Request` error when you finalize the file. As with transfers: Do not let us down.
To be able to upload a file, it must be split into chunks, and uploaded to different presigned URLs. This route can be used to fetch presigned upload URLS for each of a file's parts. These upload URLs are essentially limited access to a storage bucket hosted with Amazon. They are valid for an hour and must be re-requested if they expire.
224
+
To be able to upload a file, it must be split into chunks, and uploaded to different pre-signed URLs. This endpoint can be used to get pre-signed upload URLs for each of a file's parts. These upload URLs are essentially limited access to a storage bucket hosted with Amazon. They are valid for an hour and must be re-requested if they expire.
225
+
226
+
Use the fields from the previous response; now you need the `id` of the file, the `id` of the multipart, and you must request a upload-url for all of your `part_numbers`.
217
227
218
228
```shell
219
229
curl -i -X GET "https://dev.wetransfer.com/v2/boards/{board_id}/files/{file_id}/upload-url/{part_number}/{multipart_upload_id}" \
Please note: errors returned from S3 will be sent as XML, not JSON. If your response parser is expecting a JSON response it may throw an error here. Please see AWS' <ahref="https://docs.aws.amazon.com/AmazonS3/latest/API/ErrorResponses.html"target="_blank">S3 documentation</a> for more details about specific responses.
300
+
You're communicating directly with Amazons' S3, not with our API. Please note: errors returned from S3 will be sent as XML, not JSON. If your response parser is expecting a JSON response it may throw an error here. Please see AWS' <ahref="https://docs.aws.amazon.com/AmazonS3/latest/API/ErrorResponses.html"target="_blank">S3 documentation</a> for more details about specific responses.
Copy file name to clipboardExpand all lines: source/includes/_transfer-api.md
+89-34Lines changed: 89 additions & 34 deletions
Original file line number
Diff line number
Diff line change
@@ -12,13 +12,22 @@ Transfers must be created with files. Once the transfer has been created and fin
12
12
13
13
When you create a transfer, you must include at least one file in the transfer create request.
14
14
15
+
Creating a transfer is to inform the API that you want to create a transfer (with at least one file), but you aren't sending the files already.
16
+
17
+
What you are sending is the `message`, a property that describes what this transfer is about, and a collection of file `name`s and their `size`. This allows the API to set up a place where your files can be uploaded to in a later state. Make sure the size of the file is accurate. Please don't lie to us; we will not be able to handle your files in a later stage...
18
+
15
19
```shell
16
20
curl -i -X POST "https://dev.wetransfer.com/v2/transfers" \
17
21
-H "Content-Type: application/json" \
18
-
-H "x-api-key: your_api_key" \
19
-
-H "Authorization: Bearer jwt_token" \
20
-
-d '{"message":"My very first transfer!","files":[
If you look at that response above, you see some pointers that are needed now. All files should be uploaded to a specific place. You just have to get the place from our API. To do that, you ask the API based on the `transfer.id`, each and every `file.id`, and for each part (based on the `file.multipart.part_numbers` property).
128
+
129
+
To be able to upload a file, it must be split into parts and then each part will be uploaded to pre-signed AWS S3 URLs.
114
130
115
-
To be able to upload a file, it must be split into parts and then each part will be uploaded to presigned AWS S3 URLs. This route can be used to fetch presigned upload URLS for each of a file's parts. These upload URLs are essentially limited access to a storage bucket hosted with Amazon. NB: They are valid for an <em>hour</em> and must be re-requested if they expire.
131
+
This endpoint can be used to get pre-signed upload URLS for each of a file's parts. These upload URLs are essentially limited access to a storage bucket hosted with Amazon. NOTE: They are valid for an **hour** and must be re-requested if they expire.
116
132
117
133
```shell
118
134
curl -i -X GET "https://dev.wetransfer.com/v2/transfers/{transfer_id}/files/{file_id}/upload-url/{part_number}" \
@@ -176,24 +192,46 @@ Transfer chunks must be 5 megabytes in size, except for the very last chunk, whi
176
192
}
177
193
```
178
194
179
-
The Response Body contains the presigned S3 upload `url`.
195
+
The Response Body contains the pre-signed S3 upload `url`.
180
196
181
197
##### 404 (Not found)
182
198
183
-
If the requester tries to request an upload URL for a file that is not in one of the requester's transfers, we will respond with 404 Not found.
199
+
If you try to request an upload URL for a file that is not in the transfers, the API will respond with 404 Not found.
200
+
201
+
```json
202
+
{
203
+
"success" : false,
204
+
"message" : "Couldn't find FileObject"
205
+
}
206
+
```
207
+
208
+
##### 417 (Expectation Failed)
209
+
210
+
If you request to upload part `0`, our API will tell you that our parts are numbered for humans; we start counting at part 1:
Time to actually upload (chunks of) your file. With the pre-signed-upload-url you retrieved in the previous step, you can start uploading!
224
+
225
+
You will interact directly with Amazon S3. As such, we have no control over the messages sent by S3.
226
+
189
227
Important: errors returned from S3 will be sent as XML, not JSON. If your response parser is expecting a JSON response it may throw an error here. Please see AWS' <ahref="https://docs.aws.amazon.com/AmazonS3/latest/API/ErrorResponses.html"target="_blank">S3 documentation</a> for more details about specific responses.
<h2id="transfer-complete-file-upload">Complete a file upload</h2>
232
270
233
-
Finalize a file. Once all the parts have been uploaded succesfully, you use this endpoint to tell the system that it can start splicing the parts together to form one whole file.
271
+
In the previous step, you've uploaded your file (potentially in parts) directly to S3. The WeTransfer API has no idea when that is complete. This call informs your transfer object that all the uploading for your file is done.
272
+
273
+
Again, to inform the API about this event, you need both the transfer id and the file id. Not only that, you currently also have to inform this endpoint on the amount of part numbers.
234
274
235
275
```shell
236
276
curl -i -X PUT "https://dev.wetransfer.com/v2/transfers/{transfer_id}/files/{file_id}/upload-complete" \
If you try to finalise a file, but didn't actually upload all chunks it will respond with something like this:
326
+
327
+
```json
328
+
{
329
+
"success": false,
330
+
"message": "Chunks 1 are still missing"
331
+
}
332
+
```
333
+
283
334
<h2id="finalize-a-transfer">Finalize a transfer</h2>
284
335
285
-
Finalize the whole transfer. Once all the parts have been uploaded and finalized, you use this endpoint to tell the system that everything has been completely uploaded.
336
+
After all files are uploaded and finalized, you can close the transfer for modification, and make it available for download.
337
+
338
+
You do that by calling this endpoint. It informs the API that everything has been completely uploaded.
286
339
287
340
```shell
288
341
curl -i -X PUT "https://dev.wetransfer.com/v2/transfers/{transfer_id}/finalize" \
0 commit comments