They belong to the customs package and appear in execute and inspect responses documented at /docs/api/openapi.
#Why artifacts are first-class protocol outputs
Artifacts are not implementation leftovers. They are a core execution outcome.
That means clients can use artifact metadata to answer questions such as:
- Did execution generate the expected customs files?
- Which document variants exist right now?
- When were those files generated?
- Is the package ready for downstream broker handling?
This is especially useful for automation and AI clients because they should never need to scrape dashboard pages to infer file readiness.
#Artifact shape
The current stable artifact metadata includes:
| Field | Meaning |
|---|---|
artifact_type |
Machine-readable artifact category |
filename |
Human-recognizable generated filename |
generated_at |
Timestamp for generation |
#Current artifact types
#cci_human_readable
Filename: commercial_customs_invoice.html
Purpose:
- human-readable customs invoice view
- useful for broker review and operator inspection
#cci_csv
Filename: commercial_customs_invoice.csv
Purpose:
- flat tabular invoice export
- useful for reconciliation and spreadsheet workflows
#cci_json
Filename: commercial_customs_invoice.json
Purpose:
- structured machine-readable invoice payload
- best artifact for automation and AI systems
#packing_list
Filename: packing_list.json
Purpose:
- machine-readable summary of packed shipment contents
- useful for warehouse and broker workflows
#manifest
Filename: manifest.json
Purpose:
- compact package-level inventory of the export package
- useful for downstream indexing and validation
#Where artifacts appear
#Execute response
After POST /api/exports/execute, artifact metadata appears in the execution response so the caller can immediately see what the protocol generated.
#Inspect response
Artifacts also appear in GET /api/exports/{id} because inspect is the durable export read model.
#Customs package lookup
If you already know the package ID, GET /api/customs-packages/{id} provides package-level artifact inventory without the rest of the export state.
#How to use artifact metadata correctly
Use artifact metadata to:
- confirm generation happened
- inventory available files
- branch automation on file availability
- correlate the package state with broker handling
Do not assume artifact metadata alone means:
- a public download URL exists
- the document has been externally delivered
- the broker has acknowledged receipt
For those workflow questions, inspect the broader export state and broker submission state as well.
#Recommended client behavior
| Client type | Best practice |
|---|---|
| Human developer tools | Show artifact list alongside export status and broker submission |
| AI agents | Prefer cci_json and manifest for machine reasoning |
| Warehouse automation | Use package lookup when you only need package and artifact state |
#Operational rule
If artifact presence matters for a later action, check inspect or package lookup immediately before the action. Do not rely on stale cached file state from an earlier execute response.