{"openapi":"3.1.0","info":{"title":"Öffentlicher Dienst Gehalts-API (ÖD-Infoportal)","description":"Offizielle Gehalts-, Besoldungs- und Netto-Berechnungs-API für den Öffentlichen Dienst in Deutschland (Beamte & Tarifbeschäftigte).\n\nBereitgestellt von [infos-oeffentlicher-dienst.de](https://infos-oeffentlicher-dienst.de).\n\n**Zwei API-Modi:**\n- **Agentic API** (`/api/v1/agent/*`): Discovery → Zulagenauswahl → präzise Berechnung für autonome KI-Agenten\n- **Standard API** (`/api/v1/calculate`): Direkte Berechnung mit Kerndaten für Jobportale, HR-Systeme & Apps\n\nAuthentifizierung: `Authorization: Bearer sk_...`","contact":{"name":"ÖD-Infoportal","url":"https://infos-oeffentlicher-dienst.de/"},"version":"1.0.0"},"paths":{"/api/v1/options":{"get":{"tags":["Agent API"],"summary":"Übersicht aller Dienstherren, Tarifverträge und Besoldungsgruppen","description":"Returns all available Dienstherren (Beamte), standard Tarifverträge (Tarif)\nand medical contracts (Ärzte) with their human-readable names, all available periods (with status, labels, dates), and available groups.","operationId":"getOptions","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/agent/options":{"get":{"tags":["Agent API"],"summary":"Discovery: Stufen, Grundgehälter und alle Zulagen für einen Dienstherr/Tarifvertrag","description":"**Step 1 of the Agentic API flow.**\n\nReturns:\n- Available Besoldungsstufen with Grundgehalt amounts\n- All available Zulagen with keys, labels, values, and descriptions\n- Familienzuschlag info (how to use in /agent/calculate)\n- Available periods (current and historical)\n\nUse the returned `key` values in `selected_zulage_keys` when calling `/api/v1/agent/calculate`.","operationId":"getAgentOptions","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"dienstherr","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dienstherr"}},{"name":"tarifvertrag","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tarifvertrag"}},{"name":"gruppe","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":"A9","title":"Gruppe"}},{"name":"period_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period Key"}},{"name":"employment_type","in":"query","required":false,"schema":{"type":"string","default":"beamte","title":"Employment Type"}},{"name":"employmentType","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Employmenttype"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/agent/calculate":{"post":{"tags":["Agent API"],"summary":"Agentic Berechnung: vollständige Gehaltsberechnung mit ausgewählten Zulagen","description":"**Step 2 of the Agentic API flow.**\n\nCalculates the full monthly net salary including:\n- Grundgehalt (from table lookup or manual input)\n- Selected Zulagen (from keys returned by /agent/options)\n- Familienzuschlag (calculated server-side based on familienstand + kinder)\n- All deductions: Lohnsteuer, Solidaritätszuschlag, Kirchensteuer, KV, PV, RV\n- Sonderzahlung as separate annual amount\n\nReturns a fully itemized breakdown.","operationId":"agentCalculate","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCalculateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/api/v1/calculate":{"post":{"tags":["Standard API"],"summary":"Standard Berechnung: Netto aus Kerndaten (ohne Zulagenauswahl)","description":"**Simple one-shot salary calculation.**\n\nProvide basic employment details (Dienstherr/Tarifvertrag, Besoldungsgruppe, Stufe)\nor manual gross salary ('sonstige') and tax/insurance parameters.","operationId":"standardCalculate","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardCalculateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/api/v1/keys/free":{"post":{"tags":["Self-Service"],"summary":"Kostenlosen Entwickler-API-Key generieren (30 Requests/Monat)","description":"Generates a free API key (30 requests/month) for developers.","operationId":"api_v1_generate_free_key_api_v1_keys_free_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FreeKeyRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/mcp/sse":{"get":{"tags":["MCP Remote Server"],"summary":"Mcp Sse Handshake","description":"MCP Server-Sent Events (SSE) Handshake Endpoint.\nInitiates an MCP SSE streaming session compliant with MCP 2024-11-05.\nYields an initial 'endpoint' event with the target URL for POST messages.","operationId":"mcp_sse_handshake_mcp_sse_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"post":{"tags":["MCP Remote Server"],"summary":"Mcp Direct Streamable Post","description":"Streamable HTTP Direct POST endpoint:\nHandles JSON-RPC directly without requiring separate SSE streaming session.\nPrevents 405 Method Not Allowed when Smithery, Glama, or Streamable HTTP clients probe POST /mcp or POST /mcp/sse.","operationId":"mcp_direct_streamable_post_mcp_sse_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"options":{"tags":["MCP Remote Server"],"summary":"Mcp Options Handler","operationId":"mcp_options_handler_mcp_sse_options","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/mcp/messages":{"post":{"tags":["MCP Remote Server"],"summary":"Mcp Messages Handler","description":"MCP JSON-RPC Message Handler.\nReceives JSON-RPC requests from the client for an active SSE session.\nEnqueues the corresponding JSON-RPC response into the SSE stream.\nWorks seamlessly across all Gunicorn workers via SQLite queue.","operationId":"mcp_messages_handler_mcp_messages_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"options":{"tags":["MCP Remote Server"],"summary":"Mcp Options Handler","operationId":"mcp_options_handler_mcp_messages_options","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/mcp/":{"post":{"tags":["MCP Remote Server"],"summary":"Mcp Direct Streamable Post","description":"Streamable HTTP Direct POST endpoint:\nHandles JSON-RPC directly without requiring separate SSE streaming session.\nPrevents 405 Method Not Allowed when Smithery, Glama, or Streamable HTTP clients probe POST /mcp or POST /mcp/sse.","operationId":"mcp_direct_streamable_post_mcp__post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"options":{"tags":["MCP Remote Server"],"summary":"Mcp Options Handler","operationId":"mcp_options_handler_mcp__options","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/mcp":{"post":{"tags":["MCP Remote Server"],"summary":"Mcp Direct Streamable Post","description":"Streamable HTTP Direct POST endpoint:\nHandles JSON-RPC directly without requiring separate SSE streaming session.\nPrevents 405 Method Not Allowed when Smithery, Glama, or Streamable HTTP clients probe POST /mcp or POST /mcp/sse.","operationId":"mcp_direct_streamable_post_mcp_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"options":{"tags":["MCP Remote Server"],"summary":"Mcp Options Handler","operationId":"mcp_options_handler_mcp_options","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/.well-known/mcp/server-card.json":{"get":{"tags":["MCP Remote Server"],"summary":"Mcp Server Card","description":"Static server card metadata for Smithery, Glama, and MCP registries.\nEnables instant tool discovery without requiring active scanning.","operationId":"mcp_server_card__well_known_mcp_server_card_json_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"options":{"tags":["MCP Remote Server"],"summary":"Mcp Options Handler","operationId":"mcp_options_handler__well_known_mcp_server_card_json_options","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/mcp/server-card.json":{"get":{"tags":["MCP Remote Server"],"summary":"Mcp Server Card","description":"Static server card metadata for Smithery, Glama, and MCP registries.\nEnables instant tool discovery without requiring active scanning.","operationId":"mcp_server_card_mcp_server_card_json_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/well-known/mcp/server-card.json":{"get":{"tags":["MCP Remote Server"],"summary":"Mcp Server Card","description":"Static server card metadata for Smithery, Glama, and MCP registries.\nEnables instant tool discovery without requiring active scanning.","operationId":"mcp_server_card_well_known_mcp_server_card_json_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/llms.txt":{"get":{"tags":["Agent Discovery"],"summary":"Maschinenlesbare Übersicht für KI-Agenten","operationId":"serve_llms_txt_llms_txt_head","responses":{"200":{"description":"Successful Response"}}},"head":{"tags":["Agent Discovery"],"summary":"Maschinenlesbare Übersicht für KI-Agenten","operationId":"serve_llms_txt_llms_txt_head","responses":{"200":{"description":"Successful Response"}}}},"/llms-full.txt":{"get":{"tags":["Agent Discovery"],"summary":"Vollständige API-Spezifikation für LLMs","operationId":"serve_llms_full_txt_llms_full_txt_head","responses":{"200":{"description":"Successful Response"}}},"head":{"tags":["Agent Discovery"],"summary":"Vollständige API-Spezifikation für LLMs","operationId":"serve_llms_full_txt_llms_full_txt_head","responses":{"200":{"description":"Successful Response"}}}},"/.well-known/ai-plugin.json":{"get":{"tags":["Agent Discovery"],"summary":"ChatGPT Plugin & Action Discovery","operationId":"serve_ai_plugin_json__well_known_ai_plugin_json_get","responses":{"200":{"description":"Successful Response"}}}},"/.well-known/glama.json":{"get":{"tags":["Agent Discovery"],"summary":"Glama Connector Ownership Claim","operationId":"serve_glama_claim_json__well_known_glama_json_get","responses":{"200":{"description":"Successful Response"}}}}},"components":{"schemas":{"AgentCalculateRequest":{"properties":{"employment_type":{"type":"string","title":"Employment Type","default":"beamte"},"dienstherr":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dienstherr"},"tarifvertrag":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tarifvertrag"},"gruppe":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gruppe","default":"A9"},"stufe":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stufe","default":"3"},"period_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period Key"},"employment_percentage":{"type":"number","title":"Employment Percentage","default":100.0},"zeitraum_gehalt":{"type":"string","title":"Zeitraum Gehalt","default":"monat"},"brutto_gehalt":{"type":"number","title":"Brutto Gehalt","default":0.0},"selectedZulageKeys":{"items":{"type":"string"},"type":"array","title":"Selectedzulagekeys"},"familienstand":{"type":"string","title":"Familienstand","default":"ledig"},"kinder":{"anyOf":[{"type":"integer"},{"type":"string"}],"title":"Kinder","default":0},"ortsklasse":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ortsklasse","default":"i"},"mietenstufe":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mietenstufe","default":"i"},"steuerjahr":{"type":"integer","title":"Steuerjahr","default":2026},"steuerklasse":{"type":"integer","title":"Steuerklasse","default":1},"steuervier":{"type":"number","title":"Steuervier","default":1.0},"kirchensteuer":{"anyOf":[{"type":"boolean"},{"type":"string"}],"title":"Kirchensteuer","default":"nein"},"church_tax_rate":{"type":"number","title":"Church Tax Rate","default":0.0},"bundesland":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bundesland","default":"bayern"},"geburtsjahr":{"type":"integer","title":"Geburtsjahr","default":1992},"alter":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Alter","default":"ja"},"kinder_anzahl":{"anyOf":[{"type":"number"},{"type":"string"}],"title":"Kinder Anzahl","default":0.0},"kinderpflege":{"type":"integer","title":"Kinderpflege","default":0},"krankenversicherung":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Krankenversicherung"},"kvz":{"type":"number","title":"Kvz","default":2.9},"pkpv":{"type":"number","title":"Pkpv","default":0.0},"pkpvgesamt":{"type":"number","title":"Pkpvgesamt","default":0.0},"pkpvagz":{"type":"number","title":"Pkpvagz","default":0.0},"profi_settings":{"type":"boolean","title":"Profi Settings","default":false},"rentenversicherung":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rentenversicherung"},"arbeitslosenversicherung":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Arbeitslosenversicherung"},"zusatzversorgung":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Zusatzversorgung"},"additionalMonthlyGross":{"type":"number","title":"Additionalmonthlygross","default":0.0}},"type":"object","title":"AgentCalculateRequest","description":"Agentic API request – 100% BNR-kompatible Felder + Zulagenauswahl & Familienzuschlags-Parameter.","example":{"arbeitslosenversicherung":"nein","bundesland":"by","dienstherr":"by","employmentType":"beamte","familienstand":"verheiratet","gruppe":"A9","insuranceType":"pkvOhne","kinder":2,"kirchensteuer":"ja","ortsklasse":"iii","pkvBeitrag":500.0,"rentenversicherung":"nein","selected_zulage_keys":["amtszulagen_art_34_abs_2_satz_1_nr_2_4_5_nach_einer_dienstzeit_von_zwei_jahren"],"steuerklasse":3,"stufe":"4","zusatzversorgung":"nein"}},"FreeKeyRequest":{"properties":{"email":{"type":"string","title":"Email"}},"type":"object","required":["email"],"title":"FreeKeyRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"StandardCalculateRequest":{"properties":{"employment_type":{"type":"string","title":"Employment Type","default":"beamte"},"dienstherr":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dienstherr"},"tarifvertrag":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tarifvertrag"},"gruppe":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gruppe","default":"A9"},"stufe":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stufe","default":"3"},"period_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period Key"},"employment_percentage":{"type":"number","title":"Employment Percentage","default":100.0},"zeitraum_gehalt":{"type":"string","title":"Zeitraum Gehalt","default":"monat"},"brutto_gehalt":{"type":"number","title":"Brutto Gehalt","default":0.0},"steuerjahr":{"type":"integer","title":"Steuerjahr","default":2026},"steuerklasse":{"type":"integer","title":"Steuerklasse","default":1},"steuervier":{"type":"number","title":"Steuervier","default":1.0},"kirchensteuer":{"anyOf":[{"type":"boolean"},{"type":"string"}],"title":"Kirchensteuer","default":"nein"},"bundesland":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bundesland","default":"bayern"},"geburtsjahr":{"type":"integer","title":"Geburtsjahr","default":1992},"alter":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Alter","default":"ja"},"kinder":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"null"}],"title":"Kinder","default":"nein"},"kinder_anzahl":{"anyOf":[{"type":"number"},{"type":"string"}],"title":"Kinder Anzahl","default":0.0},"kinderpflege":{"type":"integer","title":"Kinderpflege","default":0},"krankenversicherung":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Krankenversicherung"},"kvz":{"type":"number","title":"Kvz","default":2.9},"pkpv":{"type":"number","title":"Pkpv","default":0.0},"pkpvgesamt":{"type":"number","title":"Pkpvgesamt","default":0.0},"pkpvagz":{"type":"number","title":"Pkpvagz","default":0.0},"profi_settings":{"type":"boolean","title":"Profi Settings","default":false},"rentenversicherung":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rentenversicherung"},"arbeitslosenversicherung":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Arbeitslosenversicherung"},"zusatzversorgung":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Zusatzversorgung"},"additionalMonthlyGross":{"type":"number","title":"Additionalmonthlygross","default":0.0}},"type":"object","title":"StandardCalculateRequest","description":"Standard API request – 100% BNR-kompatible Felder für Direktberechnungen.\nUnterstützt 'beamte', 'tarif', 'aerzte' und 'sonstige' (manuelles Gehalt).","example":{"arbeitslosenversicherung":"nein","bundesland":"by","dienstherr":"by","employmentType":"beamte","gruppe":"A9","insuranceType":"pkvOhne","kirchensteuer":"nein","pkvBeitrag":450.0,"rentenversicherung":"nein","steuerklasse":1,"stufe":"3","zusatzversorgung":"nein"}},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"Authorization"}}}}