# API Reference

Integrate AllCode Nexus programmatically using the REST API. Use these endpoints to pull metrics, manage users, and generate billing reports for your internal systems.

## Authentication

All API requests require a Bearer token obtained from Amazon Cognito.

```
Authorization: Bearer <access_token>
```

### Obtaining a Token

Exchange your Cognito credentials for an access token:

```bash
curl -X POST https://auth.nexus.allcode.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=<your_client_id>&client_secret=<your_client_secret>"
```

You can find your API client credentials in the Nexus portal under **Settings** → **API Access**.

### Token Lifetime

Tokens are valid for 1 hour. Cache and reuse tokens until expiry to avoid unnecessary token requests.

---

## Base URL

```
https://api.nexus.allcode.com/v1
```

---

## Endpoints

### GET /api/metrics/summary

Returns aggregated usage metrics for your organization.

**Query Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `start_date` | string | Yes | Start date (ISO 8601, e.g., `2026-01-01`) |
| `end_date` | string | Yes | End date (ISO 8601, e.g., `2026-01-31`) |
| `group_by` | string | No | Group results by `user`, `team`, `model`, or `day` |

**Example Request:**

```bash
curl -H "Authorization: Bearer <token>" \
  "https://api.nexus.allcode.com/v1/api/metrics/summary?start_date=2026-05-01&end_date=2026-05-27&group_by=user"
```

**Example Response:**

```json
{
  "period": {
    "start": "2026-05-01T00:00:00Z",
    "end": "2026-05-27T23:59:59Z"
  },
  "total_input_tokens": 12450000,
  "total_output_tokens": 8320000,
  "total_requests": 4521,
  "active_users": 23,
  "breakdown": [
    {
      "user": "jane.doe@company.com",
      "input_tokens": 1250000,
      "output_tokens": 890000,
      "requests": 412
    }
  ]
}
```

---

### GET /api/users

Returns a list of users in your organization with their current status and quota usage.

**Query Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string | No | Filter by `active`, `inactive`, or `all` (default: `all`) |
| `limit` | integer | No | Results per page (default: 50, max: 200) |
| `offset` | integer | No | Pagination offset |

**Example Request:**

```bash
curl -H "Authorization: Bearer <token>" \
  "https://api.nexus.allcode.com/v1/api/users?status=active&limit=10"
```

**Example Response:**

```json
{
  "total": 45,
  "users": [
    {
      "email": "jane.doe@company.com",
      "status": "active",
      "last_active": "2026-05-27T14:32:00Z",
      "quota_policy": "Engineering Standard",
      "tokens_used_today": 523000,
      "token_limit_today": 2000000
    }
  ]
}
```

---

### GET /api/billing/report

Returns billing data for cost attribution and chargeback.

**Query Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `month` | string | Yes | Billing month (format: `YYYY-MM`) |
| `format` | string | No | Response format: `json` (default) or `csv` |

**Example Request:**

```bash
curl -H "Authorization: Bearer <token>" \
  "https://api.nexus.allcode.com/v1/api/billing/report?month=2026-05&format=json"
```

**Example Response:**

```json
{
  "month": "2026-05",
  "organization": "Acme Corp",
  "total_cost_usd": 1247.83,
  "total_tokens": 45200000,
  "by_user": [
    {
      "email": "jane.doe@company.com",
      "input_tokens": 3200000,
      "output_tokens": 2100000,
      "cost_usd": 87.42
    }
  ],
  "by_model": [
    {
      "model": "claude-sonnet-4-20250514",
      "input_tokens": 30000000,
      "output_tokens": 20000000,
      "cost_usd": 890.00
    }
  ]
}
```

---

## Error Responses

All errors follow a consistent format:

```json
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired access token"
  }
}
```

| HTTP Status | Code | Description |
|-------------|------|-------------|
| 401 | `UNAUTHORIZED` | Missing or invalid Bearer token |
| 403 | `FORBIDDEN` | Token valid but insufficient permissions |
| 404 | `NOT_FOUND` | Endpoint or resource not found |
| 422 | `VALIDATION_ERROR` | Invalid query parameters |
| 429 | `RATE_LIMITED` | Too many requests (limit: 100/minute) |
| 500 | `INTERNAL_ERROR` | Server error — retry with backoff |

## Rate Limits

API requests are limited to **100 requests per minute** per organization. The response includes rate limit headers:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1716825600
```

## Next Steps

- [Deployment Guide](./deployment.md)
- [Security & Compliance](./security.md)