Hostilo Files API

openapi: 3.2.0
info:
  title: Hostilo REST Files API
  version: 1.1.0
  summary: Create, publish, restore and measure websites on hostilo.app.
  description: 'REST API of Hostilo.app (IMJ sp. z o.o.) for AI agents and automation tools (Make, n8n, Zapier, GPT Actions). The same actions as the Hostilo MCP server (https://hostilo.app/mcp). JSON in, JSON out. Auth: API key from Dashboard > API & tools, sent as "Authorization: Bearer hk_...". Rate limit: 60 requests per minute per key. Every action is also available as https://hostilo.app/api.php?action= (original address). Messages are in Polish. Guide: https://hostilo.app/docs#rest'
  termsOfService: https://hostilo.app/terms
  license:
    name: Proprietary, use under the Hostilo terms
    url: https://hostilo.app/terms
  contact:
    name: Hostilo support
    url: https://hostilo.app/contact
    email: hello@hostilo.app
servers:
- url: https://hostilo.app/api/v1
  description: Production
security:
- apiKey: []
tags:
- name: Files
  description: 'Multi-file projects: several files at once or a ZIP.'
paths:
  /publish_files:
    post:
      operationId: publishFiles
      summary: Publish several files
      description: Publishes many files to an existing site. index.html becomes the page, other HTML pages go to the site root with clean addresses (/about), other files go to assets/ and links are fixed. Binary files as base64. Max 300 files, 10 MB each, 20 MB total. dry_run previews.
      tags:
      - Files
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishFilesRequest'
            example:
              site_id: 123
              files:
              - path: index.html
                content: <!DOCTYPE html><html><head><link rel="stylesheet" href="css/style.css"></head><body>Hi</body></html>
              - path: css/style.css
                content: body{font-family:sans-serif}
      responses:
        '200':
          description: Success.
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportResponse'
              example:
                success: true
                dry_run: false
                url: https://my-page.hostilo.page
                message: '...'
                index: true
                files: 2
                bytes: 5120
                rewritten: 1
                overwritten: 0
                skipped: []
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/VersionConflict'
        '429':
          $ref: '#/components/responses/RateLimited'
  /import_zip:
    post:
      operationId: importZip
      summary: Import a ZIP project
      description: 'Imports a ZIP (max 20 MB) into an existing site: JSON with zip_url or zip_base64, multipart field zip, or a raw application/zip body with ?site_id. index.html is published, other files go to assets/.'
      tags:
      - Files
      parameters:
      - name: site_id
        in: query
        required: false
        description: Site id or name. Required here for a raw application/zip body.
        schema:
          type: string
      - name: dry_run
        in: query
        required: false
        description: 1 = only check the archive, change nothing.
        schema:
          type: string
          enum:
          - '0'
          - '1'
      - name: clear_assets
        in: query
        required: false
        description: 1 = delete current files in assets/ first.
        schema:
          type: string
          enum:
          - '0'
          - '1'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportZipRequest'
            example:
              site_id: 123
              zip_url: https://github.com/user/repo/archive/refs/heads/main.zip
              dry_run: true
          multipart/form-data:
            schema:
              type: object
              required:
              - zip
              properties:
                zip:
                  type: string
                  contentMediaType: application/zip
                  description: The ZIP file.
                site_id:
                  type: string
                dry_run:
                  type: string
                  enum:
                  - '0'
                  - '1'
                clear_assets:
                  type: string
                  enum:
                  - '0'
                  - '1'
          application/zip:
            schema:
              type: string
              contentMediaType: application/zip
      responses:
        '200':
          description: Success.
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  responses:
    VersionConflict:
      description: 'The site changed after expected_version. Nothing was saved: fetch the site again (getSite) and merge.'
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                enum:
                - version_conflict
              message:
                type: string
              current_version:
                type:
                - string
                - 'null'
          example:
            error: version_conflict
            message: Ktoś zapisał stronę po wersji, od której zaczynasz. Pobierz stronę ponownie i scal zmiany.
            current_version: '1792512345678'
    RateLimited:
      description: More than 60 requests per minute.
      headers:
        Retry-After:
          description: Seconds to wait.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Przekroczono limit zapytań (60/min). Spróbuj ponownie za chwilę.
            retry_after: 30
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Nieprawidłowy klucz API.
    BadRequest:
      description: Invalid input, unknown site, limit reached or wrong HTTP method.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Strona nie istnieje lub nie masz do niej dostępu.
    Forbidden:
      description: Account blocked or expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Konto wygasło. Zaloguj się do panelu, aby przedłużyć.
  headers:
    RateLimitRemaining:
      description: Requests left in the current minute.
      schema:
        type: integer
    RateLimitLimit:
      description: Requests allowed per minute.
      schema:
        type: integer
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Human-readable message (Polish).
        success:
          type: boolean
          const: false
        retry_after:
          type: integer
          description: Seconds to wait (429 only).
        site_id:
          type: integer
          description: 'createSite with files: the site was created but files were not published.'
        url:
          type: string
    ImportZipRequest:
      type: object
      required:
      - site_id
      properties:
        site_id:
          oneOf:
          - type: integer
          - type: string
          description: Site id (number) or site name.
        zip_url:
          type: string
          format: uri
          description: Public http/https link to the ZIP. Use this or zip_base64.
        zip_base64:
          type: string
          description: The ZIP as base64. Use this or zip_url.
        clear_assets:
          type: boolean
          default: false
        dry_run:
          type: boolean
          default: false
    Skipped:
      type: array
      items:
        type: object
        properties:
          name:
            type: string
          reason:
            type: string
    PublishFilesRequest:
      type: object
      required:
      - site_id
      - files
      properties:
        site_id:
          oneOf:
          - type: integer
          - type: string
          description: Site id (number) or site name.
        files:
          type: array
          minItems: 1
          maxItems: 300
          items:
            type: object
            required:
            - path
            - content
            additionalProperties: false
            properties:
              path:
                type: string
                description: Path from the site root, e.g. index.html, css/style.css, img/logo.png.
              content:
                type: string
                description: Text content, or base64 when encoding is base64.
              encoding:
                type: string
                enum:
                - utf-8
                - base64
                default: utf-8
        clear_assets:
          type: boolean
          default: false
          description: Delete current files in assets/ first.
        dry_run:
          type: boolean
          default: false
          description: Only report what would be published.
        expected_version:
          type: string
          description: Optional. Version from getSite (field version). If someone saved the site since then, the call returns 409 version_conflict and changes nothing.
    ImportResponse:
      type: object
      required:
      - success
      - url
      - message
      properties:
        success:
          type: boolean
        dry_run:
          type: boolean
        url:
          type: string
        message:
          type: string
        index:
          type: boolean
          description: index.html was (or would be) published.
        files:
          type: integer
        bytes:
          type: integer
        rewritten:
          type: integer
          description: Links fixed to point at assets/.
        overwritten:
          type: integer
        skipped:
          $ref: '#/components/schemas/Skipped'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: hk_ API key
      description: 'API key from Dashboard > API & tools (starts with hk_). Header: Authorization: Bearer hk_...'