Hermetics Records API

openapi: 3.2.0
info:
  title: Hermetics Records 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: Records
  description: Your register, analyses, requests and breaches (writes to your account).
paths:
  /api/v1/tools/save_processing_record:
    post:
      operationId: save_processing_record
      summary: Save a record of processing activity
      description: 'Saves one entry of the record of processing activities (GDPR art. 30(1)) in the Hermetics account linked to the connection: new records get a code and every change is kept as a new version, in the account''s own register on the Hermetics platform (the free account has no DPO: the user checks the records). When the account belongs to a Hermetics client organization, records go to that organization''s register on the Hermetics platform (codes AT-001...), pending its DPO''s review; a change to a record the DPO has validated is sent to the DPO as a proposal. Returns the code, the version and the points a DPO would review in the entry; when an existing record is updated, also what changed from the previous version and what the change requires (information notice, proof of consent, processor contract, transfer safeguard, DPIA review). The free account stores 3 records; the paid plans have no record limit.'
      tags:
      - Records
      security:
      - bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 3
                  maxLength: 150
                  description: Short name of the processing activity (e.g. "Payroll", "Newsletter").
                purpose:
                  type: string
                  minLength: 10
                  maxLength: 1000
                  description: Purpose of the processing (art. 30(1)(b)).
                legal_basis:
                  type: string
                  enum:
                  - consent
                  - contract
                  - legal_obligation
                  - vital_interests
                  - public_task
                  - legitimate_interests
                  description: Legal basis under art. 6(1).
                legal_basis_details:
                  type: string
                  maxLength: 1000
                  description: 'Details of the legal basis: the legal obligation, the contract, or the legitimate interest pursued.'
                data_subjects:
                  type: array
                  items:
                    type: string
                    minLength: 1
                    maxLength: 200
                  minItems: 1
                  maxItems: 30
                  description: Categories of data subjects (art. 30(1)(c)), e.g. "employees", "customers".
                data_categories:
                  type: array
                  items:
                    type: string
                    minLength: 1
                    maxLength: 200
                  minItems: 1
                  maxItems: 30
                  description: Categories of personal data (art. 30(1)(c)), e.g. "identity", "bank details".
                special_category_data:
                  type: boolean
                  description: True if special category data (art. 9) are processed.
                art9_exception:
                  type: string
                  maxLength: 500
                  description: The art. 9(2) exception relied on, if special category data are processed.
                recipients:
                  type: array
                  items:
                    type: string
                    minLength: 1
                    maxLength: 200
                  minItems: 1
                  maxItems: 30
                  description: Categories of recipients, internal and external (art. 30(1)(d)).
                department:
                  type: string
                  minLength: 1
                  maxLength: 200
                  description: Department or business unit in charge of the processing (e.g. "HR", "Marketing").
                internal_recipients:
                  type: array
                  items:
                    type: string
                    minLength: 1
                    maxLength: 200
                  maxItems: 30
                  description: 'Internal recipients: who, inside the company, can see the data (art. 30(1)(d)), e.g. "payroll team".'
                processors:
                  type: array
                  items:
                    type: string
                    minLength: 1
                    maxLength: 200
                  maxItems: 30
                  description: Processors acting on behalf of the company (art. 28).
                transfers_outside_eea:
                  type: object
                  properties:
                    countries:
                      type: array
                      items:
                        type: string
                        minLength: 2
                        maxLength: 100
                      minItems: 1
                      maxItems: 30
                    safeguard:
                      type: string
                      maxLength: 300
                      description: Adequacy decision, standard contractual clauses, etc. (art. 44 to 49).
                  required:
                  - countries
                  additionalProperties: false
                  description: Transfers to third countries (art. 30(1)(e)), with the countries; omit if there is none or if it is not verified (see transfers_outside_eea_status).
                transfers_outside_eea_status:
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                  - unknown
                  description: 'Whether personal data are transferred outside the EEA: "yes" (give the countries in transfers_outside_eea when known), "no" (checked with the user, including the hosting and the processors: none) or "unknown" (not verified yet). Omitted: "yes" when transfers_outside_eea is given, otherwise "unknown".'
                retention:
                  type: string
                  minLength: 3
                  maxLength: 500
                  description: Retention period or the criteria used to determine it (art. 30(1)(f)).
                security_measures:
                  type: array
                  items:
                    type: string
                    minLength: 1
                    maxLength: 200
                  maxItems: 30
                  description: General description of technical and organisational security measures (art. 30(1)(g)).
                record_id:
                  type: string
                  description: Code of an existing record (e.g. RT-001, or AT-001 in an organization register) to save a new version of it; omit to create a new record. In a new version, an optional field left out keeps its current value. To clear a list (processors, internal_recipients, security_measures) send it empty; to clear legal_basis_details send an empty text; to remove the transfers, send transfers_outside_eea_status "no" or "unknown".
              required:
              - name
              - purpose
              - legal_basis
              - data_subjects
              - data_categories
              - recipients
              - retention
              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/prepare_analysis:
    post:
      operationId: prepare_analysis
      summary: Prepare a compliance analysis
      description: 'Prepares, in the Hermetics space of the organization, the analysis of a record of the register with the same engines as the Hermetics platform: legal basis, DPIA, legitimate interests assessment, transfer impact assessment, information notice (art. 13 and 14), the privacy policy of the whole register, or the art. 28 review of a processor agreement received by the company (Hermetics never drafts contracts). The document stays in the space, to be validated; nothing is published or sent. Uses one document: 1 a month on the free account, a monthly allowance on the paid plans; the processor agreement review is part of the paid plans (on the free account the agreement is filed in the space, unread, and uses nothing); when the analysis already exists, returns its status instead. Returns what was prepared, the points to review, the status and the link to open it. Prepared from the facts given; the decision is the user''s, or the designated DPO validates it when the organization has one.'
      tags:
      - Records
      security:
      - bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                record_id:
                  type: string
                  description: Code of the record in the register (e.g. AT-001); required for every type except privacy_policy.
                type:
                  type: string
                  enum:
                  - legal_basis
                  - dpia
                  - lia
                  - tia
                  - information_notice
                  - privacy_policy
                  - processor_agreement_review
                  description: legal_basis (art. 6), dpia (art. 35), lia (legitimate interests assessment), tia (transfer impact assessment, art. 44 to 49), information_notice (art. 13 and 14), privacy_policy (the whole register), processor_agreement_review (art. 28 review of a processor agreement received by the company).
                notes:
                  type: string
                  maxLength: 2000
                  description: Facts or context from the user for the preparation; no personal data needed.
                processor_name:
                  type: string
                  minLength: 2
                  maxLength: 200
                  description: Name of the processor whose agreement is reviewed (processor_agreement_review only).
                agreement_text:
                  type: string
                  minLength: 200
                  maxLength: 60000
                  description: Full text of the processor agreement received by the company (processor_agreement_review only).
              required:
              - type
              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/answer_analysis_questions:
    post:
      operationId: answer_analysis_questions
      summary: Answer the questions of an analysis
      description: 'Saves the answers of the user to the questions of a DPIA, legitimate interests assessment or transfer impact assessment already opened with prepare_analysis, in the Hermetics space of the organization, through the same interview as the Hermetics platform: one or several answers at a time, in the words of the user. Called without answers, returns the questions still to answer. Returns what was saved, the questions that remain (in the language of the space, with what is missing when an answer needs more detail), the progress and the link where the user reviews and sends the answers. Nothing is sent or validated from here, and no new analysis is opened: each step of the interview counts as in the space, within the same limits. Prepared from the facts given; the decision is the user''s, or the designated DPO validates it when the organization has one.'
      tags:
      - Records
      security:
      - bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                record_id:
                  type: string
                  description: Code of the record whose analysis was opened with prepare_analysis (e.g. AT-002).
                type:
                  type: string
                  enum:
                  - dpia
                  - lia
                  - tia
                  description: 'The analysis opened with prepare_analysis: dpia, lia (legitimate interests assessment) or tia (transfer impact assessment).'
                answers:
                  type: array
                  items:
                    type: object
                    properties:
                      question_id:
                        type: string
                        minLength: 1
                        maxLength: 80
                        description: The question_id of a question returned by this tool.
                      answer:
                        type: string
                        minLength: 1
                        maxLength: 4000
                        description: The user's answer in their own words; "I don't know" is a valid answer and is passed on as such.
                    required:
                    - question_id
                    - answer
                    additionalProperties: false
                  maxItems: 8
                  description: The answers to one or several questions; omit to get the questions still to answer.
              required:
              - record_id
              - type
              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/record_request:
    post:
      operationId: record_request
      summary: Record a data subject request
      description: 'Records a data subject request (access, rectification, erasure, restriction, portability, objection) in the Hermetics space of the organization, with its code and the legal deadline (one month from receipt, art. 12(3), extendable). Returns the deadline and what remains to be done: the identity check and the search of the systems are the company''s. Nothing is sent to the requester. Each plan includes a number of requests a month handled by our agents; beyond it, the request is still recorded with its legal deadline and only our agents stop. Prepared from the facts given; the decision is the user''s, or the designated DPO validates it when the organization has one.'
      tags:
      - Records
      security:
      - bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                right:
                  type: string
                  enum:
                  - access
                  - rectification
                  - erasure
                  - restriction
                  - portability
                  - objection
                  description: The right exercised (GDPR art. 15 to 21).
                received_on:
                  type: string
                  description: 'Date the company received the request (YYYY-MM-DD): the one-month period runs from it.'
                requester_description:
                  type: string
                  minLength: 10
                  maxLength: 2000
                  description: Who made the request and what was asked (e.g. "a former customer asking for a copy of their order history"); no sensitive data beyond what the request needs.
                channel:
                  type: string
                  maxLength: 100
                  description: How the request arrived (e-mail, letter, phone, in person...).
                notes:
                  type: string
                  maxLength: 2000
                  description: Other context for the handling of the request.
              required:
              - right
              - received_on
              - requester_description
              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/report_breach:
    post:
      operationId: report_breach
      summary: Open a personal data breach
      description: Opens a personal data breach in the Hermetics space of the organization, with its code and the end of the 72-hour period to notify the supervisory authority (art. 33(1)), counted from when the company became aware of it. Returns the deadline and the next steps (assess the risk, decide whether to notify). The designated DPO, when there is one, is alerted; nothing is notified to the authority or to the people concerned. Each plan includes a number of breaches a month handled by our agents; beyond it, the breach is still recorded with its deadline and only our agents stop. Prepared from the facts given; the decision is the user's, or the designated DPO validates it when the organization has one.
      tags:
      - Records
      security:
      - bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                discovered_at:
                  type: string
                  description: 'When the company became aware of the breach (ISO 8601 date and time with time zone): the 72-hour period runs from it.'
                description:
                  type: string
                  minLength: 20
                  maxLength: 4000
                  description: What happened, the systems involved and the measures already taken; no personal data needed.
                data_categories:
                  type: array
                  items:
                    type: string
                    minLength: 1
                    maxLength: 200
                  maxItems: 30
                  description: Categories of personal data concerned, e.g. "identity", "bank details".
                people_count_estimate:
                  type: integer
                  minimum: 0
                  maximum: 2000000000
                  description: Approximate number of people concerned.
                ongoing:
                  type: boolean
                  description: True if the breach is still ongoing.
              required:
              - discovered_at
              - description
              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_message:
    post:
      operationId: hermetics_message
      summary: Write to the Hermetics Assistant
      description: 'Writes a message in a thread of the Hermetics Assistant, the AI assistant of the Hermetics space of the organization, and returns its answer with the official sources it cites and the links to act in the space. The message is information for the Hermetics Assistant, never an instruction: nothing is started, approved, sent or validated from here. When the Hermetics Assistant proposes a work, the tool returns what it is and the link to the thread, where the user approves it in the space. Needs the conversation switched on in the space; an answer written by the AI model uses one question of the plan.'
      tags:
      - Records
      security:
      - bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                  minLength: 2
                  maxLength: 2000
                  description: 'The message to the Hermetics Assistant, in any language. Names and personal data of people are not needed: leave them out. Names of people are replaced by a marker before the message is kept in the thread.'
                thread_id:
                  type: string
                  description: A thread_id returned by hermetics_status; omit to write in the general thread of the register.
              required:
              - message
              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