# CircleCI API

**Provider:** CircleCI
**Category:** developer
**Base URL:** `https://circleci.com/api/v2`
**Auth:** api-key — `Circle-Token: YOUR_PERSONAL_API_TOKEN`
**Rate Limit:** 100 requests/min
**Free Tier:** Yes — [object Object]
**Pricing:** Pay per use (pay-as-you-go)
**Docs:** https://circleci.com/docs/api/v2/

## Description

The CircleCI API v2 provides programmatic control over your CI/CD infrastructure. Trigger pipelines with custom parameters, query pipeline and workflow status, list and filter jobs, retrieve test metadata and artifacts, manage environment variables and contexts, and interact with orbs. Used for building custom deployment dashboards, automated release workflows, PR status bots, and infrastructure monitoring integrations.

## Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `https://circleci.com/api/v2/project/{project_slug}/pipeline` | Trigger a new pipeline for a project |
| GET | `https://circleci.com/api/v2/pipeline/{pipeline_id}` | Get pipeline details and status |
| GET | `https://circleci.com/api/v2/pipeline/{pipeline_id}/workflow` | List workflows in a pipeline |
| GET | `https://circleci.com/api/v2/workflow/{id}/job` | List jobs in a workflow |
| GET | `https://circleci.com/api/v2/project/{project_slug}/envvar` | List environment variables for a project |
| GET | `https://circleci.com/api/v2/insights/{project_slug}/workflows` | Get workflow performance insights and trends |

## Authentication

Generate a Personal API Token in CircleCI User Settings → Personal API Tokens. Pass it in the Circle-Token header.

```
Circle-Token: YOUR_PERSONAL_API_TOKEN
```

## Sample Request

```bash
curl "https://circleci.com/api/v2/project/github/myorg/myrepo/pipeline" \
  -H "Circle-Token: $CIRCLECI_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{"branch":"main","parameters":{"deploy_env":"staging"}}'
```

## Sample Response

```json
{
  "id": "5034460f-c7a2-4c3c-b5c2-abc123456789",
  "number": 47,
  "state": "created",
  "created_at": "2024-03-15T10:00:00.000Z",
  "trigger": { "type": "api", "actor": { "login": "kevin" } }
}
```

## Pricing Details

Free: 30k credits/month. Performance $15/mo: 25k credits/month + $0.0006/credit. Scale: custom. Credits consumed per machine type and time (Linux small: 5 credits/min, large: 20 credits/min).

---

*Source: [API Map](https://apimap.dev/apis/circleci/) — CC BY 4.0*