Exports

Export records to a file

Start a bulk export and get back an id. The file is built in the background and downloaded from GET /api/v1/exports/{id}/download once status is completed — typically within a minute.

This is the answer to "give me everything we screened in Q3". It is a job rather than a large GET because a year of a real fleet does not fit inside a request timeout, and a response that dies halfway looks like a partial answer.

The row count is measured BEFORE the job is created. If the range holds more than 500,000 rows the request is refused with the real number, rather than producing a file that is silently short — an export missing rows is worse than no export, because everyone downstream treats it as complete.

If you leave filters.created_before out, it is pinned to the moment of the request and returned to you. That makes the export reproducible: without it, a job picked up a minute later would include rows written in between, and the same "Q3" request would produce a different file tomorrow.

An export reserves no quota and screens nothing. It reads records you already hold, and is governed by the same scope that governs reading them one at a time.

Required scope: any one of vessel:screen, cargo:screen, logs:read, whichever governs the resource you name.

post/api/v1/exports

Request

  • Base URL: https://arcnautical.com
  • URL: https://arcnautical.com/api/v1/exports
  • Auth: one of:
    • HTTP bearer
    • API key in header X-ArcNautical-Key
    • HTTP bearer
    • API key in header X-ArcNautical-Key
    • HTTP bearer
    • API key in header X-ArcNautical-Key

Headers

Idempotency-Keystring required

Required for resource-creating POST requests. The same key and identical body replay the original response for 24 hours; a different body returns idempotency_conflict.

Request body

resource'screenings' | 'cargo_screenings' | 'access_log' | 'voyage_assessments' required

What to export. Each is governed by the same scope that governs reading it one record at a time: screenings by vessel:screen, cargo_screenings by cargo:screen, access_log by logs:read.

format'csv' | 'jsonl'

csv is a flat summary with a UTF-8 BOM, for a spreadsheet. jsonl is one complete record per line — for screenings that is the full evidence, identical to GET /api/v1/screenings/{id}, including match detail and per-source freshness the CSV cannot carry.

Response

Export accepted and queued.

idstring uuid required
resource'screenings' | 'cargo_screenings' | 'access_log' | 'voyage_assessments' required

What to export. Each is governed by the same scope that governs reading it one record at a time: screenings by vessel:screen, cargo_screenings by cargo:screen, access_log by logs:read.

format'csv' | 'jsonl' required
status'queued' | 'running' | 'completed' | 'failed' required
filtersobject required

The filters as applied, including the pinned created_before.

estimated_row_countinteger nullable

Rows matched when the export was accepted.

row_countinteger nullable

Rows actually written. Null until completed.

byte_sizeinteger nullable
checksum_sha256string nullable

SHA-256 of the file body, hex.

download_urlstring

Present only when status is completed.

download_countinteger
downloaded_atstring date-time nullable
created_atstring date-time required
completed_atstring date-time nullable
expires_atstring date-time required

When the FILE is deleted. The records it was built from are unaffected.

Changes

No recorded changes to this operation across all 1 revision of this API.