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

# API reference

> Authenticate with a Gecko API key, understand team scope and rate limits, and start using the v1 API.

<Info>
  Gecko's `v1` API lets you launch scans and read scan, repository, and
  vulnerability data for the team attached to your API key.
</Info>

## Before you call the API

<Steps>
  <Step title="Create an API key">
    Open **API Keys** in Gecko.

    Create a key for the team you want to query.

    Copy the full value when Gecko shows it. Gecko only shows the complete key at
    creation time.
  </Step>

  <Step title="Send the key in the request header">
    Add `X-API-Key: YOUR_API_KEY` to every authenticated request.

    Gecko API keys start with `gk_`.
  </Step>

  <Step title="Call the endpoint you need">
    Use the generated endpoint pages in this section for request and response
    details.
  </Step>
</Steps>

## Send your first request

<CodeGroup>
  ```bash cURL theme={null}
  curl https://app.gecko.security/api/v1/scans?limit=10 \
    -H "X-API-Key: $GECKO_API_KEY" \
    -H "Accept: application/json"
  ```

  ```python Python theme={null}
  import requests

  res = requests.get(
      "https://app.gecko.security/api/v1/scans",
      params={"limit": 10},
      headers={"X-API-Key": "YOUR_API_KEY"},
  )
  res.raise_for_status()
  print(res.json())
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch(
    "https://app.gecko.security/api/v1/scans?limit=10",
    { headers: { "X-API-Key": process.env.GECKO_API_KEY, Accept: "application/json" } },
  );
  const data = await res.json();
  console.log(data);
  ```
</CodeGroup>

## How access works

* `GET /api/v1/health` is public.
* All other `v1` endpoints require `X-API-Key`.
* Gecko scopes every response to the team attached to your API key.
* `GET /api/v1/scans` requires a key with `scans.read`.
* `POST /api/v1/scans` requires a key with `scans.run`.
* Scan creation also requires a configured GitLab integration for that team.

<Tip>
  Use the repository path as the `repositoryId` for repository vulnerability
  requests, and URL-encode it first. For example, send
  `gecko-security%2FPaperbaum` for `gecko-security/Paperbaum`.
</Tip>

## Rate limits

* Gecko applies `1000` requests per hour to each API key.
* Authenticated responses can include `X-RateLimit-Remaining` and
  `X-RateLimit-Reset`.
* Gecko returns `429 Too Many Requests` when a key reaches its current limit.

## What you can do

<CardGroup cols={2}>
  <Card title="Scans" icon="radar">
    List scans, launch a new scan, fetch scan vulnerabilities, and download scan
    artifacts.
  </Card>

  <Card title="Repositories" icon="folder">
    List repositories and fetch repository-level vulnerability data.
  </Card>

  <Card title="Vulnerabilities" icon="shield-halved">
    Read vulnerabilities across every scan in the active team.
  </Card>

  <Card title="Artifacts" icon="file-code">
    Fetch stored endpoint definitions and generated wiki output for a scan.
  </Card>
</CardGroup>

<Check>
  Need request and response details? Open any endpoint page in the API
  Reference sidebar.
</Check>