REST API
REST API
AFA REST API reference -- endpoints, authentication, rate limits, and error handling.
REST API
The AFA REST API provides programmatic access to code analysis, enhancement, and gate evaluation. Use it for CI/CD integration, custom tooling, or webhook-driven pipelines.
Base URL
| Environment | URL |
|---|---|
| Production | https://api.afa.undercurrentholdings.com |
| Self-hosted | http://localhost:8080 (default) |
Authentication
All endpoints except /v1/health require authentication. Pass your API key as a Bearer token:
curl -H "Authorization: Bearer uk_afa_..." \
https://api.afa.undercurrentholdings.com/v1/healthSee Authentication for details on auth methods and rate limits.
Endpoints
Core
| Method | Path | Description | Auth |
|---|---|---|---|
GET | /v1/health | Health check | No |
POST | /v1/analyze | Analyze code | Yes |
POST | /v1/enhance | Generate and validate enhancements | Yes |
POST | /v1/gate-check | Evaluate metrics against gates | Yes |
GET | /v1/history | Query audit trail | Yes |
GET | /v1/metrics | Prometheus metrics | Yes |
Customer
| Method | Path | Description | Auth |
|---|---|---|---|
GET | /v1/customer/profile | Customer record + tier | Yes |
GET | /v1/customer/usage | Usage summary | Yes |
GET | /v1/customer/keys | List API keys | Yes |
POST | /v1/customer/keys | Create API key | Yes |
DELETE | /v1/customer/keys/\{key_id\} | Revoke API key | Yes |
POST | /v1/customer/provision | Provision customer (service auth only) | Service |
Billing
| Method | Path | Description | Auth |
|---|---|---|---|
POST | /billing/checkout | Create Stripe checkout session | Yes |
POST | /billing/webhook | Stripe webhook receiver | Stripe signature |
Rate limits
Rate limits are enforced per API key via Unkey:
| Tier | Requests/minute |
|---|---|
| Community | 15 |
| Developer | 30 |
| Team | 100 |
| Enterprise | 500 |
When rate-limited, you receive HTTP 429 with a Retry-After: 60 header.
Error format
All errors return a JSON body:
{
"error": "Error type",
"detail": "Human-readable description"
}| Status | Meaning |
|---|---|
| 400 | Bad request (invalid input, unsupported language) |
| 401 | Authentication required or invalid |
| 403 | Feature not available on your tier |
| 404 | Resource not found |
| 422 | Gate hard floor violation |
| 429 | Rate limit exceeded |
| 500 | Internal error (details never exposed) |
| 501 | Feature not yet implemented |
Code size limit
The code field in analyze and enhance requests is capped at 500KB to prevent resource exhaustion via LLM billing amplification.
Starting the server
# Default (port 8080)
afa serve --transport http
# Custom port
afa serve --transport http --port 9090