# API Introduction

The Seclai REST API allows you to programmatically create and manage AI agents, knowledge bases, sources, solutions, runs, alerts, and AI-assisted configuration. This page provides an overview of how to get started with the API.

## Base URL

All API requests should be made to:

```
https://api.seclai.com/
```

## Authentication

The Seclai API supports two authentication methods: **OAuth** (recommended) and **API keys**.

### OAuth Authentication (Recommended)

OAuth uses your Seclai account credentials via Cognito. Include a Bearer token in the `Authorization` header:

```bash
Authorization: Bearer YOUR_ACCESS_TOKEN
```

OAuth tokens are obtained through the standard OAuth 2.0 Authorization Code flow with PKCE. MCP clients handle this automatically — just enter the server URL and sign in when prompted.

To target a different organization's account, include the `X-Account-Id` header:

```bash
Authorization: Bearer YOUR_ACCESS_TOKEN
X-Account-Id: ORGANIZATION_ACCOUNT_ID
```

### API Key Authentication

API keys are best suited for server-to-server integrations. Include your API key in the `X-API-Key` header:

```bash
X-API-Key: YOUR_API_KEY
```

### Get Your API Key

1. Log in to your [Seclai account](https://seclai.com/login)
2. Navigate to **API Keys** in the left sidebar
3. Click "Create API Key"
4. Copy your key and store it securely right away. The key will not be shown again.

**Important**: Treat your API keys like passwords. Never share them or commit them to version control. Each user should create their own key.

## Making Requests

### Example Request

```bash
curl https://api.seclai.com/agents \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

### Request Headers

| Header                     | Required | Description                                                |
| -------------------------- | -------- | ---------------------------------------------------------- |
| <code>Authorization</code> | \*       | OAuth Bearer token: <code>Bearer YOUR_ACCESS_TOKEN</code>  |
| <code>X-API-Key</code>     | \*       | Your API key (alternative to OAuth)                        |
| <code>X-Account-Id</code>  | No       | Target a different organization account (OAuth only)       |
| <code>Content-Type</code>  | Yes      | Set to <code>application/json</code> for POST/PUT requests |

\* One of `Authorization` or `X-API-Key` is required.

## Response Format

All responses are returned as JSON. Successful responses will have a `200` status code and include the requested data:

```json
{
  "id": "agent_abc123",
  "name": "My Agent",
  "status": "active",
  "created_at": "2026-01-12T10:00:00Z"
}
```

### Error Responses

Error responses include an error object with details:

```json
{
  "error": {
    "code": "missing_field",
    "message": "Missing required field: name"
  }
}
```

Some endpoints return errors in a `detail` envelope instead. Always branch on HTTP status first, then parse the response body for either `error` or `detail`.

### Authentication Error Codes

| HTTP Status | Error Code                          | Meaning                                                                           |
| ----------- | ----------------------------------- | --------------------------------------------------------------------------------- |
| 401         | <code>API_NOT_AUTHENTICATED</code>  | Missing or invalid API key / Bearer token                                         |
| 401         | <code>USER_NOT_AUTHENTICATED</code> | OAuth Bearer token could not be verified                                          |
| 429         | <code>RATE_LIMIT_EXCEEDED</code>    | Too many requests — see [<code>Retry-After</code> header](#429-too-many-requests) |

## Pagination

List endpoints support pagination using `limit` and `offset` parameters:

```bash
curl "https://api.seclai.com/agents?limit=20&offset=0" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Response:**

```json
{
  "data": [...],
  "has_more": true,
  "total": 150
}
```

## SDKs

We provide official SDKs to make integration easier:

- [Python SDK](https://github.com/seclai/seclai-python) - `pip install seclai`
- [JavaScript SDK](https://github.com/seclai/seclai-javascript) - `npm install @seclai/sdk`
- [Go SDK](https://github.com/seclai/seclai-go) - `go get github.com/seclai/seclai-go`
- [C# SDK](https://github.com/seclai/seclai-csharp) - `dotnet add package Seclai`
- [CLI Tool](https://github.com/seclai/seclai-cli) - `npm install -g @seclai/cli` — includes built-in skills for common workflows

## Rate Limits

The API enforces rate limits to protect service quality. Limits apply at two levels:

### Global Limits

All API requests are subject to a per-IP limit of **120 requests per minute** and a per-account limit of **300 requests per minute**, regardless of plan.

### Plan-Specific Limits

Your plan defines the maximum API requests allowed per minute. When you exceed this limit, the API returns a `429 Too Many Requests` response.

### Rate Limit Headers

Every successful API response includes rate-limit headers:

| Header                             | Description                                      |
| ---------------------------------- | ------------------------------------------------ |
| <code>X-RateLimit-Limit</code>     | Maximum requests allowed per window              |
| <code>X-RateLimit-Remaining</code> | Requests remaining in the current window         |
| <code>X-RateLimit-Reset</code>     | Unix timestamp when the rate limit window resets |

### 429 Too Many Requests

When rate-limited, the response includes a `Retry-After` header and a structured error body:

```json
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "API request quota exceeded: 60/60 requests per minute. Retry after 45s.",
    "retry_after": 45
  }
}
```

**Best practices:**

- Check `X-RateLimit-Remaining` to anticipate limits before hitting them.
- On a `429` response, wait for the `Retry-After` duration before retrying.
- Use exponential backoff for transient failures.

## Webhooks

Configure webhooks to receive real-time notifications about events in your account:

```json
{
  "event": "agent.run.completed",
  "data": {
    "run_id": "run_xyz789",
    "agent_id": "agent_abc123",
    "status": "completed"
  }
}
```

Set up webhooks in your [account settings](https://seclai.com/settings/webhooks).

## Next Steps

- [API Reference](https://seclai.com/docs/api) - Complete endpoint documentation
- [API Examples](https://seclai.com/docs/api-examples) - Common use cases and code samples
- [Model Lifecycle API Examples](https://seclai.com/docs/api-examples#model-lifecycle-controls) - Auto-upgrade and rollback settings for agents and steps
- [Authentication Guide](https://seclai.com/docs/getting-started) - Detailed authentication setup