Fetching Data

Basic Concepts

Once you have the authentication token from Creating an App, you're ready to interact with the API. Here are some key points to remember:

Base URL

The base URL for all API requests is: https://app.kinabase.com/api/v1/

Format

The request body should always be a valid JSON object.

Security

All requests must be made over HTTPS.

Authentication

All requests must include the following headers:

{
  "Content-Type": "application/json",
  "Accept": "application/json",
  "Authorization": "Bearer {your-token-here}"
}

Pagination

The API supports pagination for endpoints that return multiple records. Use query parameters to control which records are returned:

Query Parameters

• pageIndex – Zero-indexed page number (default: 0)
• pageSize – Number of records per page (default: 10, maximum: 300)
• updatedAfter – ISO 8601 timestamp to filter records modified after a specific date
• includeLists – Set to true to include related records/lists

Example Paginated Request

GET /api/v1/collections/my-collection?pageIndex=0&pageSize=50

Paginated Response

{
  "records": [...],
  "totalRecords": 1500,
  "pageIndex": 0,
  "pageSize": 50
}

Use totalRecords and pageSize to calculate how many pages are available, then increment pageIndex to fetch subsequent pages.

Fetching All Records

For large datasets (up to 100,000 records), use the /all endpoint which returns records in chunks:

GET /api/v1/collections/my-collection/all

Rate Limits and Batch Operations

Page Size Limits

• Default page size: 10 records
• Maximum page size: 300 records

Batch Operation Limits

For bulk add, update, and delete operations, the maximum batch size is 300 records per request.

Chunked Fetch Limit

The /all endpoint supports fetching up to 100,000 records in a single request.

Error Handling

If an error occurs, the API will return a JSON object with an error message:

{
  "error": "Error message describing the issue"
}

Common HTTP Status Codes

• 200 OK – Successful request
• 400 Bad Request – Invalid parameters, validation error, or limit exceeded
• 401 Unauthorized – Invalid or missing token
• 404 Not Found – Resource not found (collection, record, etc.)
• 500 Internal Server Error – Server-side error

Common Error Messages

• Collection not found
• Record not found
• Invalid App ID or Secret
• API not enabled for this tenant
• Invalid date format. Please use ISO 8601 format.
• Bulk action request size limit of 300 exceeded
• Record page size limit of 300 exceeded

Troubleshooting

If you encounter issues, here are some common troubleshooting steps:

Field Naming Convention

Field names are converted to camelCase. For example, a field labelled "Job Title" in the UI should be passed as jobTitle in API requests.

Case Sensitivity

Field names are case-sensitive. If you use Name instead of name, the request will fail with a 400 Bad Request.

Collection Identifier

You can identify a collection either by its id (UUID) or its slug (e.g., purchase-orders). The slug is the URL-friendly version of the collection name.

To find a collection's ID or slug, make a GET request to /collections and look for the id or slug property.

Date Format

When filtering by date (e.g., updatedAfter), use ISO 8601 format: 2024-01-15T10:30:00Z

Next Steps

Explore the API Reference for the complete list of available endpoints and their parameters, or view the Data Models to understand the structure of API requests and responses.