{ "openapi": "3.0.1", "info": { "title": "AgriBackup Enterprise EUDR API", "description": "# Introduction\n\nAgriBackup is the cryptographic compliance engine for EU-bound commodity imports. Built on Deterministic Logic, Immutable Evidence, and High-Throughput Ingestion, our API provides Tier-1 enterprise routing for EU Deforestation Regulation (EUDR).\n\n## The Integration Vector\nTo integrate this Digital Trust Layer into your ERP, you must execute the following sequence:\n1. **Authentication:** Generate your `X-API-Key` from the client dashboard.\n2. **Telemetry:** Register your webhook URLs via `POST /webhooks`.\n3. **Ingestion:** Push your GeoJSON polygons via `POST /polygons`.\n4. **Logistics:** Lock the batch to a shipment via `POST /shipments/link`.\n\n## Asynchronous Architecture\nBecause satellite deforestation screening and Hedera DLT anchoring take time, ingestion endpoints return a `202 Accepted`. You must listen for the corresponding Webhook to confirm cryptographic execution.\n\n## Base URLs\n* **Production:** `https://live.agribackup.com`\n* **Sandbox:** `https://sandbox.agribackup.com`", "contact": { "name": "AgriBackup Architecture Team", "url": "https://agribackup.com", "email": "contact@agribackup.com" }, "license": { "name": "Proprietary", "url": "https://agribackup.com/terms" }, "version": "v1.0" }, "servers": [ { "url": "https://live.agribackup.com", "description": "Production (Mainnet)" }, { "url": "https://sandbox.agribackup.com", "description": "Sandbox (Testnet)" } ], "tags": [ { "name": "Introduction" }, { "name": "Enterprise API Keys" }, { "name": "Enterprise Credentials" }, { "name": "Enterprise Webhooks" }, { "name": "Enterprise Suppliers" }, { "name": "Enterprise Polygons" }, { "name": "Enterprise Logistics" }, { "name": "Enterprise Batches" }, { "name": "Enterprise Risk Management" }, { "name": "Enterprise Jobs" }, { "name": "Enterprise Declarations" }, { "name": "Enterprise Evidence" }, { "name": "Enterprise Archival" }, { "name": "Enterprise Diagnostics" } ], "paths": { "/api/v1/enterprise/api-keys": { "post": { "tags": [ "Enterprise API Keys" ], "summary": "Generate a new API Key", "description": "Generates a new secure machine-to-machine API Key. Note: The initial API key must be generated via the AgriBackup Developer Dashboard using a standard human login (JWT). Subsequent keys can be generated programmatically for automated rotation.", "operationId": "createApiKey", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreateRequest" } } }, "required": true }, "responses": { "201": { "description": "API Key generated", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyGenerationResponse" } } } } }, "security": [ { "bearerAuth": [] } ] }, "get": { "tags": [ "Enterprise API Keys" ], "summary": "List API Keys", "description": "Returns a list of all active API keys for the organization (without raw keys).", "operationId": "listApiKeys", "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "*/*": { "schema": { "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/enterprise/api-keys/{keyId}": { "delete": { "tags": [ "Enterprise API Keys" ], "summary": "Delete an API Key", "description": "Permanently removes an API key.", "operationId": "deleteApiKey", "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "*/*": { "schema": { "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/enterprise/api-keys/{keyId}/rotate": { "post": { "tags": [ "Enterprise API Keys" ], "summary": "Rotate an API Key", "description": "Deactivates the old key and generates a new raw key with the same configuration.", "operationId": "rotateApiKey", "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "*/*": { "schema": { "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "bearerAuth": [] } ] } }, "/api/v1/enterprise/eudr/batches": { "post": { "tags": [ "Enterprise Batches" ], "summary": "Register a consolidated EUDR batch (Async)", "description": "Programmatically create a new EUDR batch linked to an array of pre-verified Polygon IDs. Automatically registers sourcing events and triggers a Copernicus risk assessment check. Returns 202 instantly.", "operationId": "registerBatch", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey", "schema": { "type": "string" } }, { "name": "X-Sub-Organization-ID", "in": "header", "required": false, "$ref": "#/components/parameters/SubOrganizationId", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRegistrationRequest" } } }, "required": true }, "responses": { "202": { "description": "Batch registered and risk assessment queued", "headers": { "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-Trace-Id": { "description": "Unique request trace identifier", "style": "simple", "schema": { "type": "string" } }, "Location": { "description": "URL to track the job status", "style": "simple", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAcceptedResponse" } } } }, "400": { "description": "Bad Request", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "Payload Too Large: Maximum allowed array size is 5000.", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "423": { "description": "Locked: Execution thread is currently processing the resource. Wait and retry.", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "tags": [ "Enterprise Batches" ], "summary": "List Batches", "description": "Retrieves a cursor-paginated list of registered EUDR batches.", "operationId": "getBatches", "parameters": [ { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "updated_after", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "default": 100 } } ], "responses": { "200": { "description": "List of batches successfully retrieved", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnterpriseBatchCollectionResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/enterprise/eudr/batches/{batchId}": { "get": { "tags": [ "Enterprise Batches" ], "summary": "Get batch by ID", "description": "Returns the consolidated risk state and linked shipment IDs for a single EUDR batch.", "operationId": "getBatchById", "parameters": [ { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Batch details retrieved successfully", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchDetailResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Batch not found", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "tags": [ "Enterprise Batches" ], "summary": "Update an EUDR batch", "description": "Updates batch details if it is not cryptographically linked to a shipment or TRACES NT.", "operationId": "updateBatch", "parameters": [ { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchUpdateRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "*/*": { "schema": { "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Enterprise Batches" ], "summary": "Delete an EUDR batch", "description": "Deletes a batch if it is not cryptographically linked to a shipment or TRACES NT.", "operationId": "deleteBatch", "parameters": [ { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "*/*": { "schema": { "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/enterprise/eudr/credentials/traces": { "post": { "tags": [ "Enterprise Credentials" ], "summary": "Ingest TRACES NT Credentials into Vault", "description": "Accepts the raw TRACES NT API token/password, symmetrically encrypts it via HashiCorp Vault Transit Engine, and stores the resulting ciphertext reference.", "operationId": "ingestTracesCredentials", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TracesCredentialRequest" } } }, "required": true }, "responses": { "200": { "description": "Credentials successfully encrypted and anchored in Vault", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialIngestionResponse" } } } }, "400": { "description": "Bad Request", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Enterprise Credentials" ], "summary": "Revoke and purge TRACES NT credentials", "description": "Deletes the organization's TRACES NT credentials reference from the database, permanently revoking delegation. Due to our stateless transit-based encryption, clearing the ciphertext reference completely purges the secret from the system.", "operationId": "deleteTracesCredentials", "responses": { "204": { "description": "Credentials successfully purged", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } } }, "401": { "description": "Unauthorized", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/enterprise/eudr/credentials/traces/status": { "get": { "tags": [ "Enterprise Credentials" ], "summary": "Check TRACES NT credential delegation status", "description": "Verifies if the credentials registered in HashiCorp Vault for this organization are valid by executing a connection test to the TRACES NT SOAP API.", "operationId": "getTracesCredentialsStatus", "responses": { "200": { "description": "Status checked successfully", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TracesCredentialStatusResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/enterprise/eudr/declarations/dds": { "post": { "tags": [ "Enterprise Declarations" ], "summary": "Generate Due Diligence Statement (DDS)", "description": "Generates a TRACES NT compliant DDS. Autonomously anchors provided legal_document_hashes to the Hedera ledger for land tenure proof.", "operationId": "generateDds", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DdsGenerationRequest" } } }, "required": true }, "responses": { "202": { "description": "DDS generation request accepted and queued for processing.", "headers": { "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-Trace-Id": { "description": "Unique request trace identifier", "style": "simple", "schema": { "type": "string" } }, "Location": { "description": "URL to track the job status", "style": "simple", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAcceptedResponse" } } } }, "400": { "description": "Bad Request (e.g. invalid array of polygon IDs)", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not Found (One or more provided polygon IDs do not exist or belong to another organization)", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "423": { "description": "Locked: Execution thread is currently processing the resource. Wait and retry.", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "tags": [ "Enterprise Declarations" ], "summary": "List Generated Due Diligence Statements", "description": "Returns a cursor-paginated list of generated DDS payloads and their Hedera consensus states.", "operationId": "listDdsPayloads", "parameters": [ { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "default": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "*/*": { "schema": { "$ref": "#/components/schemas/EnterpriseDdsCollectionResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/enterprise/eudr/declarations/dds/{referenceId}": { "get": { "tags": [ "Enterprise Declarations" ], "summary": "Retrieve finalized DDS payload", "description": "Returns the TRACES NT V3 XML payload and Hedera consensus timestamp once async DDS generation completes.", "operationId": "getDdsPayload", "parameters": [ { "name": "referenceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "DDS payload retrieved successfully", "headers": { "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-Trace-Id": { "description": "Unique request trace identifier", "style": "simple", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DdsRetrievalResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "DDS reference not found", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/enterprise/eudr/declarations/dds/{referenceId}/revoke": { "post": { "tags": [ "Enterprise Declarations" ], "summary": "Revoke a submitted DDS", "description": "Dispatches a revocation request to TRACES NT and anchors the revocation timestamp and receipt on Hedera.", "operationId": "revokeDds", "parameters": [ { "name": "referenceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "DDS successfully revoked", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TracesRevocationResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden (not DDS owner)", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "DDS reference not found", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/enterprise/eudr/declarations/dds/{referenceId}/submit": { "post": { "tags": [ "Enterprise Declarations" ], "summary": "Submit DDS to TRACES NT", "description": "Executes the SOAP API handshake with TRACES NT utilizing Vault-decrypted tokens, and returns the official EU reference number.", "operationId": "submitDds", "parameters": [ { "name": "referenceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "DDS successfully submitted", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TracesSubmissionResponse" } } } }, "400": { "description": "Bad Request (Missing Idempotency-Key)", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden (not DDS owner)", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "DDS reference not found", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Bad Gateway (TRACES NT error)", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/enterprise/eudr/declarations/documents/upload": { "post": { "tags": [ "Enterprise Declarations" ], "summary": "Upload Legal Land Tenure Document", "description": "Ingests physical PDF or binary documents required by TRACES NT, returns a secure cryptographic hash and internal reference URL for inclusion in the DDS payload.", "operationId": "uploadDocument", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey", "schema": { "type": "string" } }, { "name": "documentUrl", "in": "query", "description": "A presigned URL to fetch the document from asynchronously", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "description": "The physical file to upload (PDF, JPG, PNG allowed)", "format": "binary" } } } } } }, "responses": { "200": { "description": "Document successfully ingested and secured", "headers": { "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-Trace-Id": { "description": "Unique request trace identifier", "style": "simple", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentUploadResponse" } } } }, "400": { "description": "Invalid file format", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/enterprise/eudr/evidence/ledger/batch/{batchId}": { "get": { "tags": [ "Enterprise Evidence" ], "summary": "Retrieve batch cryptographic evidence", "description": "Returns raw Hedera transaction IDs, state proofs, and Merkle root hashes for a consolidated EUDR batch. All anchoring is on the Hedera DLT layer.", "operationId": "getBatchLedgerEvidence", "parameters": [ { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Batch ledger evidence retrieved", "headers": { "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-Trace-Id": { "description": "Unique request trace identifier", "style": "simple", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerEvidenceResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Batch not found", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/enterprise/eudr/evidence/ledger/polygon/{polygonId}": { "get": { "tags": [ "Enterprise Evidence" ], "summary": "Retrieve polygon cryptographic evidence", "description": "Returns raw Hedera transaction IDs, state proofs, and Merkle root hashes for a verified production polygon.", "operationId": "getPolygonLedgerEvidence", "parameters": [ { "name": "polygonId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Polygon ledger evidence retrieved", "headers": { "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-Trace-Id": { "description": "Unique request trace identifier", "style": "simple", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerEvidenceResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Polygon not found", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/enterprise/eudr/evidence/ledger/shipment/{shipmentId}": { "get": { "tags": [ "Enterprise Evidence" ], "summary": "Retrieve shipment cryptographic evidence", "description": "Traverses the supply chain graph to locate all EUDR batches mathematically linked to this shipment ID or Bill of Lading, returning their consolidated Hedera state proofs.", "operationId": "getShipmentLedgerEvidence", "parameters": [ { "name": "shipmentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Shipment ledger evidence retrieved", "headers": { "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-Trace-Id": { "description": "Unique request trace identifier", "style": "simple", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerEvidenceResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Shipment not found or not linked to any batches", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/enterprise/eudr/health": { "get": { "tags": [ "Enterprise Diagnostics" ], "summary": "Check infrastructure and service dependency health", "description": "Returns the real-time operational status, network latency, and synchronization metadata for upstream dependencies (Hedera, Copernicus CDSE, and HashiCorp Vault).", "operationId": "checkHealth", "responses": { "200": { "description": "Health status retrieved successfully", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/enterprise/eudr/jobs/{jobId}": { "get": { "tags": [ "Enterprise Jobs" ], "summary": "Retrieve job status and metrics", "description": "Returns current progress metrics, validation results, and Hedera Merkle proofs for a specific job.", "operationId": "getJobStatus", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Job details retrieved successfully", "headers": { "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "Retry-After": { "description": "Number of seconds to wait before polling again (only present if job is not completed)", "style": "simple", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnterpriseJobStatusResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Job Not Found", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Enterprise Jobs" ], "summary": "Halt asynchronous ingestion processing", "description": "Immediately signals the ingestion engine to stop processing pending items and transition the job state to CANCELLED.", "operationId": "cancelJob", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Job successfully cancelled and pending items purged", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "*/*": { "schema": { "type": "object" } } } }, "400": { "description": "Bad Request (already completed or failed)", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Job not found", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/enterprise/eudr/polygons": { "post": { "tags": [ "Enterprise Polygons" ], "summary": "Ingest GeoJSON Polygons (Async)", "description": "Programmatically ingest farm/production unit polygons. Returns 202 instantly. The bulk ingestion engine runs deforestation checks and fires 'polygon.verified' webhook upon completion.", "operationId": "ingestPolygons", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey", "schema": { "type": "string" } }, { "name": "X-Sub-Organization-ID", "in": "header", "required": false, "$ref": "#/components/parameters/SubOrganizationId", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolygonIngestionRequest" } } }, "required": true }, "responses": { "202": { "description": "Polygon ingestion accepted and queued for verification", "headers": { "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-Trace-Id": { "description": "Unique request trace identifier", "style": "simple", "schema": { "type": "string" } }, "Location": { "description": "The relative URI path to track the lifecycle phase and final cryptographic consensus receipts for this job.", "style": "simple", "schema": { "type": "string", "example": "/api/v1/enterprise/eudr/jobs/job_998877" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAcceptedResponse" } } } }, "400": { "description": "Bad Request", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "Payload Too Large: Maximum allowed array size is 5000.", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "423": { "description": "Locked: Execution thread is currently processing the resource. Wait and retry.", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "tags": [ "Enterprise Polygons" ], "summary": "List Verified Polygons", "description": "Retrieves a cursor-paginated list of all verified farm boundary polygons matching the organization scope.", "operationId": "getPolygons", "parameters": [ { "name": "starting_after", "in": "query", "description": "Cursor to retrieve the next page of results", "required": false, "schema": { "type": "string" }, "example": "uuid-1234" }, { "name": "updated_after", "in": "query", "description": "Filter for polygons updated after this ISO-8601 timestamp", "required": false, "schema": { "type": "string" }, "example": "2026-01-01T00:00:00Z" }, { "name": "limit", "in": "query", "description": "Maximum number of records to return", "required": false, "schema": { "type": "integer", "format": "int32", "default": 100 }, "example": 100 }, { "name": "status", "in": "query", "description": "Filter by compliance status", "required": false, "schema": { "type": "string", "enum": [ "PENDING", "COMPLIANT", "HIGH_RISK" ] }, "example": "COMPLIANT" } ], "responses": { "200": { "description": "List of polygons successfully retrieved", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnterprisePolygonCollectionResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/enterprise/eudr/polygons/{polygonId}": { "get": { "tags": [ "Enterprise Polygons" ], "summary": "Get Polygon compliance status", "description": "Synchronously query the deterministic EUDR compliance status (PENDING, COMPLIANT, HIGH_RISK) of a specific polygon before linking it to a high-value shipment.", "operationId": "getPolygonStatus", "parameters": [ { "name": "polygonId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Polygon status retrieved successfully", "headers": { "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-Trace-Id": { "description": "Unique request trace identifier", "style": "simple", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolygonStatusResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Polygon not found", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Enterprise Polygons" ], "summary": "Delete Polygon", "description": "Deletes a polygon if it is not cryptographically linked to a batch or shipment.", "operationId": "deletePolygon", "parameters": [ { "name": "polygonId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "*/*": { "schema": { "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/enterprise/eudr/reports/archive": { "post": { "tags": [ "Enterprise Archival" ], "summary": "Generate Bulk Archive Report", "description": "Asynchronously compiles XML payloads, Hedera state proofs, and legal document hashes into a single cryptographic ZIP artifact. Triggers a 'report.ready' webhook upon completion.", "operationId": "triggerArchiveReport", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchiveReportRequest" } } }, "required": true }, "responses": { "202": { "description": "Request accepted for processing", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ArchiveReportResponse" } } } }, "400": { "description": "Invalid request parameters", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ArchiveReportResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ArchiveReportResponse" } } } }, "429": { "description": "Too Many Requests", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ArchiveReportResponse" } } } } } } }, "/api/v1/enterprise/eudr/reports/archive/{reportId}/download": { "get": { "tags": [ "Enterprise Archival" ], "summary": "Download Bulk Archive ZIP", "description": "Retrieves the compiled ZIP artifact. The download link is temporary and time-limited.", "operationId": "downloadArchiveReport", "parameters": [ { "name": "reportId", "in": "path", "description": "The unique report identifier", "required": true, "schema": { "type": "string" }, "example": "rep_9a8b7c" } ], "responses": { "200": { "description": "Successful download", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/zip": {} } }, "401": { "description": "Unauthorized", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Report not found or expired", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } } } } }, "/api/v1/enterprise/eudr/risk/assess-coordinate": { "post": { "tags": [ "Enterprise Risk Management" ], "summary": "Assess risk by coordinate (Pre-Assessment)", "description": "Runs Country Risk Matrix lookups and satellite Sentinel-2 deforestation analysis on-the-fly for a coordinate, returning predictive risk metrics without registering a batch.", "operationId": "assessCoordinateRisk", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoordinateRiskRequest" } } }, "required": true }, "responses": { "200": { "description": "Risk assessment computed successfully", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoordinateRiskAssessmentResponse" } } } }, "400": { "description": "Invalid coordinate format or out of bounds", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/enterprise/eudr/shipments/link": { "post": { "tags": [ "Enterprise Logistics" ], "summary": "Cryptographically link a batch to a shipment (Async)", "description": "Invokes the [BATCH_SHIPMENT_GATEKEEPER] Hedera Smart Contract to lock a verified batch to a logistics shipment. Emits a 'shipment.linked' webhook upon blockchain consensus.", "operationId": "linkBatchToShipment", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentLinkRequest" } } }, "required": true }, "responses": { "202": { "description": "Smart contract lock initiated asynchronously", "headers": { "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-Trace-Id": { "description": "Unique request trace identifier", "style": "simple", "schema": { "type": "string" } }, "Location": { "description": "The relative URI path to track the lifecycle phase and final cryptographic consensus receipts for this job.", "style": "simple", "schema": { "type": "string", "example": "/api/v1/enterprise/eudr/jobs/job_998877" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAcceptedResponse" } } } }, "400": { "description": "Bad Request (e.g., Invalid Batch ID or invalid payload structure)", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Hedera EVM State Violation (e.g., Shipment already linked, double-spend attempt)", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "423": { "description": "Locked: Execution thread is currently processing the resource. Wait and retry.", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/enterprise/eudr/shipments/{batchId}/shipment/{shipmentId}": { "delete": { "tags": [ "Enterprise Logistics" ], "summary": "Unlink a Batch from a Shipment (EVM Rollback)", "description": "Asynchronously rollback the Hedera smart contract lock, freeing the batch for reassignment. Essential for logistics cancellations at the port.", "operationId": "unlinkShipment", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey", "schema": { "type": "string" } }, { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "shipmentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Smart contract unlock initiated asynchronously", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAcceptedResponse" } } } }, "400": { "description": "Bad Request (e.g., Invalid Batch ID)", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/enterprise/eudr/suppliers": { "post": { "tags": [ "Enterprise Suppliers" ], "summary": "Register Supplier Mapping", "description": "Binds an internal ERP Vendor ID to an official EU TRACES Operator UUID.", "operationId": "registerSupplier", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnterpriseSupplierRequest" } } }, "required": true }, "responses": { "200": { "description": "Supplier successfully mapped", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnterpriseSupplierResponse" } } } }, "400": { "description": "Invalid payload", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "tags": [ "Enterprise Suppliers" ], "summary": "List Supplier Mappings", "description": "Retrieves all mapped suppliers for the enterprise.", "operationId": "listSuppliers", "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "*/*": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EnterpriseSupplierResponse" } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/enterprise/eudr/suppliers/{vendorId}": { "get": { "tags": [ "Enterprise Suppliers" ], "summary": "Get Supplier Mapping", "description": "Retrieves the mapping for a specific internal ERP Vendor ID.", "operationId": "getSupplier", "parameters": [ { "name": "vendorId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "*/*": { "schema": { "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/enterprise/eudr/webhooks": { "post": { "tags": [ "Enterprise Webhooks" ], "summary": "Register Webhook Endpoint", "description": "Registers an enterprise URL to receive asynchronous compliance events like shipment.linked and polygon.verified. Webhook payloads are cryptographically signed using HMAC-SHA256 with the generated signing secret, and sent in the 'X-AgriBackup-Signature' header for verification.\n\nTo verify webhook authenticity:\n1. Extract the raw POST request body bytes/string.\n2. Extract the signature value from the 'X-AgriBackup-Signature' HTTP header.\n3. Calculate the HMAC-SHA256 hash of the raw body using the registered signing secret.\n4. Hex-encode the calculated hash.\n5. Perform a constant-time comparison between the hex-encoded hash and the header signature to avoid timing attacks.", "operationId": "registerWebhook", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRegistrationRequest" } } }, "required": true }, "responses": { "200": { "description": "Webhook successfully registered", "headers": { "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-Trace-Id": { "description": "Unique request trace identifier", "style": "simple", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRegistrationResponse" } } } }, "400": { "description": "Bad Request (e.g. invalid URL format or unsupported event type)", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict (Webhook for this event and URL already exists)", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "423": { "description": "Locked: Execution thread is currently processing the resource. Wait and retry.", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "callbacks": { "shipment.linked": { "{$request.body#/targetUrl}": { "post": { "summary": "Shipment Linked Event", "description": "Fired when a batch shipment is successfully anchored.", "parameters": [ { "name": "X-AgriBackup-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": {"$ref": "#/components/schemas/WebhookShipmentLinkedPayload"} } } }, "responses": { "200": { "description": "Successfully processed by enterprise" } } } } }, "polygon.verified": { "{$request.body#/targetUrl}": { "post": { "summary": "Polygon Verified Event", "description": "Fired when a polygon ingestion job completes.", "parameters": [ { "name": "X-AgriBackup-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": {"$ref": "#/components/schemas/WebhookPolygonVerifiedPayload"} } } }, "responses": { "200": { "description": "Successfully processed by enterprise" } } } } }, "batch.risk_assessed": { "{$request.body#/targetUrl}": { "post": { "summary": "Batch Risk Assessed Event", "description": "Fired when Copernicus NDVI risk assessment completes for a batch.", "parameters": [ { "name": "X-AgriBackup-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully processed by enterprise" } } } } }, "dds.submitted": { "{$request.body#/targetUrl}": { "post": { "summary": "DDS Submitted Event", "description": "Fired when the TRACES NT handshake succeeds and places the payload in the queue.", "parameters": [ { "name": "X-AgriBackup-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully processed by enterprise" } } } } }, "dds.validated": { "{$request.body#/targetUrl}": { "post": { "summary": "DDS Validated Event", "description": "Fired asynchronously by TRACES NT when the DDS is fully validated and clears border checks.", "parameters": [ { "name": "X-AgriBackup-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully processed by enterprise" } } } } }, "dds.rejected": { "{$request.body#/targetUrl}": { "post": { "summary": "DDS Rejected Event", "description": "Fired asynchronously by TRACES NT if the payload is rejected due to internal cross-checks (e.g., mismatched Operator UUIDs).", "parameters": [ { "name": "X-AgriBackup-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully processed by enterprise" } } } } }, "job.failed": { "{$request.body#/targetUrl}": { "post": { "summary": "Job Failed Event", "description": "Critical for alerting the ERP if an asynchronous thread crashes.", "parameters": [ { "name": "X-AgriBackup-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully processed by enterprise" } } } } }, "report.ready": { "{$request.body#/targetUrl}": { "post": { "summary": "Bulk Archival Report Ready Event", "description": "Fired when an asynchronous bulk report generation job completes successfully.", "parameters": [ { "name": "X-AgriBackup-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully processed by enterprise" } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "tags": [ "Enterprise Webhooks" ], "summary": "List Active Webhook Subscriptions", "description": "Retrieves all active webhook registrations registered for this organization. Cryptographic signing secrets are redacted for security.", "operationId": "getWebhooks", "responses": { "200": { "description": "List of active webhooks successfully retrieved", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Forbidden", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/enterprise/eudr/webhooks/dlq": { "get": { "tags": [ "Enterprise Webhooks" ], "summary": "Retrieve permanently failed webhook payloads", "description": "Pulls failed webhook payloads from the Dead-Letter Queue (DLQ). These are messages that exhausted their retry limits.", "operationId": "getDlqMessages", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "default": 10 } }, { "name": "startingAfter", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "*/*": { "schema": { "$ref": "#/components/schemas/WebhookDlqResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/enterprise/eudr/webhooks/dlq/bulk": { "delete": { "tags": [ "Enterprise Webhooks" ], "summary": "Acknowledge and delete multiple DLQ messages", "operationId": "deleteBulkDlqMessages", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDlqBulkRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/enterprise/eudr/webhooks/dlq/replay-bulk": { "post": { "tags": [ "Enterprise Webhooks" ], "summary": "Replay multiple DLQ messages to the primary exchange", "operationId": "replayBulkDlqMessages", "parameters": [ { "name": "startDate", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "endDate", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "eventType", "in": "query", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDlqBulkRequest" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/enterprise/eudr/webhooks/dlq/{eventId}": { "delete": { "tags": [ "Enterprise Webhooks" ], "summary": "Acknowledge and delete a DLQ message", "operationId": "deleteDlqMessage", "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/enterprise/eudr/webhooks/dlq/{eventId}/replay": { "post": { "tags": [ "Enterprise Webhooks" ], "summary": "Replay a DLQ message to the primary exchange", "operationId": "replayDlqMessage", "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/enterprise/eudr/webhooks/{webhookId}": { "delete": { "tags": [ "Enterprise Webhooks" ], "summary": "Delete a Webhook Registration", "operationId": "deleteWebhook", "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "*/*": { "schema": { "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/enterprise/eudr/webhooks/{webhookId}/ping": { "post": { "tags": [ "Enterprise Webhooks" ], "summary": "Webhook Cryptographic Handshake (Ping)", "description": "Dispatches a mock 'webhook.ping' event to the registered URL using the configured signing secret. This allows enterprise infosec teams to validate their HMAC-SHA256 signature verification algorithms in isolation without triggering a live data ingestion.", "operationId": "pingWebhook", "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "*/*": { "schema": { "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/enterprise/eudr/webhooks/{webhookId}/rotate-secret": { "post": { "tags": [ "Enterprise Webhooks" ], "summary": "Rotate Webhook Secret", "description": "Regenerates and returns a new HMAC-SHA256 signing secret for the specified webhook subscription.", "operationId": "rotateSecret", "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "The maximum number of requests you're permitted to make per hour.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current rate limit window.", "schema": { "type": "integer", "format": "int32" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets in UTC epoch seconds.", "schema": { "type": "integer", "format": "int32" } } }, "content": { "*/*": { "schema": { "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } } }, "components": { "schemas": { "GeoJsonCoordinates": { "type": "array", "description": "Polygon: number[][][], MultiPolygon: number[][][][] conforming to RFC 7946", "items": { "type": "array", "items": { "maxItems": 2, "minItems": 2, "type": "array", "items": { "type": "number", "format": "double" } } } }, "WebhookRegistrationRequest": { "required": [ "eventTypes", "targetUrl" ], "type": "object", "properties": { "targetUrl": { "pattern": "^https://.*", "type": "string", "description": "The enterprise endpoint URL to receive POST events", "format": "uri", "example": "https://erp.example.com/agribackup-webhooks" }, "eventTypes": { "type": "array", "example": [ "shipment.linked", "polygon.verified", "batch.risk_assessed", "dds.submitted", "dds.validated", "dds.rejected", "job.failed", "report.ready" ], "items": { "type": "string", "description": "Event type to subscribe to", "enum": [ "shipment.linked", "polygon.verified", "batch.risk_assessed", "dds.submitted", "dds.validated", "dds.rejected", "job.failed", "report.ready" ] } } }, "description": "Payload to register a webhook listener" }, "ApiError": { "required": [ "code", "details", "message" ], "type": "object", "properties": { "code": { "type": "string", "description": "Error code", "example": "VALIDATION_FAILED" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid polygon coordinates" }, "details": { "type": "array", "description": "Detailed list of validation errors, if applicable", "items": { "$ref": "#/components/schemas/ApiErrorDetail" } } }, "description": "Standard error format for all Enterprise API failures" }, "ApiErrorDetail": { "required": [ "code", "field", "issue" ], "type": "object", "properties": { "code": { "type": "string", "description": "Programmatic error code for automated branch logic", "example": "INVALID_COORDINATE_CLOSURE" }, "field": { "type": "string", "description": "The field or property that caused the error", "example": "features[0].properties.area" }, "issue": { "type": "string", "description": "A description of the issue with the field", "example": "Area must be specified in hectares and cannot be negative" } }, "description": "Detailed error information for a specific field" }, "WebhookRegistrationResponse": { "required": [ "signingSecret", "status", "targetUrl", "webhookId" ], "type": "object", "properties": { "webhookId": { "type": "string", "description": "The unique identifier of the webhook registration", "example": "wh_12345" }, "status": { "type": "string", "description": "Status of registration", "example": "REGISTERED" }, "targetUrl": { "type": "string", "description": "The registered callback target URL", "example": "https://erp.example.com/agribackup-webhooks" }, "signingSecret": { "type": "string", "description": "Cryptographic signing secret used to verify webhook payloads. Payloads sent to your callback URL are signed with HMAC-SHA256 using this secret and included in the 'X-AgriBackup-Signature' header. Verify by hashing the raw request body with this secret and comparing with the header value.", "example": "whsec_0123456789abcdef" } }, "description": "Response payload after registering a webhook" }, "ShipmentLinkedData": { "required": [ "batchId", "shipmentReference", "transactionHash" ], "type": "object", "properties": { "batchId": { "type": "string", "description": "The batch ID", "example": "batch_12345" }, "shipmentReference": { "type": "string", "description": "The shipment reference", "example": "SHIP-2026-001" }, "transactionHash": { "type": "string", "description": "Hedera transaction ID or hash", "example": "0.0.12345@1234567890.000000000" } }, "description": "Shipment Linked Data" }, "WebhookShipmentLinkedPayload": { "required": [ "attempt", "data", "eventId", "eventType", "timestamp" ], "type": "object", "properties": { "eventType": { "type": "string", "description": "The type of the event", "example": "shipment.linked" }, "eventId": { "type": "string", "description": "Event unique ID", "example": "evt_9988776655" }, "timestamp": { "type": "string", "description": "Timestamp of the event", "format": "date-time", "example": "2026-06-12T12:00:00Z" }, "attempt": { "type": "integer", "description": "The retry attempt number. 0 for the original broadcast.", "format": "int32", "example": 0 }, "nextRetry": { "type": "string", "description": "The scheduled timestamp for the next retry attempt if this delivery fails", "format": "date-time", "example": "2026-06-12T12:05:00Z" }, "data": { "$ref": "#/components/schemas/ShipmentLinkedData" } }, "description": "Payload sent to registered endpoints when a shipment is linked to a batch" }, "PolygonVerifiedData": { "required": [ "jobId", "polygonIds", "polygonsFailed", "polygonsVerified", "status" ], "type": "object", "properties": { "jobId": { "type": "string", "description": "The ingestion job ID", "example": "job_998877" }, "polygonsVerified": { "type": "integer", "description": "Number of polygons successfully verified", "format": "int32", "example": 150 }, "polygonsFailed": { "type": "integer", "description": "Number of polygons that failed verification", "format": "int32", "example": 3 }, "status": { "type": "string", "description": "Overall status", "example": "COMPLETED" }, "polygonIds": { "type": "array", "description": "Array of successfully generated unique Polygon IDs", "items": { "type": "string", "description": "Array of successfully generated unique Polygon IDs" } } }, "description": "Polygon Verified Data" }, "WebhookPolygonVerifiedPayload": { "required": [ "attempt", "data", "eventId", "eventType", "timestamp" ], "type": "object", "properties": { "eventType": { "type": "string", "description": "The type of the event", "example": "polygon.verified" }, "eventId": { "type": "string", "description": "Event unique ID", "example": "evt_1122334455" }, "timestamp": { "type": "string", "description": "Timestamp of the event", "format": "date-time", "example": "2026-06-12T12:00:00Z" }, "attempt": { "type": "integer", "description": "The retry attempt number. 0 for the original broadcast.", "format": "int32", "example": 0 }, "nextRetry": { "type": "string", "description": "The scheduled timestamp for the next retry attempt if this delivery fails", "format": "date-time", "example": "2026-06-12T12:05:00Z" }, "data": { "$ref": "#/components/schemas/PolygonVerifiedData" } }, "description": "Payload sent to registered endpoints when a polygon ingestion job completes" }, "WebhookDlqBulkRequest": { "required": [ "eventIds" ], "type": "object", "properties": { "eventIds": { "type": "array", "description": "List of event IDs to process", "example": [ "evt_123", "evt_456" ], "items": { "type": "string", "description": "List of event IDs to process", "example": "[\"evt_123\",\"evt_456\"]" } } }, "description": "Request payload for bulk DLQ operations" }, "EnterpriseSupplierRequest": { "required": [ "companyName", "operatorUuid", "vendorId" ], "type": "object", "properties": { "vendorId": { "type": "string", "description": "Internal ERP Vendor ID", "example": "VEND-1002" }, "operatorUuid": { "type": "string", "description": "Official EU TRACES NT Operator UUID", "example": "123e4567-e89b-12d3-a456-426614174000" }, "companyName": { "type": "string", "description": "Supplier Company Name", "example": "Acme Sourcing Ltd" }, "taxId": { "type": "string", "description": "Tax Identification Number", "example": "TAX-1234" }, "countryCode": { "type": "string", "description": "ISO-3166-1 alpha-3 Country Code", "example": "KEN" }, "parentVendorId": { "type": "string", "description": "Internal ERP Vendor ID of the parent supplier in the chain of custody", "example": "VEND-1001" } }, "description": "Payload to map a new supplier" }, "EnterpriseSupplierResponse": { "required": [ "companyName", "id", "operatorUuid", "vendorId" ], "type": "object", "properties": { "id": { "type": "string" }, "vendorId": { "type": "string" }, "operatorUuid": { "type": "string" }, "companyName": { "type": "string" }, "taxId": { "type": "string" }, "countryCode": { "type": "string" }, "parentVendorId": { "type": "string" } }, "description": "Supplier Mapping Response" }, "ShipmentLinkRequest": { "required": [ "batchId", "shipmentId" ], "type": "object", "properties": { "batchId": { "type": "string", "description": "The EUDR batch ID", "example": "uuid-1234" }, "shipmentId": { "type": "string", "description": "The shipment reference or logistics tracking ID", "example": "SHIP-OOCL-9988" }, "billOfLading": { "type": "string", "description": "Optional Bill of Lading document number", "nullable": true, "example": "BOL-77665544" }, "vesselName": { "type": "string", "description": "Optional Shipping Vessel Name", "nullable": true, "example": "MSC Gulsun" } }, "description": "Payload to link a batch to a shipment via Hedera Smart Contract" }, "JobAcceptedResponse": { "required": [ "createdAt", "estimatedDurationSec", "jobId", "status" ], "type": "object", "properties": { "jobId": { "type": "string", "description": "The unique asynchronous tracking job ID", "example": "job_998877" }, "status": { "type": "string", "description": "Current execution status invariant", "example": "PENDING", "enum": [ "PENDING" ] }, "estimatedDurationSec": { "type": "integer", "description": "Estimated duration in seconds before consensus or processing lock release", "format": "int32", "example": 3 }, "createdAt": { "type": "string", "description": "Timestamp when the job was accepted", "format": "date-time", "example": "2026-06-15T12:00:00Z" } }, "description": "Response payload for asynchronously accepted jobs" }, "CoordinateRiskRequest": { "required": [ "latitude", "longitude" ], "type": "object", "properties": { "latitude": { "type": "number", "description": "Geospatial latitude value", "format": "double", "example": -1.2921 }, "longitude": { "type": "number", "description": "Geospatial longitude value", "format": "double", "example": 36.8219 } }, "description": "Payload to request risk assessment for a specific coordinate" }, "CoordinateRiskAssessmentResponse": { "required": [ "auditTrail", "countryRiskLevel", "dataSource", "deforestationDetected", "deforestationProbability", "latitude", "longitude", "ndviBaseline", "ndviChange", "ndviCurrent" ], "type": "object", "properties": { "latitude": { "type": "number", "description": "Latitude evaluated", "format": "double", "example": -1.2921 }, "longitude": { "type": "number", "description": "Longitude evaluated", "format": "double", "example": 36.8219 }, "countryCode": { "type": "string", "description": "ISO-3 country code of detected country", "nullable": true, "example": "KEN" }, "countryName": { "type": "string", "description": "Detected country name", "nullable": true, "example": "Kenya" }, "countryRiskLevel": { "type": "string", "description": "Risk level assigned in matrix", "example": "STANDARD", "enum": [ "LOW", "STANDARD", "HIGH" ] }, "countryRiskJustification": { "type": "string", "description": "Justification for assigned risk level", "example": "Standard default risk assigned" }, "deforestationDetected": { "type": "boolean", "description": "Whether deforestation alerts are triggered on-the-fly", "example": false }, "deforestationProbability": { "type": "number", "description": "NDVI Deforestation Probability percentage", "example": 0.05 }, "ndviBaseline": { "type": "number", "description": "Baseline satellite NDVI index", "example": 0.72 }, "ndviCurrent": { "type": "number", "description": "Current satellite NDVI index", "example": 0.71 }, "ndviChange": { "type": "number", "description": "Computed NDVI change", "example": -0.01 }, "dataSource": { "type": "string", "description": "Satellite data source used for NDVI analysis", "example": "COPERNICUS-SENTINEL-2" }, "auditTrail": { "$ref": "#/components/schemas/RiskAuditTrail" } }, "description": "Response containing computed risk metrics for a coordinate" }, "RiskAuditTrail": { "required": [ "calculationTimestamp", "configVersionId", "cryptographicHash", "engineVersion", "finalScore", "formulaUsed", "inputs" ], "type": "object", "properties": { "configVersionId": { "type": "string" }, "calculationTimestamp": { "type": "string", "format": "date-time" }, "engineVersion": { "type": "string" }, "inputs": { "type": "object", "additionalProperties": { "type": "object" } }, "weightsApplied": { "type": "object", "additionalProperties": { "type": "number" } }, "thresholdsApplied": { "type": "object", "additionalProperties": { "type": "number" } }, "finalScore": { "type": "number" }, "formulaUsed": { "type": "string" }, "cryptographicHash": { "type": "string" } }, "description": "Cryptographic audit trail of the mathematical risk calculation" }, "ArchiveReportRequest": { "required": [ "endDate", "startDate" ], "type": "object", "properties": { "startDate": { "type": "string", "description": "Start date for the report range", "format": "date", "example": "2026-01-01" }, "endDate": { "type": "string", "description": "End date for the report range", "format": "date", "example": "2026-03-31" } }, "description": "Request to generate a bulk archive report" }, "ArchiveReportResponse": { "required": [ "message", "reportId", "status" ], "type": "object", "properties": { "reportId": { "type": "string", "description": "The unique job identifier tracking the generation process", "example": "rep_9a8b7c" }, "status": { "type": "string", "description": "Status of the job", "example": "ACCEPTED" }, "message": { "type": "string", "description": "Message indicating async processing", "example": "Bulk report generation started. A 'report.ready' webhook will be fired upon completion." } }, "description": "Response acknowledging the bulk archive request" }, "FeatureProperties": { "required": [ "area", "commodity", "farmer_id", "farmer_name", "plot_name", "unit" ], "type": "object", "properties": { "farmer_name": { "type": "string", "description": "Full name of the farmer/producer", "example": "Global Coffee Farmer #1" }, "farmer_id": { "type": "string", "description": "Unique identification reference code for the farmer", "example": "TEST_FARMER_100" }, "plot_name": { "type": "string", "description": "Descriptive name of the farm plot", "example": "Nyeri Hill Farm Block B" }, "area": { "type": "number", "description": "Area of the plot", "format": "double", "example": 2.5 }, "unit": { "type": "string", "description": "Unit of measurement. Must be explicitly set to HECTARES to guarantee deterministic satellite calibration.", "example": "HECTARES", "default": "HECTARES", "enum": [ "HECTARES" ] }, "commodity": { "type": "string", "description": "Crop commodity produced on the plot", "example": "Coffee" } }, "description": "Metadata properties associated with the spatial feature" }, "GeoJsonFeature": { "required": [ "geometry", "properties", "type" ], "type": "object", "properties": { "type": { "type": "string", "description": "GeoJSON Type (must be Feature)", "example": "Feature" }, "geometry": { "$ref": "#/components/schemas/GeoJsonGeometry" }, "properties": { "$ref": "#/components/schemas/FeatureProperties" } }, "description": "Formal GeoJSON Feature conforming to RFC 7946" }, "GeoJsonGeometry": { "required": [ "coordinates", "type" ], "type": "object", "properties": { "type": { "type": "string", "description": "Geometry type (Polygon or MultiPolygon)", "example": "Polygon", "enum": [ "Polygon", "MultiPolygon" ] }, "coordinates": { "$ref": "#/components/schemas/GeoJsonCoordinates" } }, "description": "Formal GeoJSON Geometry conforming to RFC 7946" }, "PolygonIngestionRequest": { "required": [ "features" ], "type": "object", "properties": { "features": { "maxItems": 5000, "minItems": 0, "type": "array", "description": "Array of GeoJSON Features representing farm boundaries", "items": { "$ref": "#/components/schemas/GeoJsonFeature" } } }, "description": "Payload to ingest GeoJSON polygons conforming to RFC 7946", "example": { "features": [ { "type": "Feature", "geometry": { "type": "Polygon", "coordinates": [ [ [ 36.8, -1.2 ], [ 36.9, -1.2 ], [ 36.9, -1.3 ], [ 36.8, -1.3 ], [ 36.8, -1.2 ] ] ] }, "properties": { "farmer_name": "Global Coffee Farmer #1", "farmer_id": "TEST_FARMER_100", "plot_name": "Nyeri Hill Farm Block B", "area": 2.5, "unit": "HECTARES", "commodity": "Coffee" } } ] } }, "DocumentUploadResponse": { "required": [ "documentId", "hash", "referenceUrl", "status" ], "type": "object", "properties": { "documentId": { "type": "string", "description": "Internal document identifier", "example": "doc_123456789abc" }, "hash": { "type": "string", "description": "SHA-256 hash of the ingested binary for mathematical proof", "example": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" }, "referenceUrl": { "type": "string", "description": "Internal URL to retrieve the document during TRACES NT submission", "example": "https://live.agribackup.com/api/v1/enterprise/eudr/documents/doc_123456789abc/download" }, "status": { "type": "string", "description": "Storage status", "example": "SECURED" } }, "description": "Response returned after successfully ingesting a legal document" }, "DdsGenerationRequest": { "required": [ "batchId", "legalDocumentHashes" ], "type": "object", "properties": { "batchId": { "type": "string", "description": "The EUDR batch ID", "example": "uuid-1234" }, "legalDocumentHashes": { "type": "array", "description": "Array of SHA-256 hashes representing land tenure/legality documents", "items": { "type": "string", "description": "Array of SHA-256 hashes representing land tenure/legality documents" } } }, "description": "Payload to generate a Due Diligence Statement" }, "TracesSubmissionResponse": { "required": [ "success" ], "type": "object", "properties": { "success": { "type": "boolean" }, "tracesReferenceNumber": { "type": "string" }, "verificationNumber": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" }, "submittedAt": { "type": "string", "format": "date-time" }, "hederaTransactionId": { "type": "string" } } }, "TracesRevocationResponse": { "required": [ "revokedAt", "success", "tracesReferenceNumber" ], "type": "object", "properties": { "success": { "type": "boolean" }, "tracesReferenceNumber": { "type": "string" }, "hederaTransactionId": { "type": "string" }, "revokedAt": { "type": "string", "format": "date-time" }, "message": { "type": "string" } } }, "TracesCredentialRequest": { "required": [ "tokenOrPassword" ], "type": "object", "properties": { "tokenOrPassword": { "type": "string", "description": "The raw TRACES NT API token or password", "example": "secret_abc123" }, "username": { "type": "string", "description": "Optional TRACES NT username if applicable", "example": "eudr_enterprise_user" } }, "description": "Payload to ingest TRACES NT credentials" }, "CredentialIngestionResponse": { "required": [ "status", "vaultReference" ], "type": "object", "properties": { "status": { "type": "string", "description": "Status of the ingestion", "example": "SECURED" }, "vaultReference": { "type": "string", "description": "The ciphertext reference returned by Vault", "example": "vault:v1:encodedCiphertextHere" } }, "description": "Response confirming cryptographic vault anchoring" }, "BatchRegistrationRequest": { "required": [ "commodity", "countryCode", "hsCode", "polygonIds", "quantityKg" ], "type": "object", "properties": { "commodity": { "type": "string", "description": "EUDR Commodity type or name", "example": "COFFEE" }, "countryCode": { "type": "string", "description": "ISO 3-letter country code of origin (e.g., KEN for Kenya, BRA for Brazil)", "example": "KEN" }, "hsCode": { "type": "string", "description": "HS Code (mandatory for dynamic validation)", "example": "090111" }, "quantityKg": { "type": "number", "description": "Total quantity in kilograms", "example": 5000.5 }, "polygonIds": { "maxItems": 5000, "minItems": 0, "type": "array", "description": "Array of verified Polygon IDs forming this batch", "items": { "type": "string", "description": "Array of verified Polygon IDs forming this batch" } }, "vendorIds": { "type": "array", "description": "Optional list of ERP Vendor IDs to explicitly map this batch to the Tier-1 Enterprise Supply Chain", "items": { "type": "string", "description": "Optional list of ERP Vendor IDs to explicitly map this batch to the Tier-1 Enterprise Supply Chain" } } }, "description": "Payload for registering a new consolidated batch" }, "ApiKeyCreateRequest": { "required": [ "name", "scopes" ], "type": "object", "properties": { "name": { "type": "string" }, "organizationName": { "type": "string" }, "rateLimit": { "type": "integer", "format": "int32" }, "scopes": { "type": "array", "items": { "type": "string" } } } }, "ApiKeyGenerationResponse": { "required": [ "createdAt", "id", "name", "rawApiKey", "scopes" ], "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "rawApiKey": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" } } }, "BatchUpdateRequest": { "type": "object", "properties": { "quantity": { "type": "number", "description": "Updated total weight/volume", "example": 5000 }, "commodityDescription": { "type": "string", "description": "Updated commodity description", "example": "Roasted Cocoa Beans" }, "hsCode": { "type": "string", "description": "Updated HS6 Code", "example": "180100" }, "harvestDate": { "type": "string", "description": "Updated harvest date", "format": "date", "example": "2023-11-15" } }, "description": "Payload for updating a consolidated batch pre-consensus" }, "WebhookSubscriptionResponse": { "required": [ "eventTypes", "status", "targetUrl", "webhookId" ], "type": "object", "properties": { "webhookId": { "type": "string", "description": "The unique identifier of the webhook registration", "example": "wh_12345" }, "status": { "type": "string", "description": "Status of registration", "example": "ACTIVE" }, "targetUrl": { "type": "string", "description": "The registered callback target URL", "example": "https://erp.example.com/agribackup-webhooks" }, "eventTypes": { "type": "array", "description": "Event types subscribed to", "items": { "type": "string", "description": "Event types subscribed to" } } }, "description": "Response containing webhook subscription details (signing secret redacted)" }, "WebhookDlqMessage": { "required": [ "attempts", "eventId", "eventType", "payload", "timestamp" ], "type": "object", "properties": { "eventId": { "type": "string", "description": "The unique event ID of the payload", "example": "evt_12345" }, "eventType": { "type": "string", "description": "The type of the event", "example": "shipment.linked" }, "payload": { "type": "string", "description": "The raw JSON payload string that failed to deliver" }, "timestamp": { "type": "string", "description": "When the event was originally generated" }, "attempts": { "type": "integer", "description": "Number of failed delivery attempts before DLQ routing", "format": "int32", "example": 5 } }, "description": "Message pulled from the Dead-Letter Queue" }, "WebhookDlqResponse": { "required": [ "messages", "retrievedCount" ], "type": "object", "properties": { "retrievedCount": { "type": "integer", "description": "Number of messages retrieved from the DLQ", "format": "int32", "example": 10 }, "messages": { "type": "array", "description": "The list of failed messages", "items": { "$ref": "#/components/schemas/WebhookDlqMessage" } } }, "description": "Response containing permanently failed webhook payloads" }, "EnterprisePolygonCollectionResponse": { "required": [ "data", "hasMore" ], "type": "object", "properties": { "data": { "type": "array", "description": "List of verified polygons", "items": { "$ref": "#/components/schemas/PolygonStatusResponse" } }, "hasMore": { "type": "boolean", "description": "Indicates if more records are available" }, "nextCursor": { "type": "string", "description": "Cursor to retrieve next page (null if no more records)", "nullable": true } }, "description": "Cursor-paginated collection response for enterprise polygons" }, "PolygonStatusResponse": { "required": [ "areaHectares", "commodity", "eudrStatus", "polygonId" ], "type": "object", "properties": { "polygonId": { "type": "string", "description": "Unique Polygon ID", "example": "uuid-1234" }, "commodity": { "type": "string", "description": "Crop commodity produced on the plot", "example": "Coffee" }, "eudrStatus": { "type": "string", "description": "EUDR compliance status", "example": "COMPLIANT", "enum": [ "PENDING", "COMPLIANT", "HIGH_RISK" ] }, "areaHectares": { "type": "number", "description": "Area of the plot in hectares", "format": "double", "example": 2.5 }, "createdAt": { "type": "string", "description": "Creation timestamp", "format": "date-time" } }, "description": "Deterministic compliance status of a Polygon" }, "EnterpriseJobError": { "required": [ "code", "reason" ], "type": "object", "properties": { "code": { "type": "string", "description": "Programmatic error code", "example": "POLYGON_OVERLAP" }, "field": { "type": "string", "description": "The specific field or identifier causing the failure", "example": "polygon_id_123" }, "reason": { "type": "string", "description": "Human-readable context", "example": "Polygon 12 overlaps protected park space" } }, "description": "Structured asynchronous job error payload" }, "EnterpriseJobStatusResponse": { "required": [ "compliantUnits", "errors", "failedRecords", "highRiskUnits", "jobId", "organizationId", "phase", "processedRecords", "startedAt", "totalRecords" ], "type": "object", "properties": { "jobId": { "type": "string", "description": "The unique asynchronous tracking job ID", "example": "job_998877" }, "organizationId": { "type": "string", "description": "The organization ID that initiated the job", "example": "org_test_tier1_alpha" }, "phase": { "type": "string", "description": "The current phase of the job (IMPORTING, ANALYZING, ANCHORING, GENERATING_CERTS, COMPLETED, FAILED)", "example": "COMPLETED", "enum": [ "IMPORTING", "ANALYZING", "ANCHORING", "GENERATING_CERTS", "COMPLETED", "FAILED" ] }, "totalRecords": { "type": "integer", "description": "Total records to process", "format": "int32", "example": 10 }, "processedRecords": { "type": "integer", "description": "Processed records count", "format": "int32", "example": 10 }, "failedRecords": { "type": "integer", "description": "Failed records count", "format": "int32", "example": 0 }, "compliantUnits": { "type": "integer", "description": "Compliant units detected", "format": "int32", "example": 10 }, "highRiskUnits": { "type": "integer", "description": "High risk units detected", "format": "int32", "example": 0 }, "merkleRootHash": { "type": "string", "description": "Hedera Merkle root hash or transaction ID (if anchored)", "example": "0xabc123..." }, "hederaTransactionId": { "type": "string", "description": "Hedera consensus transaction ID", "example": "0.0.8713513@1713583200-000000000" }, "errors": { "type": "array", "description": "List of structured error payloads encountered during execution", "items": { "$ref": "#/components/schemas/EnterpriseJobError" } }, "startedAt": { "type": "integer", "description": "Job start timestamp in epoch milliseconds", "format": "int64", "example": 1713583200000 }, "completedAt": { "type": "integer", "description": "Job completion timestamp in epoch milliseconds (null if still processing)", "format": "int64", "example": 1713583215000 } }, "description": "Response payload representing the current status and metrics of an asynchronous job" }, "CopernicusHealth": { "required": [ "status" ], "type": "object", "properties": { "status": { "type": "string", "description": "Status of Copernicus CDSE Sentinel OAuth & APIs", "example": "UP", "enum": [ "UP", "DOWN" ] }, "lastSync": { "type": "string", "description": "ISO-8601 Timestamp of the last successful synchronization or token check", "nullable": true, "example": "2026-06-19T12:00:00Z" } }, "description": "Copernicus Sentinel-2 Service Health Details" }, "HealthResponse": { "required": [ "services", "status" ], "type": "object", "properties": { "status": { "type": "string", "description": "Global health status of the EUDR API", "example": "OPERATIONAL", "enum": [ "OPERATIONAL", "DEGRADED", "DOWN" ] }, "services": { "$ref": "#/components/schemas/HealthServices" } }, "description": "Overall status response payload" }, "HealthServices": { "required": [ "copernicus", "hedera", "vault" ], "type": "object", "properties": { "hedera": { "$ref": "#/components/schemas/HederaHealth" }, "copernicus": { "$ref": "#/components/schemas/CopernicusHealth" }, "vault": { "$ref": "#/components/schemas/VaultHealth" } }, "description": "Integration health structures" }, "HederaHealth": { "required": [ "status" ], "type": "object", "properties": { "status": { "type": "string", "description": "Status of connection to Hedera node", "example": "UP", "enum": [ "UP", "DOWN" ] }, "latencyMs": { "type": "integer", "description": "Network latency to the Hedera consensus engine in milliseconds", "format": "int64", "nullable": true, "example": 142 } }, "description": "Hedera Ledger Health Details" }, "VaultHealth": { "required": [ "status" ], "type": "object", "properties": { "status": { "type": "string", "description": "Status of Vault template Transit operations", "example": "UP", "enum": [ "UP", "DOWN" ] } }, "description": "HashiCorp Vault Secret Management Engine Health Details" }, "HederaStateProof": { "required": [ "consensusTimestamp", "hederaTransactionId", "operationType" ], "type": "object", "properties": { "hederaTransactionId": { "type": "string", "description": "Hedera HCS transaction ID", "example": "0.0.12345@1234567890.000000000" }, "consensusTimestamp": { "type": "string", "description": "Hedera consensus timestamp", "example": "2026-06-12T12:00:00" }, "merkleProof": { "type": "string", "description": "Merkle proof path JSON for cryptographic verification" }, "operationType": { "type": "string", "description": "Ledger operation type", "example": "CREATED" } }, "description": "Individual Hedera state proof entry" }, "LedgerEvidenceResponse": { "required": [ "entityId", "entityType", "hederaTransactionIds", "stateProofs" ], "type": "object", "properties": { "entityId": { "type": "string", "description": "Entity identifier (batch or polygon UUID)", "example": "uuid-1234" }, "entityType": { "type": "string", "description": "Entity type", "example": "BATCH", "enum": [ "BATCH", "POLYGON" ] }, "hederaTransactionIds": { "type": "array", "description": "All Hedera consensus transaction IDs associated with this entity", "items": { "type": "string", "description": "All Hedera consensus transaction IDs associated with this entity" } }, "merkleRootHash": { "type": "string", "description": "Merkle root hash anchored on Hedera", "example": "0xabc123..." }, "stateProofs": { "type": "array", "description": "Hedera state proofs for independent audit verification", "items": { "$ref": "#/components/schemas/HederaStateProof" } }, "consensusTimestamp": { "type": "string", "description": "Hedera consensus timestamp (ISO-8601)", "example": "2026-06-12T12:00:00Z" } }, "description": "Cryptographic evidence anchored on the Hedera DLT" }, "DdsRetrievalResponse": { "required": [ "batchId", "referenceId", "tracesNtXml", "tracesSubmissionStatus" ], "type": "object", "properties": { "referenceId": { "type": "string", "description": "DDS reference identifier", "example": "DDS-AB12CD34" }, "batchId": { "type": "string", "description": "Associated EUDR batch ID", "example": "uuid-1234" }, "tracesNtXml": { "type": "string", "description": "TRACES NT V3 compliant XML payload" }, "hederaConsensusTimestamp": { "type": "string", "description": "Hedera consensus timestamp or transaction ID", "example": "0.0.12345@1234567890.123456789" }, "tracesSubmissionStatus": { "type": "string", "description": "TRACES NT submission status", "example": "GENERATED", "enum": [ "PENDING", "GENERATED", "SUBMITTED" ] } }, "description": "Finalized DDS payload for TRACES NT V3 submission" }, "EnterpriseDdsCollectionResponse": { "required": [ "data", "hasMore" ], "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DdsRetrievalResponse" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string" } }, "description": "Paginated list of generated DDS submissions" }, "TracesCredentialStatusResponse": { "required": [ "lastVerified", "message", "valid" ], "type": "object", "properties": { "valid": { "type": "boolean", "description": "Whether the credentials are valid and connection is active", "example": true }, "message": { "type": "string", "description": "Status or error message returned by TRACES NT client", "example": "Connected to TRACES NT SOAP API" }, "username": { "type": "string", "description": "The registered TRACES NT username", "nullable": true, "example": "eudr_enterprise_user" }, "lastVerified": { "type": "string", "description": "ISO-8601 timestamp of the connection validation check", "example": "2026-06-19T12:00:00Z" } }, "description": "Status details of TRACES NT credentials delegation" }, "BatchRegistrationResponse": { "required": [ "batchCode", "batchId", "status" ], "type": "object", "properties": { "batchId": { "type": "string", "description": "Internal database ID of the batch", "example": "uuid-1234" }, "batchCode": { "type": "string", "description": "Unique compliance code for this batch", "example": "COFFEE-KE-20260612-ABCDEF" }, "status": { "type": "string", "description": "Hedera anchoring status", "example": "PENDING_RISK_ASSESSMENT", "enum": [ "PENDING_RISK_ASSESSMENT", "COMPLIANT", "HIGH_RISK" ] } }, "description": "Response after registering a batch" }, "EnterpriseBatchCollectionResponse": { "required": [ "data", "hasMore" ], "type": "object", "properties": { "data": { "type": "array", "description": "List of batch records", "items": { "$ref": "#/components/schemas/BatchRegistrationResponse" } }, "hasMore": { "type": "boolean", "description": "Indicates if there are more records available" }, "nextCursor": { "type": "string", "description": "Cursor to use in the 'starting_after' parameter for the next page", "nullable": true } }, "description": "Paginated list of enterprise batches" }, "BatchDetailResponse": { "required": [ "batchCode", "batchId", "consolidatedRiskState", "polygonIds", "shipmentIds", "status" ], "type": "object", "properties": { "batchId": { "type": "string", "description": "Internal database ID of the batch", "example": "uuid-1234" }, "batchCode": { "type": "string", "description": "Unique compliance code for this batch", "example": "COFFEE-KEN-20260612-ABCDEF" }, "consolidatedRiskState": { "type": "string", "description": "Consolidated deterministic risk state", "example": "COMPLIANT", "enum": [ "PENDING_RISK_ASSESSMENT", "NONE", "LOW", "MEDIUM", "HIGH" ] }, "status": { "type": "string", "description": "Batch lifecycle status", "example": "CREATED" }, "shipmentIds": { "type": "array", "description": "Linked shipment reference IDs", "items": { "type": "string", "description": "Linked shipment reference IDs" } }, "polygonIds": { "type": "array", "description": "Polygon IDs contributing to this batch", "items": { "type": "string", "description": "Polygon IDs contributing to this batch" } } }, "description": "Detailed view of a single EUDR batch" } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "description": "Unique idempotency key (UUID) to prevent duplicate operations. Safely stored in Redis with a strict 24-hour TTL to prevent memory bloat during saturation attacks.", "required": true, "schema": { "type": "string", "format": "uuid" } }, "SubOrganizationId": { "name": "X-Sub-Organization-ID", "in": "header", "description": "Optional identifier to partition compliance data (polygons, batches, declarations) for a specific subsidiary or regional business unit within the conglomerate.", "required": false, "schema": { "type": "string" } } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "description": "Enterprise API Key provided via the AgriBackup developer console.", "name": "X-API-Key", "in": "header" } } } }