Blockfrost.io OpenAPI

Open Source OpenAPI specification for Blockfrost.io backend API.

Getting started • Development

Getting started

The development version is available in the master branch.
The latest active release can be found under GitHub Releases.
For the published documentation, visit docs.blockfrost.io.

Development

Blockfrost OpenAPI blockfrost-openapi.yaml specification is generated from all yaml files in src directory. Then there is Mithril Aggregator API spec mithril.yaml which can be downloaded from Mithril Github. These two specs are then merged together via openapi-merge-cli (configuration is inside openapi-merge.json). Only the Mithril endpoints with a tag Cardano » Mithril are included into the final spec.

Tag Cardano » Mithril needs to be added manually to each relevant endpoint in Mithril OpenAPI spec.

If you add a new file then don't forget to add it to paths in src/definitions.yaml.

Edit the source yaml files and build the package:

yarn build

Regenerating types

TypeScript types (src/generated-types.ts) are regenerated as part of yarn build, or standalone with:

yarn generate-types

Rust types (the rust/ crate) are generated from the bundled openapi.yaml, so run yarn build (or at least yarn bundle) first if you have changed the source yaml files. The generation uses openapi-generator, which requires a Java runtime:

yarn generate-types:rust

If you don't have Java installed, use the Docker variant, which runs the same generator version inside a container:

yarn generate-types:rust:docker

The generator version is pinned in openapitools.json — when bumping it, update the image tag in the generate-types:rust:docker script to match.

Note that the Rust generation emits models only (apis=false), so spec changes that only touch endpoints or query parameters produce no changes in the crate.

Midnight GraphQL docs

The Midnight Indexer GraphQL API documentation is generated using SpectaQL from the schema file midnight-indexer-api.graphql. The SpectaQL configuration is in spectaql.yaml and the custom theme is in spectaql-theme/.

To update the GraphQL schema, download the version matching the deployed Midnight Indexer from the Midnight Indexer repository and replace the local file:

Then rebuild with yarn bundle (SpectaQL runs as part of the bundle step) to regenerate the docs in docs/midnight/.

Feel free to open PR against the master branch. It is a great place to start any discussion for new features and changes to the Blockfrost API.

UI

When you push a new commit, the documentation for your branch is automatically generated on Vercel and added to your PR as a deployment.

Dashboard API docs

The Blockfrost Dashboard API documentation at docs.blockfrost.io/dashboard-api/ is not built from this repo. Its OpenAPI spec and Scalar build live separately and deploy as their own Vercel project. This repo only owns the docs.blockfrost.io host and reverse-proxies /dashboard-api/* to that project via a rewrites rule in vercel.json — each service's spec and build pipeline stays in its own repo.

Usage

You can download openapi.yaml directly from the repository or use this project as a dependency in your JavaScript/TypeScript project.

Typescript example

Install @blockfrost/openapi:

yarn add @blockfrost/openapi

or

npm install @blockfrost/openapi

Now you can use TypeScript types generated from the OpenAPI specification:

import { components } from '@blockfrost/openapi';

type Block = components['schemas']['block_content'];
type Address = components['schemas']['address_content'];
type UtxoAsset = components['schemas']['address_utxo_content'];

Rust crate

Add blockfrost-openapi to your Cargo.toml:

[dependencies]
blockfrost-openapi = "0.1.87"

Now you can use the generated Rust types:

use blockfrost_openapi::models::{BlockContent, AddressContent, AddressUtxoContentInner};