Integra API Guide

This guide provides comprehensive documentation for the Integra API, including endpoints, usage examples, and configuration.

Base URL

The API is served at http://localhost:8080 by default. You can view the interactive Swagger documentation at: http://localhost:8080/swagger/index.html

Endpoints

1. Health Check

• Method: GET
• Path: /health
• Description: Returns 200 OK if the service is running.

curl http://localhost:8080/health

2. Parse AL3

• Method: POST
• Path: /v1/parse
• Description: Parses an ACORD AL3 file and returns the structured JSON representation.
• Headers:
  • Content-Type: application/octet-stream or text/plain
  • Accept: application/json (default), application/x-ndjson, text/csv, application/x-parquet
• Response Metadata:
  • X-Processing-Time: Execution duration (e.g., 1.2ms)
  • X-Integra-Validation-Status: true/false

Example Request

curl -X POST \
  --data-binary "@sample.al3" \
  http://localhost:8080/v1/parse

Example Response (JSON)

{
  "data": {
    "fileId": "...",
    "policies": [...] 
  },
  "validation": {
    "valid": true,
    "errors": []
  },
  "processingTime": "1.234ms"
}

3. Validate AL3

• Method: POST
• Path: /v1/validate
• Description: Validates an AL3 file without returning the full parsed structure. Faster if you only need validity checks.

curl -X POST --data-binary "@sample.al3" http://localhost:8080/v1/validate

4. Generate AL3

• Method: POST
• Path: /v1/generate
• Description: Generates a valid AL3 file from structured JSON input. Performs strict validation against the schema.
• Headers:
  • Content-Type: application/json
• Response: JSON containing generated AL3 string and validation results.

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "policies": [{
      "code": "1MHG",
      "dataElements": {
        "Transaction Date": "20240115"
      },
      "children": [...]
    }]
  }' \
  http://localhost:8080/v1/generate

Example Response

{
  "data": "1MHG... (AL3 content)",
  "validation": {
    "valid": true,
    "errors": []
  },
  "metadata": {
    "sizeBytes": 1024,
    "groupCount": 15
  },
  "processingTime": "1.5ms"
}

Configuration

Telemetry (OpenTelemetry)

Tracing is disabled by default to avoid connection errors during local development.

• Enable: Set INTEGRA_TELEMETRY_ENABLED=true
• Endpoint: Defaults to localhost:4318. Configure with OTEL_EXPORTER_OTLP_ENDPOINT.

Server Port

• Default: 8080
• Env Var: INTEGRA_PORT (e.g., export INTEGRA_PORT=9090)

Running Integra

Integra Cloud (AWS Marketplace)

Pull and run the container from AWS Marketplace:

docker pull priyaiosystems/integra:latest
docker run -d -p 8080:8080 --name integra priyaiosystems/integra:latest

The API will be available at http://localhost:8080.

For production deployment on AWS, see the AWS Integration Guide