Skip to main content

API Walkthrough

Learn the fundamentals of using the FormKiQ Document API:

  • Adding and updating documents
  • Retrieving document content
  • Searching documents with tags and metadata

Prerequisites​

  • FormKiQ installation (Quick Start Guide)
  • API access credentials (JWT token, API key, or AWS IAM credentials)
  • API client (Postman recommended)

Postman Public API Network​

Access the FormKiQ API on the Postman Public API network for immediate testing and integration.

Postman JWT Login

Available Collections:

  1. JWT Authentication: Token-based authentication for secure session management
  2. AWS IAM Authentication: AWS Identity and Access Management integration
  3. API Key Authentication: Simple key-based access for testing and development
note

FormKiQ's API uses OpenAPI specification, available in the FormKiQ Core GitHub repository.

Acquire Access Token​

Depending on which Postman collection you want to use, authentication requires either acquiring a JWT token, setting up AWS IAM Authentication, or creating and providing an API Key

More info: API Security Tokens.

Configure Postman​

Find API URLs in CloudFormation Outputs:

FormKiQ API Urls

Configure each collection:

JWT Authentication​

  • Set baseUrl: HttpApiUrl
  • Set token: JWT token from browser

FormKiQ API Urls

IAM Authentication​

  • Set baseUrl: IamApiUrl
  • Set awsRegion: Your installation region
  • Set AWS credentials

FormKiQ API Urls

API Key Authentication​

  • Set baseUrl: KeyApiUrl
  • Set apiKey: Generated API key

FormKiQ API Urls

Working with Documents via the API​

Document Metadata Options​

FormKiQ provides two ways to add custom metadata to documents:

  1. Attributes (Recommended)

    • Structured metadata with defined types
    • Must be created at site level first
    • Supports validation and complex data types
    • Enhanced search capabilities

  2. Tags (Legacy)

    • Simple key-value pairs
    • No predefined structure
    • Limited search capabilities
For simplicity, we will work with tags during this walkthrough.

Add Document​

Use the Add new Document API under Documents:

Add Document API

Request fields:

FieldDescription
pathDocument name/path
contentTypeMedia type
isBase64Base64 encoding flag
contentDocument content
tagsDocument tags (legacy)

Example request:

{
  "path": "test.txt",
  "contentType": "text/plain",
  "isBase64": false,
  "content": "This is sample data file",
  "tags": [
    {
      "key": "category",
      "value": "sample"
    }
  ]
}
note

Maximum content size: 5MB For larger files (up to 5GB), use Add Document Upload

Get Document Metadata​

Use Get Document API with document ID:

Postman Get Document

Update Document​

Modify content, tags, or metadata using Update Document API:

Postman Update Document

Example update:

{
  "contentType": "text/plain",
  "content": "Updated content",
  "tags": [
    {
      "key": "status",
      "value": "updated"
    }
  ]
}

Search Documents​

Use Document Search API for tag and metadata queries:

Postman Update Document

Example searches:

Tag search:

{
  "query": {
    "tag": {
      "key": "category",
      "value": "sample"
    }
  }
}

Text search (requires Typesense):

{
  "query": {
    "text": "Lorem ipsum dolor"
  }
}

Next Steps​