AfriProtec API

Integrate AfriProtec's AI-powered security scanning directly into your CI/CD pipeline, custom scripts, or applications.

Base URL: https://guardianai-api-em8v.onrender.com

Overview

The AfriProtec API lets you programmatically trigger security scans, retrieve results, monitor domains, generate compliance reports, and interact with the AI security assistant. All scan endpoints are asynchronous — you start a scan and then poll for results.

Supported scan types: website, repository, email domain, network, cloud, dark web, vendor risk, breach & attack simulation, and shadow AI detection.

API Access — Pro Plan Required

Paid plan required. Programmatic API access requires an AfriProtec Pro plan. There is no free tier for API access. View pricing →

AfriProtec API keys let you query domain security scores, integrate with CI/CD pipelines, and build security dashboards. Each API key includes 1,000 queries per month. Keys use the afp_ prefix and are authenticated via the Authorization header.

To get an API key: upgrade to Pro at afriprotec.com/pricing, then generate a key in Settings → Developer API Keys.

API Key Authentication

Pass your afp_ key in the Authorization header on every API v1 request:

Authorization: Bearer afp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API keys do not expire but can be revoked from your dashboard at any time. Keys are hashed server-side — the raw key is only shown once when created.

Error Responses

Status	Error Code	Meaning
401	`invalid_api_key`	Missing, invalid, or revoked API key. Upgrade at afriprotec.com/pricing.
429	`quota_exceeded`	Monthly query quota exhausted. Upgrade for a higher quota.

# 401 response
{
  "error": "invalid_api_key",
  "message": "API access requires a paid AfriProtec Pro plan. Upgrade at afriprotec.com/pricing"
}

# 429 response
{
  "error": "quota_exceeded",
  "message": "Monthly API quota exceeded.",
  "upgrade_url": "afriprotec.com/pricing"
}

Managing API Keys

All key management endpoints require a user JWT (from dashboard login), not an API key.

POST /api/keys JWT Auth · Pro only

Generate a new API key. Only available to Pro plan users. The raw key is returned once — store it securely. Subsequent requests only return the key prefix.

Request Body

{
  "name": "CI pipeline"
}

Response (200)

{
  "key": "afp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "prefix": "afp_xxxxxxxx",
  "message": "Save this key - it will never be shown again",
  "plan": "pro",
  "monthly_quota": 1000
}

GET /api/keys JWT Auth

List your API keys. Never returns the raw key or hash — only the prefix, metadata, and usage.

Response (200)

{
  "keys": [
    {
      "id": "uuid",
      "key_prefix": "afp_xxxxxxxx",
      "name": "CI pipeline",
      "created_at": "2026-06-10T09:00:00Z",
      "last_used": "2026-06-10T14:30:00Z",
      "queries_this_month": 42,
      "monthly_quota": 1000,
      "is_active": true,
      "plan": "pro"
    }
  ]
}

DELETE /api/keys/{key_id} JWT Auth

Revoke an API key. Sets is_active=false immediately. Any integration using this key will receive a 401 response.

Domain Score

GET /api/v1/score/{domain} API Key required

Returns the current security score for a domain. Requires a valid afp_ API key. If the domain has never been scanned, returns a not_scanned status. Rate limited to 60 requests/minute per key.

Path Parameters

Parameter	Type	Description
domain	string	The domain to look up, e.g. `example.com`

curl https://guardianai-api-em8v.onrender.com/api/v1/score/example.com \
  -H "Authorization: Bearer afp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response — domain has been scanned

{
  "domain": "example.com",
  "score": 78,
  "grade": "B",
  "last_scanned": "2026-06-09",
  "critical_count": 1,
  "high_count": 3,
  "status": "monitored"
}

Response — domain not yet scanned

{
  "domain": "example.com",
  "score": null,
  "status": "not_scanned",
  "scan_url": "https://afriprotec.com/dashboard"
}

Status Values

Value	Meaning
`monitored`	Domain is registered for continuous monitoring
`scanned`	Domain has been scanned at least once
`not_scanned`	No scan data found for this domain

Grade Scale

Grade	Score Range	Meaning
`A`	80–100	Strong security posture
`B`	60–79	Good, minor issues present
`C`	40–59	Moderate risk, action recommended
`F`	0–39	Critical issues, immediate action required

Security Badge

GET /api/v1/badge/{domain}

Returns an SVG badge. If the domain owner has opted in to public badge display (via dashboard settings), shows their real security grade. Otherwise returns a generic AfriProtec branding badge. No authentication required. Cached for 1 hour.

<img src="https://guardianai-api-em8v.onrender.com/api/v1/badge/yourcompany.com"
     alt="AfriProtec Security Score">

curl https://guardianai-api-em8v.onrender.com/api/v1/badge/example.com \
  -o badge.svg

Domain owners can enable public badge display in Settings → Domains. The legacy path /badge/{domain} is still supported.

Dashboard Authentication (JWT)

Dashboard scan endpoints require a user JWT obtained from the login endpoint. Pass it in the Authorization header:

Authorization: Bearer <your_jwt_token>

Tokens are JWTs issued by Supabase Auth. They expire after one hour. Re-authenticate to get a fresh token. For programmatic API access, use an afp_ API key instead — see API Keys above.

Base URL & Versioning

All endpoints are prefixed with the base URL. The current API version is 2.0.0. No versioning prefix is used in the path.

https://guardianai-api-em8v.onrender.com

Error Handling

The API returns standard HTTP status codes and a JSON body with an error or detail field describing what went wrong.

Status	Meaning
400	Bad request — invalid input or parameters
401	Unauthorized — missing, invalid, or revoked API key or JWT token
402	Scan limit reached — upgrade your plan
403	Forbidden — action requires a higher plan (e.g. API key creation requires Pro)
404	Resource not found
422	Validation error — request body failed schema checks
429	Rate limit or monthly quota exceeded
500	Internal server error — our team is notified automatically

Register

POST /auth/register

Create a new AfriProtec account. A confirmation email is sent — the user must click the link before they can log in.

Request Body

{
  "email": "user@company.com",
  "password": "SecurePass1!",
  "full_name": "Jane Mwangi"
}

Response (200)

{
  "message": "Registration successful. Please check your email to confirm your account."
}

POST /auth/login

Authenticate and receive a JWT access token. Use this token in the Authorization header for all protected endpoints.

Request Body

{
  "email": "user@company.com",
  "password": "SecurePass1!"
}

Response (200)

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "user": {
    "id": "uuid",
    "email": "user@company.com",
    "full_name": "Jane Mwangi"
  }
}

Start a Scan

POST /scan Auth required

Start a security scan of a website, repository, email domain, or network target. The scan runs asynchronously — use the returned scan_id to poll for results.

Free plan users are limited to 2 scans. You will receive a 402 response when the limit is reached.

Request Body

Field	Type	Required	Description
repo_url	string	required	Target URL, domain, or repository path
scan_type	string	optional	`full`, `quick`, `secrets`, or `dependencies`. Default: `full`
compliance	array	optional	Frameworks to check: `kenya_dpa`, `popia`, `ndpa`, `iso27001`, `gdpr`, `pci_dss`. Default: `["kenya_dpa","popia"]`

curl -X POST https://guardianai-api-em8v.onrender.com/scan \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"repo_url":"https://yoursite.com","compliance":["kenya_dpa","gdpr"]}'

Response (200)

{
  "scan_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "running",
  "message": "Website scan started. Use /scan/a1b2c3d4-... to check results."
}

Get Scan Results

GET /scan/{scan_id}

Poll this endpoint until status is complete or failed. Recommended polling interval: 5 seconds.

curl https://guardianai-api-em8v.onrender.com/scan/a1b2c3d4-...

Response — running

{"status": "running"}

Response — complete

{
  "status": "complete",
  "results": {
    "metadata": {"target": "https://yoursite.com", "scan_type": "website"},
    "summary": {"total": 12, "critical": 1, "high": 3, "medium": 5, "low": 3},
    "all_findings": [
      {
        "id": "F001",
        "title": "SQL Injection vulnerability in login form",
        "severity": "CRITICAL",
        "file": "/login",
        "fix": "Use parameterised queries or an ORM. Never concatenate user input into SQL strings."
      }
    ],
    "compliance_report": {
      "kenya_dpa": {"status": "NON_COMPLIANT", "violations": 2, "findings": [...]},
      "gdpr": {"status": "COMPLIANT", "violations": 0}
    },
    "mitre_summary": {"techniques_hit": {...}, "tactics_hit": {...}},
    "ai_analysis": {"summary": "Critical SQL injection found in login flow..."}
  }
}

Dark Web Scan

POST /scan/darkweb Auth required

Check whether your domain or email address appears in dark web breach databases, paste sites, or credential leaks.

{
  "repo_url": "yourcompany.com"
}

Cloud Security Scan

POST /scan/cloud Auth required

Scan cloud infrastructure (AWS, Azure, GCP) endpoints for misconfigurations and exposed services.

{
  "repo_url": "portal.azure.com",
  "compliance": ["iso27001"]
}

Breach & Attack Simulation

POST /scan/bas Auth required

Simulate real-world attack techniques against your target and measure how well your defences hold up. Returns a defence effectiveness score and a list of failed controls.

{
  "target": "https://yoursite.com"
}

Shadow AI Detection

POST /scan/shadow-ai Auth required

Detect unauthorised or unvetted AI services and integrations running in your environment.

{
  "repo_url": "yourcompany.com"
}

Vendor Risk Scan

POST /vendor/scan Auth required

Assess the security posture of up to 10 third-party vendors at once. Returns a risk score and compliance status for each vendor.

Request Body

{
  "vendors": ["vendor1.com", "vendor2.com"],
  "compliance": ["kenya_dpa", "popia"]
}

Asset Discovery

POST /assets/discover Auth required

Enumerate all internet-facing assets associated with a domain — subdomains, IP ranges, open ports, and exposed services.

{
  "domain": "yourcompany.com"
}

Register Domain for Monitoring

POST /domains/register

Register a domain for 24/7 continuous monitoring. AfriProtec will scan it on a schedule and alert you when new vulnerabilities appear.

{
  "domain": "yourcompany.com",
  "email": "alerts@yourcompany.com",
  "compliance": ["kenya_dpa", "popia"]
}

List Monitored Domains

GET /domains

Returns all domains currently registered for monitoring.

Response (200)

{
  "domains": [
    {"domain": "yourcompany.com", "verified": true, "status": "active", "last_scan": "2026-06-08T10:30:00Z"}
  ]
}

Domain Scan History

GET /domains/{domain}/history

Retrieve historical scan results for a monitored domain, useful for tracking your security improvement over time.

curl https://guardianai-api-em8v.onrender.com/domains/yourcompany.com/history

Download PDF Report

GET /report/pdf/{scan_id}

Download a formatted PDF compliance report for a completed scan. The report is suitable for sharing with regulators, auditors, and investors.

curl -O -J \
  https://guardianai-api-em8v.onrender.com/report/pdf/a1b2c3d4-...

Trust Badge

GET /badge/{domain}

Returns an SVG badge showing the security score for a domain. Embed it in your website or README to show customers your security posture.

<img src="https://guardianai-api-em8v.onrender.com/badge/yourcompany.com"
     alt="AfriProtec Security Score">

For machine-readable data append /json:

GET /badge/yourcompany.com/json

{
  "domain": "yourcompany.com",
  "score": 87,
  "grade": "A",
  "scanned_at": "2026-06-08T10:30:00Z"
}

AI Security Assistant

POST /assistant Auth required

Chat with the AfriProtec AI assistant. Ask questions about security findings, compliance requirements, fix instructions, or anything cybersecurity-related.

Rate limited to 20 requests per minute per user.

Request Body

{
  "messages": [
    {"role": "user", "content": "What is SQL injection and how do I fix it?"}
  ]
}

Include previous messages in the array to maintain conversation context (max 50 messages, max 10,000 chars per message).

Response (200)

{
  "reply": "SQL injection happens when user input is inserted directly into a database query without sanitisation..."
}

Billing Status

GET /billing/status Auth required

Check the current user's plan, scan count, and remaining free scans.

Response (200)

{
  "plan": "free",
  "scan_count": 1,
  "scans_remaining": 1,
  "upgrade_url": "/payments/checkout"
}

Compliance Frameworks

Use these identifiers in the compliance array on any scan endpoint:

Identifier	Framework	Region
kenya_dpa	Kenya Data Protection Act 2019	Kenya
popia	Protection of Personal Information Act	South Africa
ndpa	Nigeria Data Protection Act 2023	Nigeria
malabo	AU Malabo Convention on Cyber Security	Pan-African
iso27001	ISO/IEC 27001:2022	International
gdpr	General Data Protection Regulation	EU / Global
pci_dss	Payment Card Industry Data Security Standard	Global

Rate Limits

Endpoint	Limit	Auth
`/api/v1/score/{domain}`	60 requests/minute · 1,000/month quota	API Key (Pro)
`/api/v1/badge/{domain}`	Unlimited (cached 1h)	None
`/scan`	10 requests/minute, 100/hour	JWT Required
`/assistant`	20 requests/minute	JWT Required
`/vendor/scan`	3 requests/minute	JWT Required
`/scan/bas`	3 requests/minute	JWT Required
`/assets/discover`	5 requests/minute	JWT Required
`/scan/darkweb`	5 requests/minute	JWT Required
`/scan/cloud`	5 requests/minute	JWT Required
`/scan/{scan_id}` (polling)	60 requests/minute	JWT Required

CI/CD Integration Example

Add AfriProtec to your GitLab pipeline to block merges with critical vulnerabilities. Requires a Pro plan API key stored as a CI secret variable (AFRIPROTEC_TOKEN = your dashboard JWT, AFRIPROTEC_API_KEY = your afp_ key for score lookups):

# .gitlab-ci.yml
afriprotec-scan:
  stage: test
  script:
    - |
      # Start a scan using your dashboard JWT
      RESPONSE=$(curl -s -X POST https://guardianai-api-em8v.onrender.com/scan \
        -H "Authorization: Bearer $AFRIPROTEC_TOKEN" \
        -H "Content-Type: application/json" \
        -d "{\"repo_url\":\"$CI_PROJECT_URL\",\"scan_type\":\"secrets\",\"compliance\":[\"kenya_dpa\"]}")
      SCAN_ID=$(echo $RESPONSE | python3 -c "import sys,json; print(json.load(sys.stdin)['scan_id'])")
      # Poll for results
      for i in $(seq 1 30); do
        sleep 10
        RESULT=$(curl -s https://guardianai-api-em8v.onrender.com/scan/$SCAN_ID \
          -H "Authorization: Bearer $AFRIPROTEC_TOKEN")
        STATUS=$(echo $RESULT | python3 -c "import sys,json; print(json.load(sys.stdin)['status'])")
        if [ "$STATUS" = "complete" ]; then
          CRITICAL=$(echo $RESULT | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['results']['summary']['critical'])")
          if [ "$CRITICAL" -gt "0" ]; then echo "FAIL: $CRITICAL critical findings"; exit 1; fi
          echo "PASS: No critical findings"; exit 0
        fi
      done
      echo "Scan timed out"; exit 1

# Query domain score using your afp_ API key
afriprotec-score:
  stage: test
  script:
    - |
      curl -s https://guardianai-api-em8v.onrender.com/api/v1/score/yourcompany.com \
        -H "Authorization: Bearer $AFRIPROTEC_API_KEY"

Questions? Email hello@afriprotec.com or visit your dashboard.

AfriProtec API

Overview

API Access — Pro Plan Required

API Key Authentication

Error Responses

Managing API Keys

Request Body

Response (200)

Response (200)

Domain Score

Path Parameters

Response — domain has been scanned

Response — domain not yet scanned

Status Values

Grade Scale

Security Badge

Dashboard Authentication (JWT)

Base URL & Versioning

Error Handling

Register

Request Body

Response (200)

Login

Request Body

Response (200)

Start a Scan

Request Body

Response (200)

Get Scan Results

Response — running

Response — complete

Dark Web Scan

Cloud Security Scan

Breach & Attack Simulation

Shadow AI Detection

Vendor Risk Scan

Request Body

Asset Discovery

Register Domain for Monitoring

List Monitored Domains

Response (200)

Domain Scan History

Download PDF Report

Trust Badge

AI Security Assistant

Request Body

Response (200)

Billing Status

Response (200)

Compliance Frameworks

Rate Limits

CI/CD Integration Example