DayPilot Generation API

openapi: 3.2.0
info:
  title: DayPilot UI Builder Public Generation API
  summary: Discovery, validation, and stateless project generation for the subset exposed by DayPilot UI Builder.
  description: This API describes the components, targets, settings, and canonical option IDs that UI Builder can configure and generate. Agents can validate a strict project specification and receive its deterministic ZIP without saving a server-side resource. It is not a complete DayPilot product capability taxonomy. A capability absent from this API must not be interpreted as unsupported by DayPilot.
  version: 1.1.0
servers:
- url: https://builder.daypilot.org
  description: Canonical DayPilot UI Builder service
security: []
tags:
- name: Generation
  description: Anonymous, stateless validation and direct project-archive generation. These POST operations deliberately grant no browser CORS permission.
paths:
  /api/v1/configurations/validate:
    description: Only POST and OPTIONS are supported. Other methods return 405. No response from this resource grants Access-Control-Allow-Origin.
    post:
      tags:
      - Generation
      summary: Validate and fully preflight a Builder project specification
      description: Prepares and validates the complete immutable project tree without saving a configuration, project, job, or archive. This generation-tree preflight does not install dependencies, certify dependency security, or run the generated project's build, lint, tests, or browser runtime. Omitted applicable settings use defaults from the pinned catalog revision. The fixed request-body maximum is 64 KiB.
      operationId: validateBuilderConfiguration
      parameters:
      - $ref: '#/components/parameters/AcceptJSON'
      - $ref: '#/components/parameters/ContentEncoding'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: https://builder.daypilot.org/schema/builder-project-v1.json#/$defs/validationRequest
      responses:
        '200':
          $ref: '#/components/responses/ValidationSuccess'
        '400':
          $ref: '#/components/responses/MutationProblem'
        '406':
          $ref: '#/components/responses/MutationProblem'
        '412':
          $ref: '#/components/responses/MutationProblem'
        '413':
          $ref: '#/components/responses/MutationProblem'
        '415':
          $ref: '#/components/responses/MutationProblem'
        '422':
          $ref: '#/components/responses/MutationProblem'
        '428':
          $ref: '#/components/responses/MutationProblem'
        '429':
          $ref: '#/components/responses/MutationRateLimited'
        '500':
          $ref: '#/components/responses/MutationProblem'
        '503':
          $ref: '#/components/responses/MutationUnavailable'
    head:
      tags:
      - Generation
      summary: Reject HEAD for configuration validation
      description: Returns the 405 Problem representation headers and no body.
      operationId: headBuilderConfigurationValidationNotAllowed
      responses:
        '405':
          $ref: '#/components/responses/MutationProblem'
        '429':
          $ref: '#/components/responses/MutationRateLimited'
    options:
      tags:
      - Generation
      summary: Inspect allowed validation methods without granting POST CORS
      operationId: optionsBuilderConfigurationValidation
      responses:
        '204':
          $ref: '#/components/responses/MutationOptions'
        '429':
          $ref: '#/components/responses/MutationRateLimited'
  /api/v1/project-archives:
    description: Only POST and OPTIONS are supported. Other methods return 405. No response from this resource grants Access-Control-Allow-Origin.
    post:
      tags:
      - Generation
      summary: Generate a digest-pinned Builder project ZIP
      description: Repeats full preflight, verifies expectedProjectDigest, and returns a deterministic ZIP directly. It creates no server-side project or retained archive. The fixed completed ZIP maximum is 8 MiB.
      operationId: generateBuilderProjectArchive
      parameters:
      - $ref: '#/components/parameters/AcceptZIP'
      - $ref: '#/components/parameters/ContentEncoding'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: https://builder.daypilot.org/schema/builder-project-v1.json#/$defs/archiveRequest
      responses:
        '200':
          $ref: '#/components/responses/ArchiveSuccess'
        '400':
          $ref: '#/components/responses/MutationProblem'
        '406':
          $ref: '#/components/responses/MutationProblem'
        '412':
          $ref: '#/components/responses/MutationProblem'
        '413':
          $ref: '#/components/responses/MutationProblem'
        '415':
          $ref: '#/components/responses/MutationProblem'
        '422':
          $ref: '#/components/responses/MutationProblem'
        '428':
          $ref: '#/components/responses/MutationProblem'
        '429':
          $ref: '#/components/responses/MutationRateLimited'
        '500':
          $ref: '#/components/responses/MutationProblem'
        '503':
          $ref: '#/components/responses/MutationUnavailable'
    head:
      tags:
      - Generation
      summary: Reject HEAD for project archives
      description: Returns the 405 Problem representation headers and no body.
      operationId: headBuilderProjectArchiveNotAllowed
      responses:
        '405':
          $ref: '#/components/responses/MutationProblem'
        '429':
          $ref: '#/components/responses/MutationRateLimited'
    options:
      tags:
      - Generation
      summary: Inspect allowed archive methods without granting POST CORS
      operationId: optionsBuilderProjectArchive
      responses:
        '204':
          $ref: '#/components/responses/MutationOptions'
        '429':
          $ref: '#/components/responses/MutationRateLimited'
components:
  headers:
    RetryAfter:
      description: Seconds until retry for a bounded quota, busy, or deadline rejection.
      schema:
        type: integer
        minimum: 1
        maximum: 60
    NoSniff:
      description: Disable content-type sniffing.
      schema:
        type: string
        const: nosniff
    NoStore:
      description: The stateless generation representation must not be stored.
      schema:
        type: string
        const: no-store
  parameters:
    ContentEncoding:
      name: Content-Encoding
      in: header
      required: false
      description: Only an absent header or identity is accepted.
      schema:
        type: string
        const: identity
    AcceptJSON:
      name: Accept
      in: header
      required: false
      description: Must positively allow application/json. An absent header is accepted.
      schema:
        type: string
      example: application/json
    AcceptZIP:
      name: Accept
      in: header
      required: false
      description: Must positively allow application/zip. An absent header is accepted.
      schema:
        type: string
      example: application/zip
  schemas:
    Problem:
      type: object
      additionalProperties: false
      required:
      - type
      - title
      - status
      - detail
      - code
      properties:
        type:
          type: string
          format: uri-reference
        title:
          type: string
          minLength: 1
        status:
          type: integer
          minimum: 400
          maximum: 599
        detail:
          type: string
          minLength: 1
        code:
          type: string
          pattern: ^[a-z0-9]+(?:_[a-z0-9]+)*$
          enum:
          - query_invalid
          - component_not_found
          - edition_invalid
          - edition_required
          - target_not_found
          - invalid_request
          - method_not_allowed
          - resource_not_found
          - rate_limit_exceeded
          - discovery_document_unavailable
          - public_response_invalid
          - public_catalog_invalid
          - internal_error
          - request_invalid
          - representation_not_acceptable
          - media_type_unsupported
          - content_encoding_unsupported
          - request_too_large
          - configuration_invalid
          - catalog_revision_mismatch
          - project_digest_mismatch
          - precondition_required
          - rate_limit_capacity_exceeded
          - public_generation_disabled
          - generation_disabled
          - generation_busy
          - generation_deadline_exceeded
          - generation_preflight_failed
          - archive_generation_failed
        issues:
          type: array
          minItems: 1
          maxItems: 64
          items:
            $ref: https://builder.daypilot.org/schema/builder-project-v1.json#/$defs/issue
    CatalogRevision:
      type: string
      description: A deterministic revision over the rule, admission, and target catalog inputs.
      pattern: ^sha256:[a-f0-9]{64}$
  responses:
    MutationUnavailable:
      description: 'Generation is disabled, busy, or exceeded its computation deadline. Busy and deadline responses include Retry-After: 1; switch responses omit it.'
      headers:
        Cache-Control:
          $ref: '#/components/headers/NoStore'
        X-Content-Type-Options:
          $ref: '#/components/headers/NoSniff'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    MutationOptions:
      description: Allowed mutation methods and request media type. The response has no body and intentionally contains no Access-Control-Allow-Origin header.
      headers:
        Allow:
          description: Supported resource methods.
          schema:
            type: string
            const: POST, OPTIONS
        Accept-Post:
          description: Accepted request media type.
          schema:
            type: string
            const: application/json
        Cache-Control:
          $ref: '#/components/headers/NoStore'
        X-Content-Type-Options:
          $ref: '#/components/headers/NoSniff'
    MutationProblem:
      description: A stable RFC 9457 public generation problem. Mutation problems intentionally contain no CORS permission.
      headers:
        Cache-Control:
          $ref: '#/components/headers/NoStore'
        X-Content-Type-Options:
          $ref: '#/components/headers/NoSniff'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    ArchiveSuccess:
      description: A complete deterministic project archive. No project or archive is retained by this operation.
      headers:
        Cache-Control:
          $ref: '#/components/headers/NoStore'
        X-Content-Type-Options:
          $ref: '#/components/headers/NoSniff'
        Content-Disposition:
          description: Attachment filename derived from the validated portable projectName.
          schema:
            type: string
            pattern: ^attachment; filename="[a-z0-9]+(?:-[a-z0-9]+)*\.zip"$
        Content-Length:
          description: Exact completed ZIP size, bounded to 8 MiB.
          schema:
            type: integer
            minimum: 1
            maximum: 8388608
        Content-Digest:
          description: RFC 9530 SHA-256 digest over the complete ZIP bytes.
          schema:
            type: string
            pattern: ^sha-256=:[A-Za-z0-9+/]{43}=:$
        DayPilot-Project-Digest:
          description: Digest of the validated generated-project tree.
          schema:
            $ref: '#/components/schemas/CatalogRevision'
        DayPilot-Catalog-Revision:
          description: Public catalog revision pinned by the request.
          schema:
            $ref: '#/components/schemas/CatalogRevision'
      content:
        application/zip:
          schema:
            type: string
            contentEncoding: base64
            contentMediaType: application/zip
            maxLength: 8388608
    MutationRateLimited:
      description: A weighted or process-wide request limit rejected the operation. No CORS permission is granted.
      headers:
        Cache-Control:
          $ref: '#/components/headers/NoStore'
        X-Content-Type-Options:
          $ref: '#/components/headers/NoSniff'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    ValidationSuccess:
      description: The exact project tree passed full generation-tree preflight. This does not certify dependency installation, dependency security, build, lint, tests, or browser runtime. No server-side resource was created.
      headers:
        Cache-Control:
          $ref: '#/components/headers/NoStore'
        X-Content-Type-Options:
          $ref: '#/components/headers/NoSniff'
        Content-Length:
          description: Exact serialized validation-body size.
          schema:
            type: integer
            minimum: 1
      content:
        application/json:
          schema:
            $ref: https://builder.daypilot.org/schema/builder-project-v1.json#/$defs/validationResponse
externalDocs:
  description: Strict public Builder project contract
  url: https://builder.daypilot.org/schema/builder-project-v1.json