MOBILE-ID · TRUSTED LTANS

Archive API

Deposit a record set, reconcile receipts and query state; distinguish acceptance from evidence readiness.

openapi.yaml openapi.json asyncapi.yaml postman-target.json

LOCAL SIMULATION · Target contracts · No network requests

POST/v1/archives

TARGET CONTRACT · API 3.0.0-draft

Acknowledgement ArchiveRequest Errors and recovery ArchiveRequested

Property	Value
Technical owner	Archive Service
Application scope	archives:write
HTTP	202
Call processing	Asynchronous work: inspect Job and the result-resource state.
Event	ArchiveRequested

Reuse the original key only for an identical retry; inspect the existing result before starting a new command.

cURL

curl --fail-with-body --request POST \
  "${BASE_URL%/}/v1/archives" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "X-Correlation-ID: ${CORRELATION_ID}" \
  --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
  --header "Content-Type: application/json" \
  --data-binary "@${REQUEST_FILE}"

Request JSON

{
  "profileId": "profile-test-01",
  "policyId": "policy-test-v1",
  "mimeType": "text/plain",
  "metadata": {
    "title": "LTANS-SYN-001 / r1",
    "sourceId": "LTANS-SYN-001",
    "sourceRevision": "r1"
  },
  "custody": "CUSTOMER_MANAGED",
  "dataReference": "https://storage.example.invalid/test/primary-record.txt",
  "digest": {
    "algorithm": "SHA-256",
    "value": "35bc4fcffc4a16c8a9db81d1a8f9042c27a1daaf51628b4c880f312178fe3085"
  },
  "archivalPeriod": {
    "endAt": "2036-10-15T00:00:00Z"
  },
  "clientReference": "LTANS-SYN-001/r1",
  "requestTime": "2026-10-15T05:00:00Z",
  "groupId": "grp-syn-001"
}

Target response

{
  "archiveId": "arc-test-001",
  "jobId": "job-test-001",
  "policyId": "policy-test-v1",
  "policyVersion": "1",
  "receivedAt": "2026-10-15T05:00:01Z",
  "state": "ACCEPTED"
}

JSON Schema

{
  "type": "object",
  "properties": {
    "profileId": {
      "type": "string"
    },
    "policyId": {
      "type": "string"
    },
    "mimeType": {
      "type": "string"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      }
    },
    "custody": {
      "type": "string",
      "enum": [
        "PROVIDER_MANAGED",
        "CUSTOMER_MANAGED",
        "HASH_ONLY"
      ]
    },
    "dataReference": {
      "type": "string",
      "format": "uri",
      "description": "Allow-listed object reference; arbitrary server-side URL fetching is forbidden."
    },
    "digest": {
      "$ref": "#/components/schemas/Digest"
    },
    "archivalPeriod": {
      "$ref": "#/components/schemas/ArchivalPeriod"
    },
    "groupId": {
      "type": "string"
    },
    "clientReference": {
      "type": "string"
    },
    "requestTime": {
      "type": "string",
      "format": "date-time"
    },
    "uploadId": {
      "type": "string",
      "minLength": 1,
      "description": "Identifier of a completed upload in an agreed storage connector; upload transport is outside these REST contracts."
    },
    "externalObjectId": {
      "type": "string",
      "minLength": 1,
      "description": "Owner-retained data identifier for hash-only preservation; not an automatic fetch URL."
    }
  },
  "required": [
    "profileId",
    "policyId",
    "mimeType",
    "custody",
    "digest",
    "archivalPeriod"
  ],
  "additionalProperties": false,
  "allOf": [
    {
      "if": {
        "properties": {
          "custody": {
            "const": "PROVIDER_MANAGED"
          }
        },
        "required": [
          "custody"
        ]
      },
      "then": {
        "required": [
          "uploadId"
        ],
        "not": {
          "anyOf": [
            {
              "required": [
                "dataReference"
              ]
            },
            {
              "required": [
                "externalObjectId"
              ]
            }
          ]
        }
      }
    },
    {
      "if": {
        "properties": {
          "custody": {
            "const": "CUSTOMER_MANAGED"
          }
        },
        "required": [
          "custody"
        ]
      },
      "then": {
        "required": [
          "dataReference"
        ],
        "not": {
          "anyOf": [
            {
              "required": [
                "uploadId"
              ]
            },
            {
              "required": [
                "externalObjectId"
              ]
            }
          ]
        }
      }
    },
    {
      "if": {
        "properties": {
          "custody": {
            "const": "HASH_ONLY"
          }
        },
        "required": [
          "custody"
        ]
      },
      "then": {
        "required": [
          "externalObjectId"
        ],
        "not": {
          "anyOf": [
            {
              "required": [
                "dataReference"
              ]
            },
            {
              "required": [
                "uploadId"
              ]
            }
          ]
        }
      }
    }
  ],
  "examples": [
    {
      "profileId": "profile-test-01",
      "policyId": "policy-test-v1",
      "mimeType": "text/plain",
      "metadata": {
        "title": "LTANS-SYN-001 / r1",
        "sourceId": "LTANS-SYN-001",
        "sourceRevision": "r1"
      },
      "custody": "CUSTOMER_MANAGED",
      "dataReference": "https://storage.example.invalid/test/primary-record.txt",
      "digest": {
        "algorithm": "SHA-256",
        "value": "35bc4fcffc4a16c8a9db81d1a8f9042c27a1daaf51628b4c880f312178fe3085"
      },
      "archivalPeriod": {
        "endAt": "2036-10-15T00:00:00Z"
      },
      "clientReference": "LTANS-SYN-001/r1",
      "requestTime": "2026-10-15T05:00:00Z",
      "groupId": "grp-syn-001"
    }
  ]
}

application/problem+json

{
  "type": "https://example.invalid/problems/archive-key-conflict",
  "title": "Archive Key Conflict",
  "code": "ARCHIVE_KEY_CONFLICT",
  "detail": "Idempotency key conflicts with another payload.",
  "correlationId": "corr-test-001",
  "requestId": "req-test-001",
  "retryable": false,
  "service": "Archive Service",
  "timestamp": "2026-10-15T05:00:01Z",
  "errors": [],
  "status": 409,
  "instance": "urn:ltans:request:req-test-001"
}

GET/v1/archives

TARGET CONTRACT · API 3.0.0-draft

ArchiveList Errors and recovery

Property	Value
Technical owner	Archive Service
Application scope	archives:read
HTTP	200
Call processing	Authentication/authorization → HTTP handling; not a resource-state enum.
Event	Audit or internal event

Reuse the original key only for an identical retry; inspect the existing result before starting a new command.

cURL

curl --fail-with-body --request GET \
  "${BASE_URL%/}/v1/archives" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "X-Correlation-ID: ${CORRELATION_ID}"

Target response

{
  "items": [
    {
      "archiveId": "arc-test-001",
      "profileId": "profile-test-01",
      "policyId": "policy-test-v1",
      "custody": "CUSTOMER_MANAGED",
      "mimeType": "application/pdf",
      "metadata": {
        "title": "Synthetic record"
      },
      "state": "EVIDENCE_READY",
      "evidenceVersion": 1
    }
  ]
}

JSON Schema

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ArchiveObject"
      }
    },
    "nextCursor": {
      "type": "string"
    }
  },
  "required": [
    "items"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "items": [
        {
          "archiveId": "arc-test-001",
          "profileId": "profile-test-01",
          "policyId": "policy-test-v1",
          "custody": "CUSTOMER_MANAGED",
          "mimeType": "text/plain",
          "metadata": {
            "title": "LTANS-SYN-001 / r1"
          },
          "state": "EVIDENCE_READY",
          "evidenceVersion": 1
        }
      ]
    }
  ]
}

application/problem+json

{
  "type": "https://example.invalid/problems/archive-key-conflict",
  "title": "Archive Key Conflict",
  "code": "ARCHIVE_KEY_CONFLICT",
  "detail": "Idempotency key conflicts with another payload.",
  "correlationId": "corr-test-001",
  "requestId": "req-test-001",
  "retryable": false,
  "service": "Archive Service",
  "timestamp": "2026-10-15T05:00:01Z",
  "errors": [],
  "status": 409,
  "instance": "urn:ltans:request:req-test-001"
}

GET/v1/archives/{archiveId}

TARGET CONTRACT · API 3.0.0-draft

ArchiveObject Errors and recovery

Property	Value
Technical owner	Archive Service
Application scope	archives:read
HTTP	200
Call processing	Authentication/authorization → HTTP handling; not a resource-state enum.
Event	Audit or internal event

Reuse the original key only for an identical retry; inspect the existing result before starting a new command.

cURL

curl --fail-with-body --request GET \
  "${BASE_URL%/}/v1/archives/${ARCHIVE_ID}" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "X-Correlation-ID: ${CORRELATION_ID}"

Target response

{
  "archiveId": "arc-test-001",
  "profileId": "profile-test-01",
  "policyId": "policy-test-v1",
  "custody": "CUSTOMER_MANAGED",
  "mimeType": "application/pdf",
  "metadata": {
    "title": "Synthetic record"
  },
  "state": "EVIDENCE_READY",
  "evidenceVersion": 1
}

JSON Schema

{
  "type": "object",
  "properties": {
    "archiveId": {
      "type": "string"
    },
    "profileId": {
      "type": "string"
    },
    "policyId": {
      "type": "string"
    },
    "custody": {
      "type": "string"
    },
    "mimeType": {
      "type": "string"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      }
    },
    "state": {
      "type": "string",
      "enum": [
        "RECEIVED",
        "VALIDATING",
        "ACCEPTED",
        "EVIDENCE_PENDING",
        "EVIDENCE_READY",
        "REJECTED",
        "EVIDENCE_FAILED"
      ]
    },
    "evidenceVersion": {
      "type": "integer",
      "minimum": 0
    }
  },
  "required": [
    "archiveId",
    "state"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "archiveId": "arc-test-001",
      "profileId": "profile-test-01",
      "policyId": "policy-test-v1",
      "custody": "CUSTOMER_MANAGED",
      "mimeType": "text/plain",
      "metadata": {
        "title": "LTANS-SYN-001 / r1"
      },
      "state": "EVIDENCE_READY",
      "evidenceVersion": 1
    }
  ]
}

application/problem+json

{
  "type": "https://example.invalid/problems/archive-key-conflict",
  "title": "Archive Key Conflict",
  "code": "ARCHIVE_KEY_CONFLICT",
  "detail": "Idempotency key conflicts with another payload.",
  "correlationId": "corr-test-001",
  "requestId": "req-test-001",
  "retryable": false,
  "service": "Archive Service",
  "timestamp": "2026-10-15T05:00:01Z",
  "errors": [],
  "status": 409,
  "instance": "urn:ltans:request:req-test-001"
}

GET/v1/archives/{archiveId}/status

TARGET CONTRACT · API 3.0.0-draft

ArchiveObject Errors and recovery

Property	Value
Technical owner	Archive Service
Application scope	archives:read
HTTP	200
Call processing	Authentication/authorization → HTTP handling; not a resource-state enum.
Event	Audit or internal event

Reuse the original key only for an identical retry; inspect the existing result before starting a new command.

cURL

curl --fail-with-body --request GET \
  "${BASE_URL%/}/v1/archives/${ARCHIVE_ID}/status" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "X-Correlation-ID: ${CORRELATION_ID}"

Target response

{
  "archiveId": "arc-test-001",
  "profileId": "profile-test-01",
  "policyId": "policy-test-v1",
  "custody": "CUSTOMER_MANAGED",
  "mimeType": "application/pdf",
  "metadata": {
    "title": "Synthetic record"
  },
  "state": "EVIDENCE_READY",
  "evidenceVersion": 1
}

JSON Schema

{
  "type": "object",
  "properties": {
    "archiveId": {
      "type": "string"
    },
    "profileId": {
      "type": "string"
    },
    "policyId": {
      "type": "string"
    },
    "custody": {
      "type": "string"
    },
    "mimeType": {
      "type": "string"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      }
    },
    "state": {
      "type": "string",
      "enum": [
        "RECEIVED",
        "VALIDATING",
        "ACCEPTED",
        "EVIDENCE_PENDING",
        "EVIDENCE_READY",
        "REJECTED",
        "EVIDENCE_FAILED"
      ]
    },
    "evidenceVersion": {
      "type": "integer",
      "minimum": 0
    }
  },
  "required": [
    "archiveId",
    "state"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "archiveId": "arc-test-001",
      "profileId": "profile-test-01",
      "policyId": "policy-test-v1",
      "custody": "CUSTOMER_MANAGED",
      "mimeType": "text/plain",
      "metadata": {
        "title": "LTANS-SYN-001 / r1"
      },
      "state": "EVIDENCE_READY",
      "evidenceVersion": 1
    }
  ]
}

application/problem+json

{
  "type": "https://example.invalid/problems/archive-key-conflict",
  "title": "Archive Key Conflict",
  "code": "ARCHIVE_KEY_CONFLICT",
  "detail": "Idempotency key conflicts with another payload.",
  "correlationId": "corr-test-001",
  "requestId": "req-test-001",
  "retryable": false,
  "service": "Archive Service",
  "timestamp": "2026-10-15T05:00:01Z",
  "errors": [],
  "status": 409,
  "instance": "urn:ltans:request:req-test-001"
}

POST/v1/archives/{archiveId}/dispositions

TARGET CONTRACT · API 3.0.0-draft

Job DispositionRequest Errors and recovery DispositionRequested

Property	Value
Technical owner	Storage Service
Application scope	disposition:write
HTTP	202
Call processing	Asynchronous work: inspect Job and the result-resource state.
Event	DispositionRequested

Reuse the original key only for an identical retry; inspect the existing result before starting a new command.

cURL

curl --fail-with-body --request POST \
  "${BASE_URL%/}/v1/archives/${ARCHIVE_ID}/dispositions" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "X-Correlation-ID: ${CORRELATION_ID}" \
  --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
  --header "Content-Type: application/json" \
  --data-binary "@${REQUEST_FILE}"

Request JSON

{
  "scope": "PAYLOAD",
  "approvalId": "approval-test-004",
  "reason": "Synthetic expiry test"
}

Target response

{
  "jobId": "job-disposition-001",
  "state": "QUEUED",
  "resourceId": "arc-test-001",
  "correlationId": "corr-test-001",
  "pollAfterSeconds": 2
}

JSON Schema

{
  "type": "object",
  "properties": {
    "scope": {
      "type": "string",
      "enum": [
        "PAYLOAD",
        "EVIDENCE",
        "BOTH"
      ]
    },
    "approvalId": {
      "type": "string"
    },
    "reason": {
      "type": "string"
    }
  },
  "required": [
    "scope",
    "approvalId",
    "reason"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "scope": "PAYLOAD",
      "approvalId": "approval-test-004",
      "reason": "Synthetic expiry test"
    }
  ]
}

application/problem+json

{
  "type": "https://example.invalid/problems/archive-key-conflict",
  "title": "Archive Key Conflict",
  "code": "ARCHIVE_KEY_CONFLICT",
  "detail": "Idempotency key conflicts with another payload.",
  "correlationId": "corr-test-001",
  "requestId": "req-test-001",
  "retryable": false,
  "service": "Storage Service",
  "timestamp": "2026-10-15T05:00:01Z",
  "errors": [],
  "status": 409,
  "instance": "urn:ltans:request:req-test-001"
}

Archive API

Next steps

Search LTANS documentation