Kora V3 API Documentation

Kora is an open source, web based digital repository platform designed for cultural heritage institutions, projects, and scholars interested in cataloging, curating, managing, preserving, sharing, and displaying digital objects and associated metadata. Kora allows users to build digital repository projects around a variety of digitized and born-digital objects, such as documents, images, audio, video, and 3D models. Beyond digital objects, Kora also allows users to include non-material culture entities, such as events or people, in their digital repository project. Kora’s architecture and user experience is centered around providing an unprecedented level of flexibility in a project's metadata structure. This flexibility allows users to create multiple forms for managing records, each with their own robust structure and metadata scheme. This flexibility allows institutions, projects, and individual scholars to customize Kora to meet the unique needs of their particular project or collection.

Kora is designed for distributed record creation and management among multiple collaborators. Users can work on the same project from anywhere in the world as long as they have access to the web. Each project in a Kora installation includes granular control over user permissions. Project administrators aren’t locked into specific types of users with fixed permissions. Instead, they can flexibly create different types of user permission groups to meet the needs of their project and collaborators. Users can be added and removed from those permission groups as the needs of the project dictates.

A single installation of Kora can support any number of discreet digital repository projects, thereby making it a perfect solution for institutions and individuals looking for a single solution to support a variety of digital collections. While each project in a Kora installation is a silo with its own users and records, users can search across all projects for which they have access within an installation. This makes Kora a perfect solution for institutions interested in managing separate collections or projects under the same institutional umbrella. In addition, the Kora API can be used to display records (including searching and browsing) in a public facing website from across multiple projects in one Kora installation.

In order to support data portability and project workflows, Kora includes powerful import and export tools. Records (object + metadata) can be imported as XML, JSON, and CSV and exported as XML or JSON individually or in a batch. In keeping with the need to ensure authenticity and integrity of uploaded and imported files, Kora automatically generates fixity information on all ingested files, which can be used to verify that files are free from tampering and corruption.

The Kora V3 API provides developers with programmatic access to projects, forms, fields, and records, making it possible to integrate Kora into external applications, automate data workflows, and build custom tools on top of its infrastructure.

This enhanced documentation merges the official V3 reference with clarifying details and examples from earlier drafts to support external developers in learning and using the API effectively.

📘 Full user documentation: Kora Documentation
💻 Official repository: matrix-msu/kora

Kora 3 is a flexible, open-source platform designed for managing complex digital collections and research data. It enables projects to model, store, and search information in highly customizable ways. The Kora V3 API provides developers with programmatic access to projects, forms, fields, and records, making it possible to integrate Kora into external applications, automate data workflows, and build custom tools on top of its infrastructure.

This enhanced documentation merges the official V3 reference with clarifying details and examples from earlier drafts to support external developers in learning and using the API effectively.

Base URL

{YOUR_KORA_URL}/{API_FUNCTION_URI}

GET Functions

Get Kora Version

Request Type: GET
URI: api/version
Purpose: Returns the version number of the Kora installation.

Get Project Forms

Request Type: GET
URI: api/projects/{project_id}/forms
Purpose: Lists forms in a project, including Form ID, name, and description.

Get Form Fields

Request Type: GET
URI: api/projects/{project_id}/forms/{form_id}/fields
Purpose: Lists fields in a given form, including their configurations.

Get Form Record Count

Request Type: GET
URI: api/projects/{project_id}/forms/{form_id}/recordCount
Purpose: Returns the number of records in a form.

POST Functions

Create Form

Request Type: POST
URI: api/projects/{project_id}/forms/create
Parameters:
- bearer_token: Kora auth token with CREATE permissions
- form: JSON form data

Edit Field Options

Request Type: PUT
URI: api/projects/{project_id}/forms/{form_id}/fields
Parameters:
- bearer_token: Kora auth token with EDIT permissions
- fields: JSON structure of fields to modify

Create Record

Request Type: POST
URI: api/create
Parameters:
- bearer_token: Kora auth token with CREATE permissions
- form: Form ID or internal name
- fields: JSON record data (see Import Example)
- zip_file (optional): Zip file with associated files

Import Example

[
 {
  "Text":"Your text value",
  "Rich Text":"Your <b>rich</b> text value",
  "Integer":"3",
  "Float":"3.21",
  "List":"List value",
  "Multi Select List":["List value","Another value"],
  "Generated List":["List value","Another value"],
  "Date":"2012-12-21",
  "DateTime":"2012-12-21 11:11:11",
  "Historical Date": { 
   "prefix":"circa",
   "year":"2012",
   "month":"12",
   "day":"21",
   "era":"CE"
  },
  "Boolean": 1,
  "Geolocator":[
   {
    "geometry":{
     "location":{"lat":42.7314094,"lng":-84.476258}
    },
    "description":"Matrix",
    "formatted_address":"288 Farm Ln, East Lansing, MI 48823"
   }
  ],
  "File Field":[
   {
    "name":"filename.ext",
    "caption":"Caption to explain file"
   }
  ],
  "Associator":["1-23-4","5-67-8","9-10-11"],
  "reverseAssociations": {
   "Outside Associator": ["1-3-77","1-3-78"]
  }
 }
]

Update Record

Request Type: PUT
URI: api/edit
Parameters:
- _method: Must be "put"
- bearer_token: Kora auth token with EDIT permissions
- form: Form ID or internal name
- kid: Record ID to update
- fields: JSON record data (see Import Example)
- zip_file (optional): Zip file with files

Delete Record

Request Type: DELETE
URI: api/delete
Parameters:
- _method: Must be "delete"
- bearer_token: Kora auth token with DELETE permissions
- form: Form ID or internal name
- kids: Array of record IDs to delete

Search Functions

Record Search

Request Type: POST
URI: api/search
Purpose: Search for records in Kora.

Parameters

forms: JSON search definition (can contain multiple searches)
format: (optional, default: JSON, options: JSON, KORA_OLD, XML)
merge: (optional) Merge fields from multiple searches
sort: (optional) Sort results by fields or metadata
index: (optional) Start index for results
count: (optional) Number of results to return

Form Search Structure

[
  {
    "bearer_token": "XXXXXXXXXXXXXXXXXXXXXX",
    "form": 37,
    "data": true,
    "meta": true,
    "size": false,
    "return_fields": ["field1","field2"],
    "assoc": false,
    "assoc_fields": ["fieldA"],
    "reverse_assoc": true,
    "sort": [{"field1": "ASC"}],
    "index": 0,
    "count": 25,
    "filters": true,
    "filter_count": 5,
    "filter_fields": ["field1"],
    "queries": [
      {"search":"keyword","key_words":["example"],"key_method":"AND"}
    ],
    "logic": {"and":[0]}
  }
]

Advanced Search Query Structure

Common Parameters

negative: (default: false) Invert query results for this field
empty: (default: false) Match records where no data exists

Field-Specific Parameters

Text Field: {"input":"string","partial":false}
Rich Text Field: {"input":"string"}
Integer Field: {"left":0,"right":10,"invert":false}
Float Field: {"left":0.1,"right":3.5,"invert":false}
List Field: {"input":"List option"}
Multi Select List Field: {"input":["opt1","opt2"]}
Generated List Field: {"input":["opt1","opt2"]}
Combo List Field: { "Subfield": {"input":"value"} }
Date Field: { "begin_year":2000,"end_year":2025 }
Date Time Field: { "begin_year":2000,"end_year":2025,"begin_hour":0,"end_hour":23 }
Historical Date Field: { "begin_year":100,"end_year":500,"begin_era":"CE","end_era":"BCE" }
Boolean Field: { "input":true }
Geolocator Field: { "lat":42.73,"lng":-84.47,"range":500 }
Associator Field: { "input":["1-1-0","1-1-1"],"any":false }

API Helper Functions

Form Search Builder

Generates JSON for record searches.

Parameters:

fid: Form ID
token: Auth token
flags: Array of flags (data, meta, size, assoc, reverse_assoc, filters, real_names)
fields: Array of field IDs to return
sort: Sort fields
queries: Query arrays
qLogic: Logic array
index: Start index
count: Number of records
filterCount: Minimum threshold for filters
filterFields: Fields included in filters
assocFields: Fields included for associated records

Keyword Query Builder

keyString: Keywords
method: AND/OR/EXACT
not: Boolean
flids: Fields to search
customWildCards: Boolean

KID Query Builder

kids: IDs
not: Boolean
legacy: Boolean

Advanced Query Builder

advData: Parameters (see Advanced Search)
not: Boolean

Query Logic Builder

Combines queries with operators.

Parameters:

queryObj1: Query index or logic array
operator: Comparison operator
queryObj2: Query index or logic array

Error Handling

Typical HTTP errors:

400: Bad request
401: Unauthorized
403: Forbidden
404: Not found
409: Conflict
429: Rate limit
500: Server error

Error response format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Detail about what went wrong",
    "fields": {"name":"Must not be empty"},
    "request_id": "req_12345"
  }
}

Changelog

v3.0.0 — Current version, updated API functions and enhanced search structures
v2.x — Legacy references merged for clarity

Contributing

Contributions to improve Kora or its documentation are welcome!
If you’d like to contribute, please:

Fork the official Kora repository
Create a feature branch (git checkout -b feature/YourFeature)
Commit your changes (git commit -m 'Add some feature')
Push to the branch (git push origin feature/YourFeature)
Open a Pull Request

Please make sure to follow coding standards and add/update documentation as needed.

License

Kora is released under the MIT License.
You are free to use, modify, and distribute this software in accordance with the license terms.

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
LICENSE		LICENSE
README.md		README.md

License

watrall/kora3-api-documentation

Folders and files

Latest commit

History

Repository files navigation

Kora V3 API Documentation

Table of Contents

Base URL

GET Functions

Get Kora Version

Get Project Forms

Get Form Fields

Get Form Record Count

POST Functions

Create Form

Edit Field Options

Create Record

Import Example

Update Record

Delete Record

Search Functions

Record Search

Parameters

Form Search Structure

Advanced Search Query Structure

Common Parameters

Field-Specific Parameters

API Helper Functions

Form Search Builder

Keyword Query Builder

KID Query Builder

Advanced Query Builder

Query Logic Builder

Error Handling

Changelog

Contributing

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Packages