---
title: "Register Upload"
method: POST
path: "/v1/register_upload/"
tags: ["Public"]
---

# Register Upload

`POST /v1/register_upload/`

## Request

- Base URL: `https://api.koncile.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.koncile.ai/v1/register_upload/`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/koncile/apis/koncile-api/docs/v1/register_upload/post.ts> (a function with typed inputs; its response is checked against the schema)

Start extraction for files already uploaded to their presigned URLs (step 2 of 2).

Safe to retry: a handle that is already running or already finished comes
back under `skipped`, never started or charged twice.

Per handle: one file that cannot be started (not uploaded yet, too large)
comes back under `rejected` and the others are started anyway. The call
only fails as a whole when every handle is refused, or when storage cannot
be reached (503 — nothing has been started, retry the same request).

## Request body

- PublicRegisterUploadRequest: Request body for POST /v1/register_upload/.
  - `upload_ids` integer[], required: Handles from /v1/presign_upload/, for files that have actually been uploaded. All must belong to the caller's company.

## Response `200`

Successful Response

- PublicRegisterUploadResponse: Response for POST /v1/register_upload/. `skipped` and `rejected` are always present — an empty list when there is nothing to report — so a client never has to branch on a key that sometimes vanishes.
  - `task_ids` string[]: One task per newly-started file, pollable with /v1/fetch_tasks_results. Every task reaches a terminal status (UPLOAD-016).
  - `uploads` PublicRegisteredUpload[]: The same tasks, paired with the handle each one was started for. `task_ids` alone leaves a caller matching by position across two lists once some handles are skipped.
    - `upload_id` integer, required
    - `task_id` string, required
  - `skipped` PublicRegisterSkipped[]: Handles that were already started or already terminal.
    - `upload_id` integer, required
    - `reason` string, required: `already_done` / `already_failed` — the upload already reached a terminal state. `already_dispatched` / `recovery_claimed` — it is already being processed. None of these start a second extraction or a second charge.
  - `rejected` PublicRegisterRejected[]: Handles refused in this call. One bad handle never fails the others in the same request: they are started and returned above. Only when EVERY handle is refused does the call itself fail (UPLOAD-015).
    - `upload_id` integer, required
    - `reason` string, required: `not_uploaded` — nothing has been PUT to this handle's upload_url yet; PUT it, then register it again. `too_large` — the object exceeds the maximum upload size; presign again with a smaller file. `recovery_claimed` — the upload was left unregistered and has since been picked up for processing; find the resulting document in your document list.
    - `retryable` boolean, required: True when registering this same handle again can succeed once the stated problem is fixed.

## Other responses

- `422`: Validation Error

## Changes

- **2026-09-25** `1446f41e0cd4`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/koncile/apis/koncile-api/changes/v1/register_upload/post.md)

---

[API](https://skmtc.dev/koncile/apis/koncile-api.md) - [All operations](https://skmtc.dev/koncile/apis/koncile-api/llms.txt) - [OpenAPI document](https://skmtc.dev/koncile/apis/koncile-api/revisions/37187db89a87?raw)