---
title: "OpenAPI specification"
description: "Download the complete source-validated OpenAPI 3.1 licensing contract, including actual statuses, errors, headers and examples."
slug: "/docs/v1/api/openapi"
section: "API reference"
order: 40
audience: "all"
level: "intermediate"
last_updated: "2026-10-17"
version: "v1"
related: ["/docs/v1/start/authentication", "/docs/v1/api/conventions"]
draft: false
---
Use the machine-readable reference alongside the endpoint guides; schema validation is not an access-control decision.

## What you will learn
- Download identical JSON/YAML contracts.
- Understand recommended input schemas, response strictness and signing limits.

## Prerequisites
- Read [API conventions](/docs/v1/api/conventions).
- Complete [the Sandbox quickstart](/docs/v1/start/quickstart).

## Downloads
- [OpenAPI JSON](/docs/openapi.json)
- [OpenAPI YAML](/docs/openapi.yaml)
Both files describe the same API v1 contract using OpenAPI 3.1.1 and JSON Schema2020-12. They include all 11 registered licensing operations,25 named request/response components, [developer](/docs/v1/start/glossary#developer)/installation/public-app credential schemes, required management [scopes](/docs/v1/start/glossary#scope) and the exact current error/header behavior. They do not invent [customer](/docs/v1/start/glossary#customer)/[product](/docs/v1/start/glossary#product)/list/payment endpoints.
The only server URL is https://licensing.kdpika.com/api/v1. Sandbox/[Live](/docs/v1/start/glossary#live) is bound by credentials and the [activation](/docs/v1/start/glossary#activation) header, not a separate host. x-required-scope records a developer scope without pretending the bearer credential is OAuth.

## Inputs, responses and examples
Input schemas describe supported recommended JSON types. The actual PHP backend also trims/casts some values and ignores unknown fields; a strict schema cannot describe those malformed-input coercions as if every violation were rejected identically. Use the endpoint constraints/conventions for that distinction.
Response schemas describe every emitted nested field and nullability. Example success bodies are captured from the isolated Sandbox; [license keys](/docs/v1/start/glossary#license-key)/tokens are replaced with obvious placeholders. The 69 per-operation error examples use actual captured errors. A shared global INTERNAL_ERROR example is explicitly identified when reused across operations instead of claiming a separate induced outage for each handler.
Dates use UTC-labelled ISO8601 offsets as emitted by the builders, with the known database-session display-time limitation documented. [Features](/docs/v1/start/glossary#feature) can be a dynamic object or an empty array in current PHP output. Do not assume every feature is boolean.
A JSON-schema match does not verify Ed25519, preserve signed numeric tokens or enforce product/environment/installation/time policy. Read [signed responses](/docs/v1/security/signed-responses) before authorizing access.

## Validation and drift checks
The authoring tool checks exact source hashes and route inventory before generation. Real local Sandbox requests validate success/error bodies against the generated schema. JSON and YAML equality, every example, all schema definitions and negative fixtures are checked. Standard Spectral OAS rules produce zero errors/warnings/hints; a deliberately missing operationId fails the gate.
The local Spectral JS API uses pinned packages and no disabled rule set. No Node runtime or external schema fetch is required on hosting; the published files are compiled artifacts. A new product behavior must update source facts, schemas, samples and executed tests before publication.

## Importing the contract
1. Download JSON or YAML. Expected: the same11 operations, not a login page.
2. Import that file into your OpenAPI 3.1-compatible local editor/client. Expected: request/response schemas and three credential schemes are recognized.
3. Configure only your Sandbox test credentials. Expected: no Live operation or real customer mutation during exploration.
4. Compare generated clients against the actual runnable examples and vectors. Expected: signature bytes, null handling and error fallbacks are tested rather than assumed.

## Expected result
You have the actual v1 contract and can validate response shape without mistaking it for cryptographic or business authorization.

## Common mistakes
- Using an OpenAPI 3.0-only validator for 3.1 type/null/schema features.
- Treating request schema guidance as proof of strict PHP input rejection.
- Replacing Ed25519 verification with a schema or success-flag check.

## Security notes
Keep generated client credentials private, use HTTPS and never auto-upload populated test environments or private captures to a public schema editor.

## Troubleshooting
| Symptom | Cause | Action |
| --- | --- | --- |
| Importer rejects type arrays/const | Tool supports an older OpenAPI/JSON Schema dialect | Use a3.1-compatible importer |
| Documented route missing from generator | Stale exported contract or unsupported version | Download the current exact file and compare the operation |
| Valid JSON but signature failure | Shape is not byte authenticity | Run the published verifier/vectors and fail closed |

## Next steps
Review [the endpoint reference](/docs/v1/api/public-key) and [signature verification](/docs/v1/security/verify-ed25519).

## Related
- [Authentication](/docs/v1/start/authentication)
- [API conventions](/docs/v1/api/conventions)
- [License lifecycle](/docs/v1/start/license-lifecycle)