openapi: 3.2.0
info:
  title: Huddlekit Projects API
  version: 1.0.0
  summary: Read and create feedback comments, change their status and subscribe to comment webhooks.
  description: The Huddlekit REST API reads a workspace's projects, web apps, documents and comments, creates comments, changes a comment's status and manages webhook subscriptions.
  termsOfService: https://huddlekit.com/terms
  contact:
    name: Huddlekit
    email: hello@huddlekit.com
    url: https://huddlekit.com
servers:
- url: https://app.huddlekit.com/api/v1
  description: Production
security:
- apiKey: []
tags:
- name: Projects
  description: Website projects, web apps and documents that comments are attached to.
paths:
  /projects:
    get:
      operationId: listProjects
      tags:
      - Projects
      summary: List everything comments can be attached to
      description: Lists every website project, web app and document in the workspace. Each item's `id` and `surface` are what `listComments` and `createComment` take as `parent_id` and `surface`. Not paginated. Requires the `read` scope.
      responses:
        '200':
          description: All projects, web apps and documents.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListProjectsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  schemas:
    ListProjectsResponse:
      type: object
      required:
      - projects
      properties:
        projects:
          type: array
          description: Every website project, web app and document in the workspace, in that order, each group newest first. Not paginated.
          items:
            $ref: '#/components/schemas/Project'
      example:
        projects:
        - id: 0d3c7a52-9e61-4f0b-8a2d-5b7e1c4f9a36
          name: Acme marketing site
          url: https://acme.example
          created_at: '2026-09-01T09:30:00.000Z'
          surface: website
        - id: 4e8b1d6a-2c7f-4b3e-9d1a-6f5c0e8b2a74
          name: Brand guidelines.pdf
          url: null
          created_at: '2026-08-20T14:02:11.000Z'
          surface: document
    Project:
      type: object
      description: 'Something comments can be attached to: a website project, a web app or a document.'
      required:
      - id
      - name
      - url
      - created_at
      - surface
      properties:
        id:
          type: string
          format: uuid
          description: Parent id. Pass it as `parent_id` (with the same `surface`) to list or create comments.
        name:
          type: string
          description: Display name.
        url:
          type:
          - string
          - 'null'
          description: Base URL of the website or web app. Always null for documents; may be null for a web app.
        created_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When it was created.
        surface:
          $ref: '#/components/schemas/Surface'
    PlanRequiredError:
      type: object
      description: Returned with 403 when the key's workspace is not on a plan that includes API access.
      required:
      - error
      - requiredPlans
      properties:
        error:
          type: string
          description: Human-readable message naming the required plan.
        requiredPlans:
          type: array
          description: Plan ids that include API access.
          items:
            type: string
      example:
        error: This feature requires the Team plan.
        requiredPlans:
        - team
    Surface:
      type: string
      enum:
      - website
      - webapp
      - document
      description: 'What a comment is attached to. `website`: a website project (the parent is a project). `webapp`: a web app that runs the Huddlekit SDK widget (the parent is a web app). `document`: an uploaded PDF, image or video (the parent is a document).'
    Error:
      type: object
      description: Error body returned by every failed call.
      required:
      - error
      properties:
        error:
          type: string
          description: Short, human-readable error message.
        detail:
          type: string
          description: Extra explanation, when there is one.
      example:
        error: Unauthorized
        detail: Invalid or revoked API key
  responses:
    Forbidden:
      description: The key lacks the scope this call needs (`{"error":"Forbidden","detail":"This key lacks the \"read\" scope"}`), or the workspace has no active Team subscription (body includes `requiredPlans`).
      content:
        application/json:
          schema:
            anyOf:
            - $ref: '#/components/schemas/PlanRequiredError'
            - $ref: '#/components/schemas/Error'
          example:
            error: This feature requires the Team plan.
            requiredPlans:
            - team
    Unauthorized:
      description: No API key, a malformed `Authorization` header, or an invalid, revoked or expired key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Unauthorized
            detail: 'Send your key as: Authorization: Bearer hk_live_…'
    ServiceUnavailable:
      description: A temporary failure, such as the API key, the workspace plan or the parent record could not be checked. Safe to retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Could not verify the workspace plan
    TooManyRequests:
      description: 'Rate limit exceeded. Limits: 200 reads and 30 writes per minute per API key, counted per endpoint group (`/me`, `/projects`, `/comments`, `/comments/{id}`, `/hooks`, `/events/recent`) and separately for reads and writes; `DELETE /hooks/{id}` counts toward the `/hooks` writes. Refused calls count too. Wait the number of seconds in `Retry-After`, then retry.'
      headers:
        Retry-After:
          description: Whole seconds until the limit resets (at least 1).
          schema:
            type: integer
            minimum: 1
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Too many requests
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: hk_live_ + 64 hex characters
      description: 'Workspace API key, created in the Huddlekit app and shown once. Send it as `Authorization: Bearer hk_live_<64 lowercase hex characters>`. The key identifies the workspace; there is no user session. GET calls need the `read` scope; POST, PATCH and DELETE calls need `write`.'
externalDocs:
  description: REST API guide
  url: https://huddlekit.com/support/using-the-rest-api