Kamai Turns API

openapi: 3.2.0
info:
  title: Kamai Turns 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: Turns
  description: One message and its answer. Rate an answer.
paths:
  /v1/conversations/{conversation_id}/turns/{turn_id}/feedback:
    post:
      tags:
      - Turns
      summary: Rate an answer
      description: Thumbs up or down on one answer, with an optional comment. A second rating of the same turn replaces the first.
      operationId: rate_turn_v1_conversations__conversation_id__turns__turn_id__feedback_post
      security:
      - HTTPBearer: []
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: string
          title: Conversation Id
      - name: turn_id
        in: path
        required: true
        schema:
          type: string
          title: Turn Id
      - name: X-Kamai-Partner-User-Token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'For partners whose users sign in through them: the partner''s own token for the end user. Kamai verifies it with the partner and acts as that user. Without it the call acts as the API key''s owner.'
          title: X-Kamai-Partner-User-Token
        description: 'For partners whose users sign in through them: the partner''s own token for the end user. Kamai verifies it with the partner and acts as that user. Without it the call acts as the API key''s owner.'
      - name: X-Kamai-Partner
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Your partner ID, as Kamai gave it to you: the partner that issued `X-Kamai-Partner-User-Token`. Required with it.'
          title: X-Kamai-Partner
        description: 'Your partner ID, as Kamai gave it to you: the partner that issued `X-Kamai-Partner-User-Token`. Required with it.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TurnFeedback'
            examples:
              down:
                summary: Thumbs down with a comment
                value:
                  rating: down
                  comment: The count misses the doors on level 2.
      responses:
        '204':
          description: Successful Response
        '400':
          description: 'On a key enabled for partner users: `X-Kamai-Partner` missing (`partner_id_required`) or not valid for this key (`partner_id_invalid`), or `X-Kamai-Partner-User-Token` missing (`partner_user_token_required`).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api__external__v1__conversations__ErrorResponse'
        '401':
          description: No API key, a revoked key (`unauthorized`), or a partner user token the partner rejected (`partner_token_invalid`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api__external__v1__conversations__ErrorResponse'
        '404':
          description: Project, sheet or conversation not found for the acting user (`not_found`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api__external__v1__conversations__ErrorResponse'
        '502':
          description: The assistant or the partner failed to answer (`upstream_error`, `partner_unavailable`). Safe to retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api__external__v1__conversations__ErrorResponse'
        '503':
          description: Chat is not available on this deployment (`chat_unavailable`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api__external__v1__conversations__ErrorResponse'
        '422':
          description: 'A field is invalid: `detail` lists which, or carries `invalid_request`.'
components:
  schemas:
    TurnFeedback:
      properties:
        rating:
          type: string
          enum:
          - up
          - down
          title: Rating
        comment:
          anyOf:
          - type: string
            maxLength: 2000
          - type: 'null'
          title: Comment
      type: object
      required:
      - rating
      title: TurnFeedback
    api__external__v1__conversations__ErrorResponse:
      properties:
        detail:
          additionalProperties: true
          type: object
          title: Detail
          description: '`error` is a stable code; `message` is for people.'
      type: object
      required:
      - detail
      title: ErrorResponse
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer