{
  "openapi": "3.1.0",
  "info": {
    "title": "Plateau Candy Agent API",
    "version": "1.2.0",
    "description": "Machine-readable endpoints for AI agents. Plateau Candy is a design studio for emerging technologies in Cologne, Germany.\n\n**Versioning policy:** The current stable surface is API version 1, served at the canonical `/api/v1/*` paths documented below. The unversioned `/api/*` paths are permanent aliases of the same operations (both are answered identically; existing integrations never need to migrate). Every response carries an `X-API-Version` header. Breaking changes would only ever appear under `/api/v2/*`; existing paths then keep working for at least 6 months and announce retirement via `Deprecation` and `Sunset` headers (RFC 8594). Additive changes (new fields, new endpoints) happen in place and are not considered breaking.\n\n**Errors:** All error responses (4xx/5xx) are RFC 9457 `application/problem+json` — see the `Problem` schema: `type`, `title`, `status`, `detail`, plus a stable machine-readable `code` extension and a legacy `error` object for older clients.",
    "contact": {
      "name": "Plateau Candy",
      "email": "hi@plateaucandy.de",
      "url": "https://www.plateaucandy.de"
    }
  },
  "servers": [
    {
      "url": "https://www.plateaucandy.de",
      "description": "Production. /api/v1/* is the canonical v1 surface; the unversioned /api/* paths are permanent aliases of the same operations."
    }
  ],
  "x-versioning": {
    "current": 1,
    "scheme": "URL path (/api/v1/*; unversioned /api/* = permanent alias) + X-API-Version response header",
    "breakingChanges": "Only under a new path prefix (/api/v2/*).",
    "deprecation": "Announced via Deprecation and Sunset headers (RFC 8594), minimum 6 months notice."
  },
  "x-rateLimit": {
    "description": "All endpoints return X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. Exceeding the limit returns 429 with Retry-After header.",
    "limits": {
      "public-read": "60 requests per minute",
      "public-write": "10 requests per minute",
      "authenticated": "120 requests per minute"
    },
    "headers": [
      "X-RateLimit-Limit",
      "X-RateLimit-Remaining",
      "X-RateLimit-Reset",
      "Retry-After"
    ]
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Partner API key. How to obtain one: https://www.plateaucandy.de/auth.md"
      }
    },
    "schemas": {
      "Problem": {
        "type": "object",
        "description": "RFC 9457 problem details (application/problem+json), returned by every 4xx/5xx response. The `code` extension is the stable machine-readable error code; the `error` object repeats it in the pre-1.2 legacy shape for older clients.",
        "required": [
          "type",
          "title",
          "status",
          "detail",
          "code"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "Problem type URI (RFC 9457); about:blank when the status code says it all",
            "examples": [
              "about:blank"
            ]
          },
          "title": {
            "type": "string",
            "description": "Short human-readable summary (HTTP reason phrase)"
          },
          "status": {
            "type": "integer",
            "description": "HTTP status code, mirrored into the body"
          },
          "detail": {
            "type": "string",
            "description": "Human-readable explanation of this occurrence"
          },
          "code": {
            "type": "string",
            "description": "Machine-readable error code, stable across releases",
            "examples": [
              "NOT_FOUND",
              "RATE_LIMITED",
              "UNAUTHORIZED",
              "MISSING_FIELDS",
              "INVALID_JSON",
              "INVALID_EMAIL"
            ]
          },
          "error": {
            "type": "object",
            "description": "Legacy envelope (deprecated, kept for pre-1.2 clients)",
            "required": [
              "code",
              "message",
              "status"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "status": {
                "type": "integer"
              }
            }
          }
        }
      },
      "JsonLdDocument": {
        "type": "object",
        "description": "Schema.org JSON-LD document.",
        "required": [
          "@context",
          "@type"
        ],
        "properties": {
          "@context": {
            "type": "string",
            "examples": [
              "https://schema.org"
            ]
          },
          "@type": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "SearchResults": {
        "type": "object",
        "required": [
          "query",
          "count",
          "results"
        ],
        "properties": {
          "query": {
            "type": "object",
            "properties": {
              "q": {
                "type": "string"
              },
              "tag": {
                "type": "string"
              },
              "client": {
                "type": "string"
              },
              "lang": {
                "type": "string"
              }
            }
          },
          "count": {
            "type": "integer"
          },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "title",
                "slug",
                "language",
                "url"
              ],
              "properties": {
                "title": {
                  "type": "string"
                },
                "slug": {
                  "type": "string"
                },
                "client": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "tags": {
                  "type": [
                    "array",
                    "null"
                  ],
                  "items": {
                    "type": "string"
                  }
                },
                "language": {
                  "type": "string",
                  "enum": [
                    "en",
                    "de"
                  ]
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "markdownUrl": {
                  "type": "string",
                  "format": "uri"
                },
                "dateModified": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "ApiDirectory": {
        "type": "object",
        "required": [
          "name",
          "version",
          "endpoints"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "schema_version": {
            "type": "string"
          },
          "last_updated": {
            "type": "string",
            "format": "date"
          },
          "endpoints": {
            "type": "object",
            "description": "Endpoint groups; each entry carries url, method(s) and description.",
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      },
      "NegotiationResult": {
        "type": "object",
        "required": [
          "match",
          "fit_score",
          "query",
          "capabilities_matched",
          "next_steps"
        ],
        "properties": {
          "match": {
            "type": "boolean"
          },
          "fit_score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "Weighted capability/experience/capacity fit"
          },
          "query": {
            "type": "string"
          },
          "capabilities_matched": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "matching_experience": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "title": {
                  "type": "string"
                },
                "client": {
                  "type": "string"
                },
                "role": {
                  "type": "string"
                },
                "period": {
                  "type": "string"
                },
                "outcome": {
                  "type": "string"
                },
                "capabilities": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "relevance": {
                  "type": "number"
                }
              }
            }
          },
          "relevant_team": {
            "type": "object",
            "properties": {
              "led_by": {
                "type": "string"
              },
              "roles": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "model": {
                "type": "string"
              },
              "scale": {
                "type": "string"
              },
              "start": {
                "type": "string"
              }
            }
          },
          "capacity": {
            "$ref": "#/components/schemas/Capacity"
          },
          "experience": {
            "type": "object",
            "properties": {
              "principal_experience_years": {
                "type": "integer"
              },
              "extended_network_specialists": {
                "type": "integer"
              },
              "named_clients": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "all_capabilities": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "next_steps": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/NextStep"
            }
          }
        }
      },
      "NextStep": {
        "type": "object",
        "required": [
          "action",
          "url"
        ],
        "properties": {
          "action": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "method": {
            "type": "string",
            "enum": [
              "GET",
              "POST"
            ]
          }
        }
      },
      "Capacity": {
        "type": "object",
        "description": "Current studio capacity; also served standalone at /api/capacity.json.",
        "properties": {
          "availability": {
            "type": "string",
            "examples": [
              "open",
              "limited"
            ]
          },
          "start": {
            "type": "string"
          },
          "team_model": {
            "type": "string"
          },
          "principal": {
            "type": "string"
          },
          "booking": {
            "type": "string",
            "format": "uri"
          }
        },
        "additionalProperties": true
      },
      "BriefingReceipt": {
        "type": "object",
        "required": [
          "id",
          "status",
          "next_step",
          "contact"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "received"
            ]
          },
          "partner": {
            "type": "string",
            "description": "Only present on authenticated partner submissions"
          },
          "next_step": {
            "type": "string"
          },
          "contact": {
            "type": "string"
          }
        }
      },
      "InquiryReceipt": {
        "type": "object",
        "required": [
          "id",
          "status",
          "type",
          "message",
          "contact"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "received"
            ]
          },
          "type": {
            "type": "string",
            "enum": [
              "consultation",
              "partnership",
              "project",
              "general"
            ]
          },
          "message": {
            "type": "string"
          },
          "contact": {
            "type": "string"
          }
        }
      },
      "SubscriptionReceipt": {
        "type": "object",
        "required": [
          "status",
          "callback_url",
          "topics"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "subscribed"
            ]
          },
          "callback_url": {
            "type": "string",
            "format": "uri"
          },
          "topics": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "notify_on": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "message": {
            "type": "string"
          }
        }
      },
      "WebhookRegistration": {
        "type": "object",
        "required": [
          "status",
          "callback_url",
          "events"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "registered"
            ]
          },
          "partner": {
            "type": "string"
          },
          "callback_url": {
            "type": "string",
            "format": "uri"
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "valid_events": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "message": {
            "type": "string"
          }
        }
      },
      "WorkflowResult": {
        "type": "object",
        "description": "Envelope shared by all server-side workflows; workflow-specific payload fields sit alongside the envelope keys.",
        "required": [
          "workflow",
          "steps_executed"
        ],
        "properties": {
          "workflow": {
            "type": "string",
            "enum": [
              "discovery",
              "booking",
              "matching"
            ]
          },
          "steps_executed": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "additionalProperties": true
      },
      "AgentCard": {
        "type": "object",
        "description": "A2A Agent Identity Card (v0.3). Full field reference: https://a2a-protocol.org",
        "required": [
          "name",
          "description",
          "url"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "skills": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        },
        "additionalProperties": true
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Validation error — the request body or parameters are malformed (codes: MISSING_FIELDS, INVALID_JSON, INVALID_EMAIL, …)",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Bearer token missing or invalid (code: UNAUTHORIZED)",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found (code: NOT_FOUND)",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit exceeded (code: RATE_LIMITED)",
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds until rate limit resets"
          },
          "X-RateLimit-Limit": {
            "schema": {
              "type": "integer"
            }
          },
          "X-RateLimit-Remaining": {
            "schema": {
              "type": "integer"
            }
          },
          "X-RateLimit-Reset": {
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "ServerError": {
        "description": "Unexpected server error (typed body, machine-readable code)",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      }
    }
  },
  "paths": {
    "/api/v1/services": {
      "get": {
        "operationId": "getServices",
        "summary": "Returns service catalog as Schema.org OfferCatalog",
        "description": "Full service catalog of the studio as a Schema.org OfferCatalog (JSON-LD). Read-only, cacheable, no auth.",
        "tags": [
          "read"
        ],
        "responses": {
          "200": {
            "description": "Service catalog (JSON-LD)",
            "content": {
              "application/ld+json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonLdDocument"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/api/v1/work": {
      "get": {
        "operationId": "getWork",
        "summary": "Returns portfolio as Schema.org ItemList",
        "description": "All published case studies as a Schema.org ItemList (JSON-LD). Read-only, cacheable, no auth.",
        "tags": [
          "read"
        ],
        "responses": {
          "200": {
            "description": "Portfolio case studies (JSON-LD)",
            "content": {
              "application/ld+json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonLdDocument"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/api/v1/search": {
      "get": {
        "operationId": "searchWork",
        "summary": "Search and filter portfolio by keyword, tag, or client",
        "description": "Free-text and faceted search over the case study index. Returns matching projects with canonical and Markdown URLs.",
        "tags": [
          "read"
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Free-text search"
          },
          {
            "name": "tag",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by tag"
          },
          {
            "name": "client",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by client name"
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "en"
            },
            "description": "Language (en or de)"
          }
        ],
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResults"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/api/v1/directory": {
      "get": {
        "operationId": "getDirectory",
        "summary": "Master index of all machine-readable endpoints",
        "description": "The recommended entry point: lists every machine-readable endpoint with method and purpose.",
        "tags": [
          "discovery"
        ],
        "responses": {
          "200": {
            "description": "API directory",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiDirectory"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/api/v1/capacity.json": {
      "get": {
        "operationId": "getCapacity",
        "summary": "Current studio capacity and earliest start",
        "description": "Availability signal for scheduling agents: capacity status, earliest start, team model, booking link.",
        "tags": [
          "read"
        ],
        "responses": {
          "200": {
            "description": "Current capacity",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Capacity"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/api/v1/negotiate.json": {
      "post": {
        "operationId": "negotiateProjectFit",
        "summary": "Agent negotiation: check if Plateau Candy can handle a specific project",
        "description": "Send a project description; returns a fit score with matched capabilities, comparable case studies, current capacity and concrete next steps.",
        "tags": [
          "negotiate"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "query"
                ],
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "Project description in natural language"
                  },
                  "type": {
                    "type": "string",
                    "description": "Optional project type hint"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Match result with confidence, capabilities, similar work, next steps",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NegotiationResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/api/v1/briefing": {
      "post": {
        "operationId": "submitBriefing",
        "summary": "Submit a project briefing",
        "description": "Structured project intake. Returns a receipt with an id; a human responds within 48h. Supports Idempotency-Key header.",
        "tags": [
          "write"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "project_type",
                  "brief",
                  "email"
                ],
                "properties": {
                  "project_type": {
                    "type": "string"
                  },
                  "brief": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "agency": {
                    "type": "string"
                  },
                  "timeline": {
                    "type": "string"
                  },
                  "budget_range": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Briefing received",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BriefingReceipt"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/api/v1/inquiry": {
      "post": {
        "operationId": "submitInquiry",
        "summary": "Submit a general inquiry",
        "description": "General contact endpoint for consultation, partnership or project inquiries. Returns a receipt with an id.",
        "tags": [
          "write"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "email",
                  "message"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "message": {
                    "type": "string"
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "consultation",
                      "partnership",
                      "project",
                      "general"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Inquiry received",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InquiryReceipt"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/api/v1/subscribe": {
      "post": {
        "operationId": "subscribeToUpdates",
        "summary": "Subscribe to topic-based updates. Agents register callback URLs for event notifications.",
        "description": "Topic subscription without auth: register a callback URL and topics; matching publications trigger a webhook POST.",
        "tags": [
          "subscribe",
          "webhooks"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "callback_url",
                  "topics"
                ],
                "properties": {
                  "callback_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "URL to receive webhook POST notifications"
                  },
                  "topics": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Topics to subscribe to (e.g. 'AI Architecture', 'Brand Systems')"
                  },
                  "notify_on": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "case_study.published",
                        "capacity.changed",
                        "service.added",
                        "service.updated"
                      ]
                    },
                    "description": "Event types to receive notifications for"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Subscription registered — webhook notifications will be sent to callback_url",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriptionReceipt"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/api/v1/webhooks/register": {
      "post": {
        "operationId": "registerWebhook",
        "summary": "Register a webhook endpoint for real-time event notifications (requires auth)",
        "description": "Partner-authenticated webhook registration for the full event set. Auth guide: https://www.plateaucandy.de/auth.md",
        "tags": [
          "subscribe",
          "webhooks"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "callback_url",
                  "events"
                ],
                "properties": {
                  "callback_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "URL to receive POST notifications when events occur"
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "case_study.published",
                        "capacity.changed",
                        "service.added",
                        "service.updated"
                      ]
                    },
                    "description": "Events to subscribe to"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Webhook registered — events will be POSTed to callback_url",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookRegistration"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/api/v1/workflows/discovery.json": {
      "get": {
        "operationId": "workflowDiscovery",
        "summary": "Server-side workflow: aggregates profile + capabilities + work + services in 1 request",
        "description": "One-call orientation: studio profile, capabilities, portfolio and services aggregated server-side — saves 4 round trips.",
        "tags": [
          "workflow"
        ],
        "responses": {
          "200": {
            "description": "Aggregated discovery data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkflowResult"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/api/v1/workflows/booking.json": {
      "post": {
        "operationId": "workflowBooking",
        "summary": "Server-side workflow: event types + available slots + curated options in 1 request",
        "description": "Booking preparation in one call: live consultation types, next available slots and curated options for the given project type.",
        "tags": [
          "workflow"
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "project_type": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Curated booking options",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkflowResult"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/api/v1/workflows/matching.json": {
      "post": {
        "operationId": "workflowMatching",
        "summary": "Server-side workflow: problem analysis + capability match + similar work + contact",
        "description": "Send a problem statement; returns the negotiation result plus contact options in one call.",
        "tags": [
          "workflow"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "problem"
                ],
                "properties": {
                  "problem": {
                    "type": "string",
                    "description": "Problem statement in natural language"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Problem-solution match result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkflowResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/api/v1/feed.xml": {
      "get": {
        "operationId": "getAtomFeed",
        "summary": "Atom feed with latest case studies and updates — agents can poll or use webhooks for push",
        "description": "Atom 1.0 feed of publications. Prefer /api/subscribe for push notifications instead of polling.",
        "tags": [
          "subscribe"
        ],
        "responses": {
          "200": {
            "description": "Atom XML feed",
            "content": {
              "application/atom+xml": {
                "schema": {
                  "type": "string",
                  "description": "Atom 1.0 XML document"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/.well-known/agent.json": {
      "get": {
        "operationId": "getAgentCard",
        "summary": "A2A Agent Identity Card (v0.3)",
        "description": "Agent identity with declared skills and endpoints. Canonical path: /.well-known/agent-card.json (this path is a stable alias).",
        "tags": [
          "discovery"
        ],
        "responses": {
          "200": {
            "description": "Agent card with skills and URIs",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentCard"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/api/v1/markdown/{language}/{slug}": {
      "get": {
        "operationId": "getProjectMarkdown",
        "summary": "Returns project content as Markdown",
        "description": "Full case study body as plain Markdown — the token-efficient way to read project content.",
        "tags": [
          "read"
        ],
        "parameters": [
          {
            "name": "language",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "de"
              ]
            }
          },
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Project content in Markdown",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    }
  }
}