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

# API Reference

> Programmatic access to Corridor findings, guardrails, PR reviews, team settings, and dashboard data.

Corridor exposes a REST API that you can use to integrate with CI/CD pipelines, custom dashboards, or other tools. All endpoints are available via API tokens.

## Authentication

Include your API token in the `Authorization` header:

```bash theme={null}
curl -H "Authorization: Bearer cor_your_token_here" \
  https://app.corridor.dev/api/teams
```

You can generate API tokens from **Profile > API Tokens** in the Corridor dashboard. Tokens use the `cor_` prefix and have the same access as the user who created them.

<Note>
  API tokens cannot perform admin operations. Those require a standard user session.
</Note>

## Base URL

```
https://app.corridor.dev/api
```

All paths below are relative to this base URL.

***

## Findings

Retrieve and manage security findings across your projects.

### Search findings

```
GET /findings/search
```

| Parameter | Type   | Required | Description                                       |
| --------- | ------ | -------- | ------------------------------------------------- |
| `teamId`  | string | Yes      | Team ID to search within                          |
| `search`  | string | No       | Search term (matches title, file path, or CWE)    |
| `state`   | string | No       | Filter by state: `open`, `closed`, or `potential` |
| `limit`   | number | No       | Max results (default 10, max 50)                  |

```bash theme={null}
curl -H "Authorization: Bearer cor_..." \
  "https://app.corridor.dev/api/findings/search?teamId=TEAM_ID&state=open&limit=20"
```

**Response:**

```json theme={null}
[
  {
    "id": "finding-uuid",
    "title": "SQL Injection in userController.ts",
    "affectedFile": "src/controllers/userController.ts",
    "cwe": "CWE-89",
    "severity": "critical",
    "state": "open",
    "createdAt": "2025-01-15T10:30:00Z",
    "projectId": "project-uuid",
    "projectName": "my-app"
  }
]
```

### Get finding

```
GET /findings/:id
```

Returns the full finding with related project, rule, scan, and PR review data.

```bash theme={null}
curl -H "Authorization: Bearer cor_..." \
  https://app.corridor.dev/api/findings/FINDING_ID
```

### Update finding

```
PUT /findings/:id
```

| Field                  | Type   | Description                                                          |
| ---------------------- | ------ | -------------------------------------------------------------------- |
| `state`                | string | `open` or `closed`                                                   |
| `closedReason`         | string | Reason for closing                                                   |
| `closedReasonCategory` | string | `false_positive`, `risk_accepted`, `vulnerability_fixed`, or `other` |
| `severity`             | string | `critical`, `high`, `medium`, or `low`                               |
| `title`                | string | Updated title                                                        |
| `description`          | string | Updated description                                                  |
| `cwe`                  | string | CWE identifier                                                       |
| `affectedFile`         | string | File path                                                            |

All fields are optional. Include only the fields you want to update.

```bash theme={null}
curl -X PUT -H "Authorization: Bearer cor_..." \
  -H "Content-Type: application/json" \
  -d '{"state": "closed", "closedReasonCategory": "false_positive", "closedReason": "Not exploitable in this context"}' \
  https://app.corridor.dev/api/findings/FINDING_ID
```

### Delete finding

```
DELETE /findings/:id
```

***

## Guardrails

Guardrails are security rules that Corridor enforces during code reviews and real-time analysis. They are managed per-project as "reports."

### List guardrails for a project

```
GET /projects/:id/reports
```

Returns all guardrails (reports) and rulesets attached to a project.

```bash theme={null}
curl -H "Authorization: Bearer cor_..." \
  https://app.corridor.dev/api/projects/PROJECT_ID/reports
```

**Response:**

```json theme={null}
{
  "reports": [
    {
      "id": "report-uuid",
      "name": "SQL Injection Prevention",
      "guardrail": "Never use string concatenation for SQL queries...",
      "type": "guardrail",
      "createdAt": "2025-01-10T08:00:00Z"
    }
  ],
  "ruleset": []
}
```

### Create a guardrail

```
POST /projects/:id/reports
```

| Field       | Type   | Required | Description                        |
| ----------- | ------ | -------- | ---------------------------------- |
| `name`      | string | Yes      | Guardrail name                     |
| `guardrail` | string | Yes      | The guardrail rule text            |
| `type`      | string | No       | `guardrail` (default) or `context` |

```bash theme={null}
curl -X POST -H "Authorization: Bearer cor_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "No hardcoded secrets", "guardrail": "Never commit API keys, passwords, or secrets directly in source code. Use environment variables or a secrets manager."}' \
  https://app.corridor.dev/api/projects/PROJECT_ID/reports
```

### Generate a guardrail with AI

```
POST /projects/:id/guardrails/generate
```

| Field         | Type   | Required | Description                                                       |
| ------------- | ------ | -------- | ----------------------------------------------------------------- |
| `description` | string | Yes      | Plain-language description of the guardrail (max 1000 characters) |

Returns a `taskId` you can use to track generation progress.

```bash theme={null}
curl -X POST -H "Authorization: Bearer cor_..." \
  -H "Content-Type: application/json" \
  -d '{"description": "Prevent use of eval() and similar dynamic code execution functions"}' \
  https://app.corridor.dev/api/projects/PROJECT_ID/guardrails/generate
```

### Update a guardrail

```
PUT /projects/:id/reports/:reportId
```

| Field       | Type   | Description              |
| ----------- | ------ | ------------------------ |
| `name`      | string | Updated name             |
| `guardrail` | string | Updated rule text        |
| `type`      | string | `guardrail` or `context` |

### Delete a guardrail

```
DELETE /projects/:id/reports/:reportId
```

### List guardrail packs

```
GET /projects/:id/packs
```

Returns the security packs (curated guardrail collections) attached to a project.

***

## PR Reviews

Access pull request review results and AI analysis.

### List PR reviews

```
GET /teams/:id/pr-reviews
```

| Parameter   | Type   | Description           |
| ----------- | ------ | --------------------- |
| `limit`     | number | Max results           |
| `offset`    | number | Pagination offset     |
| `type`      | string | Filter by review type |
| `sortBy`    | string | Sort field            |
| `sortOrder` | string | `ASC` or `DESC`       |

```bash theme={null}
curl -H "Authorization: Bearer cor_..." \
  "https://app.corridor.dev/api/teams/TEAM_ID/pr-reviews?limit=10&sortOrder=DESC"
```

**Response:**

```json theme={null}
{
  "data": [
    {
      "id": "pr-review-uuid",
      "title": "SQL Injection in userController.ts",
      "severity": "high",
      "state": "open",
      "affectedFile": "src/controllers/userController.ts",
      "createdAt": "2025-01-15T10:30:00Z",
      "cwe": "CWE-89",
      "prReview": { "id": "...", "github_pr_id": 123 },
      "project": { "id": "...", "name": "my-app" }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 42,
    "totalPages": 5,
    "hasNext": true,
    "hasPrev": false
  }
}
```

### Get PR review

```
GET /teams/:id/pr-reviews/:prReviewId
```

Returns the full PR review including comments, findings, and metadata.

### Get PR review by PR number

```
GET /teams/:id/pr-reviews/by-pr
```

Look up PR reviews by pull request number and repository name.

| Parameter     | Type    | Required | Description                                                                          |
| ------------- | ------- | -------- | ------------------------------------------------------------------------------------ |
| `prNumber`    | integer | Yes      | The pull request / merge request number                                              |
| `repoName`    | string  | Yes      | Repository name (matched against project name or the repo portion of the GitHub URL) |
| `fullHistory` | boolean | No       | When `true`, returns all complete reviews for the PR. Default: only the most recent. |

**Default (most recent review):**

```bash theme={null}
curl -H "Authorization: Bearer cor_..." \
  "https://app.corridor.dev/api/teams/TEAM_ID/pr-reviews/by-pr?prNumber=42&repoName=my-app"
```

```json theme={null}
{
  "id": "pr-review-uuid",
  "body": "Review summary...",
  "github_pr_id": 42,
  "publish_status": "SUCCEEDED",
  "event": "COMMENT",
  "findings": [
    {
      "id": "finding-uuid",
      "title": "SQL Injection in db.ts",
      "severity": "critical",
      "state": "open"
    }
  ],
  "labels": [],
  "task": {
    "id": "task-uuid",
    "project": { "id": "project-uuid", "name": "my-app" }
  },
  "createdAt": "2025-01-15T10:30:00Z"
}
```

**Full history (`fullHistory=true`):**

```bash theme={null}
curl -H "Authorization: Bearer cor_..." \
  "https://app.corridor.dev/api/teams/TEAM_ID/pr-reviews/by-pr?prNumber=42&repoName=my-app&fullHistory=true"
```

```json theme={null}
{
  "reviews": [
    { "id": "review-2", "body": "...", "createdAt": "2025-01-16T08:00:00Z" },
    { "id": "review-1", "body": "...", "createdAt": "2025-01-15T10:30:00Z" }
  ],
  "total": 2
}
```

Only reviews with `publish_status = SUCCEEDED` are returned. Results are ordered newest first. Returns `404` if no matching complete review exists.

### List PR review findings

```
GET /teams/:id/pr-review-findings
```

| Parameter    | Type   | Description                  |
| ------------ | ------ | ---------------------------- |
| `prReviewId` | string | Filter by specific PR review |
| `limit`      | number | Max results                  |
| `offset`     | number | Pagination offset            |

***

## Team Settings

Manage team configuration, members, and preferences.

### List teams

```
GET /teams
```

Returns all teams the authenticated user belongs to.

### Get team

```
GET /teams/:id
```

### Get team permissions

```
GET /teams/:id/permissions
```

Returns the current user's role and permissions for the team.

### Invite a user

```
POST /teams/:id/invite
```

| Field   | Type   | Required | Description                   |
| ------- | ------ | -------- | ----------------------------- |
| `email` | string | Yes      | Email address to invite       |
| `role`  | string | No       | `admin` or `member` (default) |

### Remove a user

```
DELETE /teams/:teamId/users/:userId
```

***

## Dashboard & Analytics

Access dashboard metrics and AI usage data.

### Get dashboard data

```
GET /teams/:id/dashboard-data
```

Returns aggregated security metrics including findings by severity, trends over time, and top projects.

```bash theme={null}
curl -H "Authorization: Bearer cor_..." \
  https://app.corridor.dev/api/teams/TEAM_ID/dashboard-data
```

### List LLM requests

```
GET /teams/:id/list-requests
```

Returns a summary of AI/LLM requests made across the team, useful for tracking AI usage and compliance.

### Get guardrail invocations

```
GET /teams/:id/guardrail-invocations-staging
```

| Parameter   | Type   | Required | Description                                |
| ----------- | ------ | -------- | ------------------------------------------ |
| `reportId`  | string | Yes      | Guardrail report ID to get invocations for |
| `period`    | string | No       | Time period (default `7d`)                 |
| `projectId` | string | No       | Filter by project                          |
| `limit`     | number | No       | Max results (default 15)                   |
| `offset`    | number | No       | Pagination offset                          |

Returns data on which guardrails were triggered during real-time code analysis (hook events and security checks).

### Get stop hook invocations

```
GET /teams/:id/stop-hook-invocations
```

Returns instances where Corridor's hooks blocked an action (e.g., prevented an insecure code pattern from being applied).

### Log extension data

```
POST /log
```

The primary endpoint used by IDE extensions to send code analysis data to Corridor. Accepts a request body with a `type` field that determines processing:

| Type                     | Description                                  |
| ------------------------ | -------------------------------------------- |
| `hook-event`             | Real-time hook events from IDE extensions    |
| `async-security-check`   | Asynchronous security analysis of code edits |
| `fetch-security-results` | Retrieve cached security analysis results    |
| `mcp-detection`          | Report detected MCP servers                  |
| `compliance-data`        | Submit compliance telemetry                  |

<Tip>
  This endpoint is primarily used by the Corridor IDE extension. You typically don't need to call it directly unless you're building a custom integration.
</Tip>

***

## Projects

### List projects

```
GET /projects
```

| Parameter | Type   | Required | Description                  |
| --------- | ------ | -------- | ---------------------------- |
| `teamId`  | string | Yes      | Team ID to list projects for |

Returns all projects for the specified team.

### Get project

```
GET /projects/:id
```

### Get project findings

```
GET /projects/:id/findings
```

Returns all findings for a specific project.

***

## Error handling

All endpoints return standard HTTP status codes:

| Status | Meaning                                 |
| ------ | --------------------------------------- |
| `200`  | Success                                 |
| `400`  | Bad request — check your parameters     |
| `401`  | Unauthorized — invalid or missing token |
| `403`  | Forbidden — insufficient permissions    |
| `404`  | Not found                               |
| `500`  | Server error                            |

Error responses include a JSON body:

```json theme={null}
{
  "error": "Description of what went wrong"
}
```

## Rate limits

API tokens are subject to rate limiting. If you receive a `429` response, wait before retrying.

## Next steps

<CardGroup cols={2}>
  <Card title="Corridor MCP" icon="robot" href="/features/corridor-mcp">
    Use Corridor tools directly from your AI assistant
  </Card>

  <Card title="Findings" icon="magnifying-glass" href="/features/findings">
    Learn more about findings management
  </Card>

  <Card title="Guardrails" icon="shield-check" href="/features/guardrails">
    Configure security guardrails
  </Card>

  <Card title="PR Reviews" icon="code-pull-request" href="/features/pr-reviews">
    Automated pull request reviews
  </Card>
</CardGroup>