OpenAPI Spec

Use MINT’s machine-readable specification to discover and call the cohort and asset-definition HTTP interfaces served by these docs.

Download openapi.json · View specification

export MINT_DOCS_BASE="https://docs.mint.us"
curl --fail --show-error "$MINT_DOCS_BASE/openapi.json" -o openapi.json

Set MINT_DOCS_BASE to your running docs origin. The spec uses a relative server URL (/), so it follows the host serving it. When importing a downloaded file, set your client’s base URL to that origin.

What’s included

The OpenAPI 3.1.0 specification describes two read-only HTTP operations, returning 12 cohort definitions and 12 associated asset definitions:

Operation	Returns
GET /cohorts.json	The complete registry: catalogId, version, scope, and records.
GET /asset-definitions.json	Asset structures, inspection fields, evidence, and source references.

The response schema includes stable IDs, asset structures, definitions, evidence requirements, decision questions, aliases, source references, and the four null rule fields. Registry version 0.1.0 and its reviewed schema are preserved. OpenAPI 3.1 supports the existing Draft 2020-12 schema, including its const and null constraints.

There is no authentication, request body, query parameter, or pagination for either operation. Exact-ID lookup and search happen in the JavaScript and Python clients, not through separate HTTP endpoints.

Use the specification

Use tools with OpenAPI 3.1 and JSON Schema Draft 2020-12 support to:

• Generate client libraries with a compatible code generator.
• Import the operation into an API client such as Postman, Insomnia, or Bruno.
• Let agents discover the operation, its response fields, and the expected types.
• Validate downloaded registry responses against the included schema.

Tool support for OpenAPI 3.1 varies. The existing MINT clients provide working definition lookup without code generation or package installation.

Make a request

curl --fail --show-error "$MINT_DOCS_BASE/cohorts.json"

A successful response is 200 application/json and contains all twelve records. The specification embeds the cohort response schema at components.schemas.CohortRegistry and the asset definition schema at components.schemas.AssetDefinitionCatalog and links to the actual registry as its response example. The same schema is available separately as cohorts.schema.json.

Hosting failures do not have a defined MINT JSON error envelope. Check the HTTP status before parsing a response; the MINT clients report download failures as FETCH_FAILED.

Scope

This specification describes definition discovery, not a public asset marketplace or a membership service. It does not expose local CLI commands, Floating host tools, company holdings, buyer-fit decisions, or asset transactions as HTTP operations. Definitions remain separate from actual available assets.

Browse the cohort definition index for each cohort’s fields, evidence requirements, complete response, and working code examples.

See Asset definitions for the asset client examples and field meanings.