{"openapi":"3.1.0","info":{"title":"GrowIN Portugal Agent API","version":"1.0.0","description":"Public read-only and deterministic capabilities for verified Portugal knowledge, calculations, evidence-backed case assessment, journey planning, live-derived public-service discovery and monitored availability, and GrowIN professional-service discovery. The API does not expose transactional actions."},"servers":[{"url":"https://www.growinportugal.com"}],"tags":[{"name":"Discovery"},{"name":"Knowledge"},{"name":"Calculations"},{"name":"Assessment"},{"name":"Journey"},{"name":"Services"},{"name":"Public services"}],"paths":{"/api/agent/v1/capabilities":{"get":{"operationId":"getAgentCapabilities","tags":["Discovery"],"summary":"Discover GrowIN agent capabilities and protocol endpoints","responses":{"200":{"description":"Capability catalogue","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/agent/v1/openapi":{"get":{"operationId":"getAgentOpenApi","tags":["Discovery"],"summary":"Get this OpenAPI document","responses":{"200":{"description":"OpenAPI 3.1 document","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/agent/v1/knowledge/search":{"get":{"operationId":"searchPortugalKnowledge","tags":["Knowledge"],"summary":"Search verified Portugal Ledger facts","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":500}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":10}}],"responses":{"200":{"description":"Source-backed Ledger search results","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/agent/v1/knowledge/fact":{"get":{"operationId":"getVerifiedFact","tags":["Knowledge"],"summary":"Get a canonical Ledger fact, optionally at a historical date","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":180}},{"name":"at","in":"query","required":false,"description":"ISO date for point-in-time resolution.","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Canonical or point-in-time Ledger fact","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/agent/v1/knowledge/history":{"get":{"operationId":"getFactHistory","tags":["Knowledge"],"summary":"Get recorded supersession history for a Ledger fact","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":180}}],"responses":{"200":{"description":"Recorded Ledger fact history","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/agent/v1/calculators/net-salary":{"post":{"operationId":"calculateNetSalary","tags":["Calculations"],"summary":"Estimate Portugal Category A employee net salary","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"amount":{"type":"number","exclusiveMinimum":0},"amountPeriod":{"type":"string","enum":["monthly","annual"],"default":"monthly"},"payments":{"type":"integer","enum":[12,14],"default":14},"region":{"type":"string","enum":["mainland","madeira","azores"],"default":"mainland"},"situation":{"type":"string","enum":["single","married"],"default":"single"},"dependents":{"type":"integer","minimum":0,"default":0},"irsJovem":{"type":"boolean","default":false},"irsJovemYear":{"type":"integer","minimum":1,"maximum":10,"default":1},"mealAllowance":{"anyOf":[{"type":"null"},{"type":"object","additionalProperties":false,"properties":{"method":{"type":"string","enum":["card","cash"]},"perDay":{"type":"number","minimum":0},"workingDaysPerMonth":{"type":"integer","minimum":0}},"required":["method","perDay","workingDaysPerMonth"]}]}},"required":["amount"]}}}},"responses":{"200":{"description":"Deterministic salary estimate","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/agent/v1/calculators/isv":{"post":{"operationId":"calculateIsv","tags":["Calculations"],"summary":"Estimate Portugal passenger-car ISV","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"fuel":{"type":"string","enum":["gasoline","diesel","phev","ev"]},"engineCc":{"type":"number","exclusiveMinimum":0},"co2GKm":{"type":"number","minimum":0},"norm":{"type":"string","enum":["WLTP","NEDC"],"default":"WLTP"},"ageYears":{"type":"number","minimum":0,"default":0},"dieselParticleSurcharge":{"type":"boolean","default":true}},"required":["fuel"]}}}},"responses":{"200":{"description":"Deterministic ISV estimate","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/agent/v1/advisor/assess":{"post":{"operationId":"assessPortugalCase","tags":["Assessment"],"summary":"Assess a structured Portugal case using the GrowIN Advisor deterministic route core","description":"Returns evidence-governed route conclusions backed by validated Ledger fact IDs. Input is deliberately restricted to canonical non-identifying case facts.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"objective":{"type":"string","maxLength":600,"description":"Short non-identifying description of the Portugal objective."},"locale":{"type":"string","enum":["en","ar","pt"],"default":"en"},"caseFacts":{"type":"array","maxItems":40,"description":"Explicit non-identifying case facts. Do not send names, email addresses, phone numbers, document numbers or other personal identifiers.","items":{"type":"object","additionalProperties":false,"properties":{"key":{"type":"string","enum":["goal","nationality","citizenship_region","current_country","residence_status","years_legal_residence","support_type","monthly_income_eur","employment_type","has_job_offer","business_stage","business_activity","company_form","founder_count","founder_residence","needs_residence_route","has_portuguese_nif","has_fiscal_representative","has_accommodation","has_registered_office","has_certified_accountant","has_digital_signing","has_corporate_shareholder","service_preference","signing_route","company_name_status","cae_status","has_spouse_or_partner","dependent_children","ifici_pathway","applicant_role","employer_entity","employer_turnover","employer_recognition","prior_portugal_tax_residence","tax_years","tax_income_sources","tax_filing_status","portugal_arrival_date","us_tax_coordination","spreadsheet_available","property_goal","vehicle_goal","vehicle_ownership_period","foreign_residence_period","portugal_residence_start","vehicle_entry_status","licence_issuing_country","residence_start_date","visit_window","licence_validity","licence_categories","licence_authentication","licence_translation","target_timing"],"description":"Canonical non-identifying GrowIN case-state key."},"value":{"type":"string","minLength":1,"maxLength":200},"label":{"type":"string","maxLength":100}},"required":["key","value"]}}},"required":["caseFacts"]}}}},"responses":{"200":{"description":"Evidence-backed case assessment","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/agent/v1/journey/plan":{"post":{"operationId":"buildPortugalPlan","tags":["Journey"],"summary":"Build an evidence-backed Portugal journey plan","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"objective":{"type":"string","maxLength":600,"description":"Short non-identifying description of the Portugal objective."},"locale":{"type":"string","enum":["en","ar","pt"],"default":"en"},"caseFacts":{"type":"array","maxItems":40,"description":"Explicit non-identifying case facts. Do not send names, email addresses, phone numbers, document numbers or other personal identifiers.","items":{"type":"object","additionalProperties":false,"properties":{"key":{"type":"string","enum":["goal","nationality","citizenship_region","current_country","residence_status","years_legal_residence","support_type","monthly_income_eur","employment_type","has_job_offer","business_stage","business_activity","company_form","founder_count","founder_residence","needs_residence_route","has_portuguese_nif","has_fiscal_representative","has_accommodation","has_registered_office","has_certified_accountant","has_digital_signing","has_corporate_shareholder","service_preference","signing_route","company_name_status","cae_status","has_spouse_or_partner","dependent_children","ifici_pathway","applicant_role","employer_entity","employer_turnover","employer_recognition","prior_portugal_tax_residence","tax_years","tax_income_sources","tax_filing_status","portugal_arrival_date","us_tax_coordination","spreadsheet_available","property_goal","vehicle_goal","vehicle_ownership_period","foreign_residence_period","portugal_residence_start","vehicle_entry_status","licence_issuing_country","residence_start_date","visit_window","licence_validity","licence_categories","licence_authentication","licence_translation","target_timing"],"description":"Canonical non-identifying GrowIN case-state key."},"value":{"type":"string","minLength":1,"maxLength":200},"label":{"type":"string","maxLength":100}},"required":["key","value"]}}},"required":["caseFacts"]}}}},"responses":{"200":{"description":"Ordered route plan, requirements, resources and optional GrowIN execution offer","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/agent/v1/services/search":{"get":{"operationId":"findGrowinService","tags":["Services"],"summary":"Find a GrowIN professional service by need or route","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":500}},{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["en","ar","pt"],"default":"en"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":8}}],"responses":{"200":{"description":"Matching canonical GrowIN services","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/agent/v1/public-services":{"get":{"operationId":"listPublicServices","tags":["Public services"],"summary":"List the live-derived IRN public-service catalogue and monitored hot set","responses":{"200":{"description":"Public-service catalogue metadata and monitored service definitions","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/agent/v1/public-services/search":{"get":{"operationId":"findPublicService","tags":["Public services"],"summary":"Search the live-derived IRN SIGA service taxonomy","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":300}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":12}}],"responses":{"200":{"description":"Canonical SIGA Tema/Subtema/Motivo matches; discovery only","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/agent/v1/public-services/availability":{"get":{"operationId":"findPublicServiceAvailability","tags":["Public services"],"summary":"Resolve an IRN SIGA service and read its explicit monitoring/availability state","description":"Returns available-live, monitored-no-slot, monitored-stale, monitoring-pending, or catalog-only. Catalog-only means GrowIN does not currently monitor that service; it does not mean the authority has no appointments.","parameters":[{"name":"service","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":300}},{"name":"q","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":300}},{"name":"district","in":"query","required":false,"schema":{"type":"string","maxLength":80}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Explicit monitored or catalog-only availability state; non-transactional","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/agent/v1/public-services/empresa-na-hora":{"get":{"operationId":"findEmpresaNaHoraAvailability","tags":["Public services"],"summary":"Read latest Empresa na Hora availability (legacy compatibility endpoint)","parameters":[{"name":"district","in":"query","required":false,"schema":{"type":"string","maxLength":80}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Latest availability snapshot; discovery only, non-transactional","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}}},"x-growin":{"capabilityVersion":"1","transactionalActionsExposed":false,"mcp":"https://www.growinportugal.com/mcp","ledger":"https://www.growinportugal.com/api/data","privacy":"Structured assessment inputs are designed for non-identifying case facts. Do not send names, contact details, document numbers or other personal identifiers."}}