Skip to main content

REST API Testing

This guide provides examples for testing the PermitProof REST API via the ESPv2 proxy in the dev environment.

Authentication​

REST API calls via ESPv2 proxy require both Authorization and x-original-authorization headers.

# Generate Firebase bearer token
CODEPROOF_FIREBASE_TOKEN=$(./firebase-token-generator/generate-token.sh sanchos101@gmail.com)

# Set ESPv2 service host (dev environment)
ESP_SERVICE_HOST=construction-code-expert-esp2-dev-6yieikr6ca-uc.a.run.app

Note: Direct gRPC calls only need the authorization header. REST API calls via ESPv2 require both headers for proper authentication flow.

Page Ingestion API​

Trigger asynchronous PDF page ingestion and processing:

curl -X POST https://${ESP_SERVICE_HOST}/v1/architectural-plans/R2024.0091-2024-10-14/ingest-async \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${CODEPROOF_FIREBASE_TOKEN}" \
  -H "x-original-authorization: Bearer ${CODEPROOF_FIREBASE_TOKEN}" \
  -d '{
    "project_id": "R2024.0091-2024-10-14",
    "filename": "21_Wiggins_DCA_Progress_Set_10142024-1.pdf",
    "page_number": 6,
    "force_reprocess": false,
    "enable_orientation_detection": true
  }'

Expected Response:

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PENDING",
  "message": "Task created successfully"
}

Processing Time: 15-20 minutes for typical architectural plan pages.

Code Applicability API​

Trigger asynchronous code applicability analysis:

curl -X POST https://${ESP_SERVICE_HOST}/v1/code-applicability/analyze/async \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${CODEPROOF_FIREBASE_TOKEN}" \
  -H "x-original-authorization: Bearer ${CODEPROOF_FIREBASE_TOKEN}" \
  -d '{
    "architectural_project_id": "R2024.0091-2024-10-14",
    "page_number": 6,
    "icc_book_id": "2217",
    "max_relevant_chapters": 5
  }'

Expected Response:

{
  "task_id": "650e8400-e29b-41d4-a716-446655440001",
  "status": "PENDING",
  "message": "Analysis task created successfully"
}

Processing Time: 2-15 minutes depending on complexity.

Task Progress Tracking​

Both job types use Firestore-based progress tracking. You can monitor task progress in real-time:

Using Firestore SDK (Frontend)​

// Subscribe to real-time task updates
const taskId = response.task_id;

firestore.collection('tasks').doc(taskId).onSnapshot(doc => {
  const task = doc.data();
  console.log(`Progress: ${task.progress}% - ${task.message}`);
  
  // Display cost metadata
  if (task.costAnalysis) {
    console.log(`Cost: $${task.costAnalysis.estimatedTotalCostUsd}`);
    console.log(`Tokens: ${task.costAnalysis.totalTokens}`);
  }
  
  // Check completion
  if (task.status === 'COMPLETED') {
    console.log('Task completed successfully!');
  } else if (task.status === 'FAILED') {
    console.error('Task failed:', task.error_message);
  }
});

Using gRPC Task Status API​

# Query task status via gRPC
grpcurl -import-path src/main/proto \
  -proto src/main/proto/task.proto \
  -H "authorization: Bearer ${CODEPROOF_FIREBASE_TOKEN}" \
  -d '{"task_id": "550e8400-e29b-41d4-a716-446655440000"}' \
  ${GRPC_SERVER_HOST}:443 \
  org.codetricks.construction.code.assistant.service.TaskService/GetTaskStatus

Using REST Task Status API​

# Query task status via REST
curl -X POST https://${ESP_SERVICE_HOST}/v1/tasks/status \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${CODEPROOF_FIREBASE_TOKEN}" \
  -H "x-original-authorization: Bearer ${CODEPROOF_FIREBASE_TOKEN}" \
  -d '{
    "task_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

Other REST API Endpoints​

Get Architectural Plan​

curl -X POST https://${ESP_SERVICE_HOST}/org.codetricks.construction.code.assistant.service.ArchitecturalPlanService/GetArchitecturalPlan \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${CODEPROOF_FIREBASE_TOKEN}" \
  -H "x-original-authorization: Bearer ${CODEPROOF_FIREBASE_TOKEN}" \
  -d '{
    "architectural_plan_id": "R2024.0091-2024-10-14"
  }'

Get Plan Page PDF​

curl -X POST https://${ESP_SERVICE_HOST}/org.codetricks.construction.code.assistant.service.ArchitecturalPlanService/GetArchitecturalPlanPagePdf \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${CODEPROOF_FIREBASE_TOKEN}" \
  -H "x-original-authorization: Bearer ${CODEPROOF_FIREBASE_TOKEN}" \
  -d '{
    "architectural_plan_id": "R2024.0091-2024-10-14",
    "page_number": 2
  }'

Get Applicable Code Sections​

curl -X POST https://${ESP_SERVICE_HOST}/org.codetricks.construction.code.assistant.service.ArchitecturalPlanReviewService/GetApplicableCodeSections \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${CODEPROOF_FIREBASE_TOKEN}" \
  -H "x-original-authorization: Bearer ${CODEPROOF_FIREBASE_TOKEN}" \
  -d '{
    "architectural_plan_id": "R2024.0091-2024-10-14",
    "page_number": 6,
    "icc_book_id": "2217"
  }'

Get ICC Book Table of Contents​

curl -X POST https://${ESP_SERVICE_HOST}/org.codetricks.construction.code.assistant.service.ArchitecturalPlanReviewService/GetIccBookTableOfContents \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${CODEPROOF_FIREBASE_TOKEN}" \
  -H "x-original-authorization: Bearer ${CODEPROOF_FIREBASE_TOKEN}" \
  -d '{
    "icc_book_id": "2217"
  }'

Get Page Compliance Report​

curl -X POST https://${ESP_SERVICE_HOST}/org.codetricks.construction.code.assistant.service.ArchitecturalPlanReviewService/GetPageComplianceReport \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${CODEPROOF_FIREBASE_TOKEN}" \
  -H "x-original-authorization: Bearer ${CODEPROOF_FIREBASE_TOKEN}" \
  -d '{
    "architectural_plan_id": "R2024.0091-2024-10-14",
    "page_number": 6,
    "icc_book_id": "2217"
  }'

Check Authorization Status​

curl -X POST https://${ESP_SERVICE_HOST}/v1/authorization \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${CODEPROOF_FIREBASE_TOKEN}" \
  -H "x-original-authorization: Bearer ${CODEPROOF_FIREBASE_TOKEN}" \
  -d '{
    "client_email": "sanchos101@gmail.com"
  }'

Common Book IDs​

For testing code applicability and compliance APIs:

  • 2217 - IBC 2021
  • 3123 - IBC 2021 (NJ Edition)
  • 3815 - Florida Building Code 2023
  • 3100 - ICC/ANSI A117.1-2017 (Accessibility)
  • 1156 - ICC 300-2017

Troubleshooting​

Authentication Errors​

If you receive 401 Unauthorized or 403 Forbidden:

  1. Verify token is valid: Regenerate the token
  2. Check user is allowlisted: Verify user is in the appropriate Google Group
  3. Verify both headers: Ensure both Authorization and x-original-authorization are present
  4. Check token expiration: Firebase tokens expire after 1 hour

Connection Errors​

If you receive connection errors:

  1. Verify ESPv2 service is running: Check Cloud Run console
  2. Check service URL: Ensure ESP_SERVICE_HOST is correct
  3. Verify network connectivity: Test with a simple curl to the health endpoint

Task Not Found Errors​

If task status queries return "not found":

  1. Verify task ID: Check the response from the async API call
  2. Wait for task creation: There may be a brief delay before task appears in Firestore
  3. Check Firestore console: Verify task exists in the tasks collection