Learn about our RFC process, Open RFC meetings & more.Join in the discussion! »


4.0.0 • Public • Published

CircleCi API Wrapper

A wrapper for CircleCi API written in TypeScript.

CircleCI branch CircleCI (all branches) Coverage Status

npm version GitHub npm bundle size

Renovate enabled dependencies Status devDependencies Status

Usable in node and the browser. If used in a TypeScript project, you will get types, and auto-complete for all of the api responses. You will no longer need to tab back and fourth to the API documentation. Will work in Node or the browser!

I recommend using this library if you are writing a tool or website in TypeScript. I have created definitions for each of the CircleCi endpoints. There may still be some errors, but I am open to contributions on making them better.

If there are any features you would like, please feel free to open up an issue.



I did my best to correctly add types for all of the supported endpoints. However if you notice an incorrect payload type, or some missing properties, please open up an issue, or submit a pull request.

CircleCI API v2

CircleCI is going to be rolling out a new version of their api (see here). Currently this library does not support v2, but I will update it in the future, see #228 for updates.

Migrating from v3 to v4

There have been some breaking changes, please see MIGRATING.md for more info.


Add using yarn or npm

yarn add circleci-api
## or 
npm install circleci-api


Get your API token from CircleCi

There are two ways to use this library.

1. CircleCi class

Get instance of the factory.

// Module
import { CircleCI, GitType, CircleCIOptions } from "circleci-api";
// Configure the factory with some defaults
const options: CircleCIOptions = {
  // Required for all requests
  token: "", // Set your CircleCi API token
  // Optional
  // Anything set here can be overriden when making the request
  // Git information is required for project/build/etc endpoints
  vcs: {
    type: GitType.GITHUB, // default: github
    owner: "worldturtlemedia",
    repo: "circleci-api"
  // Optional query params for requests
    branch: "master", // default: master
    filter: "completed"
// Create the api object
const api = new CircleCI(options)
// Use the api
 * Grab the latest artifacts from a successful build on a certain branch
 * @param [branch="master"] - Artifacts for certain branch
 * @return List of successfully built artifact objects
export async function getLatestArtifacts(branch: string = "master"): Promise<Artifact[]> {
  try {
    // Will use the repo defined in the options above
    const result: Aritfact[] = await api.latestArtifacts({ branch, filter: "successful" })
    console.log(`Found ${result.length} artifacts`)
    return result
  } catch (error) {
    console.log("No build artifacts found")
  return []
  .then(artifacts => {
      .forEach(({ path, url }: Artifact) => console.log(`${path} -> ${url}`))
// Or override settings set above
    { branch: "develop" },
      vcs: { repo: "awesome-repo" },
      options: { filter: "successful" }
  .then((artifacts: Artifact[]) => console.log(`Found ${artifacts.length} artifacts`))
  .catch(error => console.error(error))

2. Manually

The individual functions can also be imported if you only need one or two. To help with tree-shaking.

import { getMe, getLatestArtifacts } from "circleci-api";
const CIRCLECI_TOKEN: string = "circle-ci-token";
  .then(me => console.log("token is valid"))
  .catch(error => console.error("invalid token"));
getLatestArtifacts(CIRCLECI_TOKEN, {
  vcs: {
    owner: "billyBob",
    repo: "super-cool-app"
  options: {
    filter: "failed",
    branch: "feature-smith2"
  .then(result => console.log(`Found ${result.length} artifacts`))
  .catch(error => console.error(error));

Self-hosted CircleCI

You can supply a custom baseURL to override the default https://circleci.com/api/v1.1.

// Using the CircleCi class
new CircleCI({
  token: "my-token",
  vcs: { owner: "worldturtlemedia", repo = "circleci-api" },
  circleHost: "https://my-selfhosted-circleci.com/"
// Using the standalone functions
getLatestArtifacts("my-token", {

All of the standalone functions support a custom circleHost property. Using the CircleCI class you must specify it in the constructor.


There are three similar demos are available in the demo folder.

Note: I recommend VSCode for viewing and editing the examples. It will give you great intellisense about the library.

For the TypeScript & JavaScript follow the steps below:

# Step 1 - Change into demo folder and install dependencies 
cd demo
# Javascript example: 
node ./index.js
# Typescript example: 
npx ts-node --project ../tsconfig.base.json ./index.ts
# To view Browser example, first build project 
yarn build
# Then open `index.html` in your browser 

Supported endpoints

Using factory:

Optional properties:

export interface CircleRequest {
  token?: string;
  vcs?: GitInfo;
  options?: Options;

Any function with an optional paramater of CircleRequest can override any of the values you assigned when using the circleci() factory.

Name Required Optional Returns
me() none none Me
projects() none CircleRequest Project[]
followProject() { vcs: GitInfo } none FollowNewResult
recentBuilds() none { limit: number, offset: number } BuildSummary[]
builds() none { limit: number, offset: number } BuildSummary[]
buildsFor() branch: string = "master" { limit: number, offset: number } BuildSummary[]
build() buildNumber: number CircleRequest BuildWithSteps
artifacts() buildNumber: number CircleRequest Artifact[]
latestArtifacts() none CircleRequest Artifact[]
retry() buildNumber: number CircleRequest BuildSummary
cancel() buildNumber: number CircleRequest BuildSummary
triggerBuild() none CircleRequest Build
triggerBuildFor() branch: string = "master" CircleRequest Build
clearCache() none CircleRequest ClearCacheResponse
listEnvVars() none CircleRequest EnvVariable[]
addEnvVar() variable: EnvVariable CircleRequest EnvVariable
getEnvVar() envName: string CircleRequest EnvVariable
deleteEnvVar() envName: string CircleRequest MessageResponse
checkoutKeys() none CircleRequest CheckoutKeyResponse
createCheckoutKey() type: CheckoutType CircleRequest CheckoutKeyResponse
checkoutKey() fingerprint: string CircleRequest CheckoutKeyResponse
deleteCheckoutKey() fingerprint: string CircleRequest DeleteCheckoutKeyResponse
getTestMetadata() buildNumber: number CircleRequest TestMetadataResponse
addSSHKey() key: SSHKey CircleRequest none
addHerokuKey() key: HerokuKey CircleRequest none

Missing endpoint

The last remaining endpoint probably won't be added unless there is demand.

Name Link
Add user to build ref


<<<<<<< HEAD This library uses boilerplate typescript-library-starter. So see that repo for more information about the setup, and layout of the files.

This library uses commitizen for commit messages, so be sure to use yarn commit when commiting your changes,

  1. Fork this repo
  2. Add your awesome feature
  3. If adding functionality, add tests for your feature
  4. Commit using commitizen: yarn commit
  5. Submit a PR


# Setup 
git clone https://github.com/worldturtlemedia/circleci-api
cd circleci-api
# Make some changes 
# Run tests then build 
yarn test:prod
yarn build
# Use commitzen to commit 
yarn commit
# If all is good, open a PR! 




MIT License
Copyright (c) 2019 WorldTurtleMedia
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.


npm i circleci-api

DownloadsWeekly Downloads






Unpacked Size

1.21 MB

Total Files


Last publish


  • avatar