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

# API Reference

> Get started with the Corgea API

# Welcome to the Corgea API

The Corgea API allows you to programmatically interact with Corgea's application security platform. Automate vulnerability scanning, retrieve security issues, manage fixes, and integrate Corgea into your development workflow.

## What can you do with the Corgea API?

<CardGroup cols={2}>
  <Card title="Scan Management" icon="radar">
    Initiate security scans, upload scan results, and monitor scan progress
  </Card>

  <Card title="Issue Management" icon="bug">
    Retrieve vulnerability details, manage issue status, and track remediation
  </Card>

  <Card title="Auto-Fix Retrieval" icon="wand-magic-sparkles">
    Access AI-generated security fixes and patches for identified vulnerabilities
  </Card>

  <Card title="CI/CD Integration" icon="code-branch">
    Integrate security scanning into your continuous integration pipelines
  </Card>
</CardGroup>

## API Capabilities

### Authentication & Authorization

* **Token Verification**: Verify API tokens and retrieve user information
* **Authorization Flow**: Exchange authorization codes for API tokens

### Scanning APIs

* **Start Scan**: Initiate new blast scans with chunked file uploads for large codebases
* **Upload Scan Results**: Submit scan reports from external security tools
* **Get Scans**: Retrieve scan history with filtering and pagination
* **Get Scan Details**: Access detailed information about specific scans
* **Scan Reports**: Generate HTML or SARIF reports for scans

### Issue Management APIs

* **Get Issues**: List all security issues with filtering options
* **Get Issue Details**: Retrieve comprehensive information about specific vulnerabilities
* **SCA Issues**: Access Software Composition Analysis (SCA) vulnerabilities
* **Issue Filtering**: Filter by project, repository, urgency, and more

### Policy Management

* **Blocking Rules**: Define and manage security policies
* **Rule Validation**: Check if scans violate blocking rules
* **Policy Enforcement**: Prevent deployments based on security policies

## Base URL

All API requests should be made to either:

Our multi-tenant environment

```
https://www.corgea.app/api/v1
```

Or your single tenant environment

```
https://<your-instance>.corgea.app/api/v1
```

## Authentication

The Corgea API uses API key authentication. Include your API token in the request header:

```bash theme={null}
CORGEA-TOKEN: your_api_token_here
```

### Getting Started with Authentication

1. **Obtain an API Token**: Get your API token from your Corgea account settings
2. **Verify Your Token**: Use the `/verify` endpoint to confirm your token is valid
3. **Optional User Info**: Include `?user_info=true` to get user and company details

### Authentication Methods

**Header-based Authentication** (Recommended):

```bash theme={null}
curl -H "CORGEA-TOKEN: your_api_token_here" \
     https://www.corgea.app/api/v1/verify
```

**Path-based Authentication** (Deprecated):

```bash theme={null}
curl https://www.corgea.app/api/v1/verify/your_token_here
```

### Authorization Flow

For applications that need to authenticate users:

1. Redirect users to Corgea's authorization page
2. Users authorize your application and receive an authorization code
3. Exchange the code for an API token using `/authorize?code=your_code`

<Note>
  Some endpoints (like `/verify/{token}` and `/authorize`) don't require authentication. Check individual endpoint documentation for specific requirements.
</Note>

## Response Format

All API responses are returned in JSON format. Successful responses include a `status` field:

```json theme={null}
{
  "status": "ok",
  "data": { }
}
```

Error responses include descriptive messages:

```json theme={null}
{
  "status": "error",
  "message": "Description of the error"
}
```

## HTTP Status Codes

The API uses standard HTTP status codes:

| Code  | Description                                      |
| ----- | ------------------------------------------------ |
| `200` | Request successful                               |
| `400` | Bad request - invalid parameters or request body |
| `401` | Unauthorized - invalid or missing authentication |
| `404` | Resource not found                               |
| `429` | Rate limit exceeded                              |
| `500` | Internal server error                            |

## Pagination

Endpoints that return lists support pagination using query parameters:

* `page`: Page number (default: 1)
* `page_size`: Number of results per page (default: 20, max: 50)

Paginated responses include:

```json theme={null}
{
  "status": "ok",
  "page": 1,
  "total_pages": 5,
  "data": []
}
```

## Need Help?

<CardGroup cols={2}>
  <Card title="Authentication Guide" icon="key" href="/api-reference/authentication">
    Learn how to authenticate your API requests
  </Card>

  <Card title="Support" icon="life-ring" href="https://corgea-community.slack.com/join/shared_invite/zt-2cjmxat2f-Znvd06nP2gn9RYOSWrZI2A#">
    Contact our support team for assistance
  </Card>
</CardGroup>

## Quick Start

Get started with the Corgea API in three steps:

1. **Get your API token** from your Corgea account settings
2. **Verify your token** using the `/verify` endpoint with header authentication
3. **Make your first request** to retrieve scans or issues

Explore the API endpoints in the sidebar to learn more about available functionality.