Hermetics Law API

openapi: 3.2.0
info:
  title: Hermetics Law API
  version: 1.0.0
  description: 'EU data protection law and the record of processing activities (GDPR art. 30): the official texts with their status, the obligations of a company, and the records, analyses, requests and breaches of your Hermetics account. Information, not legal advice: without a designated DPO, the final decision is yours.'
  contact:
    email: contact@hermetics.fr
    url: https://hermetics.fr/mcp
servers:
- url: https://hermetics.fr
tags:
- name: Law
  description: Official texts and obligations (read only).
paths:
  /api/v1/tools/search_law:
    post:
      operationId: search_law
      summary: Search EU data protection law
      description: Searches the official texts on data protection (GDPR, ePrivacy, AI Act, EDPB guidance, CJEU case law, and the national law, authority guidance and decisions held for each country) and returns the most relevant passages verbatim, each with its current status (in force, applicable from a date, amended) and its official link.
      tags:
      - Law
      security:
      - bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                question:
                  type: string
                  minLength: 3
                  maxLength: 2000
                  description: The legal question, in any language (French gives the best results today). Names and personal data are not needed.
                country:
                  type: string
                  enum:
                  - AT
                  - BE
                  - BG
                  - HR
                  - CY
                  - CZ
                  - DK
                  - EE
                  - FI
                  - FR
                  - DE
                  - GR
                  - HU
                  - IE
                  - IT
                  - LV
                  - LT
                  - LU
                  - MT
                  - NL
                  - PL
                  - PT
                  - RO
                  - SK
                  - SI
                  - ES
                  - SE
                  - IS
                  - LI
                  - 'NO'
                  description: ISO code of an EU or EEA country (e.g. FR, DE, ES) to add its national law and authority guidance to the EU texts; omit for EU texts only.
              required:
              - question
              additionalProperties: false
      responses:
        '200':
          description: 'The tool result: `result` holds the structured data, `text` the same answer as plain text.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolResult'
        '401':
          description: Missing or invalid key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Unknown tool.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Invalid arguments, a limit of the plan reached, or the tool could not complete the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests from this address; retry later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Temporarily unavailable; retry later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/tools/gdpr_obligations:
    post:
      operationId: gdpr_obligations
      summary: GDPR obligations of a company
      description: 'Lists the GDPR obligations of a company established in an EU or EEA country from a few facts (size, website and cookies, e-mail marketing, sensitive data, video surveillance, AI...). Deterministic rules: each obligation comes with its legal basis and a suggested search_law query for the official text. A fact left out is treated as unknown, except processors, which are assumed.'
      tags:
      - Law
      security:
      - bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                country:
                  type: string
                  enum:
                  - AT
                  - BE
                  - BG
                  - HR
                  - CY
                  - CZ
                  - DK
                  - EE
                  - FI
                  - FR
                  - DE
                  - GR
                  - HU
                  - IE
                  - IT
                  - LV
                  - LT
                  - LU
                  - MT
                  - NL
                  - PL
                  - PT
                  - RO
                  - SK
                  - SI
                  - ES
                  - SE
                  - IS
                  - LI
                  - 'NO'
                  description: Country where the company is established (ISO code of an EU or EEA country, e.g. FR, DE, ES, IT).
                employees:
                  type: integer
                  minimum: 0
                  maximum: 1000000
                  description: Number of employees (0 if none).
                public_sector:
                  type: boolean
                  description: True if the organisation is a public authority or public body.
                website:
                  type: boolean
                  description: True if the company has a website or app.
                non_essential_cookies:
                  type: boolean
                  description: True if the website or app uses non-essential cookies or trackers (analytics, advertising, social media pixels).
                email_marketing:
                  type: boolean
                  description: True if the company sends marketing e-mails or SMS to individuals.
                processors:
                  type: boolean
                  description: True if providers process personal data on its behalf (hosting, SaaS, payroll, CRM). Assumed true if omitted.
                transfers_outside_eea:
                  type: boolean
                  description: True if personal data is sent to providers or entities outside the EEA (e.g. US SaaS).
                special_category_data:
                  type: boolean
                  description: True if it processes special category data (health, biometrics, genetic data, religion, union membership, sex life or orientation, ethnic origin, political opinions).
                large_scale:
                  type: boolean
                  description: True if the processing concerns a large number of people (large scale).
                systematic_monitoring:
                  type: boolean
                  description: True if it systematically monitors people (online behaviour tracking, geolocation, profiling for advertising, CCTV of public areas).
                evaluation_or_scoring:
                  type: boolean
                  description: True if it evaluates or scores people (credit scoring, profiling, performance rating).
                automated_decisions:
                  type: boolean
                  description: True if it takes automated decisions with legal or similarly significant effects on people.
                vulnerable_people:
                  type: boolean
                  description: True if it processes data of vulnerable people (children, patients, elderly people).
                cctv:
                  type: boolean
                  description: True if it uses video surveillance (CCTV).
                ai:
                  type: boolean
                  description: True if it develops or uses AI systems that interact with or make decisions about people.
              required:
              - country
              additionalProperties: false
      responses:
        '200':
          description: 'The tool result: `result` holds the structured data, `text` the same answer as plain text.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolResult'
        '401':
          description: Missing or invalid key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Unknown tool.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Invalid arguments, a limit of the plan reached, or the tool could not complete the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests from this address; retry later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Temporarily unavailable; retry later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/tools/list_processing_records:
    post:
      operationId: list_processing_records
      summary: List the records of processing activities
      description: 'Lists the records of processing activities (GDPR art. 30(1)) saved in the Hermetics account linked to the connection, in their latest version, with their full content. For an account of a Hermetics client organization, lists the organization''s whole register on the Hermetics platform, whatever the origin of each record, with its status. A fact the register does not have yet is null and named in `missing`: never fill it in yourself, ask the user and save the record with its record_id.'
      tags:
      - Law
      security:
      - bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: {}
              additionalProperties: false
      responses:
        '200':
          description: 'The tool result: `result` holds the structured data, `text` the same answer as plain text.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolResult'
        '401':
          description: Missing or invalid key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Unknown tool.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Invalid arguments, a limit of the plan reached, or the tool could not complete the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests from this address; retry later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Temporarily unavailable; retry later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/tools/pending_reviews:
    post:
      operationId: pending_reviews
      summary: Records to review after a change in the law
      description: Lists the records of processing activities that a new rule (law, guidance, decision) may affect, with the rule, its source and the reason; saving a new version of a record closes its reviews. Reviews are part of the paid plans.
      tags:
      - Law
      security:
      - bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: {}
              additionalProperties: false
      responses:
        '200':
          description: 'The tool result: `result` holds the structured data, `text` the same answer as plain text.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolResult'
        '401':
          description: Missing or invalid key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Unknown tool.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Invalid arguments, a limit of the plan reached, or the tool could not complete the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests from this address; retry later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Temporarily unavailable; retry later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/tools/hermetics_status:
    post:
      operationId: hermetics_status
      summary: Where your Hermetics space stands
      description: 'Returns what the Hermetics Assistant, the AI assistant of the Hermetics space of the organization, shows at the top of the space: one sentence on where the space stands, the first points that wait for the user (their kind and the link to act in the space, never their content), the latest changes saved to the records and what each one requires (in the language of the space), and the open conversation threads as references. Deterministic, no AI model, read-only; it uses no allowance of the plan. Nothing is decided or changed.'
      tags:
      - Law
      security:
      - bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: {}
              additionalProperties: false
      responses:
        '200':
          description: 'The tool result: `result` holds the structured data, `text` the same answer as plain text.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolResult'
        '401':
          description: Missing or invalid key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Unknown tool.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Invalid arguments, a limit of the plan reached, or the tool could not complete the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests from this address; retry later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Temporarily unavailable; retry later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ToolResult:
      type: object
      required:
      - result
      - text
      properties:
        result:
          type:
          - object
          - 'null'
          description: Structured data returned by the tool.
        text:
          type: string
          description: The same answer as plain text.
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - hint
          properties:
            code:
              type: string
              description: 'Stable error code: unauthorized, unknown_tool, tool_error, request_failed, not_found.'
            message:
              type: string
              description: What went wrong.
            hint:
              type: string
              description: What to do next.
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: A Hermetics key (hk_...), created at https://hermetics.fr/mcp/cle with a free account.
externalDocs:
  description: Assistants and API
  url: https://hermetics.fr/mcp#api