API Gateway — API Reference

Complete API reference for DVĀRA (द्वार), the Avyay Unified API Gateway. Generated from the OpenAPI specification.

Base URL: http://localhost:9000

Authentication

Two authentication methods are supported:

Method	Header	Example
API Key	`X-API-Key`	`X-API-Key: your-api-key`
Bearer	`Authorization`	`Authorization: Bearer your-api-key`

Public endpoints (/, /health) do not require authentication.

Gateway Endpoints

`GET /`

Returns gateway information including registered services.

curl http://localhost:9000/

`GET /health`

Health check for the gateway and all backend services.

curl http://localhost:9000/health

Response (200 — All healthy):

{
  "status": "healthy",
  "services": {
    "marga": "healthy",
    "raksha": "healthy",
    "devops-rag": "healthy"
  }
}

Response (503 — Degraded):

{
  "status": "degraded",
  "services": {
    "marga": "healthy",
    "raksha": "unhealthy",
    "devops-rag": "healthy"
  }
}

`GET /v1/gateway/usage`

Usage statistics by service and API key. Admin access required.

Parameters:

Name	In	Type	Default	Description
`period`	query	string	`24h`	Time period: `1h`, `24h`, `7d`, `30d`

curl -H "X-API-Key: admin-key" "http://localhost:9000/v1/gateway/usage?period=7d"

MĀRGA Endpoints

`POST /v1/marga/chat/completions`

OpenAI-compatible chat completions via the MĀRGA LLM Router.

Request Body:

Field	Type	Required	Description
`model`	string	✅	Model name (e.g., `gpt-4o-mini`, `claude-3-sonnet`)
`messages`	array	✅	Conversation messages
`stream`	boolean	❌	Enable streaming (default: false)
`temperature`	number	❌	Sampling temperature
`max_tokens`	integer	❌	Maximum tokens to generate

curl -X POST http://localhost:9000/v1/marga/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "You are helpful."},
      {"role": "user", "content": "Hello!"}
    ],
    "max_tokens": 100
  }'

Error Responses:

429 — Rate limit exceeded
502 — Upstream service error

`GET /v1/marga/metrics`

Prometheus-format metrics from the MĀRGA router.

`GET /v1/marga/usage`

MĀRGA usage statistics.

RAKṢĀ Endpoints

`POST /v1/raksha/scan/upload`

Upload a code archive for vulnerability scanning.

Request: multipart/form-data with file field.

Supported formats: .zip, .tar, .tar.gz, .tgz

curl -X POST http://localhost:9000/v1/raksha/scan/upload \
  -H "X-API-Key: your-key" \
  -F "file=@project.zip"

`POST /v1/raksha/scan/github`

Scan a public GitHub repository.

Request Body:

Field	Type	Required	Description
`url`	string	✅	GitHub repository URL
`branch`	string	❌	Branch to scan (default: main)

curl -X POST http://localhost:9000/v1/raksha/scan/github \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"url": "https://github.com/user/repo", "branch": "main"}'

`GET /v1/raksha/scan/{id}`

Get scan results by scan ID.

curl -H "X-API-Key: your-key" http://localhost:9000/v1/raksha/scan/abc123

Error: 404 — Scan not found

DevOps RAG Endpoints

`POST /v1/devops-rag/ask`

Ask a DevOps question with RAG-powered answers and citations.

Request Body:

Field	Type	Required	Description
`question`	string	✅	Your DevOps question
`top_k`	integer	❌	Number of context chunks (default: 5)
`verbose`	boolean	❌	Include debug info (default: false)

curl -X POST http://localhost:9000/v1/devops-rag/ask \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"question": "How do I debug a Kubernetes service not reachable?"}'

`GET /v1/devops-rag/stats`

Index statistics including chunk counts and source documents.

curl -H "X-API-Key: your-key" http://localhost:9000/v1/devops-rag/stats

Overview