Developer API Documentation

Access your Fruitask data programmatically with our REST API.

Quick Start

1. Generate an API Key

Go to Account Settings and create an API key with the permissions you need.

2. Create a Workspace Token

In your workspace settings, go to the API tab and create a workspace token.

3. Make API Requests

Use your API key in the X-API-Key header and include the workspace token in the URL.

Base URL

https://integrations.fruitask.com/

Authentication

All API requests require two authentication components:

API Key (Header)

Include your API key in the X-API-Key header.

X-API-Key: fk_xxxxxxxxxxxx

Workspace Token (URL)

Include the workspace token in the URL path.

https://integrations.fruitask.com/{table_name}/{workspace_token}/rows

Security Note: Never expose your API keys or workspace tokens in client-side code. Always make API calls from your server.

Rate Limiting

Read requests100 requests/minute

Write/Delete requests30 requests/minute

Rate limit information is included in response headers:

X-RateLimit-Limit - Maximum requests allowed
X-RateLimit-Remaining - Requests remaining
X-RateLimit-Reset - Unix timestamp when limit resets

API Endpoints

GET/workspace/{token}/info

Get workspace information including storage usage and limits.

GET/workspace/{token}/tables

List all tables in the workspace with their columns.

GET/{table_name}/{token}/info

Get table schema including all column definitions.

GET/{table_name}/{token}/rows

Get all rows with pagination.

Query Parameters:

pagePage number (default: 1)

limitRows per page (default: 50, max: 200)

includeChildrenInclude child table data (true/false)

GET/{table_name}/{token}/rows/{row_id}

Get a specific row by ID or row number. Add ?includeChildren=true to include child data.

POST/{table_name}/{token}/rows

Create a new row. Pass cell values in the request body.

PUT/{table_name}/{token}/rows/{row_id}

Update a row. Only include the cells you want to update.

GET/{table_name}/{token}/rows/{row_id}/cells/{column_id}

Get a specific cell value. Column can be ID or name.

PUT/{table_name}/{token}/rows/{row_id}/cells/{column_id}

Update a specific cell value.

{ "value": "new value" }

DELETE/{table_name}/{token}/rows/{row_id}

Delete a specific row by ID or row number.

GET/{table_name}/{token}/search

Search for rows containing a value.

Query Parameters:

qSearch query (required)

columnColumn to search (optional, searches all if not provided)

pagePage number for results

limitResults per page (max: 200)

Deprecated Endpoint

This endpoint is provided for backward compatibility with the legacy Fruitask API. Not recommended for new integrations. Use the standard /{table_name}/{token}/rows endpoint instead.

GET/{table_name}/{token}/deprecated-rowsLegacy

Get all rows in the legacy Fruitask format. Returns a flat array where each row is an object with column names as keys and cell values as values.

Calendar API Endpoints

Manage calendar events programmatically. Calendar endpoints use the same authentication (API Key + Workspace Token) as table endpoints.

Note: Calendars are user-scoped, not workspace-scoped. The workspace_token in the URL is used for authentication only. These endpoints return all calendars the authenticated user has access to, regardless of workspace. You can find a calendar's ID in its Settings → General tab.

GET/calendar/{workspace_token}/calendars

List all calendars the authenticated user has access to.

GET/calendar/{workspace_token}/{calendar_id}/events

Get events from a calendar. Supports date range filtering and recurring event expansion.

Query Parameters:

startStart date ISO string (e.g. 2026-03-01T00:00:00Z)

endEnd date ISO string (e.g. 2026-03-31T23:59:59Z)

categoryIdFilter events by category ID

POST/calendar/{workspace_token}/{calendar_id}/events

Create a new calendar event.

PUT/calendar/{workspace_token}/{calendar_id}/events/{event_id}

Update an existing event. Only include the fields you want to change.

DELETE/calendar/{workspace_token}/{calendar_id}/events/{event_id}

Delete a calendar event.

Query Parameters (for recurring events):

scopeall (default), single, or future

instanceDateRequired when scope is future (ISO date string)

Knowledge Base API Endpoints

Chat with your workspace's AI Knowledge Base programmatically. Use these endpoints to integrate Fruitask's RAG-powered AI chat into your own applications.

Prerequisites: The AI Knowledge Base plugin must be installed on your workspace and you must have at least one document embedded before you can use the chat endpoint.

GET/knowledge/{workspace_token}/status

Check the knowledge base status, including whether it's available and how many documents are embedded.

POST/knowledge/{workspace_token}/chat

Send a message to chat with your knowledge base. The AI uses RAG (Retrieval Augmented Generation) to answer based on your embedded documents.

Request Body:

messageRequired. The question or message to send (max 2000 characters)

historyOptional array of previous messages for context: [{ role: "user"|"assistant", content: "..." }]

Webhook Notification API

Push notifications into Fruitask from any external service. This endpoint only requires an API Key — no workspace token needed.

Authentication: Only the X-API-Key header is required. The notification is sent to the API key owner's account.

POST/notify

Create an in-app notification for the API key owner. Use this to integrate external services, CI/CD pipelines, monitoring tools, or any webhook-based system.

Request Body:

titleRequired. Notification title (max 200 characters)

messageOptional. Notification body text (max 500 characters)

urlOptional. Action URL the user can click to view details

metadataOptional. Arbitrary JSON object for extra data

Error Codes

400Bad Request - Invalid parameters or missing required fields

401Unauthorized - Invalid or missing API key/workspace token

403Forbidden - Insufficient permissions

404Not Found - Resource does not exist

429Too Many Requests - Rate limit exceeded

500Internal Server Error - Server-side error

Code Examples

# Get all rows from a table
curl -X GET 'https://integrations.fruitask.com//Tasks/wt_your_token/rows?page=1&limit=50' \
  -H 'X-API-Key: fk_your_api_key'

# Create a new row
curl -X POST 'https://integrations.fruitask.com//Tasks/wt_your_token/rows' \
  -H 'X-API-Key: fk_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{"cells": {"Name": "New Task", "Status": "Pending"}}'

# Update a cell
curl -X PUT 'https://integrations.fruitask.com//Tasks/wt_your_token/rows/1/cells/Status' \
  -H 'X-API-Key: fk_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{"value": "Completed"}'

# --- Calendar API ---

# List calendars
curl -X GET 'https://integrations.fruitask.com//calendar/wt_your_token/calendars' \
  -H 'X-API-Key: fk_your_api_key'

# Get events by date range
curl -X GET 'https://integrations.fruitask.com//calendar/wt_your_token/CALENDAR_ID/events?start=2026-03-01T00:00:00Z&end=2026-03-31T23:59:59Z' \
  -H 'X-API-Key: fk_your_api_key'

# Create a calendar event
curl -X POST 'https://integrations.fruitask.com//calendar/wt_your_token/CALENDAR_ID/events' \
  -H 'X-API-Key: fk_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{"title": "Team Meeting", "startDate": "2026-03-10T14:00:00Z", "endDate": "2026-03-10T15:00:00Z"}'

# Delete a calendar event
curl -X DELETE 'https://integrations.fruitask.com//calendar/wt_your_token/CALENDAR_ID/events/EVENT_ID' \
  -H 'X-API-Key: fk_your_api_key'

# --- Knowledge Base API ---

# Check KB status
curl -X GET 'https://integrations.fruitask.com//knowledge/wt_your_token/status' \
  -H 'X-API-Key: fk_your_api_key'

# Chat with knowledge base
curl -X POST 'https://integrations.fruitask.com//knowledge/wt_your_token/chat' \
  -H 'X-API-Key: fk_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{"message": "What is the return policy?", "history": []}'  

# --- Webhook Notification API ---

# Send a notification (no workspace token needed)
curl -X POST 'https://integrations.fruitask.com//notify' \
  -H 'X-API-Key: fk_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{"title": "Build Complete", "message": "Build #42 deployed.", "url": "https://ci.example.com/42"}'