circleci-v2-sdk v4.1.3
CircleCI API Node SDK
The CircleCI API Node SDK is a NPM library for accessing the resources that make up the CircleCI API V2.
SDK Installation
NPM
npm add circleci-v2-sdk
Yarn
yarn add circleci-v2-sdk
SDK Example Usage
Example
import { Circleci } from "circleci-v2-sdk";
async function run() {
const sdk = new Circleci({
security: {
apiKeyHeader: "<YOUR_API_KEY_HERE>",
},
});
const res = await sdk.context.addEnvironmentVariableToContext({
requestBody: {
value: "some-secret-value",
},
contextId: "0407a4cd-7d9d-4359-a2ad-0a7c67c0ba96",
envVarName: "string",
});
if (res.statusCode == 200) {
// handle response
}
}
run();
Available Resources and Operations
context
- addEnvironmentVariableToContext - Add or update an environment variable
- createContext - Create a new context
- deleteContext - Delete a context
- deleteEnvironmentVariableFromContext - Remove an environment variable
- getContext - Get a context
- listContexts - List contexts
- listEnvironmentVariablesFromContext - List environment variables
insights
- getAllInsightsBranches - Get all branches for a project
- getFlakyTests - Get flaky tests for a project
- getJobTimeseries - Job timeseries data
- getOrgSummaryData - Get summary metrics with trends for the entire org, and for each project.
- getProjectWorkflowJobMetrics - Get summary metrics for a project workflow's jobs.
- getProjectWorkflowMetrics - Get summary metrics for a project's workflows
- getProjectWorkflowRuns - Get recent runs of a workflow
- getProjectWorkflowTestMetrics - Get test metrics for a project's workflows
- getProjectWorkflowsPageData - Get summary metrics and trends for a project across it's workflows and branches
- getWorkflowSummary - Get metrics and trends for workflows
user
- getCollaborations - Collaborations
- getCurrentUser - User Information
- getUser - User Information
oidcTokenManagement
- deleteOrgClaims - Delete org-level claims
- deleteProjectClaims - Delete project-level claims
- getOrgClaims - Get org-level claims
- getProjectClaims - Get project-level claims
- patchOrgClaims - Patch org-level claims
- patchProjectClaims - Patch project-level claims
policyManagement
- createPolicyBundle - Creates policy bundle for the context
- getDecisionLog - Retrieves the owner's decision audit log by given decisionID
- getDecisionLogPolicyBundle - Retrieves Policy Bundle for a given decision log ID
- getDecisionLogs - Retrieves the owner's decision audit logs.
- getDecisionSettings - Get the decision settings
- getPolicyBundle - Retrieves Policy Bundle
- getPolicyDocument - Retrieves a policy document
- makeDecision - Makes a decision
- setDecisionSettings - Set the decision settings
pipeline
- continuePipeline - Continue a pipeline
- getPipelineById - Get a pipeline by ID
- getPipelineByNumber - Get a pipeline by pipeline number
- getPipelineConfigById - Get a pipeline's configuration
- listMyPipelines - Get your pipelines
- listPipelines - Get a list of pipelines
- listPipelinesForProject - Get all pipelines
- listWorkflowsByPipelineId - Get a pipeline's workflows
- triggerPipeline - Trigger a new pipeline
project
- createCheckoutKey - Create a new checkout key
- createEnvVar - Create an environment variable
- deleteCheckoutKey - Delete a checkout key
- deleteEnvVar - Delete an environment variable
- getCheckoutKey - Get a checkout key
- getEnvVar - Get a masked environment variable
- getProjectBySlug - Get a project
- listCheckoutKeys - Get all checkout keys
- listEnvVars - List all environment variables
job
- cancelJob - Cancel job
- getJobArtifacts - Get a job's artifacts
- getJobDetails - Get job details
- getTests - Get test metadata
schedule
- createSchedule - Create a schedule
- deleteScheduleById - Delete a schedule
- getScheduleById - Get a schedule
- listSchedulesForProject - Get all schedules
- updateSchedule - Update a schedule
webhook
- createWebhook - Create an outbound webhook
- deleteWebhook - Delete an outbound webhook
- getWebhookById - Get a webhook
- getWebhooks - List webhooks
- updateWebhook - Update an outbound webhook
workflow
- approvePendingApprovalJobById - Approve a job
- cancelWorkflow - Cancel a workflow
- getWorkflowById - Get a workflow
- listWorkflowJobs - Get a workflow's jobs
- rerunWorkflow - Rerun a workflow
Error Handling
Handling errors in this SDK should largely match your expectations. All operations return a response object or throw an error. If Error objects are specified in your OpenAPI Spec, the SDK will throw the appropriate Error type.
Error Object | Status Code | Content Type |
---|---|---|
errors.SDKError | 4xx-5xx | / |
Example
import { Circleci } from "circleci-v2-sdk";
async function run() {
const sdk = new Circleci({
security: {
apiKeyHeader: "<YOUR_API_KEY_HERE>",
},
});
let res;
try {
res = await sdk.context.addEnvironmentVariableToContext({
requestBody: {
value: "some-secret-value",
},
contextId: "0407a4cd-7d9d-4359-a2ad-0a7c67c0ba96",
envVarName: "string",
});
} catch (err) {
if (err instanceof errors.SDKError) {
console.error(err); // handle exception
throw err;
}
}
if (res.statusCode == 200) {
// handle response
}
}
run();
Server Selection
Select Server by Index
You can override the default server globally by passing a server index to the serverIdx: number
optional parameter when initializing the SDK client instance. The selected server will then be used as the default on the operations that use it. This table lists the indexes associated with the available servers:
# | Server | Variables |
---|---|---|
0 | https://circleci.com/api/v2 | None |
Example
import { Circleci } from "circleci-v2-sdk";
async function run() {
const sdk = new Circleci({
serverIdx: 0,
security: {
apiKeyHeader: "<YOUR_API_KEY_HERE>",
},
});
const res = await sdk.context.addEnvironmentVariableToContext({
requestBody: {
value: "some-secret-value",
},
contextId: "0407a4cd-7d9d-4359-a2ad-0a7c67c0ba96",
envVarName: "string",
});
if (res.statusCode == 200) {
// handle response
}
}
run();
Override Server URL Per-Client
The default server can also be overridden globally by passing a URL to the serverURL: str
optional parameter when initializing the SDK client instance. For example:
import { Circleci } from "circleci-v2-sdk";
async function run() {
const sdk = new Circleci({
serverURL: "https://circleci.com/api/v2",
security: {
apiKeyHeader: "<YOUR_API_KEY_HERE>",
},
});
const res = await sdk.context.addEnvironmentVariableToContext({
requestBody: {
value: "some-secret-value",
},
contextId: "0407a4cd-7d9d-4359-a2ad-0a7c67c0ba96",
envVarName: "string",
});
if (res.statusCode == 200) {
// handle response
}
}
run();
Custom HTTP Client
The Typescript SDK makes API calls using the axios HTTP library. In order to provide a convenient way to configure timeouts, cookies, proxies, custom headers, and other low-level configuration, you can initialize the SDK client with a custom AxiosInstance
object.
For example, you could specify a header for every request that your sdk makes as follows:
import { circleci-v2-sdk } from "Circleci";
import axios from "axios";
const httpClient = axios.create({
headers: {'x-custom-header': 'someValue'}
})
const sdk = new Circleci({defaultClient: httpClient});
Authentication
Per-Client Security Schemes
This SDK supports the following security schemes globally:
Name | Type | Scheme |
---|---|---|
apiKeyHeader | apiKey | API key |
apiKeyQuery | apiKey | API key |
basicAuth | http | HTTP Basic |
You can set the security parameters through the security
optional parameter when initializing the SDK client instance. The selected scheme will be used by default to authenticate with the API for all operations that support it. For example:
import { Circleci } from "circleci-v2-sdk";
async function run() {
const sdk = new Circleci({
security: {
apiKeyHeader: "<YOUR_API_KEY_HERE>",
},
});
const res = await sdk.context.addEnvironmentVariableToContext({
requestBody: {
value: "some-secret-value",
},
contextId: "0407a4cd-7d9d-4359-a2ad-0a7c67c0ba96",
envVarName: "string",
});
if (res.statusCode == 200) {
// handle response
}
}
run();