API reference

Gecko’s v1 API lets you launch scans and read scan, repository, and vulnerability data for the team attached to your API key.

Before you call the API

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.

Send the key in the request header

Add X-API-Key: YOUR_API_KEY to every authenticated request.Gecko API keys start with gk_.

Call the endpoint you need

Use the generated endpoint pages in this section for request and response details.

Send your first request

curl https://app.gecko.security/api/v1/scans?limit=10 \
  -H "X-API-Key: $GECKO_API_KEY" \
  -H "Accept: application/json"

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())

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);

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.

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.

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

Scans

List scans, launch a new scan, fetch scan vulnerabilities, and download scan artifacts.

Repositories

List repositories and fetch repository-level vulnerability data.

Vulnerabilities

Read vulnerabilities across every scan in the active team.

Artifacts

Fetch stored endpoint definitions and generated wiki output for a scan.

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

Overview

Scans

Repositories

Vulnerabilities

Utility

Before you call the API

Send your first request

How access works

Rate limits

What you can do

Scans

Repositories

Vulnerabilities

Artifacts

​Before you call the API

​Send your first request

​How access works

​Rate limits

​What you can do

Scans

Repositories

Vulnerabilities

Artifacts

Before you call the API

Send your first request

How access works

Rate limits

What you can do