API compatibility and updates

Dockt product endpoints use the /v1 route prefix. The public OpenAPI JSON describes the contract deployed at https://api.dockt.com.

Treat OpenAPI as an external dependency. Keep an approved contract or generated client version with your application instead of regenerating it without review during every build.

Pin the contract you use

Download the contract when you intentionally update your integration:

curl --fail-with-body --silent --show-error \
  https://api.dockt.com/openapi.json \
  --output openapi.json

Commit the file or the client types generated from it. Review the diff before deployment, then run your contract and workflow tests.

The top-level OpenAPI info.version identifies the published contract document. Continue to use the /v1 path prefix shown by each operation.

Handle contract growth safely

Write response parsing so a compatible contract addition does not stop an existing workflow:

• Ignore extra response object fields. Dockt response schemas allow additional properties; request bodies retain strict validation.
• Give unfamiliar descriptive values and codes a safe fallback.
• Use top-level result fields before optional supporting detail.
• Treat resource IDs and pagination cursors as opaque strings.
• Branch on Problem Details type, not its human-readable title or detail.

For a new Document classification, fact, check, or Finding code, preserve the response and use its returned human-readable explanation when available. Do not convert an unfamiliar value into success.

Assessment input value_type and cardinality, resolved input assurance, and Fact source kind are extensible strings. Their OpenAPI descriptions list known values. Preserve unfamiliar values without inferring their meaning. Lifecycle states and Decision outcomes remain closed enums and require contract review before their values change.

Interpret assessment input metadata

The Assessment response uses input_requests to list details a check still needs. Each entry describes the format and allowed values. Use this information to validate values your application already knows. Show users the result and any missing evidence instead of a questionnaire.

Each entry can include these fields:

• value_type describes the value, such as a country code, date, or Boolean.
• cardinality is one or many. If omitted, use one.
• max_items limits a list. Lists contain at most eight string values; a field may specify a smaller limit.
• unit identifies a measurement, such as days.
• options lists the allowed selection values.

The policy-authoring catalog also exposes this metadata in assessment_input_fields. Use the field’s metadata instead of inferring its type or unit from its code.

If your application cannot handle a field’s type or number of values (cardinality), keep the entry and continue displaying supported checks. Do not submit a guessed value. If an assurance value is unfamiliar, show that verification information is unavailable; do not label the value as verified.

Review state-machine changes

When an OpenAPI diff changes a status or result enum, review every branch in your integration:

• Document status and document_result.
• Assessment status, input_requests, and latest_decision.
• Decision decision, signal, Finding impact, and requirement status.
• Notification event type and canonical resource reads.
• Problem Details type and HTTP status.

Keep a fallback for an unfamiliar value so your application can retain the response, avoid an unsafe automatic action, and route the case for investigation.

Update generated clients

Use this update sequence:

1. Download the new OpenAPI document.
2. Diff it against the approved version in your application.
3. Regenerate client types in a review branch.
4. Compile the application and run parser tests against the curated examples.
5. Run authentication, idempotency, upload, notification delivery, and recovery tests in a test Workspace.
6. Deploy the client update through your normal release process.

Do not make generated client updates an unreviewed production build step.

Diagnose an unexpected response

If a response does not match the contract version you reviewed:

1. Retain the HTTP status, response headers, and redacted response body.
2. Record x-request-id.
3. Compare the operation with the deployed OpenAPI document.
4. Contact hello@dockt.com with the request ID and operation name.

Never include bearer tokens, webhook secrets, document contents, or raw personal data in a support request.