> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/api-references/readme/api-reference-19/files.md).

# Files

The queue of files a file-based stream imports: upload one, see what is waiting, change the load order, remove one, queue a failed one again.

## Retrieving a stream's files

> Lists what a file-based stream still has to import, in the order it will be read, and what it has\
> already dealt with. A file is identified by the SHA-256 of its content, so re-sending the same bytes\
> is recognised however the file is named.

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"tags":[{"name":"Files","description":"The queue of files a file-based stream imports: upload one, see what is waiting, change the load order, remove one, queue a failed one again."}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["importtool.import_trigger"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"importtool.import_trigger":"Needed to trigger, schedule, monitor, and cancel import runs; to manage a file-based stream's file queue; and to read configurations, streams, schedules, runs, and imported data."}}}}},"schemas":{"FileQueue":{"title":"File queue","type":"object","description":"What a stream still has to import, and what it has already dealt with.","properties":{"pending":{"type":"array","items":{"$ref":"#/components/schemas/ImportFile"},"description":"The files waiting to be imported, in the order they will be read."},"history":{"type":"array","items":{"$ref":"#/components/schemas/ImportFile"},"description":"Files already dealt with, newest first."},"pendingTruncated":{"type":"boolean","description":"True when more files are waiting than this response carries. The load order cannot be changed while it is true, because an order that cannot name every waiting file has no meaning."},"pendingTotal":{"type":"integer","format":"int64","description":"How many files are waiting in total, however many this response lists."},"lastProcessed":{"description":"The newest file the stream has imported. Absent when it has imported none. Returned whatever `historyLimit` is, because a run with no file waiting reads this file again (a snapshot stream).","type":"object","allOf":[{"$ref":"#/components/schemas/ImportFile"}]}}},"ImportFile":{"title":"Import file","type":"object","description":"One file a file-based stream has been given, and what became of it.","properties":{"id":{"type":"string","format":"uuid","description":"The file's identifier."},"fileName":{"type":"string","description":"The name the file was given, used to display it and to infer compression."},"size":{"type":"integer","format":"int64","description":"The file's size in bytes."},"status":{"type":"string","enum":["PENDING","IN_PROGRESS","PROCESSED","FAILED"],"description":"Where the file is in its life. Possible values:\n\n* `PENDING` – waiting to be imported.\n* `IN_PROGRESS` – a run has claimed it and is reading it.\n* `PROCESSED` – read to completion. Set only once its records have been written, so a run that\n  fails part-way leaves the file importable.\n* `FAILED` – the stream that read the file finished `FAILED`. The file could not be read\n  (malformed, truncated, wrong charset), or the import failed for another reason, such as the\n  target being unavailable. Such a file can be queued again with the content the service holds, or\n  uploaded again. Records that fail individually do not\n  put a file here: a stream that finishes with record failures still marks its file imported."},"loadRank":{"type":"integer","format":"int64","description":"The position in the drain order. For an incremental feed the order is part of the data: a later file's values win on a key an earlier one also carries."},"queuedAt":{"type":"string","format":"date-time","description":"When the file was added to the queue."},"processedAt":{"type":"string","format":"date-time","description":"When the file finished being imported."},"runId":{"type":"string","format":"uuid","description":"The run that consumed it."},"recordsRead":{"type":"integer","description":"How many records came out of it."},"message":{"type":"string","description":"Why the file ended as it did, when that needs saying — a file superseded by a newer snapshot in the same run, or one imported with record-level failures."}}},"errorMessage":{"title":"Error","description":"Schema for specific API errors.","type":"object","properties":{"code":{"type":"integer","description":"HTTP status code.","minimum":100,"maximum":599},"status":{"description":"The HTTP status reason phrase, for example `Conflict`.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"resourceId":{"description":"Identifier of the resource the error concerns, for example the configuration of a run that conflicts with an active run, or the run a retry was requested for. `null` when the error concerns no single resource.","type":"string","nullable":true},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"Error Detail","description":"One problem causing the error.","type":"object","properties":{"message":{"type":"string","description":"What is wrong."},"field":{"type":"string","description":"The field the problem concerns, when there is one."}}}}},"required":["status","code","message"]}},"responses":{"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"NotFound_404":{"description":"The requested resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"InternalServiceError_500":{"description":"An unexpected error occurred in the service. The body is the framework's default error body, not the error schema of the other responses.","content":{"application/json":{"schema":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time","description":"When the error occurred."},"status":{"type":"integer","description":"The HTTP status code."},"error":{"type":"string","description":"The HTTP status reason phrase."},"path":{"type":"string","description":"The request path."}}}}}}}},"paths":{"/importtool/{tenant}/streams/{streamId}/files":{"get":{"summary":"Retrieving a stream's files","description":"Lists what a file-based stream still has to import, in the order it will be read, and what it has\nalready dealt with. A file is identified by the SHA-256 of its content, so re-sending the same bytes\nis recognised however the file is named.","operationId":"GET-importtool-stream-files","tags":["Files"],"parameters":[{"schema":{"type":"integer","default":100,"minimum":1,"maximum":500},"in":"query","name":"historyLimit","description":"Number of the stream's most recently handled files to return in `history`. A value below 1 is\ntreated as 1, and a value above 500 as 500. This parameter does not limit `pending`: the queue is\nreturned in full up to 2000 files, and `pendingTruncated` and `pendingTotal` indicate when it is\nlonger than the response."}],"responses":{"200":{"description":"The request was successful. The queue and the history are returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileQueue"}}}},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"404":{"$ref":"#/components/responses/NotFound_404"},"500":{"$ref":"#/components/responses/InternalServiceError_500"}}}}}}
```

## Uploading a file for a stream to import

> Queues a delimited file (CSV or one of its variants) for a file-based stream to import on its next\
> run. Nothing is imported by this request.\
> \
> The file is stored, and its content hash recorded, so the same bytes are never imported twice: a\
> file this stream has already imported is refused rather than queued again. A file that previously\
> failed is accepted, because the usual reason is that it has been fixed. To import a failed file again\
> unchanged, queue it again with the stored content instead of uploading it.\
> \
> The request is refused while the stream's job has a run in flight if the upload would replace bytes\
> the stream already holds — a run may be reading them, and a retry may be waiting to re-read them.\
> A file the stream has not seen before is a new queue entry and is accepted at any time.

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"tags":[{"name":"Files","description":"The queue of files a file-based stream imports: upload one, see what is waiting, change the load order, remove one, queue a failed one again."}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["importtool.import_trigger"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"importtool.import_trigger":"Needed to trigger, schedule, monitor, and cancel import runs; to manage a file-based stream's file queue; and to read configurations, streams, schedules, runs, and imported data."}}}}},"schemas":{"ImportFile":{"title":"Import file","type":"object","description":"One file a file-based stream has been given, and what became of it.","properties":{"id":{"type":"string","format":"uuid","description":"The file's identifier."},"fileName":{"type":"string","description":"The name the file was given, used to display it and to infer compression."},"size":{"type":"integer","format":"int64","description":"The file's size in bytes."},"status":{"type":"string","enum":["PENDING","IN_PROGRESS","PROCESSED","FAILED"],"description":"Where the file is in its life. Possible values:\n\n* `PENDING` – waiting to be imported.\n* `IN_PROGRESS` – a run has claimed it and is reading it.\n* `PROCESSED` – read to completion. Set only once its records have been written, so a run that\n  fails part-way leaves the file importable.\n* `FAILED` – the stream that read the file finished `FAILED`. The file could not be read\n  (malformed, truncated, wrong charset), or the import failed for another reason, such as the\n  target being unavailable. Such a file can be queued again with the content the service holds, or\n  uploaded again. Records that fail individually do not\n  put a file here: a stream that finishes with record failures still marks its file imported."},"loadRank":{"type":"integer","format":"int64","description":"The position in the drain order. For an incremental feed the order is part of the data: a later file's values win on a key an earlier one also carries."},"queuedAt":{"type":"string","format":"date-time","description":"When the file was added to the queue."},"processedAt":{"type":"string","format":"date-time","description":"When the file finished being imported."},"runId":{"type":"string","format":"uuid","description":"The run that consumed it."},"recordsRead":{"type":"integer","description":"How many records came out of it."},"message":{"type":"string","description":"Why the file ended as it did, when that needs saying — a file superseded by a newer snapshot in the same run, or one imported with record-level failures."}}},"errorMessage":{"title":"Error","description":"Schema for specific API errors.","type":"object","properties":{"code":{"type":"integer","description":"HTTP status code.","minimum":100,"maximum":599},"status":{"description":"The HTTP status reason phrase, for example `Conflict`.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"resourceId":{"description":"Identifier of the resource the error concerns, for example the configuration of a run that conflicts with an active run, or the run a retry was requested for. `null` when the error concerns no single resource.","type":"string","nullable":true},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"Error Detail","description":"One problem causing the error.","type":"object","properties":{"message":{"type":"string","description":"What is wrong."},"field":{"type":"string","description":"The field the problem concerns, when there is one."}}}}},"required":["status","code","message"]}},"responses":{"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"NotFound_404":{"description":"The requested resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"InternalServiceError_500":{"description":"An unexpected error occurred in the service. The body is the framework's default error body, not the error schema of the other responses.","content":{"application/json":{"schema":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time","description":"When the error occurred."},"status":{"type":"integer","description":"The HTTP status code."},"error":{"type":"string","description":"The HTTP status reason phrase."},"path":{"type":"string","description":"The request path."}}}}}}}},"paths":{"/importtool/{tenant}/streams/{streamId}/files":{"post":{"summary":"Uploading a file for a stream to import","description":"Queues a delimited file (CSV or one of its variants) for a file-based stream to import on its next\nrun. Nothing is imported by this request.\n\nThe file is stored, and its content hash recorded, so the same bytes are never imported twice: a\nfile this stream has already imported is refused rather than queued again. A file that previously\nfailed is accepted, because the usual reason is that it has been fixed. To import a failed file again\nunchanged, queue it again with the stored content instead of uploading it.\n\nThe request is refused while the stream's job has a run in flight if the upload would replace bytes\nthe stream already holds — a run may be reading them, and a retry may be waiting to re-read them.\nA file the stream has not seen before is a new queue entry and is accepted at any time.","operationId":"POST-importtool-stream-files","tags":["Files"],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"The file to import."}},"required":["file"]}}}},"responses":{"200":{"description":"The request was successful. The file is queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportFile"}}}},"400":{"description":"No file was sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"404":{"$ref":"#/components/responses/NotFound_404"},"409":{"description":"The stream has already imported this exact file, the file is already queued, the stream does not read files, or a run in flight is using the bytes this upload would replace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"413":{"description":"The file is larger than this environment's upload limit. Publish it at an HTTP(S) URL and set that as the connection's file URL instead.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"500":{"$ref":"#/components/responses/InternalServiceError_500"},"503":{"description":"File upload is not configured in this environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}}}}}}}
```

## Retrieving the file upload limits

> Returns the largest file this environment accepts, and whether uploading is available at all, so a\
> client can state the limit and reject an oversize file before sending it.

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"tags":[{"name":"Files","description":"The queue of files a file-based stream imports: upload one, see what is waiting, change the load order, remove one, queue a failed one again."}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["importtool.import_trigger"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"importtool.import_trigger":"Needed to trigger, schedule, monitor, and cancel import runs; to manage a file-based stream's file queue; and to read configurations, streams, schedules, runs, and imported data."}}}}},"responses":{"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"NotFound_404":{"description":"The requested resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"InternalServiceError_500":{"description":"An unexpected error occurred in the service. The body is the framework's default error body, not the error schema of the other responses.","content":{"application/json":{"schema":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time","description":"When the error occurred."},"status":{"type":"integer","description":"The HTTP status code."},"error":{"type":"string","description":"The HTTP status reason phrase."},"path":{"type":"string","description":"The request path."}}}}}}},"schemas":{"errorMessage":{"title":"Error","description":"Schema for specific API errors.","type":"object","properties":{"code":{"type":"integer","description":"HTTP status code.","minimum":100,"maximum":599},"status":{"description":"The HTTP status reason phrase, for example `Conflict`.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"resourceId":{"description":"Identifier of the resource the error concerns, for example the configuration of a run that conflicts with an active run, or the run a retry was requested for. `null` when the error concerns no single resource.","type":"string","nullable":true},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"Error Detail","description":"One problem causing the error.","type":"object","properties":{"message":{"type":"string","description":"What is wrong."},"field":{"type":"string","description":"The field the problem concerns, when there is one."}}}}},"required":["status","code","message"]}}},"paths":{"/importtool/{tenant}/streams/{streamId}/files/limits":{"get":{"summary":"Retrieving the file upload limits","description":"Returns the largest file this environment accepts, and whether uploading is available at all, so a\nclient can state the limit and reject an oversize file before sending it.","operationId":"GET-importtool-stream-file-limits","tags":["Files"],"responses":{"200":{"description":"The request was successful.","content":{"application/json":{"schema":{"type":"object","properties":{"maxUploadBytes":{"type":"integer","format":"int64","description":"The largest file accepted, in bytes."},"gatewayLimited":{"type":"boolean","description":"Whether `maxUploadBytes` is set by the API gateway in front of the service rather than by the service itself. A larger file is then refused by the gateway, with the gateway's own `413` error body, before it reaches the service. Use the connection's file URL for it."},"uploadSupported":{"type":"boolean","description":"False when the environment has nowhere to store an uploaded file. A file URL on the connection does not help: a fetched file is stored in the same place."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"404":{"$ref":"#/components/responses/NotFound_404"},"500":{"$ref":"#/components/responses/InternalServiceError_500"}}}}}}
```

## Setting the order in which files are imported

> Sets the order in which the waiting files are read. For an incremental feed the order is the data: a\
> later file's values win on a key an earlier one also carries, so an older export must be placed before\
> a newer one.\
> \
> The request takes every waiting file's identifier, in load order, rather than moving one file: ranks\
> are only meaningful relative to each other, and a partial list would leave the omitted files at their\
> old ranks interleaved with the new ones. A list that is not exactly the waiting set is refused.\
> \
> The request is refused while the job has a run in flight, which may be draining the queue as the order\
> changes.

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"tags":[{"name":"Files","description":"The queue of files a file-based stream imports: upload one, see what is waiting, change the load order, remove one, queue a failed one again."}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["importtool.import_trigger"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"importtool.import_trigger":"Needed to trigger, schedule, monitor, and cancel import runs; to manage a file-based stream's file queue; and to read configurations, streams, schedules, runs, and imported data."}}}}},"schemas":{"ImportFile":{"title":"Import file","type":"object","description":"One file a file-based stream has been given, and what became of it.","properties":{"id":{"type":"string","format":"uuid","description":"The file's identifier."},"fileName":{"type":"string","description":"The name the file was given, used to display it and to infer compression."},"size":{"type":"integer","format":"int64","description":"The file's size in bytes."},"status":{"type":"string","enum":["PENDING","IN_PROGRESS","PROCESSED","FAILED"],"description":"Where the file is in its life. Possible values:\n\n* `PENDING` – waiting to be imported.\n* `IN_PROGRESS` – a run has claimed it and is reading it.\n* `PROCESSED` – read to completion. Set only once its records have been written, so a run that\n  fails part-way leaves the file importable.\n* `FAILED` – the stream that read the file finished `FAILED`. The file could not be read\n  (malformed, truncated, wrong charset), or the import failed for another reason, such as the\n  target being unavailable. Such a file can be queued again with the content the service holds, or\n  uploaded again. Records that fail individually do not\n  put a file here: a stream that finishes with record failures still marks its file imported."},"loadRank":{"type":"integer","format":"int64","description":"The position in the drain order. For an incremental feed the order is part of the data: a later file's values win on a key an earlier one also carries."},"queuedAt":{"type":"string","format":"date-time","description":"When the file was added to the queue."},"processedAt":{"type":"string","format":"date-time","description":"When the file finished being imported."},"runId":{"type":"string","format":"uuid","description":"The run that consumed it."},"recordsRead":{"type":"integer","description":"How many records came out of it."},"message":{"type":"string","description":"Why the file ended as it did, when that needs saying — a file superseded by a newer snapshot in the same run, or one imported with record-level failures."}}},"errorMessage":{"title":"Error","description":"Schema for specific API errors.","type":"object","properties":{"code":{"type":"integer","description":"HTTP status code.","minimum":100,"maximum":599},"status":{"description":"The HTTP status reason phrase, for example `Conflict`.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"resourceId":{"description":"Identifier of the resource the error concerns, for example the configuration of a run that conflicts with an active run, or the run a retry was requested for. `null` when the error concerns no single resource.","type":"string","nullable":true},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"Error Detail","description":"One problem causing the error.","type":"object","properties":{"message":{"type":"string","description":"What is wrong."},"field":{"type":"string","description":"The field the problem concerns, when there is one."}}}}},"required":["status","code","message"]}},"responses":{"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"NotFound_404":{"description":"The requested resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"InternalServiceError_500":{"description":"An unexpected error occurred in the service. The body is the framework's default error body, not the error schema of the other responses.","content":{"application/json":{"schema":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time","description":"When the error occurred."},"status":{"type":"integer","description":"The HTTP status code."},"error":{"type":"string","description":"The HTTP status reason phrase."},"path":{"type":"string","description":"The request path."}}}}}}}},"paths":{"/importtool/{tenant}/streams/{streamId}/files/order":{"put":{"summary":"Setting the order in which files are imported","description":"Sets the order in which the waiting files are read. For an incremental feed the order is the data: a\nlater file's values win on a key an earlier one also carries, so an older export must be placed before\na newer one.\n\nThe request takes every waiting file's identifier, in load order, rather than moving one file: ranks\nare only meaningful relative to each other, and a partial list would leave the omitted files at their\nold ranks interleaved with the new ones. A list that is not exactly the waiting set is refused.\n\nThe request is refused while the job has a run in flight, which may be draining the queue as the order\nchanges.","operationId":"PUT-importtool-stream-file-order","tags":["Files"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Every waiting file's identifier, in the order they must be imported."}}}},"responses":{"200":{"description":"The request was successful. The queue is returned in its new order.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ImportFile"}}}}},"400":{"description":"The list is not exactly the set of waiting files.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"404":{"$ref":"#/components/responses/NotFound_404"},"409":{"description":"The job has a run in flight, or the queue is too long to be reordered in one request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"500":{"$ref":"#/components/responses/InternalServiceError_500"}}}}}}
```

## Removing a file from the queue

> Removes a waiting file and deletes the stored bytes with it. Only a waiting file can be removed: one\
> a run has claimed must not vanish underneath it, and one already imported is history — removing that\
> record would make the same bytes importable again, which is the one thing the file ledger exists to\
> prevent.\
> \
> The request is refused while the job has a run in flight: the run may claim the file at any moment,\
> and a retry may be waiting to re-read it.

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"tags":[{"name":"Files","description":"The queue of files a file-based stream imports: upload one, see what is waiting, change the load order, remove one, queue a failed one again."}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["importtool.import_trigger"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"importtool.import_trigger":"Needed to trigger, schedule, monitor, and cancel import runs; to manage a file-based stream's file queue; and to read configurations, streams, schedules, runs, and imported data."}}}}},"responses":{"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"NotFound_404":{"description":"The requested resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"InternalServiceError_500":{"description":"An unexpected error occurred in the service. The body is the framework's default error body, not the error schema of the other responses.","content":{"application/json":{"schema":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time","description":"When the error occurred."},"status":{"type":"integer","description":"The HTTP status code."},"error":{"type":"string","description":"The HTTP status reason phrase."},"path":{"type":"string","description":"The request path."}}}}}}},"schemas":{"errorMessage":{"title":"Error","description":"Schema for specific API errors.","type":"object","properties":{"code":{"type":"integer","description":"HTTP status code.","minimum":100,"maximum":599},"status":{"description":"The HTTP status reason phrase, for example `Conflict`.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"resourceId":{"description":"Identifier of the resource the error concerns, for example the configuration of a run that conflicts with an active run, or the run a retry was requested for. `null` when the error concerns no single resource.","type":"string","nullable":true},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"Error Detail","description":"One problem causing the error.","type":"object","properties":{"message":{"type":"string","description":"What is wrong."},"field":{"type":"string","description":"The field the problem concerns, when there is one."}}}}},"required":["status","code","message"]}}},"paths":{"/importtool/{tenant}/streams/{streamId}/files/{fileId}":{"delete":{"summary":"Removing a file from the queue","description":"Removes a waiting file and deletes the stored bytes with it. Only a waiting file can be removed: one\na run has claimed must not vanish underneath it, and one already imported is history — removing that\nrecord would make the same bytes importable again, which is the one thing the file ledger exists to\nprevent.\n\nThe request is refused while the job has a run in flight: the run may claim the file at any moment,\nand a retry may be waiting to re-read it.","operationId":"DELETE-importtool-stream-file","tags":["Files"],"responses":{"204":{"description":"The request was successful. The file is removed."},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"404":{"$ref":"#/components/responses/NotFound_404"},"409":{"description":"The file is no longer waiting — a run has claimed it or already imported it — or the job has a run in flight.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"500":{"$ref":"#/components/responses/InternalServiceError_500"}}}}}}
```

## Queuing a failed file again

> Puts a file whose import failed (\`status\` \`FAILED\`) back at the end of the stream's queue, so the next\
> run reads it again. The service reads the content it already holds for the file, so you do not need to\
> upload the file again. Use this after you fix the cause of the failure, for example a mapping.\
> \
> Only a failed file can be queued again. An imported file (\`status\` \`PROCESSED\`) cannot be queued again, because\
> importing an older snapshot again would overwrite newer data. When a file was imported with some\
> records failing, its status is \`PROCESSED\`: retry those records with the run's\
> \`POST /importtool/{tenant}/runs/{runId}/retry\` operation instead.\
> \
> On a snapshot stream, a run reads the newest file in the queue. So a failed file cannot be queued again after\
> a newer file has arrived for the stream, whether that file is imported, waiting or being read: queued again,\
> the older snapshot would be imported over the newer data. Upload a corrected current file instead. A stream\
> with incremental files reads its files in queue order, so this restriction does not apply.\
> \
> The request is refused while the job has a run in the \`QUEUED\`, \`RUNNING\`, or \`RESUMABLE\` status.

```json
{"openapi":"3.0.0","info":{"title":"Import Service","version":"0.0.1"},"tags":[{"name":"Files","description":"The queue of files a file-based stream imports: upload one, see what is waiting, change the load order, remove one, queue a failed one again."}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["importtool.import_trigger"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"importtool.import_trigger":"Needed to trigger, schedule, monitor, and cancel import runs; to manage a file-based stream's file queue; and to read configurations, streams, schedules, runs, and imported data."}}}}},"schemas":{"ImportFile":{"title":"Import file","type":"object","description":"One file a file-based stream has been given, and what became of it.","properties":{"id":{"type":"string","format":"uuid","description":"The file's identifier."},"fileName":{"type":"string","description":"The name the file was given, used to display it and to infer compression."},"size":{"type":"integer","format":"int64","description":"The file's size in bytes."},"status":{"type":"string","enum":["PENDING","IN_PROGRESS","PROCESSED","FAILED"],"description":"Where the file is in its life. Possible values:\n\n* `PENDING` – waiting to be imported.\n* `IN_PROGRESS` – a run has claimed it and is reading it.\n* `PROCESSED` – read to completion. Set only once its records have been written, so a run that\n  fails part-way leaves the file importable.\n* `FAILED` – the stream that read the file finished `FAILED`. The file could not be read\n  (malformed, truncated, wrong charset), or the import failed for another reason, such as the\n  target being unavailable. Such a file can be queued again with the content the service holds, or\n  uploaded again. Records that fail individually do not\n  put a file here: a stream that finishes with record failures still marks its file imported."},"loadRank":{"type":"integer","format":"int64","description":"The position in the drain order. For an incremental feed the order is part of the data: a later file's values win on a key an earlier one also carries."},"queuedAt":{"type":"string","format":"date-time","description":"When the file was added to the queue."},"processedAt":{"type":"string","format":"date-time","description":"When the file finished being imported."},"runId":{"type":"string","format":"uuid","description":"The run that consumed it."},"recordsRead":{"type":"integer","description":"How many records came out of it."},"message":{"type":"string","description":"Why the file ended as it did, when that needs saying — a file superseded by a newer snapshot in the same run, or one imported with record-level failures."}}},"errorMessage":{"title":"Error","description":"Schema for specific API errors.","type":"object","properties":{"code":{"type":"integer","description":"HTTP status code.","minimum":100,"maximum":599},"status":{"description":"The HTTP status reason phrase, for example `Conflict`.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"resourceId":{"description":"Identifier of the resource the error concerns, for example the configuration of a run that conflicts with an active run, or the run a retry was requested for. `null` when the error concerns no single resource.","type":"string","nullable":true},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"Error Detail","description":"One problem causing the error.","type":"object","properties":{"message":{"type":"string","description":"What is wrong."},"field":{"type":"string","description":"The field the problem concerns, when there is one."}}}}},"required":["status","code","message"]}},"responses":{"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"NotFound_404":{"description":"The requested resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"InternalServiceError_500":{"description":"An unexpected error occurred in the service. The body is the framework's default error body, not the error schema of the other responses.","content":{"application/json":{"schema":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time","description":"When the error occurred."},"status":{"type":"integer","description":"The HTTP status code."},"error":{"type":"string","description":"The HTTP status reason phrase."},"path":{"type":"string","description":"The request path."}}}}}}}},"paths":{"/importtool/{tenant}/streams/{streamId}/files/{fileId}/requeue":{"post":{"summary":"Queuing a failed file again","description":"Puts a file whose import failed (`status` `FAILED`) back at the end of the stream's queue, so the next\nrun reads it again. The service reads the content it already holds for the file, so you do not need to\nupload the file again. Use this after you fix the cause of the failure, for example a mapping.\n\nOnly a failed file can be queued again. An imported file (`status` `PROCESSED`) cannot be queued again, because\nimporting an older snapshot again would overwrite newer data. When a file was imported with some\nrecords failing, its status is `PROCESSED`: retry those records with the run's\n`POST /importtool/{tenant}/runs/{runId}/retry` operation instead.\n\nOn a snapshot stream, a run reads the newest file in the queue. So a failed file cannot be queued again after\na newer file has arrived for the stream, whether that file is imported, waiting or being read: queued again,\nthe older snapshot would be imported over the newer data. Upload a corrected current file instead. A stream\nwith incremental files reads its files in queue order, so this restriction does not apply.\n\nThe request is refused while the job has a run in the `QUEUED`, `RUNNING`, or `RESUMABLE` status.","operationId":"POST-importtool-stream-file-requeue","tags":["Files"],"responses":{"200":{"description":"The request was successful. The file is queued again in the `PENDING` status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportFile"}}}},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"404":{"$ref":"#/components/responses/NotFound_404"},"409":{"description":"The file has not failed, its stored content is no longer available, or it is not one of this stream's files. Also returned when a newer file arrived after it on a snapshot stream, and while the job has a run in flight.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"500":{"$ref":"#/components/responses/InternalServiceError_500"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.emporix.io/api-references/readme/api-reference-19/files.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
