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 unknown object fields when your language and validation policy allow it.
• Give unfamiliar enum and code values 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.

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.
• Webhook 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, webhook, 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.