API Documentation

# AI Coalition Network - API Documentation

**Version:** 1.0
**Base URL:** `https://ai-coalition.net/api`
**Last Updated:** January 2026

---

## Table of Contents

1. [Overview](#overview)
2. [Security & Authentication](#security--authentication)
3. [Getting Started](#getting-started)
4. [V1 REST API Endpoints](#v1-rest-api-endpoints)
5. [LLM-Optimized Endpoints](#llm-optimized-endpoints)
6. [Rate Limiting](#rate-limiting)
7. [Error Handling](#error-handling)
8. [Data Models](#data-models)
9. [Scoring Methodology](#scoring-methodology)

---

## Overview

The AI Coalition Network API provides programmatic access to our comprehensive database of ethical AI companies. This partner-only API enables you to:

- **Discover** ethical AI companies with detailed profiles
- **Access** company rankings based on ethics, profitability, and innovation
- **Filter** companies by profitability tier, focus areas, and search criteria
- **Integrate** verified AI company data into your applications

**Access Level:** Partner-only (requires admin or partner role)

---

## Security & Authentication

### Security Overview

The AI Coalition Network API implements enterprise-grade security measures:

- ✅ **Token-based authentication** using Laravel Sanctum
- ✅ **Role-based access control** (admin/partner roles required)
- ✅ **HTTPS encryption** for all API requests
- ✅ **Rate limiting** to prevent abuse
- ✅ **Audit logging** of all API access

### Authentication Method

All API requests must be authenticated using a **Bearer token** in the Authorization header.

#### Step 1: Obtain Your API Token

1. **Log in** to your AI Coalition Network account
2. Navigate to your **Dashboard** at `https://ai-coalition.net/dashboard`
3. Click the **"View API Token"** button (visible only to partners/admins)
4. Click **"Generate API Token"** to create your token
5. **Copy and save** your token immediately (it will only be shown once)

#### Step 2: Use Your Token

Include your token in the `Authorization` header of every API request:

```bash
Authorization: Bearer YOUR_TOKEN_HERE
```

### Authentication Examples

#### cURL Example
```bash
curl -H "Authorization: Bearer 2|bRgEvYP1vLF4Hs2koLCvLYQPYL7nsk50t4y6ph1i159d7634" \
     https://ai-coalition.net/api/v1/companies
```

#### JavaScript/Fetch Example
```javascript
fetch('https://ai-coalition.net/api/v1/companies', {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN_HERE',
    'Accept': 'application/json'
  }
})
.then(response => response.json())
.then(data => console.log(data));
```

#### Python Example
```python
import requests

headers = {
    'Authorization': 'Bearer YOUR_TOKEN_HERE',
    'Accept': 'application/json'
}

response = requests.get(
    'https://ai-coalition.net/api/v1/companies',
    headers=headers
)

data = response.json()
print(data)
```

#### PHP Example
```php
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://ai-coalition.net/api/v1/companies');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_TOKEN_HERE',
    'Accept: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);
?>
```

### Token Security Best Practices

⚠️ **IMPORTANT:** Treat your API token like a password!

- **Never commit** tokens to version control (use environment variables)
- **Never share** tokens publicly or in client-side code
- **Rotate tokens** regularly for enhanced security
- **Use HTTPS** for all API requests
- **Store tokens** in secure credential management systems

---

## Getting Started

### Quick Start Guide

1. **Verify your partner status** - Ensure you have admin or partner role
2. **Generate your API token** - Visit `/api-token` page
3. **Test the connection** - Make a simple API call
4. **Explore the data** - Browse companies and rankings

### Test Your Connection

```bash
curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     https://ai-coalition.net/api/v1/companies?per_page=5
```

Expected response: HTTP 200 with a JSON array of companies

### Common Use Cases

- **Display ethical AI companies** on your website
- **Filter companies** by profitability tier for investors
- **Track company rankings** and score changes over time
- **Search companies** by focus areas (e.g., "healthcare AI", "NLP")
- **Integrate company data** into partner dashboards

---

## V1 REST API Endpoints

### 1. List Companies

Retrieve a paginated list of verified AI companies with filtering and sorting options.

**Endpoint:** `GET /v1/companies`

**Authentication:** Required (Bearer token)

#### Query Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `page` | integer | No | 1 | Page number for pagination |
| `per_page` | integer | No | 15 | Items per page (max 50) |
| `search` | string | No | - | Search in name, tagline, description |
| `tier` | string | No | - | Filter by: `highly-profitable`, `profitable`, `pre-revenue` |
| `sort` | string | No | `rank` | Sort by: `rank`, `name`, `newest` |

#### Example Request

```bash
curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     "https://ai-coalition.net/api/v1/companies?sort=rank&per_page=20&tier=highly-profitable"
```

#### Response Structure

```json
{
  "data": [
    {
      "uuid": "9d4e5f6g-7h8i-9j0k-1l2m-3n4o5p6q7r8s",
      "slug": "anthropic",
      "name": "Anthropic",
      "tagline": "AI safety and research company",
      "website": "https://anthropic.com",
      "logo_url": "https://ai-coalition.net/storage/company-logos/anthropic.png",
      "profitability_tier": "highly-profitable",
      "scores": {
        "overall": 87.5,
        "profitability": 85.0,
        "ethics": 92.0,
        "innovation": 86.0
      },
      "focus_areas": [
        "Machine Learning",
        "Natural Language Processing",
        "AI Safety"
      ],
      "created_at": "2024-01-15T10:30:00+00:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 20,
    "total": 93
  },
  "links": {
    "first": "https://ai-coalition.net/api/v1/companies?page=1",
    "last": "https://ai-coalition.net/api/v1/companies?page=5",
    "prev": null,
    "next": "https://ai-coalition.net/api/v1/companies?page=2"
  }
}
```

#### Field Descriptions

**Company Object:**
- `uuid` (string) - Unique identifier for the company
- `slug` (string) - URL-friendly identifier
- `name` (string) - Company name
- `tagline` (string|null) - Short company description
- `website` (string|null) - Company website URL
- `logo_url` (string|null) - Full URL to company logo image
- `profitability_tier` (string) - One of: `highly-profitable`, `profitable`, `pre-revenue`
- `scores` (object) - Scoring breakdown
  - `overall` (float) - Composite score (0-100)
  - `profitability` (float) - Profitability score (0-100)
  - `ethics` (float) - Ethics score (0-100)
  - `innovation` (float) - Innovation score (0-100)
- `focus_areas` (array) - Array of company focus areas/technologies
- `created_at` (string) - ISO 8601 timestamp of company creation

**Meta Object:**
- `current_page` (integer) - Current page number
- `last_page` (integer) - Total number of pages
- `per_page` (integer) - Items per page
- `total` (integer) - Total number of companies matching criteria

**Links Object:**
- `first` (string) - URL to first page
- `last` (string) - URL to last page
- `prev` (string|null) - URL to previous page (null if on first page)
- `next` (string|null) - URL to next page (null if on last page)

---

### 2. Get Company Details

Retrieve detailed information about a specific company including description, ethics statement, and statistics.

**Endpoint:** `GET /v1/companies/{uuid}`

**Authentication:** Required (Bearer token)

#### Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `uuid` | string | Yes | Company UUID |

#### Example Request

```bash
curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     "https://ai-coalition.net/api/v1/companies/9d4e5f6g-7h8i-9j0k-1l2m-3n4o5p6q7r8s"
```

#### Response Structure

```json
{
  "data": {
    "uuid": "9d4e5f6g-7h8i-9j0k-1l2m-3n4o5p6q7r8s",
    "slug": "anthropic",
    "name": "Anthropic",
    "tagline": "AI safety and research company",
    "website": "https://anthropic.com",
    "logo_url": "https://ai-coalition.net/storage/company-logos/anthropic.png",
    "profitability_tier": "highly-profitable",
    "scores": {
      "overall": 87.5,
      "profitability": 85.0,
      "ethics": 92.0,
      "innovation": 86.0
    },
    "focus_areas": [
      "Machine Learning",
      "Natural Language Processing",
      "AI Safety"
    ],
    "description": "Anthropic is an AI safety and research company working to build reliable, interpretable, and steerable AI systems.",
    "ethics_statement": "We are committed to building AI systems that are safe, beneficial, and aligned with human values.",
    "stats": {
      "followers": 1245,
      "posts": 42,
      "jobs": 15,
      "products": 3
    },
    "created_at": "2024-01-15T10:30:00+00:00"
  }
}
```

#### Additional Fields (Detailed View)

**Extended Company Object:**
- `description` (string|null) - Full company description
- `ethics_statement` (string|null) - Company's ethics and values statement
- `stats` (object) - Company statistics
  - `followers` (integer) - Number of users following this company
  - `posts` (integer) - Number of published posts by this company
  - `jobs` (integer) - Number of active job listings
  - `products` (integer) - Number of active products

---

### 3. Get Rankings

Retrieve the top-ranked companies based on overall scores.

**Endpoint:** `GET /v1/rankings`

**Authentication:** Required (Bearer token)

#### Query Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `limit` | integer | No | 50 | Number of companies to return (max 100) |

#### Example Request

```bash
curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     "https://ai-coalition.net/api/v1/rankings?limit=10"
```

#### Response Structure

```json
{
  "data": [
    {
      "rank": 1,
      "uuid": "9d4e5f6g-7h8i-9j0k-1l2m-3n4o5p6q7r8s",
      "name": "Anthropic",
      "slug": "anthropic",
      "logo_url": "https://ai-coalition.net/storage/company-logos/anthropic.png",
      "scores": {
        "overall": 87.5,
        "profitability": 85.0,
        "ethics": 92.0,
        "innovation": 86.0
      },
      "profitability_tier": "highly-profitable"
    }
  ],
  "meta": {
    "total": 10,
    "limit": 10,
    "generated_at": "2024-12-20T15:30:00+00:00"
  }
}
```

---

### 4. Get Company Ranking Details

Get detailed ranking information and score history for a specific company.

**Endpoint:** `GET /v1/rankings/{uuid}`

**Authentication:** Required (Bearer token)

#### Example Request

```bash
curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     "https://ai-coalition.net/api/v1/rankings/9d4e5f6g-7h8i-9j0k-1l2m-3n4o5p6q7r8s"
```

#### Response Structure

```json
{
  "data": {
    "uuid": "9d4e5f6g-7h8i-9j0k-1l2m-3n4o5p6q7r8s",
    "name": "Anthropic",
    "rank": 1,
    "scores": {
      "overall": 87.5,
      "profitability": 85.0,
      "ethics": 92.0,
      "innovation": 86.0
    },
    "score_history": [
      {
        "score": 87.5,
        "calculated_at": "2024-12-20T02:00:00+00:00"
      },
      {
        "score": 86.2,
        "calculated_at": "2024-12-19T02:00:00+00:00"
      }
    ]
  }
}
```

---

## LLM-Optimized Endpoints

These endpoints provide comprehensive data optimized for consumption by AI assistants and LLM crawlers.

### 1. Get All Companies (LLM Format)

**Endpoint:** `GET /llm/companies`

**Authentication:** Required (Bearer token)

**Caching:** Responses are cached for 1 hour

#### What's Included

- Complete company profiles with full descriptions
- Detailed ethics statements
- Scoring methodology explanations
- Company statistics
- Direct links to company profiles
- Contextual information for AI processing

---

### 2. Get Rankings (LLM Format)

**Endpoint:** `GET /llm/rankings`

**Authentication:** Required (Bearer token)

**Caching:** Responses are cached for 1 hour

#### What's Included

- Top 50 ranked companies
- All scoring dimensions with explanations
- Key focus areas for each company
- Metadata about ranking methodology

---

## Rate Limiting

### Limits

- **Standard Rate:** 60 requests per minute per IP address
- **Burst Allowance:** Up to 100 requests per minute for short periods

### Rate Limit Headers

All API responses include:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1640000000
```

### Handling Rate Limits

When you exceed the rate limit:

```json
{
  "message": "Too many requests. Please try again later.",
  "retry_after": 45
}
```

**Best Practices:**
- Monitor the `X-RateLimit-Remaining` header
- Implement exponential backoff for retries
- Cache responses when possible

---

## Error Handling

### Error Response Format

All errors follow a consistent structure:

```json
{
  "error": "Unauthorized",
  "message": "You must be a partner to access this resource."
}
```

### HTTP Status Codes

| Code | Status | Description |
|------|--------|-------------|
| `200` | OK | Request successful |
| `401` | Unauthorized | Missing or invalid authentication token |
| `403` | Forbidden | Lacking required role (partner/admin) |
| `404` | Not Found | Resource doesn't exist |
| `422` | Unprocessable Entity | Validation error |
| `429` | Too Many Requests | Rate limit exceeded |
| `500` | Internal Server Error | Server error |

### Common Error Scenarios

#### 1. Missing Authentication
```bash
curl "https://ai-coalition.net/api/v1/companies"

# Response: 401
{
  "error": "Unauthenticated",
  "message": "You must be logged in to access this resource."
}
```

#### 2. Invalid Role
```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://ai-coalition.net/api/v1/companies"

# Response: 403
{
  "error": "Unauthorized",
  "message": "You must be a partner to access this resource."
}
```

---

## Data Models

### Company Object (Summary)

```typescript
{
  uuid: string;
  slug: string;
  name: string;
  tagline: string | null;
  website: string | null;
  logo_url: string | null;
  profitability_tier: 'highly-profitable' | 'profitable' | 'pre-revenue';
  scores: {
    overall: number;         // 0-100
    profitability: number;   // 0-100
    ethics: number;          // 0-100
    innovation: number;      // 0-100
  };
  focus_areas: string[];
  created_at: string;
}
```

### Company Object (Detailed)

Includes all fields from summary plus:

```typescript
{
  description: string | null;
  ethics_statement: string | null;
  stats: {
    followers: number;
    posts: number;
    jobs: number;
    products: number;
  };
}
```

### Profitability Tiers

| Tier | Description |
|------|-------------|
| `highly-profitable` | Established companies with strong revenue |
| `profitable` | Companies generating consistent revenue |
| `pre-revenue` | Startups and early-stage companies |

---

## Scoring Methodology

Companies are ranked using a composite score based on three weighted dimensions. Scores are recalculated daily.

### Scoring Dimensions

#### 1. Profitability Score (35% weight)

**Factors:**
- Profitability tier
- Company age and stability
- Team size and growth
- Market presence
- Community engagement

**Why it matters:** Financial sustainability indicates long-term viability.

#### 2. Ethics Score (30% weight)

**Factors:**
- Ethics statement quality
- Focus on socially beneficial AI
- Transparency and openness
- Community engagement
- Verification status
- Commitment to responsible AI

**Why it matters:** Ethical practices ensure AI benefits humanity.

#### 3. Innovation Score (35% weight)

**Factors:**
- Product diversity and count
- Breadth of AI focus areas
- Active hiring (job postings)
- Content creation
- Research contributions
- Technology capabilities

**Why it matters:** Innovation drives progress in AI.

### Score Calculation

```
Overall Score = (Profitability × 0.35) + (Ethics × 0.30) + (Innovation × 0.35)
```

**Score Range:** 0-100 (higher is better)

**Update Frequency:** Daily at 2:00 AM UTC

### Ranking Methodology

1. Companies sorted by overall score (descending)
2. Only verified, active companies included
3. Ties broken by ethics score, then profitability score
4. Rankings update daily with score calculations

---

## Support

### Getting Help

- **Documentation:** https://ai-coalition.net/methodology
- **API Token Issues:** https://ai-coalition.net/api-token
- **Technical Support:** Contact via platform
- **Feature Requests:** Submit via partner dashboard

### Status & Updates

- **API Status:** All systems operational
- **Planned Maintenance:** Announced 48 hours in advance
- **Version Updates:** Backward compatibility guaranteed

---

**Last Updated:** January 2026
**API Version:** 1.0
**Documentation Version:** 1.0