Kamai Blueprints / Files API

openapi: 3.2.0
info:
  title: Kamai Blueprints / Files API
  description: 'Read construction drawings from your own software. Upload a PDF plan; Kamai reads it and gives you back every room, wall,

    door and window with measurements in metres, every printed word, and every printed table (schedules, legends, revision

    blocks), as JSON. ## Authentication


    Create an API key at Kamai → Settings → API keys and send it on every request:


    ```

    Authorization: Bearer

    ```


    A key acts as the user who created it and sees only that user''s projects. Keep it on your server. A call without a key,

    or with a revoked one, gets `401`. Revoking a key, or a change Kamai makes to its settings, takes effect within 3 minutes. ## Acting for your users


    A partner whose users sign in through it can use any API key to act for those users. The request carries, next to the

    key, `X-Kamai-Partner` (your partner ID, as Kamai gave it to you) and `X-Kamai-Partner-User-Token` (that user''s own token

    from you). Kamai checks the token with you and acts as that user: that user''s projects, that user''s page quota, as if the

    user did it in Kamai. Without the two headers the key acts as its own owner. One header without the other is `400`

    (`partner_id_required`, `partner_user_token_required`). A user who does not exist in Kamai or is disabled gets `403`

    (`act_as_not_allowed`). A key Kamai has tied to one partner always needs both headers and never acts as its owner. What the key may do for a user is set by Kamai on the key:


    | | routes | needs |

    |---|---|---|

    | read | every `GET`, and `POST /v1/blueprints/{blueprint_id}/markups/clip` | the key enabled for partner users |

    | change | create and update projects, upload, update sheets, create and update markups, rename conversations | edit enabled |

    | delete | delete projects, jobs, markups and conversations, cancel jobs | delete enabled, separately from edit |


    A route the key may not use gets `403` (`edit_not_allowed`, `delete_not_allowed`). On every key, not only for partner users, renaming a conversation needs edit enabled and deleting one needs delete enabled; a new key has both off. Replacing a sheet''s features with

    `PUT /v1/blueprints/{blueprint_id}` for a user needs the `revision` you read as `base_revision` (`422`

    `base_revision_required`), and replacing them with none counts as a delete. Conversations work the same way;

    with edit enabled for the key, the assistant may change the user''s drawings and undo that user''s own changes; keys

    without it never write. Uploads count against the user''s own page quota. Kamai keeps the answer of each token check for up to 60 seconds, so a user you disable on your side can still be served

    for that long. ## The usual flow


    1. `POST /v1/blueprints/upload/init` returns a signed URL. 2. `PUT` the PDF to that URL. 3. `POST /v1/blueprints/upload/complete` returns a `job_id`. It starts one job per upload: calling it again with the

    same `file_uuid` returns the same `job_id` (`409` with `Retry-After` while the first call is still running). To send

    another file, start a new upload with `init`. 4. Poll `GET /v1/projects/{project_id}/jobs/{job_id}` every 5–10 s until `status` is final: `SUCCEEDED`, or

    `FAILED` / `CANCELLED` / `ABANDONED`, which end the job; for those, show `error_code` and `error_message`. The PDF check fails a job with `pdf_incomplete` (the file looks cut off or damaged: download or export it again),

    `pdf_filter_unsupported` (Brotli compression, or a PDF that cannot be read) or `pdf_scan_over_budget` (too large or

    complex to check). New `error_code` values can be added over time: treat one you do not know as a failure and show

    its `error_message`. The job record is written when processing starts, not when the upload returns, and when many uploads are queued that

    can take minutes. Until then, a `job_id` you got from an upload answers `404` with `detail` `Job not found`: keep

    polling it. `Project not found` is final. 5. On `SUCCEEDED`, read the sheet with `GET /v1/blueprints/{blueprint_id}`.'
  version: 0.1.0
tags:
- name: Blueprints / Files
  description: 'Signed URLs for every file of a sheet: the original PDF, previews, the vector drawing and map tiles.'
paths:
  /v1/blueprints/{blueprint_id}/files:
    get:
      tags:
      - Blueprints / Files
      summary: Get download links for a sheet's files
      description: Signed URLs for every file artifact of a blueprint, in one response.
      operationId: get_blueprint_file_urls_v1_blueprints__blueprint_id__files_get
      security:
      - HTTPBearer: []
      parameters:
      - name: blueprint_id
        in: path
        required: true
        schema:
          type: string
          title: Blueprint Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlueprintFileUrlsResponse'
              examples:
                real:
                  summary: A sheet with tiles
                  description: Real response shape from a Kamai test account, 2026-10-13. Names, text and ids are illustrative; numbers and structure are as returned. Signatures cut; tiles trimmed to 3.
                  value:
                    blueprint_id: bbbbbbbb-0000-4000-8000-000000000002
                    manifest_version: 1
                    artifact_versions:
                      schema_version: 1
                      revision: '1'
                      legacy_unversioned: true
                      tiles:
                        '0_0_0': '1790000000000011'
                        '1_0_0': '1790000000000012'
                        '1_0_1': '1790000000000013'
                      tile_format: webp
                    window_expires_at: 1791903600
                    refresh_after: 1791900000
                    urls:
                      original_pdf: https://storage.googleapis.com/example-bucket/blueprints/bbbbbbbb-0000-4000-8000-000000000002/original.pdf?X-Goog-Algorithm=…&X-Goog-Signature=…
                      preview_webp: https://storage.googleapis.com/example-bucket/blueprints/bbbbbbbb-0000-4000-8000-000000000002/preview.webp?X-Goog-Algorithm=…&X-Goog-Signature=…
                      scaled_png: https://storage.googleapis.com/example-bucket/blueprints/bbbbbbbb-0000-4000-8000-000000000002/scaled.png?X-Goog-Algorithm=…&X-Goog-Signature=…
                      vector_svg: https://storage.googleapis.com/example-bucket/blueprints/bbbbbbbb-0000-4000-8000-000000000002/vector.svg?X-Goog-Algorithm=…&X-Goog-Signature=…
                      tiles:
                        0.0.0.webp: https://storage.googleapis.com/example-bucket/blueprints/bbbbbbbb-0000-4000-8000-000000000002/tiles/0.0.0.webp?X-Goog-Algorithm=…&X-Goog-Signature=…
                        1.0.0.webp: https://storage.googleapis.com/example-bucket/blueprints/bbbbbbbb-0000-4000-8000-000000000002/tiles/1.0.0.webp?X-Goog-Algorithm=…&X-Goog-Signature=…
                        1.0.1.webp: https://storage.googleapis.com/example-bucket/blueprints/bbbbbbbb-0000-4000-8000-000000000002/tiles/1.0.1.webp?X-Goog-Algorithm=…&X-Goog-Signature=…
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    ArtifactVersions:
      properties:
        schema_version:
          type: integer
          const: 1
          title: Schema Version
        revision:
          anyOf:
          - type: string
            pattern: ^0*[1-9][0-9]*$
          - type: 'null'
          title: Revision
        legacy_unversioned:
          type: boolean
          title: Legacy Unversioned
          default: false
        original_pdf:
          anyOf:
          - type: string
            pattern: ^0*[1-9][0-9]*$
          - type: 'null'
          title: Original Pdf
        preview_webp:
          anyOf:
          - type: string
            pattern: ^0*[1-9][0-9]*$
          - type: 'null'
          title: Preview Webp
        scaled_png:
          anyOf:
          - type: string
            pattern: ^0*[1-9][0-9]*$
          - type: 'null'
          title: Scaled Png
        vector_svg:
          anyOf:
          - type: string
            pattern: ^0*[1-9][0-9]*$
          - type: 'null'
          title: Vector Svg
        tiles:
          anyOf:
          - patternProperties:
              ^(0|[1-9][0-9]*)_(0|[1-9][0-9]*)_(0|[1-9][0-9]*)$:
                type: string
                pattern: ^0*[1-9][0-9]*$
            type: object
          - type: 'null'
          title: Tiles
        tile_format:
          anyOf:
          - type: string
            enum:
            - png
            - webp
          - type: 'null'
          title: Tile Format
      type: object
      required:
      - schema_version
      title: ArtifactVersions
    ArtifactUrls:
      properties:
        original_pdf:
          anyOf:
          - type: string
          - type: 'null'
          title: Original Pdf
        preview_webp:
          anyOf:
          - type: string
          - type: 'null'
          title: Preview Webp
        scaled_png:
          anyOf:
          - type: string
          - type: 'null'
          title: Scaled Png
        vector_svg:
          anyOf:
          - type: string
          - type: 'null'
          title: Vector Svg
        tiles:
          additionalProperties:
            type: string
          type: object
          title: Tiles
          description: Tile name (z.x.y.png, or z.x.y.webp on a sheet whose artifact_versions.tile_format is webp) to signed URL for published tiles. Legacy records use readiness flags and dimensions; an unknown tile may 404.
      type: object
      required:
      - original_pdf
      - preview_webp
      - scaled_png
      - vector_svg
      - tiles
      title: ArtifactUrls
    BlueprintFileUrlsResponse:
      properties:
        blueprint_id:
          type: string
          title: Blueprint Id
        manifest_version:
          type: integer
          const: 1
          title: Manifest Version
          default: 1
        artifact_versions:
          anyOf:
          - $ref: '#/components/schemas/ArtifactVersions'
          - type: 'null'
        window_expires_at:
          type: integer
          title: Window Expires At
          description: Epoch seconds when every URL in this response expires
        refresh_after:
          type: integer
          title: Refresh After
          description: Epoch seconds after which a fresh call returns new URLs
        urls:
          $ref: '#/components/schemas/ArtifactUrls'
      type: object
      required:
      - blueprint_id
      - window_expires_at
      - refresh_after
      - urls
      title: BlueprintFileUrlsResponse
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer