> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ocean.security/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Ocean Security API for threat detection and security metrics

## Welcome to the Ocean Security API

The Ocean Security API provides programmatic access to threat detection data, security metrics, and email protection insights for your organization.

Prefer to work from the spec directly? [Download the OpenAPI spec](/openapi.yaml) to generate clients, import into Postman, or explore in your tool of choice.

<CardGroup cols={3}>
  <Card title="Threats API" icon="shield-exclamation" href="/api-reference/threats/list-recent-threats">
    Retrieve and analyze detected email threats
  </Card>

  <Card title="Metrics API" icon="chart-line" href="/api-reference/metrics/get-top-highlighted-threats">
    Access security analytics and ROI metrics
  </Card>

  <Card title="SONAR API" icon="satellite-dish" href="/api-reference/sonar/list-phishing-reports">
    Manage phishing reports and response analytics
  </Card>

  <Card title="MCP Server" icon="plug" href="/api-reference/mcp/overview">
    Connect AI agents (Claude Code, Copilot, Cursor) via MCP
  </Card>
</CardGroup>

## Authentication

All API endpoints require authentication using an API key passed via the `X-Api-Key` header.

```bash theme={null}
curl -X GET "https://api.ocean.security/api/v1/threats" \
  -H "X-Api-Key: your-api-key-here"
```

<Warning>
  Keep your API key secure and never expose it in client-side code or public repositories.
</Warning>

<Note>
  The [MCP server](/api-reference/mcp/overview) accepts the same API key, but OAuth 2.1 is the
  recommended way to authenticate an MCP client — see
  [MCP authentication](/api-reference/mcp/overview#authentication).
</Note>

## Base URL

All API requests should be made to:

```
https://api.ocean.security
```

## Rate Limiting

API requests are rate limited to ensure fair usage. If you need higher limits, please contact support.

## Response Format

All responses are returned in JSON format with a consistent structure:

```json theme={null}
{
  "status": 200,
  "results": {
    // Response data
  }
}
```

For paginated endpoints, the response includes pagination information:

```json theme={null}
{
  "status": 200,
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total": 150
  },
  "results": {
    "items": [...]
  }
}
```

## Error Handling

When an error occurs, the API returns an appropriate HTTP status code along with an error message:

```json theme={null}
{
  "error": "Invalid API key"
}
```

| Status Code | Description                               |
| ----------- | ----------------------------------------- |
| 400         | Bad Request - Invalid parameters          |
| 401         | Unauthorized - Invalid or missing API key |
| 404         | Not Found - Resource doesn't exist        |
| 500         | Internal Server Error                     |