openapi: 3.0.3
info:
  title: Height APP Activities Field Templates API
  description: "Unofficial Open API 3.1 specification for [Height App API](https://www.notion.so/API-documentation-643aea5bf01742de9232e5971cb4afda). This is not affiliated with Height team.\n\n---\n# Authentication\n\nThe Height API uses API keys to authenticate requests. **You can view your API key in the Height settings under API**.\n\nAuthentication to the API is performed via the `Authorization` header. All API requests should be made over HTTPs.\n\ni.e. Get your workspace.\n\n```bash\ncurl https://api.height.app/workspace \\\n  -H \"Authorization: api-key secret_1234\"\n```\n\nThird-party applications must connect to the Height API using [OAuth2](https://www.notion.so/API-documentation-643aea5bf01742de9232e5971cb4afda). \n\nSee [OAuth Apps on Height](https://www.notion.so/OAuth-Apps-on-Height-a8ebeab3f3f047e3857bd8ce60c2f640) for more information.\n\n# Object formats\n\nAll objects have a unique `id` ([UUID v4](https://en.m.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random))) and a `model` attribute to distinguish the model type.\n\ne.g. a task object.\n\n```json\n{\n  \"id\": \"123e4567-e89b-12d3-a456-426655440000\",\n  \"model\": \"task\",\n  \"name\": \"Fix bug\",\n  \"index\": 1,\n  \"status\": \"backLog\",\n  [...]\n}\n```\n\n# Date formats\n\nEvery date uses the ISO format e.g.\n\n```js\n\"2019-11-07T17:00:00.000Z\"\n```\n\n# Real-time\n\nAny change that you make to the API will be pushed to every user in real-time: i.e. creating tasks or messages.\n\n# Rate limits\n\nTo keep incoming traffic under control and maintain a great experience for all our users, our API is behind a rate limiter. Users who send many requests in quick succession may see error responses that show up as status code 429.\n\nHeight allows up to 120 requests/min, but we have stricter limits on these endpoints:\n\n- `POST /activities`: 60 requests/min\n- `POST /tasks`: 60 requests/min"
  contact:
    email: gil@beomjun.kr
  license:
    name: MIT
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
servers:
- url: https://api.height.app
security:
- apiKey: []
tags:
- name: Field Templates
paths:
  /fieldTemplates:
    get:
      tags:
      - Field Templates
      summary: List all field templates
      operationId: listAllFieldTemplates
      x-codeSamples:
      - lang: JavaScript
        label: SDK
        source: 'const height = new Height({secretKey: ''secret_your-key''});


          height.fieldTemplates.all();'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAllFieldTemplatesResponse'
  /fieldTemplates/:id/options:
    post:
      tags:
      - Field Templates
      summary: Create an option for a field template
      description: This endpoint adds an option to a `select` or `labels` field template.
      operationId: createFieldTemplateOption
      x-codeSamples:
      - lang: JavaScript
        label: SDK
        source: 'const height = new Height({secretKey: ''secret_your-key''});


          height.fieldTemplates.createOption({...});'
      parameters:
      - name: id
        in: path
        description: field template id (UUID)
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFieldTemplateOptionRequest'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldTemplateObject'
  /fieldTemplates/:id/options/:optionId:
    put:
      tags:
      - Field Templates
      summary: Update or delete an option for a field template
      operationId: updateFieldTemplateOption
      x-codeSamples:
      - lang: JavaScript
        label: SDK
        source: 'const height = new Height({secretKey: ''secret_your-key''});


          height.fieldTemplates.updateOption({...});'
      description: 'This endpoint updates or deletes an option to a `select` or `labels` field template.


        The field template must be unlocked to use this endpoint.  Locking and unlocking field templates is an enterprise feature.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: optionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFieldTemplateOptionRequest'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldTemplateObject'
components:
  schemas:
    UpdateFieldTemplateOptionRequest:
      type: object
      required:
      - value
      properties:
        value:
          type: string
        hue:
          type: number
          description: number between 0 and 360 (optional)
        deleted:
          type: boolean
    ListAllFieldTemplatesResponse:
      type: object
      required:
      - list
      properties:
        list:
          type: array
          items:
            $ref: '#/components/schemas/FieldTemplateObject'
    CreateFieldTemplateOptionRequest:
      type: object
      required:
      - value
      properties:
        value:
          type: string
        hue:
          type: number
          description: number between 0 and 360 (optional)
    FieldTemplateObject:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique id of the field template.
        model:
          type: string
          enum:
          - fieldTemplate
          description: The model is always `fieldTemplate`.
        name:
          type: string
          description: The name of the field template.
        type:
          type: string
          description: 'Possible types:


            - `text`: any text value attribute (i.e. Story Points)

            - `labels`: used for tags for example

            - `select`: used for priority, sprint,…

            - `date`: used for due date,…

            - `linkedTasks`: usually used for dependencies and so on

            - `status`: the status attribute (only one field template of that type)'
          enum:
          - text
          - labels
          - select
          - date
          - linkedTasks
          - status
        labelSets:
          type: array
          description: An array of label sets, only available when the type of the field template is `status`.
          items:
            type: object
            required:
            - id
            - model
            - value
            properties:
              id:
                type: string
                format: uuid
                description: The unique id of the field label set.
              model:
                type: string
                enum:
                - fieldLabelSet
                description: The model is always `fieldLabelSet`.
              value:
                type: string
                description: The name of the field label set.
        labels:
          type: array
          description: Only available when the type of the field template is `labels`, `select` or `status`.
          items:
            type: object
            required:
            - id
            - model
            - value
            - hue
            - statusState
            properties:
              id:
                type: string
                description: UUID or string (backLog, inProgress and done are hard-coded).
              model:
                type: string
                enum:
                - fieldLabel
                description: The model is always `fieldLabel`.
              value:
                type: string
                description: The name of the label.
              hue:
                type: number
                description: The hue of the label's color (between 0 and 360).
              labelSetId:
                type: string
                format: uuid
                description: The id of the label set this label belongs to, if any. Only if the type of field template is `status`.
              statusState:
                type: string
                description: 'The state of the status, only available when the type of the field template is `status`.

                  Note that a task is considered as completed if its status has a state of `canceled` or `completed`.'
                enum:
                - default
                - started
                - blocked
                - canceled
                - completed
        archive:
          type: boolean
          description: This attribute has been archived.
      required:
      - id
      - model
      - name
      - type
      - archive
  securitySchemes:
    apiKey:
      type: apiKey
      name: Authorization
      description: "The Height API uses API keys to authenticate requests. **You can view your API key in the Height settings under API**.\n ex: `api-key secret_1234`"
      in: header
externalDocs:
  description: Height official API Docs
  url: https://www.notion.so/API-documentation-643aea5bf01742de9232e5971cb4afda