{
  "openapi": "3.1.0",
  "info": {
    "title": "Veylen Studios ARA API",
    "version": "1.2.0",
    "description": "A truthful discovery and live project-consultation contract for AI agents. The required sequence is check availability, hold a slot, obtain explicit user consent, and complete the booking.",
    "contact": {
      "name": "Veylen Studios",
      "email": "hello@veylenstudios.com",
      "url": "https://veylenstudios.vercel.app/"
    }
  },
  "servers": [
    {
      "url": "https://veylenstudios.vercel.app"
    }
  ],
  "paths": {
    "/api/ara/v1/business": {
      "get": {
        "operationId": "getBusiness",
        "summary": "Get the canonical Veylen Studios business profile",
        "responses": {
          "200": {
            "description": "Canonical business profile",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/BusinessResponse" }
              }
            }
          }
        }
      }
    },
    "/api/ara/v1/services": {
      "get": {
        "operationId": "listServices",
        "summary": "List the services Veylen Studios offers",
        "responses": {
          "200": {
            "description": "Service catalog",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ServicesResponse" }
              }
            }
          }
        }
      }
    },
    "/api/ara/v1/availability": {
      "get": {
        "operationId": "checkAvailability",
        "summary": "Check live project-consultation availability",
        "parameters": [
          {
            "name": "start",
            "in": "query",
            "required": true,
            "description": "Inclusive ISO 8601 date-time search boundary.",
            "schema": { "type": "string", "format": "date-time" }
          },
          {
            "name": "end",
            "in": "query",
            "required": true,
            "description": "Exclusive ISO 8601 date-time search boundary.",
            "schema": { "type": "string", "format": "date-time" }
          }
        ],
        "responses": {
          "200": {
            "description": "Live bookable 15-minute slots in the requested range."
          },
          "503": {
            "$ref": "#/components/responses/BookingNotConfigured"
          }
        }
      }
    },
    "/api/ara/v1/holds": {
      "post": {
        "operationId": "holdSlot",
        "summary": "Temporarily hold a live consultation slot",
        "parameters": [
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["slot_id"],
                "properties": {
                  "slot_id": { "type": "string" },
                  "source": { "type": "string", "description": "Calling agent, plugin, or web surface." }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Slot held temporarily. The response contains a hold_id, private hold_token, slot, and expiration time."
          },
          "503": {
            "$ref": "#/components/responses/BookingNotConfigured"
          }
        }
      }
    },
    "/api/ara/v1/bookings": {
      "post": {
        "operationId": "completeBooking",
        "summary": "Confirm a held project-consultation slot with explicit user consent",
        "description": "The server, not the AI client, validates the hold, availability, required identity fields, and consent before confirmation.",
        "parameters": [
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["hold_id", "hold_token", "customer", "consent"],
                "properties": {
                  "hold_id": { "type": "string" },
                  "hold_token": { "type": "string", "description": "Private token returned by holdSlot. Do not expose it to other users." },
                  "source": { "type": "string", "description": "Calling agent, plugin, or web surface." },
                  "attribution": { "type": "object", "description": "Optional first-party referral context.", "additionalProperties": { "type": "string" } },
                  "customer": {
                    "type": "object",
                    "required": ["name", "email"],
                    "properties": {
                      "name": { "type": "string", "minLength": 1 },
                      "email": { "type": "string", "format": "email" },
                      "phone": { "type": "string" },
                      "project_summary": { "type": "string", "maxLength": 2000 }
                    },
                    "additionalProperties": false
                  },
                  "consent": {
                    "type": "object",
                    "required": ["booking_confirmation", "language", "timestamp"],
                    "properties": {
                      "booking_confirmation": { "const": true },
                      "marketing": { "type": "boolean", "default": false },
                      "language": { "type": "string" },
                      "timestamp": { "type": "string", "format": "date-time" },
                      "source": { "type": "string" }
                    },
                    "additionalProperties": false
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Confirmed booking with a stable booking ID, California-local time, and private management URL."
          },
          "503": {
            "$ref": "#/components/responses/BookingNotConfigured"
          }
        }
      }
    },
    "/api/ara/v1/manage-booking": {
      "get": {
        "operationId": "getManagedBooking",
        "summary": "View a booking using its private management token",
        "parameters": [
          { "name": "booking_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } },
          { "name": "token", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Private booking status and consultation time." } }
      },
      "post": {
        "operationId": "changeManagedBooking",
        "summary": "Cancel or reschedule a booking using its private management token",
        "requestBody": { "required": true, "content": { "application/json": { "schema": {
          "type": "object",
          "required": ["action", "booking_id", "management_token"],
          "properties": {
            "action": { "type": "string", "enum": ["cancel", "reschedule"] },
            "booking_id": { "type": "string", "format": "uuid" },
            "management_token": { "type": "string" },
            "hold_id": { "type": "string", "format": "uuid", "description": "Required for reschedule." },
            "hold_token": { "type": "string", "description": "Required for reschedule." }
          },
          "additionalProperties": false
        } } } },
        "responses": { "200": { "description": "Updated booking status and consultation time." } }
      }
    }
  },
  "components": {
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "description": "A unique key that prevents duplicate holds or bookings when an agent retries.",
        "schema": { "type": "string", "minLength": 8, "maxLength": 200 }
      }
    },
    "responses": {
      "BookingNotConfigured": {
        "description": "The production calendar is temporarily unavailable or misconfigured.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ConfigurationRequired" }
          }
        }
      }
    },
    "schemas": {
      "BusinessResponse": {
        "type": "object",
        "required": ["data", "meta"],
        "properties": {
          "data": { "type": "object" },
          "meta": { "type": "object" }
        }
      },
      "ServicesResponse": {
        "type": "object",
        "required": ["data", "meta"],
        "properties": {
          "data": {
            "type": "array",
            "items": { "type": "object" }
          },
          "meta": { "type": "object" }
        }
      },
      "ConfigurationRequired": {
        "type": "object",
        "required": ["error", "operation", "status", "required_configuration"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": { "const": "booking_provider_not_configured" },
              "message": { "type": "string" }
            }
          },
          "operation": { "type": "string" },
          "status": { "const": "configuration_required" },
          "required_configuration": {
            "type": "array",
            "items": { "type": "string" }
          }
        }
      }
    }
  }
}