API Reference
All Metiss AI backend services are deployed on GCP Cloud Run and routed through the API Gateway. This page lists every available endpoint across all services.
Base URL
https://api.metiss.ai/v1/{service-name}/{endpoint}Authentication
All endpoints (except /health) require a valid bearer token issued by the authenticator service. Pass it in the Authorization header:
Authorization: Bearer <id_token>Obtain an ID token by exchanging your Firebase refresh token via POST /v1/authenticator-service/refresh-token. Tokens are short-lived; refresh as needed. The API Gateway validates the token and rejects requests with 401 if it is missing or expired.
?token= URL parameter, exchanges it for an ID token on load, and uses that ID token for all subsequent API calls within the session.Authenticator Service
Handles token issuance and refresh. Base path: /v1/authenticator-service
| Method & path | Description | Auth required |
|---|---|---|
POST /get-token | Exchange Firebase credentials for an ID token. | No |
POST /refresh-token | Exchange a Firebase refresh token for a short-lived ID token. Used by the widget on load. | No |
Utility Bill Service
AI-powered extraction of structured data from electricity bills. Base path: /v1/utility-bill-service
| Method & path | Description | Mode |
|---|---|---|
POST /process-bill | Upload a bill file (PDF/PNG/JPG/JPEG) and extract structured data synchronously. Returns customer info, billing amounts, meter readings, and up to 12 months of usage history. | Sync |
POST /process-utility-bill | Process a bill already stored in GCS. Triggers background extraction — poll for status. | Async |
POST /poll-utility-bill-status | Poll the status of an async extraction job using transactionId. Returns status, percentage, and message. | — |
GET /health | Health check. Returns {'status':'ok'}. | — |
See Utility Bill AI for full request/response schemas and retry logic.
Savings Insight Service
Generates personalised solar savings reports combining Google Solar API data with Gemini. Base path: /v1/savings-insight-service
| Method & path | Description | Returns |
|---|---|---|
POST /savings-insight-report | Full pipeline — geocodes address, fetches roof data, calculates financials, generates Gemini report, and triggers email + PDF delivery. | Report JSON + transaction ID |
POST /generate-savings-insights | LLM report generation only. Caller supplies pre-computed usage and financial data; Gemini generates the report sections. | Validated report sections JSON |
POST /generate-pdf-report | Renders an existing LLM report response to PDF. | PDF binary stream |
GET /health | Health check. | {'status':'ok'} |
See Savings Insight for the full calculation model and report schema.
Widget Service
Serves the Lead Widget's configuration and orchestrates lead creation into external systems. Base path: /v1/widget-service
| Method & path | Description | Notes |
|---|---|---|
GET /widget-info | Returns the partner's widget configuration — logo URL, serving states, roof types, and custom widget info content. | Called on widget load |
GET /energy-providers | Returns the list of electricity providers available for a given address/state. | Called after address entry |
GET /roof-analysis | Analyses a property's roof type from satellite imagery using the Google Solar API. | — |
POST /create-lead | Creates a qualified lead in the partner's Salesforce CRM. | Called after contact details step |
POST /create-opportunity | Creates a Salesforce opportunity linked to an existing lead. | — |
POST /contact | Creates a contact record in the Metiss platform. | — |
POST /property | Creates a property record linked to a contact. | — |
PUT /property/{property_uuid} | Updates an existing property record. | — |
POST /property/{property_uuid}/upload | Attaches documents or details to a property record. | — |
POST /process-widget-savings-info | Processes utility bill data from the widget flow and triggers the savings insight pipeline. | — |
GET /health | Health check. | — |
Appointment Handling Service
Manages field service appointment scheduling via Skedulo. Base path: /v1/appointment-handling-service
| Method & path | Description | Notes |
|---|---|---|
GET /available-slots/{organization_uuid} | Returns available appointment time slots for the given partner organisation from Skedulo. | — |
POST /create-appointment | Books a field service appointment in Skedulo for a given time slot and property. | — |
GET /health | Health check. | — |
Contract Approval Service
Handles partner contract upload, AI-powered analysis, and approval workflows. Base path: /v1/contract-approval-service
| Method & path | Description | Mode |
|---|---|---|
POST /analyze-contract | Uploads and analyses a contract document. Returns a structured summary and approval status. | Async |
POST /analyze-contract-bill | Analyses a contract that includes billing information. | Async |
POST /poll-contract-approval-status | Polls the processing status of a contract analysis job using transactionId. | — |
GET /health | Health check. | — |
Email Agent
Handles outbound customer communications and billing email tracking. Base path: /v1/email-agent
| Method & path | Description | Notes |
|---|---|---|
POST /check-inbox | Checks the configured email inbox for incoming messages. | — |
POST /track-billing-email-messages | Tracks and logs billing-related email message activity. | — |
GET /health | Health check. | — |
PDF Generator Service
Renders HTML content and templates to PDF. Base path: /v1/pdf-generator-service
| Method & path | Description | Returns |
|---|---|---|
POST /generate-pdf-from-html | Accepts raw HTML and returns a rendered PDF. | PDF binary stream |
POST /generate-pdf-from-template | Renders a named template with provided data variables to PDF. | PDF binary stream |
POST /generate-savings-report | Renders a savings insight report (from the savings-insight-service output) to a formatted PDF. | PDF binary stream |
Common response codes
| Code | Meaning | Common cause |
|---|---|---|
200 | Success | Request processed successfully. |
400 | Bad request | Invalid input, missing required fields, unsupported file type, or inactive subscription. |
401 | Unauthorised | Missing, expired, or invalid bearer token. |
403 | Forbidden | Token valid but caller lacks permission for the requested resource. |
500 | Internal server error | Unexpected processing failure — check logs via GCP Cloud Logging. |