Knack Object Records API

openapi: 3.1.0
info:
  title: Knack REST Object Records 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
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'
components:
  schemas:
    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
    Record:
      type: object
      description: A Knack record. Fields are keyed by field IDs (for example, field_1).
      additionalProperties: true
      properties:
        id:
          type: string
    DeleteResponse:
      type: object
      properties:
        delete:
          type: boolean
    RecordListResponse:
      type: object
      properties:
        total_pages:
          type: integer
        current_page:
          type: integer
        total_records:
          type: integer
        records:
          type: array
          items:
            $ref: '#/components/schemas/Record'
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
              field:
                type: string
                nullable: true
  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'
  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