API Overview

The CICosts API allows you to programmatically access your CI/CD cost data. Use it to build integrations, automate reporting, and extend CICosts functionality.

Base URL

https://api.cicosts.dev/v1

API Availability

Plan	API Access
Free	Read-only, limited
Pro	Full access
Team	Full access + higher limits

Authentication

All API requests require authentication via API key:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.cicosts.dev/v1/costs

See Authentication for details.

Response Format

All responses are JSON:

{
  "data": { ... },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2024-01-15T12:00:00Z"
  }
}

Error Responses

Errors include a code and message:

{
  "error": {
    "code": "invalid_parameter",
    "message": "start_date must be before end_date",
    "details": {
      "field": "start_date"
    }
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

Rate Limits

Plan	Requests/Hour
Free	100
Pro	1,000
Team	10,000

Rate limit headers are included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1705320000

Pagination

List endpoints support pagination:

GET /v1/workflows?limit=50&offset=100

Response includes pagination info:

{
  "data": [...],
  "pagination": {
    "total": 250,
    "limit": 50,
    "offset": 100,
    "has_more": true
  }
}

Available Endpoints

Costs

Endpoint	Description
GET /costs	Get cost data
GET /costs/summary	Get cost summary
GET /costs/export	Export cost data

Workflows

Endpoint	Description
GET /workflows	List workflows
GET /workflows/:id	Get workflow details
GET /workflows/:id/runs	List workflow runs

Alerts

Endpoint	Description
GET /alerts	List alerts
POST /alerts	Create alert
PUT /alerts/:id	Update alert
DELETE /alerts/:id	Delete alert

Webhooks

Endpoint	Description
GET /webhooks	List webhooks
POST /webhooks	Create webhook
DELETE /webhooks/:id	Delete webhook

SDKs and Libraries

Official SDKs

Coming soon:

• JavaScript/TypeScript
• Python
• Go

Community Libraries

Check our GitHub for community-contributed libraries.

Quick Start

1. Get Your API Key

1. Go to Settings → API
2. Click Generate Key
3. Copy the key (shown once)

2. Make Your First Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.cicosts.dev/v1/costs/summary

Response:

{
  "data": {
    "today": 47.82,
    "this_week": 312.50,
    "this_month": 1247.00,
    "projected": 1890.00
  }
}

3. Explore the API

Use the endpoints in this documentation to:

• Pull cost data into your dashboards
• Build custom reports
• Set up integrations
• Automate workflows

Best Practices

Cache Responses

Cost data doesn't change frequently:

• Cache summary data for 5-10 minutes
• Cache historical data for longer

Use Webhooks

Instead of polling:

• Set up webhooks for real-time updates
• Reduce API calls
• Get instant notifications

Handle Errors Gracefully

Always check for errors:

try {
  const response = await fetch('/costs');
  if (!response.ok) {
    const error = await response.json();
    console.error(error.error.message);
  }
} catch (err) {
  // Handle network errors
}

Respect Rate Limits

If rate limited:

• Wait until X-RateLimit-Reset
• Implement exponential backoff
• Consider caching more aggressively

---

Next: Authentication →