openapi: 3.1.0
info:
  title: DirektVermittlungDe API
  version: 1.0.0
  description: |
    API for efficient communication between citizens and authorities.
    Key features: Document Intake, Auto-Routing, Interaction Threads.
    [cite: 1, 3]

servers:
  - url: https://api.direktvermittlung.de/v1
    description: Production Server

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://id.bund.de/auth
          tokenUrl: https://api.direktvermittlung.de/oauth/token
          scopes:
            citizen:write: "Submit documents and inquiries"
            official:read: "View assigned cases"
            official:write: "Respond to inquiries"

  schemas:
    DocumentEnvelope:
      type: object
      required: [metadata]
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        metadata:
          [cite_start]description: Plaintext metadata required for the Routing Engine[cite: 8].
          type: object
          required: [authorityId, docType]
          properties:
            authorityId:
              type: string
              example: "Finanzamt-München-I"
            referenceNumber:
              type: string
              [cite_start]description: Aktenzeichen/Kassenzeichen [cite: 3]
            docType:
              type: string
              enum: [NOTICE, COURT_ORDER, GENERAL_INQUIRY]
            issuedAt:
              type: string
              format: date-time
        encryptedPayload:
          type: string
          format: base64
          [cite_start]description: E2E Encrypted PDF content or scan[cite: 27].
        status:
          type: string
          enum: [RECEIVED, ROUTED, ASSIGNED, CLOSED]
          readOnly: true

    InteractionThread:
      type: object
      properties:
        id:
          type: string
          format: uuid
        documentId:
          type: string
          format: uuid
        type:
          type: string
          [cite_start]enum: [TEXT_CHAT, CALLBACK_REQUEST, APPOINTMENT] [cite: 10]
        status:
          type: string
          enum: [OPEN, PENDING_OFFICIAL, PENDING_CITIZEN, RESOLVED]

    Message:
      type: object
      properties:
        id:
          type: string
        senderRole:
          type: string
          enum: [CITIZEN, OFFICIAL]
        content:
          type: string
          description: Encrypted message content.
        timestamp:
          type: string
          format: date-time

paths:
  /documents:
    post:
      summary: Upload a new document (FR-1)
      description: Creates a DocumentEnvelope. [cite_start]The Routing Engine will process the metadata asynchronously[cite: 8].
      security:
        - OAuth2: [citizen:write]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentEnvelope'
      responses:
        '201':
          description: Document Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentEnvelope'

  /documents/{id}/threads:
    post:
      summary: Start an interaction (FR-3)
      [cite_start]description: Initiate a callback request, text inquiry, or appointment[cite: 10].
      security:
        - OAuth2: [citizen:write]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [type]
              properties:
                type:
                  type: string
                  enum: [TEXT_CHAT, CALLBACK_REQUEST, APPOINTMENT]
                initialMessage:
                  type: string
      responses:
        '201':
          description: Thread Started

  /threads/{threadId}/messages:
    get:
      summary: Get message history (FR-4)
      description: Uses cursor-based pagination for chat history.
      parameters:
        - name: threadId
          in: path
          required: true
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
        - name: before
          in: query
          schema:
            type: string
            format: date-time
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Message'

  /exports:
    post:
      summary: Export data to authority system (FR-7)
      [cite_start]description: Triggers an async export job to the eAkte[cite: 16].
      security:
        - OAuth2: [official:read]
      responses:
        '202':
          description: Export Accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobId:
                    type: string
                  status:
                    type: string
                    example: "QUEUED"