Blumee Service API

openapi: 3.2.0
info:
  title: Blumee Service API
  version: 0.1.0
  summary: Flower-delivery offers from German partner florists, searchable by text and photo.
  description: 'Blumee compares bouquets and potted plants that vetted German florists deliver. This API is

    the read side of that catalog: filter it, search it by meaning, or identify the flowers in a

    photo and get offers that look like it.


    ### Three things worth knowing before the endpoint list


    **No authentication, and none is coming.** There are no accounts, no keys, no sign-up. Send

    requests. What protects the service is spend: 60 requests per minute per caller, plus a

    daily budget on the endpoints that call a paid model. See `https://blumee.app/auth.md`.


    **Blumee sells nothing.** Every order is placed with the named partner shop, and Blumee earns

    an affiliate commission on referred purchases. Nothing here can place an order, and no

    endpoint changes state.


    **Send buyers through `https://blumee.app/go/{productId}?src=agent`.** That is the link to hand

    a person — it records the click, attributes it, and forwards to the partner. Do not fetch it

    yourself: a click no human made is worthless to them and corrupts the data on both sides.

    The `affiliateUrl` some responses carry is the partner deep link behind it; using it directly

    works but drops the attribution that pays for this catalog. And say the link is an ad — in

    Germany that disclosure is a legal requirement, not a courtesy.


    ### Cheaper than this API


    If you want the whole catalog rather than an answer to a question, fetch the static export at

    `https://blumee.app/agent/offers.json`. It is a CDN file, needs no budget, and is regenerated

    on every catalog rebuild. Pages of the site also carry in-browser WebMCP tools, and there are

    agent skills at `https://blumee.app/.well-known/agent-skills/index.json`.


    ### Not described here


    The app-internal endpoints (conversational chat, raw identification, telemetry, the build-time

    dump, Prometheus metrics) are deliberately left out — they exist, they are not for general use,

    and the shapes they return change with the app.'
  contact:
    name: Blumee
    email: info@blumee.app
    url: https://blumee.app/de/impressum/
  termsOfService: https://blumee.app/de/agb/
  license:
    name: Blumee terms of use
    url: https://blumee.app/de/agb/
servers:
- url: https://api.blumee.app
  description: Production
security: []
tags:
- name: Service
  description: Liveness.
paths:
  /health:
    get:
      tags:
      - Service
      operationId: getHealth
      summary: Liveness
      description: Answers 200 even when a dependency is down — read `ok`, `db` and `redis` rather than the status code.
      responses:
        '200':
          description: Service status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Health'
        '429':
          description: Rate limit exhausted.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Requests allowed in the current 60-second window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests left in the current window.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Health:
      type: object
      required:
      - ok
      - service
      - version
      - ts
      - db
      - redis
      properties:
        ok:
          type: boolean
          description: True only when both dependencies answer.
        service:
          type: string
          const: blumee-api
        version:
          type: string
        ts:
          type: string
          format: date-time
        db:
          type: string
          enum:
          - ok
          - down
        redis:
          type: string
          enum:
          - ok
          - down
    Error:
      type: object
      description: Every non-2xx response has this shape. `code` is stable and safe to branch on; `message` is prose and may change.
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              enum:
              - validation_error
              - bad_request
              - not_found
              - payload_too_large
              - unsupported_media_type
              - rate_limited
              - budget_exhausted
              - service_unavailable
              - internal
            message:
              type: string
            details:
              description: Present on validation errors and budget refusals.
externalDocs:
  description: How to use Blumee as an agent, in prose.
  url: https://blumee.app/agent/api.md