# MyCO2 Carbon Intelligence API

Calculate carbon dioxide equivalent (CO2e) emissions for financial transactions, flights, and physical activities. Supports 140+ countries and multiple classification systems.

## Base URL

`https://sandbox.myco2suite.com/api/v1`

## Authentication

All API requests require an API key passed via the `x-api-key` header:

```
x-api-key: your_api_key_here
```

Sign up at `https://myco2suite.com` to get an API key.

## Endpoints

### Transaction Emissions (Spend-Based)

Calculate CO2e from financial transaction amounts.

```http
POST /transaction
```

**Parameters:**
- `mcc` (string, optional) - Merchant Category Code (4 digits)
- `bea_code` (string, optional) - BEA industry code
- `naics` (string, optional) - NAICS industry code
- `isic` (string, optional) - ISIC activity code
- `sic` (string, optional) - SIC industry code
- `nace` (string, optional) - NACE activity code
- `spend_amount` (number, required) - Transaction amount
- `currency` (string) - ISO 4217 currency code (default: USD)
- `country` (string) - ISO 3166-1 alpha-2 country code (default: US)
- `year` (integer, optional) - Data year for emission factors

**Example:**
```json
{
  "mcc": "5411",
  "spend_amount": 150.00,
  "currency": "USD",
  "country": "US"
}
```

**Response:**
```json
{
  "co2e_grams": 19050,
  "co2e_kg": 19.05,
  "co2e_tonnes": 0.01905,
  "input": { ... },
  "factor": { ... },
  "methodology": { ... }
}
```

### Flight Emissions

Calculate CO2e from flight details.

```http
POST /flight
```

**Parameters:**
- `origin` (string, required) - Origin airport code (IATA, UN/LOCODE, or lat/long)
- `destination` (string, required) - Destination airport code
- `cabin_class` (string) - economy, premium_economy, business, first (default: economy)
- `trip_type` (string) - one_way or return (default: one_way)

**Example:**
```json
{
  "origin": "JFK",
  "destination": "LAX",
  "cabin_class": "economy",
  "trip_type": "one_way"
}
```

### Activity Emissions

Calculate CO2e from physical activities.

```http
POST /activity
```

**Parameters:**
- `activity_type` (string, required) - Activity type code
- `quantity` (number, required) - Activity quantity
- `country` (string) - ISO 3166-1 alpha-2 country code (default: US)
- `year` (integer, optional) - Data year

**Example:**
```json
{
  "activity_type": "car_km",
  "quantity": 500,
  "country": "US"
}
```

### Emission Factors

Look up emission factors by classification code or activity type.

```http
GET /factor
```

**Parameters:**
- `classification_code` (string) - Industry/activity code
- `classification_system` (string) - mcc, bea, naics, isic, sic, nace, or activity
- `activity_type` (string) - Activity type code
- `country` (string) - Country code (default: US)
- `year` (integer, optional) - Data year

### Activity Types

List all available activity types.

```http
GET /activity-types
```

### Budget

Calculate carbon budget scenarios.

```http
POST /budget
```

## Agent Protocols

### A2A (Agent-to-Agent)

MyCO2 supports Google's A2A protocol for agent discovery and collaboration.

**Agent Card:** `GET /api/v1/a2a/agent-card`

Returns agent capabilities in JSON format compatible with the A2A specification.

**JSON-RPC Endpoint:** `POST /api/v1/a2a/rpc`

Supported methods:
- `SendMessage` - Send a task message
- `GetTask` - Get task status
- `CancelTask` - Cancel a task
- `ListTasks` - List all tasks

### ACP (Agent Communication Protocol)

MyCO2's native agent protocol for carbon calculation delegation.

**Endpoint:** `GET /api/v1/acp/agents`

### MCP (Model Context Protocol)

Local AI client integration for Claude Desktop, Cursor, etc.

See `/mcp/README.md` for setup instructions.

## Rate Limits

- Free tier: 1,000 requests/month
- Rate limit headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`

## Error Responses

All errors return a consistent format:

```json
{
  "error": "Error message",
  "field": "field_name",
  "message": "Human-readable description"
}
```

HTTP status codes:
- `400` - Invalid request
- `401` - Missing or invalid API key
- `422` - Validation error
- `429` - Rate limit exceeded
- `500` - Server error

## Data Sources

Emission factors are sourced from:
- EPA Supply Chain GHG Emission Factors (US)
- DEFRA/BEIS UK Greenhouse Gas Conversion Factors (UK)
- Australian NGA Factors (AU)
- Singapore NEA Factors (SG)

## Support

- Documentation: `https://docs.myco2suite.com`
- Email: `hello@myco2suite.com`
- API Base: `https://sandbox.myco2suite.com/api/v1`