Goa-gel-fullstack/Documentation/developers/index.md

# API Documentation

## Overview

The platform provides REST APIs for integrating with external systems. All APIs use JSON for request and response bodies.

## Base URL

```
Production: https://api.license.gov.in/v1
Staging:    https://api-staging.license.gov.in/v1
```

## Interactive API Documentation

Explore and test APIs using our interactive Swagger UI:

**<ApiDocsLink />**

The Swagger documentation provides:
- Complete endpoint specifications
- Request/response schemas
- Interactive "Try it out" functionality
- Authentication testing

## Authentication

All API requests require authentication via Bearer token.

```http
Authorization: Bearer <access_token>
```

Obtain tokens through the authentication endpoint. See [Authentication](/developers/authentication) for details.

## Request Format

```http
POST /applications HTTP/1.1
Host: api.license.gov.in
Authorization: Bearer eyJhbGc...
Content-Type: application/json

{
  "licenseType": "TRADE_LICENSE",
  "applicantId": "12345",
  "data": { ... }
}
```

## Response Format

### Success Response

```json
{
  "success": true,
  "data": {
    "id": "APP-2026-00001",
    "status": "SUBMITTED"
  }
}
```

### Error Response

```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid license type",
    "details": [
      { "field": "licenseType", "message": "Must be one of: TRADE_LICENSE, FOOD_LICENSE" }
    ]
  }
}
```

## Rate Limits

| Tier | Requests/minute | Burst |
|------|-----------------|-------|
| Standard | 60 | 100 |
| Premium | 300 | 500 |

Rate limit headers included in all responses:
```http
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1707500000
```

## API Endpoints

| Category | Endpoint | Description |
|----------|----------|-------------|
| Auth | `POST /auth/token` | Obtain access token |
| Applications | `POST /applications` | Submit new application |
| Applications | `GET /applications/:id` | Get application status |
| Documents | `POST /documents/upload` | Upload document |
| Verification | `GET /verify/:tokenId` | Verify certificate |

## SDKs

Official SDKs available:
- JavaScript/TypeScript: `npm install @license-authority/sdk`
- Python: `pip install license-authority-sdk`
- Java: Maven artifact `gov.in.license:license-authority-sdk`

## Documentation

- [Authentication](/developers/authentication) - Token management
- [Core APIs](/developers/core-apis) - Application and document APIs
- [Blockchain APIs](/developers/blockchain-apis) - Certificate verification
- [Webhooks](/developers/webhooks) - Event notifications
- [Error Handling](/developers/errors) - Error codes and handling