circleci-api

library4.1.4jsnpmunverified

The `circleci-api` library provides a client for interacting with the CircleCI API, designed for use in both Node.js and browser environments. Written entirely in TypeScript, it offers comprehensive type definitions and auto-completion for API responses, significantly reducing the need to consult external documentation. The current stable version is 4.1.4. While the project has seen bug fix releases in 2020-2021, its major version updates are less frequent, with v4.0.0 released in 2019. A key differentiator is its robust TypeScript support, providing static analysis benefits that many alternative plain JavaScript wrappers lack. However, it's important to note that this library currently supports only CircleCI API v1 and does not yet integrate with the newer CircleCI API v2, which is a known limitation the maintainers plan to address in the future.

devops http-networking

npm install circleci-api

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CIRCLECI-API

circleci-api

devopsjavascriptv4.1.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CircleCI

✓ import { CircleCI } from 'circleci-api';

✗ const CircleCI = require('circleci-api').CircleCI;

Primarily designed for ES Modules and TypeScript. CommonJS usage is less idiomatic and might lack full type benefits.

GitType

✓ import { GitType } from 'circleci-api';

✗ import { GitType as Type } from 'circleci-api';

GitType is an enum for specifying the VCS type (e.g., GITHUB, BITBUCKET). Import directly by name.

CircleCIOptions

✓ import { CircleCIOptions } from 'circleci-api';

✗ import { Options } from 'circleci-api';

This interface defines the configuration object for the CircleCI client. Ensure you import the specific type name.

This quickstart initializes the CircleCI client and fetches the latest successful build artifacts for a specified repository and branch, demonstrating basic setup and API interaction.

import { CircleCI, GitType, CircleCIOptions, Artifact } from 'circleci-api'; // Set your CircleCI API token securely via environment variables const circleciToken = process.env.CIRCLECI_TOKEN ?? ''; if (!circleciToken) { console.error('CIRCLECI_TOKEN environment variable is not set.'); process.exit(1); } const options: CircleCIOptions = { token: circleciToken, vcs: { type: GitType.GITHUB, owner: 'worldturtlemedia', repo: 'circleci-api' }, options: { branch: 'master', filter: 'successful' } }; const api = new CircleCI(options); async function getLatestSuccessfulArtifacts(): Promise<Artifact[]> { try { console.log('Fetching latest successful artifacts...'); const result: Artifact[] = await api.latestArtifacts(); console.log(`Found ${result.length} artifacts on branch '${options.options?.branch}'`); return result; } catch (error: any) { console.error('Failed to fetch artifacts:', error.message); if (error.response && error.response.data) { console.error('API Error details:', error.response.data); } return []; } } getLatestSuccessfulArtifacts();

Debug

Known issues

breakingVersion 4.0.0 introduced breaking changes, specifically reordering parameters for several standalone functions. Developers migrating from v3.x should consult the MIGRATING.md file for details to avoid runtime errors.

fix

Review the MIGRATING.md documentation (https://github.com/worldturtlemedia/circleci-api/blob/master/MIGRATING.md) to adjust function call signatures for updated parameter orders.

affects: >=4.0.0

gotchaThis library currently supports only CircleCI API v1. It does not integrate with or support the newer CircleCI API v2. Attempting to use v2 specific endpoints or features will not work.

fix

Be aware that only CircleCI API v1 functionality is available. For CircleCI API v2 interactions, consider alternative clients or direct HTTP requests until this library is updated.

affects: >=3.0.0

gotchaWhile comprehensive, the TypeScript type definitions may have occasional inaccuracies or missing properties for specific API response payloads. The maintainers welcome contributions to improve type accuracy.

fix

If encountering type errors or missing properties, consider casting the response to `any` as a temporary workaround and/or contribute a pull request with improved type definitions.

affects: >=3.0.0

Errors

Common errors & fixes

Cannot find module 'circleci-api/typings' or its corresponding type declarations.

Incorrect path to the typings file, specifically prior to version 4.1.2.

fix

Ensure you are using `circleci-api@4.1.2` or newer. If the problem persists, check your `tsconfig.json` for proper `typeRoots` configuration or node module resolution.

Error: Cannot find module 'axios' (or similar bundling errors related to axios)

Issues with module resolution or bundling tools (like Webpack/Rollup) not correctly locating `axios`, especially in older versions or specific build configurations.

fix

Upgrade `circleci-api` to the latest version (v3.3.1 fixed a specific path issue). Ensure `axios` is correctly installed as a direct dependency or peer dependency if required by your bundler configuration.

API Error: No build (or other 4xx/5xx status codes)

The API request failed due to invalid credentials, incorrect project/branch details, insufficient permissions, or a server-side issue.

fix

Double-check your `CIRCLECI_TOKEN` environment variable for correctness. Verify the `vcs.owner`, `vcs.repo`, and `options.branch` match an existing CircleCI project and branch with builds. Inspect the error response for more specific details.

Upgrade

Version history

4.1.4latest on npm

Audit

Dependencies

axiosrequiredHTTP client for making API requests.

Agent activity

12 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/worldturtlemedia/circleci-api ↗

packagehttps://www.npmjs.com/package/circleci-api ↗

homepagehttps://circleci.com ↗