REST API & Rate Limiting Overview

blackLen exposes a clean, predictable RESTful API powering the operator web application and programmatic workflows.

Request Authentication

All authenticated API endpoints require a valid JWT Access Token passed via the HTTP Authorization header:

GET /api/v1/projects/ HTTP/1.1
Host: api.blacklen.com
Authorization: Bearer <your_access_token>
Content-Type: application/json

Standard Response Envelope

All API responses follow a uniform JSON envelope structure:

Success Response (HTTP 200 / 201):

{
  "status": "success",
  "status_code": 200,
  "message": "Projects fetched successfully",
  "data": [
    {
      "uuid": "4f9d2a80-e765-4d69-b52b-8a719c2f6d5e",
      "title": "Q3 Infrastructure Penetration Test",
      "slug": "q3-infrastructure-penetration-test",
      "status": "active",
      "client": "Acme Corp"
    }
  ]
}

Error Response (HTTP 400 / 401 / 403 / 404 / 429):

{
  "status": "error",
  "status_code": 400,
  "message": "Validation failed",
  "errors": {
    "title": ["This field is required."]
  }
}

Rate Limiting & Abuse Defense

To ensure platform reliability and protect against automated abuse, API endpoints are monitored by adaptive rate limiters:

1. Per-Minute Burst Protection: Protects against aggressive automated loops or runaway scripts while providing generous headroom for normal operator navigation.
2. Daily Volumetric Ceilings: Prevents system resource exhaustion across active user sessions.
3. Authentication Defense: Sensitive endpoints enforce specialized limits to mitigate automated password spraying and brute-force attacks.

Handling Rate Limits (HTTP 429 Too Many Requests):

When a rate limit threshold is reached, the API returns a standard HTTP 429 status code. Automated scripts should incorporate exponential backoff retry strategies.