Skip to main content

API Reference

The Checkmate API is fully documented using the OpenAPI 3.0 standard, providing a comprehensive, machine-readable specification that can be used with various API tools and generators.

Download OpenAPI Spec​

📥 Download openapi.yaml - Complete OpenAPI 3.0 specification

What is OpenAPI?​

OpenAPI is an industry-standard specification for documenting RESTful APIs. It provides:

  • Machine-readable format - Tools can automatically generate client libraries, tests, and documentation
  • Interactive documentation - Use with Swagger UI or other viewers
  • Type safety - Generate strongly-typed clients in various languages
  • Validation - Validate requests and responses against the spec

Using the OpenAPI Spec​

1. Swagger UI / Swagger Editor​

  1. Go to Swagger Editor
  2. Click File → Import URL
  3. Enter the URL to your hosted openapi.yaml
  4. Explore the interactive API documentation

Alternatively, paste the contents directly:

  1. Download the openapi.yaml file
  2. Go to Swagger Editor
  3. Click File → Import File and select the downloaded file

2. Postman​

  1. Open Postman
  2. Click Import in the top left
  3. Choose Upload Files or Link
  4. Import the openapi.yaml file
  5. Postman will create a collection with all endpoints

3. Generate Client Libraries​

Use OpenAPI Generator to create client libraries in your language:

# Install OpenAPI Generator
npm install @openapitools/openapi-generator-cli -g

# Generate TypeScript client
openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./generated/typescript-client

# Generate Python client
openapi-generator-cli generate \
  -i openapi.yaml \
  -g python \
  -o ./generated/python-client

# Generate Java client
openapi-generator-cli generate \
  -i openapi.yaml \
  -g java \
  -o ./generated/java-client

Available Generators:

  • JavaScript/TypeScript (axios, fetch, node)
  • Python
  • Java
  • Go
  • Ruby
  • PHP
  • C#
  • Swift
  • Kotlin
  • And many more...

4. Redoc​

Generate beautiful, responsive API documentation:

# Install Redoc CLI
npm install -g redoc-cli

# Generate static HTML documentation
redoc-cli bundle openapi.yaml -o api-docs.html

5. VS Code Extension​

Use the OpenAPI (Swagger) Editor extension:

  1. Install the OpenAPI (Swagger) Editor extension in VS Code
  2. Open your openapi.yaml file
  3. Right-click and select Preview OpenAPI
  4. Get real-time validation and auto-completion

6. API Testing with Insomnia​

  1. Open Insomnia
  2. Click Create → File
  3. Choose From File and select openapi.yaml
  4. Insomnia creates requests for all endpoints
  5. Configure authentication and test the API

Validation​

Validate the OpenAPI spec to ensure correctness:

# Using Swagger CLI
npm install -g @apidevtools/swagger-cli
swagger-cli validate openapi.yaml

# Using OpenAPI Validator
npm install -g ibm-openapi-validator
lint-openapi openapi.yaml

Hosted Documentation​

You can host your own interactive API documentation:

Using Swagger UI​

# Install dependencies
npm install swagger-ui-express

# Express.js example
const express = require('express');
const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs');

const app = express();
const swaggerDocument = YAML.load('./openapi.yaml');

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

app.listen(3001, () => {
  console.log('API docs available at http://localhost:3001/api-docs');
});

Using Redoc​

<!DOCTYPE html>
<html>
  <head>
    <title>Checkmate API</title>
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
    <style>
      body {
        margin: 0;
        padding: 0;
      }
    </style>
  </head>
  <body>
    <redoc spec-url='/openapi.yaml'></redoc>
    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
  </body>
</html>

Specification Details​

OpenAPI Version​

Version: 3.0.0

API Version​

Version: 1.0.0

Base URLs​

  • Development: http://localhost:3000
  • Production: Your deployed URL

Authentication Schemes​

  • Type: API Key
  • Name: user_session
  • Location: Cookie
  • Used by: Web applications

2. Bearer Token​

  • Type: HTTP Bearer
  • Scheme: Bearer
  • Used by: API clients, scripts, integrations

Endpoints Coverage​

The OpenAPI spec includes all endpoints:

  • ✅ Projects (Create, Read, Update, Delete)
  • ✅ Tests (CRUD, Bulk operations)
  • ✅ Runs (CRUD, Status updates, Lock/Unlock)
  • ✅ Labels, Squads, Sections (CRUD)
  • ✅ Configuration (Priorities, Platforms, etc.)
  • ✅ Users & Authentication
  • ✅ Reports (Downloads)

Example: TypeScript Client Usage​

After generating a TypeScript client:

import { Configuration, ProjectsApi, TestsApi } from './generated/typescript-client';

// Configure API client
const config = new Configuration({
  basePath: 'http://localhost:3000',
  apiKey: 'Bearer your_api_token_here'
});

const projectsApi = new ProjectsApi(config);
const testsApi = new TestsApi(config);

// Get projects
async function getProjects() {
  const response = await projectsApi.getProjects({
    orgId: 1,
    page: 1,
    pageSize: 10
  });
  return response.data;
}

// Create test
async function createTest() {
  const response = await testsApi.createTest({
    title: 'New Test',
    projectId: 1,
    sectionId: 5,
    priorityId: 2
  });
  return response.data;
}

Keeping Up to Date​

The OpenAPI specification is maintained in the main repository:

/openapi.yaml

When the API changes:

  1. The spec is updated in the repository
  2. Run yarn build in the docs folder to sync
  3. Regenerate client libraries if needed
tip

Watch the GitHub repository for updates to the API specification.

Resources​

OpenAPI Specification

Learn more about OpenAPI

OpenAPI Docs →

Swagger Editor

Online editor and validator

Try Now →

OpenAPI Generator

Generate client libraries

View Docs →

Postman Collection

Import into Postman

View Collection →

Next Steps​