> ## 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.

## 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` |
| `createdAfter` | string | No | Include findings created at or after this ISO-8601 timestamp |
| `createdBefore` | string | No | Include findings created at or before this ISO-8601 timestamp |
| `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&createdAfter=2025-01-01T00:00:00Z&createdBefore=2025-01-31T23:59:59Z&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
```

### Export findings as SARIF (Beta)

```
GET /teams/:id/findings/sarif
```

> [!WARNING]
>
> This endpoint is in beta. Its parameters and response format can change.

Returns your team's findings as a [SARIF 2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html) document, served as `application/sarif+json`. You can send it as-is to any tool that ingests SARIF, such as Wiz.

Use an API token from a user with access to Findings.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `defaultBranchOnly` | boolean | No | `true` for findings on each project's default branch. Also includes findings with no recorded branch |
| `branch` | string | No | Restrict to one branch |
| `projectId` | string | No | Restrict to one project, by its UUID |
| `state` | string | No | `open` or `closed` |
| `severity` | string | No | `critical`, `high`, `medium`, or `low`. Comma-separate several: `critical,high` |
| `cwe` | string | No | Restrict to one CWE, for example `CWE-89` |
| `tag` | string | No | Restrict to a tag. Repeat for several tags |
| `search` | string | No | Match against title, file path, or CWE |
| `createdAfter` | string | No | ISO-8601 timestamp. Findings created at or after it |
| `excludeAIFalsePositives` | boolean | No | `true` to drop likely false positives |
| `source` | string | No | `corridor` (default), or `bugcrowd` if your team uses the Bugcrowd integration |
| `cursor` | string | No | `nextCursor` from the previous page |
| `limit` | number | No | Findings per page, 1 to 500. Defaults to 500 |

An unknown parameter or an invalid value returns 400, with a message that names it. A `projectId` outside your team returns 404.

```bash theme={null}
curl -H "Authorization: Bearer cor_..." \
  "https://app.corridor.dev/api/teams/TEAM_ID/findings/sarif?defaultBranchOnly=true&state=open"
```

**Response:**

```json theme={null}
{
  "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
  "version": "2.1.0",
  "properties": {
    "corridor": { "limit": 500, "total": 412, "hasMore": false, "nextCursor": null, "generatedAt": "2025-01-15T10:30:00Z" }
  },
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "Corridor",
          "informationUri": "https://corridor.dev",
          "version": "0.0.741",
          "rules": [
            {
              "id": "corridor/CWE-89",
              "name": "CWE89",
              "shortDescription": { "text": "SQL Injection" },
              "helpUri": "https://cwe.mitre.org/data/definitions/89.html",
              "properties": { "tags": ["security", "external/cwe/cwe-89"], "security-severity": "7.0" }
            }
          ]
        }
      },
      "automationDetails": { "id": "corridor/findings/project-uuid/main/" },
      "versionControlProvenance": [
        {
          "repositoryUri": "https://github.com/acme/api",
          "branch": "refs/heads/main",
          "mappedTo": { "uriBaseId": "REPO_ROOT" }
        }
      ],
      "results": [
        {
          "ruleId": "corridor/CWE-89",
          "ruleIndex": 0,
          "level": "error",
          "rank": 75,
          "message": { "text": "User input reaches a raw SQL query without parameterization." },
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": { "uri": "src/controllers/userController.ts", "uriBaseId": "REPO_ROOT" },
                "region": { "startLine": 42, "startColumn": 5, "endLine": 42, "endColumn": 60 }
              }
            }
          ],
          "partialFingerprints": { "corridorFindingId/v1": "finding-uuid" },
          "hostedViewerUri": "https://app.corridor.dev/projects/project-uuid/findings/finding-uuid",
          "properties": {
            "title": "SQL Injection in userController.ts",
            "state": "open",
            "severity": "high",
            "branch": "main",
            "security-severity": "7.0"
          }
        }
      ]
    }
  ]
}
```

#### Paging

Each page holds up to 500 findings. To get the next page, pass `properties.corridor.nextCursor` as `cursor`. Stop when it is `null`. If a cursor returns 400, start again from the first page.

#### Fields

| SARIF field | Value |
| - | - |
| `level` | `error` for critical and high, `warning` for medium, `note` for low |
| `properties.security-severity` | 9.0, 7.0, 5.0, or 3.0, from critical to low |
| `ruleId` | The CWE, such as `corridor/CWE-89`, or `corridor/unspecified` |
| `partialFingerprints` | The Corridor finding ID. Use it to deduplicate findings |
| `suppressions` | Set on closed findings. Pass `state=open` to leave them out |
| `hostedViewerUri` | Link to the finding in Corridor |
| `automationDetails.id` | `corridor/findings/<projectId>/<branch>/`. One run per project and branch. `~no-branch` replaces the branch when it is unknown |

***

## 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` or `SKIPPED` are returned. Results are ordered newest first.

**Response codes**

The response body includes a `status` field on every non-success outcome so callers can branch without parsing error strings.

| HTTP | `status` | When |
| - | - | - |
| `200` | *(absent)* | A complete review exists. Body is the review (or `{ reviews, total }` with `fullHistory=true`). |
| `200` | `in_progress` | A scan is in flight for this PR but no review has been written yet. Body is `{ "status": "in_progress" }`. Poll this endpoint again to fetch the review once it lands. |
| `404` | `repo_not_found` | No project under this team matches `repoName`. |
| `404` | `pr_review_not_found` | The repo exists but no complete review and no in-progress scan was found for this PR. |

### 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`, `member`, or `ideUser` (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.

### 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` | Retired. Returns success without analyzing the edit |
| `fetch-security-results` | Retired. Always returns an empty list |
| `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.

***

## 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

> [card] [Corridor MCP](https://docs.corridor.dev/features/corridor-mcp.md)
>
> Use Corridor tools directly from your AI assistant

> [card] [Findings](https://docs.corridor.dev/features/findings.md)
>
> Learn more about findings management

> [card] [Guardrails](https://docs.corridor.dev/features/guardrails.md)
>
> Configure security guardrails

> [card] [PR Reviews](https://docs.corridor.dev/features/pr-reviews.md)
>
> Automated pull request reviews


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.