> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ai-gust.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Reference: managing uploads, errors and conventions

> List and cancel open uploads, the error reference, the caveats and the file conventions for partner uploads.

The interactive [API reference](https://api.prod.ai-gust.io/api/redoc#tag/tenant_connector_external_uploads) (ReDoc) documents these endpoints with their exact schemas — look under **Connector external uploads**. This page covers everything around them: managing uploads, errors and file conventions.

## List open uploads

```
GET {API_BASE_URL}/tenants/{TENANT_ID}/connectors/{CONNECTOR_ID}/uploads
Authorization: Bearer {ACCESS_TOKEN}
```

Returns every upload that is not yet processed (`AWAITING_UPLOAD`, `PENDING` or `RUNNING`), with its scope, parameters and — while awaiting files — its current upload URL:

```json theme={null}
{
  "uploads": [
    {
      "upload_id": "440d08a1-fcba-4627-8e5c-bd6456cdcf57",
      "progress": "AWAITING_UPLOAD",
      "started": "2026-10-13T08:00:00+00:00",
      "administration_code": null,
      "full_upload": false,
      "upload_url": "https://.../uploads/...?sig=...",
      "expires_at": "2026-10-15T08:00:00+00:00"
    }
  ]
}
```

Once processing finishes, the upload **disappears from the list**. Exception: an upload whose processing **failed** stays visible with progress `FAILED` while its run is still open on our side — report it to us with its `upload_id`. Note that we are notified of failures automatically, so we may already be looking into it.

## Get one upload

```
GET {API_BASE_URL}/tenants/{TENANT_ID}/connectors/{CONNECTOR_ID}/uploads/{UPLOAD_ID}
Authorization: Bearer {ACCESS_TOKEN}
```

Returns one open upload — the same object as in the list. Processed or cancelled uploads return `404` (`UPLOAD_NOT_FOUND`), just like they disappear from the list.

## Cancel an open upload

Discards the uploaded files and releases the upload, for example to restart with different parameters:

```
POST {API_BASE_URL}/tenants/{TENANT_ID}/connectors/{CONNECTOR_ID}/uploads/{UPLOAD_ID}/cancel
Authorization: Bearer {ACCESS_TOKEN}
```

Idempotent: cancelling an already-closed upload is a no-op; an unknown upload id returns `404` (`UPLOAD_NOT_FOUND`). Cancelling an upload that was already submitted returns `409 Conflict` (`UPLOAD_NOT_AWAITING`) — at that point the batch is being processed and can no longer be cancelled.

```json theme={null}
{ "cancelled": true, "upload_id": "440d08a1-fcba-4627-8e5c-bd6456cdcf57" }
```

Uploads that are never submitted are cancelled automatically roughly 2 days after creation.

The old upload URL may still work after cancel, but you must stop using it. Uploading more files does not reopen the cancelled batch.

## File conventions

* Place each file in a **subfolder named after its endpoint type**, one level below the upload directory root (for example `{UPLOAD_URL}/invoices/...`).
* All files in such a subfolder share the **data format agreed with aiGust** for that endpoint type. That format is bespoke: it is discussed and settled with us before you start (see [Upload data as an integration partner](https://docs.ai-gust.io/integrate/ext-upload-overview.md)).
* Files placed directly in the root of the upload directory are **ignored** — they belong to no endpoint type.

## Caveats and limitations

* **One open upload per scope.** A scope is either the whole connector or a single `administration_code`. Multiple administrations can have an open upload at the same time, but a connector-wide upload blocks all administration-scoped ones — and vice versa.
* **No new upload while a previous one is processing.** After you submit, the upload is processed (`PENDING`/`RUNNING` in the upload list) and overlapping `create` calls are rejected with `409 Conflict` until it finishes. Poll the upload list to know when you can open the next batch.
* **Parameters are locked while an upload is open.** Calling `create` with a different `administration_code` or `full_upload` than the open batch returns `409 Conflict` — submit or cancel the open upload first.
* **Administrations must be active.** Creating an upload for an unknown or inactive administration fails (`404` / `400` — see [errors](#errors)). Deactivating an administration *after* opening its upload makes its **submit** fail the same way.
* **New administrations require a connector-wide upload.** Administration discovery happens on connector-wide uploads (no `administration_code`). An administration-scoped upload can only target an *existing* administration — a brand-new code fails with `404`. To onboard a new administration, open a connector-wide upload first; afterwards it can be synced scoped.
* **Submit within 2 days.** An upload that is never submitted is cancelled automatically roughly 2 days after creation and its files are deleted. Check `expires_at` for the upload URL's expiry.
* **Submitting is final.** Finish uploading and finalizing all files before submit. The URL may still work afterwards, but you must stop using it. During processing, aiGust takes a separate copy of the batch; later uploads do not update that copy. Create a new upload for additional data.
* **Automatic processing only covers connector-wide uploads.** If enabled for your connector, the daily schedule processes existing open connector-wide uploads. Uploads for a single administration must always be submitted manually. The schedule does not create uploads or retry previously submitted runs.
* **Follow the agreed data format.** The uploader is responsible for the uploaded data. Empty uploads follow the normal processing flow and may fail; they are not automatically skipped or marked successful.

## Errors

All endpoints return a JSON error body, in one of two shapes:

```json theme={null}
{ "detail": "Human-readable message" }
```

```json theme={null}
{ "detail": { "code": "MACHINE_READABLE_CODE", "message": "Human-readable message" } }
```

### 401 — authentication

Example: `{ "detail": "Access token expired" }`. Your token is expired or invalid — request a new one and retry the call.

### 403 — forbidden

Your credentials are valid but not authorized for this call. The provisioned credentials only work for **your own connector** — using them with another connector id (even within the same firm) returns 403.

### 404 — not found

* **Without a `code`**: the tenant or connector id is unknown to us.
* `ADMINISTRATION_NOT_FOUND` — the `administration_code` does not exist on this connector.
* `UPLOAD_NOT_FOUND` — the `upload_id` does not exist on this connector (or the upload is already processed, on the get-by-id endpoint).

### 400 — bad request

* **Without a `code`**: the action is not supported for this connector — the `upload/*` endpoints are only available on external-upload connectors.
* `ADMINISTRATION_NOT_SYNCABLE` — the administration exists but is not active for syncing (for example deactivated); the message includes its current status.
* `NO_SYNCABLE_ADMINISTRATIONS` — the connector has no active, syncable administrations.

### 409 — conflict

* **Without a `code`** on `create`: an upload is already open for an overlapping scope — submit or cancel it first; the message describes the conflict.
* `UPLOAD_NOT_AWAITING` — the upload exists but is no longer awaiting files (it was already submitted and is pending, running or processed). The message includes the current state. Submitting or cancelling is only possible while an upload awaits files; request a new upload URL once processing has finished.
* `OPEN_SYNC_EXISTS` — a sync is currently running or pending for this connector; a new upload can be opened once it finishes.
* `ADMINISTRATIONS_LOCKED` — one or more administrations are locked by a running sync; retry shortly.

### 500 — server error

Something went wrong on our side (for example the upload storage is unreachable). Retry later, check the [platform status](https://docs.ai-gust.io/setup/support/platform-status.md), or contact us; the `upload_id` helps us investigate.

| Code | HTTP | Endpoints |
| - | - | - |
| `ADMINISTRATION_NOT_FOUND` | 404 | create, submit |
| `UPLOAD_NOT_FOUND` | 404 | get, submit, cancel |
| `ADMINISTRATION_NOT_SYNCABLE` | 400 | create, submit |
| `NO_SYNCABLE_ADMINISTRATIONS` | 400 | create, submit |
| `OPEN_SYNC_EXISTS` | 409 | create, submit |
| `ADMINISTRATIONS_LOCKED` | 409 | create, submit |
| `UPLOAD_NOT_AWAITING` | 409 | submit, cancel |

## Security notes

* The upload URL is write-only: you cannot read, list, or delete anything.
* Your client credentials are scoped to **your connector only** — they cannot read or modify any other connector, and all calls outside the `upload/*` lifecycle are rejected.
* Keep the Client Secret and upload URLs confidential — they grant write access.
* Stop using an upload URL after submit or cancel, even if it still accepts files.
* Contact us to revoke API access. Already-issued upload URLs can remain valid until their own `expires_at`, even after API access is revoked.

Questions? Contact [integrations@ai-gust.io](mailto:integrations@ai-gust.io).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.