Hoshin Kanri Sharing API

openapi: 3.2.0
info:
  title: Hoshin Kanri Sharing API
  version: 0.9.0
  description: 'Beta: operations and fields may still change. Covers the operations the Hoshin MCP server uses. For an AI agent, prefer MCP at https://hoshin.app/mcp. An admin creates a token from the API tokens link in the app header. Error messages are in English; rely on the `error` code.'
servers:
- url: https://hoshin.app
tags:
- name: Sharing
paths:
  /api/matrices/{id}/shares:
    get:
      operationId: listShares
      tags:
      - Sharing
      summary: List the public links of a matrix
      description: Refused to a read-only token.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShareList'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: createShare
      tags:
      - Sharing
      summary: Publish a matrix on a public read-only link
      description: Anyone holding the link can read the matrix. At most 10 active links per matrix. Refused to a read-only token.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                label:
                  type:
                  - string
                  - 'null'
                  maxLength: 200
                expiresInDays:
                  type:
                  - integer
                  - 'null'
                  minimum: 1
                  maximum: 365
                hideFigures:
                  type: boolean
                  description: 'true: the page shows no value, target, unit or external link, only the structure. Internal elements are never shown either way.'
                fullSheets:
                  type: boolean
                  description: 'true: the initiative pages of this link show the full sheet (owner, sponsor, who does the next action, blockers, the sentence behind the health; resources only with figures). For a trusted audience. Default false.'
      security:
      - bearerAuth: []
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShareCreated'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/matrices/{id}/shares/{shareId}:
    delete:
      operationId: revokeShare
      tags:
      - Sharing
      summary: Revoke a public link
      description: Refused to a read-only token.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: shareId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShareRevoked'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Stable machine-readable code, among them UNAUTHORIZED, FORBIDDEN, MATRIX_EDIT_RESTRICTED, DEFAULT_MATRIX_ADMIN_ONLY, NOT_FOUND, INVALID_ID, VALIDATION_ERROR, EMPTY_UPDATE, NOT_ADJACENT, TOO_MANY_SHARES.
        message:
          type: string
        issues:
          type: array
          items:
            type: object
            additionalProperties: {}
          description: Invalid fields, on VALIDATION_ERROR.
      required:
      - error
    ShareList:
      type: object
      properties:
        shares:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              tokenPreview:
                type: string
              label:
                type:
                - string
                - 'null'
              active:
                type: boolean
              createdAt:
                type: string
                format: date-time
              expiresAt:
                type:
                - string
                - 'null'
                format: date-time
              revokedAt:
                type:
                - string
                - 'null'
                format: date-time
              lastAccessedAt:
                type:
                - string
                - 'null'
                format: date-time
              accessCount:
                type: integer
              createdBy:
                type:
                - string
                - 'null'
              hideFigures:
                type: boolean
              fullSheets:
                type: boolean
            required:
            - id
            - tokenPreview
            - label
            - active
            - createdAt
            - expiresAt
            - revokedAt
            - lastAccessedAt
            - accessCount
            - createdBy
            - hideFigures
            - fullSheets
      required:
      - shares
    ShareRevoked:
      type: object
      properties:
        revoked:
          type: boolean
          enum:
          - true
        id:
          type: string
          format: uuid
      required:
      - revoked
      - id
    ShareCreated:
      type: object
      properties:
        id:
          type: string
          format: uuid
        url:
          type: string
          description: Public read-only link, shown once.
        tokenPreview:
          type: string
        label:
          type:
          - string
          - 'null'
        expiresAt:
          type:
          - string
          - 'null'
          format: date-time
        hideFigures:
          type: boolean
        fullSheets:
          type: boolean
        hiddenElements:
          type: integer
          description: Internal elements left off the page.
        matrixName:
          type: string
        note:
          type: string
      required:
      - id
      - url
      - tokenPreview
      - label
      - expiresAt
      - hideFigures
      - fullSheets
      - hiddenElements
      - matrixName
      - note
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'An API token, hk_..., or an OAuth 2.1 access token. OAuth needs PKCE S256 and a registered client: https://hoshin.app/.well-known/oauth-authorization-server'