openapi: 3.1.0
info:
  title: Knack REST API
  description: >-
    Knack is a no-code database and application platform. The Knack REST API
    exposes record management against application objects and views via
    predictable, resource-oriented URLs. All requests and responses use JSON.
    Authentication uses an Application ID combined with a REST API key, both
    passed in request headers.
  version: v1
  contact:
    name: Knack Developer Support
    url: https://docs.knack.com/reference/introduction-to-the-api
servers:
  - url: https://api.knack.com/v1
    description: Knack production REST API server
security:
  - ApplicationId: []
    RestApiKey: []
tags:
  - name: Object Records
    description: CRUD operations on records via object endpoints
  - name: View Records
    description: Operations on records via page view endpoints
paths:
  /objects/{object_key}/records:
    get:
      operationId: listObjectRecords
      summary: List Object Records
      description: >-
        Retrieve a paginated list of records for a given object. Supports
        filtering, sorting, and pagination via query parameters.
      tags:
        - Object Records
      parameters:
        - name: object_key
          in: path
          required: true
          schema:
            type: string
          description: Object key (for example, object_1)
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
          description: Page number to retrieve
        - name: rows_per_page
          in: query
          required: false
          schema:
            type: integer
            default: 25
          description: Number of records per page
        - name: sort_field
          in: query
          required: false
          schema:
            type: string
          description: Field key to sort by
        - name: sort_order
          in: query
          required: false
          schema:
            type: string
            enum: [asc, desc]
          description: Sort direction
        - name: filters
          in: query
          required: false
          schema:
            type: string
          description: JSON-encoded filter rules
      responses:
        '200':
          description: Successful response with record list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createObjectRecord
      summary: Create Object Record
      description: Create a new record for the specified object.
      tags:
        - Object Records
      parameters:
        - name: object_key
          in: path
          required: true
          schema:
            type: string
          description: Object key (for example, object_1)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecordRequest'
      responses:
        '200':
          description: Record created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Record'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /objects/{object_key}/records/{record_id}:
    get:
      operationId: getObjectRecord
      summary: Get Object Record
      description: Retrieve a single record by identifier from a given object.
      tags:
        - Object Records
      parameters:
        - name: object_key
          in: path
          required: true
          schema:
            type: string
        - name: record_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response with the record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Record'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateObjectRecord
      summary: Update Object Record
      description: Update fields on an existing record by identifier.
      tags:
        - Object Records
      parameters:
        - name: object_key
          in: path
          required: true
          schema:
            type: string
        - name: record_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecordRequest'
      responses:
        '200':
          description: Record updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Record'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteObjectRecord
      summary: Delete Object Record
      description: Delete a record by identifier from a given object.
      tags:
        - Object Records
      parameters:
        - name: object_key
          in: path
          required: true
          schema:
            type: string
        - name: record_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Record deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /pages/{scene_key}/views/{view_key}/records:
    get:
      operationId: listViewRecords
      summary: List View Records
      description: >-
        Retrieve records via a page view. View-based requests honor the
        view's configured filters, columns, and access controls.
      tags:
        - View Records
      parameters:
        - name: scene_key
          in: path
          required: true
          schema:
            type: string
          description: Scene (page) key (for example, scene_1)
        - name: view_key
          in: path
          required: true
          schema:
            type: string
          description: View key (for example, view_1)
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
        - name: rows_per_page
          in: query
          required: false
          schema:
            type: integer
            default: 25
      responses:
        '200':
          description: Successful response with record list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    ApplicationId:
      type: apiKey
      in: header
      name: X-Knack-Application-Id
      description: Knack Application ID identifying the target application
    RestApiKey:
      type: apiKey
      in: header
      name: X-Knack-REST-API-Key
      description: REST API key authorizing the request
  responses:
    Unauthorized:
      description: Missing or invalid Application ID or REST API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
              field:
                type: string
                nullable: true
    Record:
      type: object
      description: A Knack record. Fields are keyed by field IDs (for example, field_1).
      additionalProperties: true
      properties:
        id:
          type: string
    RecordRequest:
      type: object
      description: >-
        Payload to create or update a record. Use field keys (field_X) as
        property names with appropriate values for each field type.
      additionalProperties: true
    RecordListResponse:
      type: object
      properties:
        total_pages:
          type: integer
        current_page:
          type: integer
        total_records:
          type: integer
        records:
          type: array
          items:
            $ref: '#/components/schemas/Record'
    DeleteResponse:
      type: object
      properties:
        delete:
          type: boolean