# API Reference

Complete reference for the Presage REST API.

## Base URL

```
https://api.presage.tech/v1
```

## Authentication

All API requests require a Bearer token in the Authorization header:

```
Authorization: Bearer psg_your_api_key_here
```

API keys can be created and managed at [app.presage.tech/settings/api-keys](https://app.presage.tech/settings/api-keys).

## Rate Limits

| Plan | Requests/Minute | Requests/Day |
|------|-----------------|--------------|
| Free | 10 | 1,000 |
| Pro | 100 | 50,000 |
| Enterprise | Custom | Unlimited |

Rate limit headers are included in all responses:
- `X-RateLimit-Limit`: Your limit
- `X-RateLimit-Remaining`: Remaining requests
- `X-RateLimit-Reset`: Unix timestamp when limit resets

## Endpoints

### POST /predict

Make a prediction using a Presage model.

**Request Body:**

```json
{
  "model": "presage-vitals-v1",
  "input": {
    "heart_rate": 72,
    "blood_pressure_systolic": 120,
    "blood_pressure_diastolic": 80,
    "respiratory_rate": 16,
    "temperature": 98.6,
    "oxygen_saturation": 98
  },
  "options": {
    "include_confidence": true,
    "include_explanations": false
  }
}
```

**Response:**

```json
{
  "id": "pred_abc123",
  "model": "presage-vitals-v1",
  "model_version": "1.2.0",
  "prediction": {
    "risk_score": 0.12,
    "risk_level": "low",
    "confidence": 0.94
  },
  "created_at": "2024-01-15T10:30:00Z",
  "latency_ms": 45
}
```

### POST /predict/batch

Make multiple predictions in a single request (up to 100).

**Request Body:**

```json
{
  "model": "presage-vitals-v1",
  "inputs": [
    { "heart_rate": 72, "blood_pressure_systolic": 120, ... },
    { "heart_rate": 85, "blood_pressure_systolic": 135, ... }
  ]
}
```

**Response:**

```json
{
  "id": "batch_xyz789",
  "model": "presage-vitals-v1",
  "predictions": [
    { "risk_score": 0.12, "risk_level": "low", "confidence": 0.94 },
    { "risk_score": 0.45, "risk_level": "moderate", "confidence": 0.89 }
  ],
  "created_at": "2024-01-15T10:30:00Z"
}
```

### GET /models

List available models.

**Response:**

```json
{
  "models": [
    {
      "id": "presage-vitals-v1",
      "name": "Vitals Risk Assessment",
      "version": "1.2.0",
      "description": "Predicts patient risk from vital signs",
      "status": "active"
    },
    {
      "id": "presage-clinical-v1",
      "name": "Clinical Decision Support",
      "version": "2.0.1",
      "description": "Clinical decision support from patient data",
      "status": "active"
    }
  ]
}
```

### GET /models/{model_id}

Get details for a specific model, including its model card.

**Response:**

```json
{
  "id": "presage-vitals-v1",
  "name": "Vitals Risk Assessment",
  "version": "1.2.0",
  "description": "Predicts patient risk from vital signs",
  "input_schema": { ... },
  "output_schema": { ... },
  "model_card": {
    "intended_use": "...",
    "limitations": "...",
    "performance_metrics": { ... }
  }
}
```

### GET /usage

Get your current usage statistics.

**Response:**

```json
{
  "period": "2024-01",
  "plan": "pro",
  "api_calls": {
    "used": 12500,
    "limit": 50000,
    "remaining": 37500
  },
  "by_model": {
    "presage-vitals-v1": 10000,
    "presage-clinical-v1": 2500
  }
}
```

## Error Responses

All errors follow this format:

```json
{
  "error": {
    "code": "invalid_request",
    "message": "The 'heart_rate' field is required",
    "param": "input.heart_rate"
  }
}
```

### Error Codes

| Code | HTTP Status | Description |
|------|-------------|-------------|
| `invalid_api_key` | 401 | API key is invalid or expired |
| `rate_limit_exceeded` | 429 | Too many requests |
| `invalid_request` | 400 | Request body is malformed |
| `model_not_found` | 404 | Requested model doesn't exist |
| `insufficient_quota` | 402 | Plan quota exceeded |
| `internal_error` | 500 | Server error (retry with backoff) |

## SDKs

Official SDKs handle authentication, retries, and error handling:

- **Python**: `pip install presage`
- **Node.js**: `npm install @presage/sdk`
- **Go**: `go get github.com/Presage-Security/SmartSpectra`
- **Ruby**: `gem install presage`

## Webhooks

Enterprise plans can configure webhooks for async notifications. Contact support@presage.tech to enable.