> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://docs.agentmail.to/llms.txt.

# Complete File

POST https://api.agentmail.to/v0/inboxes/{inbox_id}/files/{file_id}/complete

Makes a pending file `ready` once its bytes are uploaded, and returns it, with its `download_url` if the key
has `file_read`. Calling it on a file that is already `ready` returns the file.

Returns `409` if the bytes haven't been uploaded yet, or if what was uploaded doesn't match the file's `size`
and `sha256`. Returns `404` for a file that has expired or was deleted, including a pending file not
completed within a day of its creation.

Requires the `file_create` permission. Only a key with `file_read`, or the key that created the file, can
complete it; any other key gets `404`.

Reference: https://docs.agentmail.to/api-reference/inboxes/files/complete

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Servers

- `https://api.agentmail.to` (prod, default)
- `https://x402.api.agentmail.to` (prod-x402)
- `https://mpp.api.agentmail.to` (prod-mpp)
- `https://api.agentmail.eu` (eu-prod)

## Request

### Path parameters

- `inbox_id` (string, required) — The ID of the inbox.
- `file_id` (string, required) — ID of the file. A UUID.

## Response

### 200

- `content_type` (string, required) — The file's MIME type, such as `application/pdf`. Defaults to `application/octet-stream`.
- `created_at` (datetime, required) — When the file was created.
- `email` (string, required) — Email address of the inbox.
- `file_id` (string, required) — ID of the file. A UUID.
- `inbox_id` (string, required) — The ID of the inbox.
- `name` (string, required) — The path's last segment. A download saves under this name.
- `path` (string, required) — Where the file lives in its inbox's drive, such as `reports/q3.pdf`. Unique within the inbox. Segments are separated by `/`, with no leading or trailing `/`, no empty, `.` or `..` segment, no `\` and no control or invisible characters. At most 1,024 bytes, and at most 255 bytes per segment. Stored in Unicode NFC, so two spellings of one name are one path. Case is kept.
- `sha256` (string, required) — The base64 encoding of the file's 32-byte SHA-256 digest, as S3's `x-amz-checksum-sha256` takes it (44 characters, ending in `=`). S3 refuses an upload whose bytes don't match.
- `size` (integer, required) — Size of the file in bytes. At most 104,857,600 (100 MiB).
- `status` (enum, required) — `pending` until its bytes are uploaded and the upload is completed, then `ready`. Only a `ready` file has a download URL. A pending file is deleted if it isn't completed within a day.
  - Allowed values: `pending`, `ready`
- `updated_at` (datetime, required) — When the file last changed, such as when its upload was completed.
- `download_expires_at` (datetime, optional) — When `download_url` stops working. Never after the file's own expiry.
- `download_url` (string, optional) — A signed URL that downloads the file's bytes, named by `name`. No API key is needed to use it, so treat it as a secret. It works until `download_expires_at`, at most an hour, even after the file is deleted. Get the file again for a fresh one.
- `expires_at` (datetime, optional) — When the file expires. After it, the file is gone from get and list and its path is free; its bytes are deleted soon after. Absent for a file that never expires.

## Errors

### 400 Validation Error

- `name` (string, required) — Name of error.
- `errors` (any, required) — Validation errors. Each entry has a path and a message identifying the invalid field.
- `code` (string, optional) — Stable, machine-readable error code in snake_case (for example, not_found or missing_permission). Branch on this rather than the message text.
- `message` (string, optional) — Error message.
- `fix` (string, optional) — The concrete next action that resolves the error.
- `docs` (string, optional) — Link to the error reference entry for this code.

### 403 File Forbidden Error

`code` says why: `forbidden` when the organization hasn't joined AgentMail Labs; `missing_permission` when the credential lacks the file permission the endpoint needs, including `file_create` in an organization that hasn't completed agent verification, and every file permission for an organization- or pod-scoped key under a content-access policy; `account_suspended`, `pod_suspended` or `inbox_suspended` when the organization, pod or inbox is suspended; and, for Create File only, `limit_exceeded` when the file doesn't fit the organization's Drive quota.

- `name` (string, required) — Name of error.
- `message` (string, required) — Error message.
- `code` (string, optional) — Stable, machine-readable error code in snake_case (for example, not_found or missing_permission). Branch on this rather than the message text.
- `fix` (string, optional) — The concrete next action that resolves the error.
- `docs` (string, optional) — Link to the error reference entry for this code.

### 404 Not Found Error

- `name` (string, required) — Name of error.
- `message` (string, required) — Error message.
- `code` (string, optional) — Stable, machine-readable error code in snake_case (for example, not_found or missing_permission). Branch on this rather than the message text.
- `fix` (string, optional) — The concrete next action that resolves the error.
- `docs` (string, optional) — Link to the error reference entry for this code.

### 409 Conflict Error

- `name` (string, required) — Name of error.
- `message` (string, required) — Error message.
- `code` (string, optional) — Stable, machine-readable error code in snake_case (for example, not_found or missing_permission). Branch on this rather than the message text.
- `fix` (string, optional) — The concrete next action that resolves the error.
- `docs` (string, optional) — Link to the error reference entry for this code.

## Examples

**Response**

```json
{
  "content_type": "application/pdf",
  "created_at": "2026-10-14T16:20:00Z",
  "email": "reports@agentmail.to",
  "file_id": "6f1c2f4e-8d3b-4a5e-9c7d-1b2a3c4d5e6f",
  "inbox_id": "reports@agentmail.to",
  "name": "q3.pdf",
  "path": "reports/q3.pdf",
  "sha256": "n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg=",
  "size": 48213,
  "status": "ready",
  "updated_at": "2026-10-14T16:20:05Z",
  "download_expires_at": "2026-10-14T17:20:05Z",
  "download_url": "https://cdn.agentmail.to/files/6f1c2f4e-8d3b-4a5e-9c7d-1b2a3c4d5e6f?filename=71332e706466&Signature=..."
}
```

**SDK Code**

```python
import requests

url = "https://api.agentmail.to/v0/inboxes/reports%40agentmail.to/files/6f1c2f4e-8d3b-4a5e-9c7d-1b2a3c4d5e6f/complete"

headers = {"Authorization": "Bearer <api_key>"}

response = requests.post(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.agentmail.to/v0/inboxes/reports%40agentmail.to/files/6f1c2f4e-8d3b-4a5e-9c7d-1b2a3c4d5e6f/complete';
const options = {method: 'POST', headers: {Authorization: 'Bearer <api_key>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agentmail.to/v0/inboxes/reports%40agentmail.to/files/6f1c2f4e-8d3b-4a5e-9c7d-1b2a3c4d5e6f/complete"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Bearer <api_key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.agentmail.to/v0/inboxes/reports%40agentmail.to/files/6f1c2f4e-8d3b-4a5e-9c7d-1b2a3c4d5e6f/complete")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <api_key>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.agentmail.to/v0/inboxes/reports%40agentmail.to/files/6f1c2f4e-8d3b-4a5e-9c7d-1b2a3c4d5e6f/complete")
  .header("Authorization", "Bearer <api_key>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.agentmail.to/v0/inboxes/reports%40agentmail.to/files/6f1c2f4e-8d3b-4a5e-9c7d-1b2a3c4d5e6f/complete', [
  'headers' => [
    'Authorization' => 'Bearer <api_key>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.agentmail.to/v0/inboxes/reports%40agentmail.to/files/6f1c2f4e-8d3b-4a5e-9c7d-1b2a3c4d5e6f/complete");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <api_key>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <api_key>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.agentmail.to/v0/inboxes/reports%40agentmail.to/files/6f1c2f4e-8d3b-4a5e-9c7d-1b2a3c4d5e6f/complete")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```