# Generated by scripts/build-project-tools.mjs - DO NOT EDIT.
# Source of truth: admin/project-tools.yaml (next-openapi-schema).
openapi: 3.0.3
info:
  title: Gametize Project Creation Tools (Public Subset)
  description: >
    Public OpenAPI description of the two Gametize Administrator API v1 operations needed for
    AI-assisted project creation:

    1. Upload an image, media, or document and receive a public file URL
       (`/files/upload.json`). Use the returned `fileUrl` for project images.

    2. Create a new Project from a Gametize project JSON string
       (`/projects/import.json`). The JSON uses the same FileHub project
       export/import format as the CMS Import/Export tool.

    These operations are authenticated with admin API client credentials (contact your Gametize
    account manager). Start at the documentation index `/openapi/` (human-readable, lists everything
    below), or use the companion documents served next to this file:

    - `/openapi/project-json-guide.md` - how to construct valid project
      JSON: structure, supported challenge types, and rules.
    - `/openapi/project-json-example.json` - a complete valid example
      project JSON.

    All other Administrator API operations are not described here and require their own credentials
    and scopes.
  version: 1.0.0
  contact:
    name: Gametize Support
    email: support@gametize.com
  license:
    name: Proprietary - Gametize API Terms of Use
    url: https://start.gametize.com/terms
servers:
  - url: https://{platform}/api/admin/v1
    description: >
      Your Gametize platform host. Replace {platform} with the API host of your platform (for
      example gametize.com, or your client platform domain).
    variables:
      platform:
        default: gametize.com
security:
  - AdminClientKey: []
    AdminClientSecret: []
tags:
  - name: files
    description: Media upload for use inside project content
  - name: projects
    description: Project creation from project JSON
paths:
  /files/upload.json:
    post:
      tags:
        - files
      summary: Upload a file (administrator)
      description: |-
        Uploads an image, media, or document into platform storage and returns a
        public URL you can reference in project JSON (e.g. as a challenge or
        project banner image). Optionally associates the file with a project.

        Send `multipart/form-data` with the required `file` part. Supported types
        and the maximum size (30 MB) match the platform File Manager: images,
        PDF, and Office documents. Unsafe or unsupported content is rejected.

        PNG/JPG/JPEG uploads may be compressed before storage; the response field
        `fileCompressed` reports whether that happened. Compression keeps the
        original resolution and never fails an upload.

        `fileName` in the response is the stored name (it may be randomised by
        the platform), not the original upload name. Use `fileUrl` in project
        JSON image fields.
      operationId: adminUploadFile
      parameters:
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AdminFileUploadRequest'
      security:
        - AdminClientKey: []
          AdminClientSecret: []
      responses:
        '200':
          description: File uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminFileUploadResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /projects/import.json:
    post:
      tags:
        - projects
      summary: Create a project from a Gametize project JSON string
      description: |-
        Creates a **new** Project from a Gametize project JSON string, using the
        same FileHub project format as the platform's own project export/import
        tool. This endpoint never updates an existing project.

        Send the JSON either as the `projectJson` text field
        (multipart/form-data or application/x-www-form-urlencoded) or, for large
        payloads, as the `projectJsonFile` upload part (multipart/form-data only,
        recommended - uploads are not bound by the per-field string length
        limit).

        The response returns the new `projectId`. When some content items could
        not be imported, the project is still created and
        `partialImportWarning` explains what to fix in the CMS.

        How to build valid project JSON (structure, supported challenge types,
        examples): see the companion guide served with this document at
        `/openapi/project-json-guide.md`.
      operationId: adminImportProject
      parameters:
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AdminProjectImportRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/AdminProjectImportRequest'
      security:
        - AdminClientKey: []
          AdminClientSecret: []
      responses:
        '200':
          description: Project created from import
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminProjectImportResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  securitySchemes:
    AdminClientKey:
      type: apiKey
      in: header
      name: X-Admin-Client-Key
      description: Admin API client key. Send in the X-Admin-Client-Key header.
    AdminClientSecret:
      type: apiKey
      in: header
      name: X-Admin-Client-Secret
      description: Admin API client secret. Send in the X-Admin-Client-Secret header.
  parameters:
    RequestId:
      name: X-Request-Id
      in: header
      required: false
      description: Optional request correlation ID echoed back in logs.
      schema:
        type: string
        example: req-550e8400-e29b-41d4-a716-446655440000
  responses:
    BadRequestError:
      description: Bad request - missing or invalid parameters, or rejected content.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AdminApiErrorResponse'
          example:
            errorCode: invalid_request
            errorMessage: Missing project JSON.
    UnauthorizedError:
      description: Unauthorized - invalid or missing admin API client credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AdminApiErrorResponse'
          example:
            errorCode: unauthorized
            errorMessage: Invalid admin API credentials.
    ForbiddenError:
      description: Forbidden - the supplied credentials are not allowed to perform this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AdminApiErrorResponse'
          example:
            errorCode: forbidden
            errorMessage: Insufficient permissions for this operation.
    InternalServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AdminApiErrorResponse'
          example:
            errorCode: internal_error
            errorMessage: Internal server error.
  schemas:
    AdminApiErrorResponse:
      type: object
      required:
        - errorCode
        - errorMessage
      properties:
        errorCode:
          type: string
          description: Machine-readable error code.
          enum:
            - unauthorized
            - forbidden
            - invalid_request
            - file_upload_failed
            - internal_error
        errorMessage:
          type: string
          description: Human-readable error message.
    AdminProjectImportRequest:
      type: object
      minProperties: 1
      description: >
        Project import input. Supply the FileHub project JSON either as the `projectJson` text field
        or as the `projectJsonFile` part (multipart only, recommended for large payloads). Exactly
        one of the two is required; the file part takes precedence when both are supplied.
      properties:
        projectJson:
          type: string
          description: >
            FileHub project JSON string (same format as project export). Subject to the platform
            per-field size limit; use `projectJsonFile` for long JSON.
          example: '{"version":"1","project":{"projectTitle":"My Project"}}'
        projectJsonFile:
          type: string
          format: binary
          description: >
            FileHub project JSON uploaded as a file part (multipart/form-data only). Supports
            project JSON larger than the text-field size limit.
    AdminProjectImportResponse:
      type: object
      required:
        - projectId
        - projectCreated
      properties:
        projectId:
          type: integer
          format: int64
          description: Unique identifier of the newly created project.
          example: 12345
        projectCreated:
          type: boolean
          description: Indicates that the project was created from the imported JSON.
          example: true
        projectTitle:
          type: string
          description: |-
            Title of the created project, taken from the imported JSON. Omitted when
            unavailable.
          example: Employee Onboarding 2024
        partialImportWarning:
          type: string
          description: >
            Present when the project was created but some content items (topics, challenges, or
            related content) failed to import. The project still exists with everything that
            imported successfully.
          example: Project created, but some content items failed to import.
    AdminFileUploadRequest:
      type: object
      required:
        - file
      description: >
        Admin file upload input. The `file` part is required. `projectId` is optional: when omitted
        or 0, the file is uploaded without project association (platform-level shared folder). When
        greater than 0, the file is stored under that project and the API client's account must have
        admin access to it.
      properties:
        file:
          type: string
          format: binary
          description: >
            The file to upload (image, media, or document). Types and maximum size mirror the CMS
            File Manager (images, PDF, and Office documents; 30 MB limit). Unsafe or unsupported
            content is rejected.
        projectId:
          type: integer
          format: int64
          minimum: 0
          description: >
            Optional project to associate the file with. Omit or use 0 for a platform-level upload.
            Any negative value is treated as no project association.
          example: 123
    AdminFileUploadResponse:
      type: object
      required:
        - fileId
        - fileName
        - filePath
        - fileUrl
        - fileUploaded
        - fileCompressed
      description: >
        Uploaded file metadata. `fileName` is the actually stored name (which may be
        randomised/obfuscated when filename randomisation is enabled), not the original upload name.
        `projectId` is only present for project-associated uploads.
      properties:
        fileId:
          type: integer
          format: int64
          description: Unique identifier of the stored file record.
          example: 12345
        fileName:
          type: string
          description: >
            The stored file name (as shown in the File Manager list). May differ from the original
            upload name when filename randomisation is enabled.
          example: training-material-a1b2c3.pdf
        filePath:
          type: string
          description: |-
            Stored path of the file within the platform, for reference. Use
            `fileUrl` when referencing the file from project JSON.
          example: /files/all/training-material-a1b2c3.pdf
        fileUrl:
          type: string
          description: Absolute public URL of the uploaded file.
          example: https://example.gametize.com/files/all/training-material-a1b2c3.pdf
        fileUploaded:
          type: boolean
          description: Indicates that the file was uploaded successfully. Always `true` on success.
          example: true
        fileCompressed:
          type: boolean
          description: |-
            `true` when the stored image was compressed before storage (PNG/JPG/JPEG
            only, and only when the platform has image compression configured and it
            succeeded). `false` for all other uploads, including when compression was
            skipped or failed (the original image is always kept in that case).
          example: false
        projectId:
          type: integer
          format: int64
          description: >
            Associated project ID. Present only when the upload was project-associated; omitted for
            platform-level uploads.
          example: 123