immokit-ai Me API

openapi: 3.2.0
info:
  title: bodenrichtwert.ai Me API
  description: 'API for retrieving German land values (Bodenrichtwerte) by address.

    Provide a full German address and receive the land value in EUR per square meter,

    including the land use type, reference date, municipality, and source attribution.

    Covers all German states except Schleswig-Holstein, Sachsen, and Bayern (blocked for legal reasons, HTTP 451).'
  version: 1.2.0
  contact:
    url: https://api.bodenrichtwert.ai
servers:
- url: https://api.immokit.ai
  description: Production REST API
tags:
- name: Me
paths:
  /api/me:
    get:
      operationId: getUserProfile
      summary: Get your profile and current usage statistics
      description: 'Returns your user ID, subscription plan (free, starter, pro, or enterprise), your current

        usage, your monthly hard cap, and the state of your 14-day Pro trial.

        Useful for checking remaining quota before making requests.'
      security:
      - OAuth2: []
      - BearerAuth: []
      - QueryToken: []
      responses:
        '200':
          description: User profile and usage data
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Your user ID
                  plan:
                    type: string
                    enum:
                    - free
                    - starter
                    - pro
                    - enterprise
                    description: Your booked subscription plan
                  effective_plan:
                    type: string
                    enum:
                    - free
                    - starter
                    - pro
                    - enterprise
                    description: The plan currently in effect — "pro" while the 14-day trial is active, otherwise same as plan
                  usage_this_month:
                    type: integer
                    description: Number of API requests counted this month
                  limit:
                    type:
                    - integer
                    - 'null'
                    description: Effective hard cap this month — 100 during the trial, 0 on free (paywall), 50 on starter, 500 on pro, null on enterprise (unlimited by contract). Requests exceeding the cap are rejected with 402 limit_reached.
                  quota_exhausted:
                    type: boolean
                    description: true when the next lookup would be blocked with 402 limit_reached
                  upgrade_url:
                    type:
                    - string
                    - 'null'
                    description: Deep link to the billing page of the immokit.ai account (`produkt=bodenrichtwert`) when quota_exhausted, otherwise null
                  trial_expires_at:
                    type:
                    - string
                    - 'null'
                    format: date-time
                    description: When the 14-day Pro trial ends (ISO 8601), or null if no trial
                  trial_usage:
                    type: integer
                    description: Requests used during the trial window
                  trial_limit:
                    type: integer
                    description: Total request cap for the entire trial window (currently 100)
                  trial_active:
                    type: boolean
                    description: true while the trial is running and not exhausted
        '401':
          description: Missing or invalid Bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Unexpected internal error — retry later; contact support@bodenrichtwert.ai if it persists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Me
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error code
        message:
          type: string
          description: Human-readable error description
        status:
          type: integer
          description: HTTP status code
        reason:
          type: string
          enum:
          - trial_exhausted
          - no_active_plan
          description: Only on 402 limit_reached — why the quota is exhausted
        upgrade_url:
          type: string
          description: Only on 402 limit_reached — deep link to the billing page of the immokit.ai account (`produkt=bodenrichtwert`) to book a plan
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://bodenrichtwert.ai/oauth/authorize
          tokenUrl: https://bodenrichtwert.ai/oauth/token
          scopes: {}
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Static API key issued in the dashboard (Entwickler → API-Keys). Pass as

        `Authorization: Bearer <key>`. Alternative to the OAuth2 flow above —

        recommended for direct server-to-server integrations that skip the

        interactive OAuth consent screen.

        '
    QueryToken:
      type: apiKey
      in: query
      name: token
      description: 'The same API key as `BearerAuth`, passed as `?token=<key>` instead of in a header.


        Intended **only** for clients that cannot set request headers — Google Sheets

        `=IMPORTXML`/`=IMPORTDATA` and comparable spreadsheet importers. Every other client

        should use the `Authorization` header, which takes precedence when both are present.


        A credential in a URL is structurally weaker than one in a header: it is visible to

        anyone who can read the spreadsheet formula or the link. Responses authenticated this

        way are sent with `Cache-Control: no-store`, and our request logs and analytics record

        only the path, never the query string — but the key should still be a dedicated one

        with an expiry date, revocable in the dashboard.

        '