Timill Platform Documentation

REST API

REST API reference for Timill Platform including all endpoints and request/response formats.

REST API reference for Timill Platform including all endpoints and request/response formats.

Base URL#

https://your-domain.com/api/v1

Authentication#

All endpoints require JWT authentication except public endpoints:

Authorization: Bearer <token>

Endpoints#

Instance-admin endpoints (/api/v1/admin/...) — listing every group on the instance and managing manual Plus subscriptions — live on a separate, scope-gated surface, documented for instance admins inside your own instance at /docs/api-reference/admin-rest-api/.

Authentication#

MethodEndpointDescription
POST/auth/loginLogin with email/password
POST/auth/logoutLogout
POST/auth/refreshRefresh token
POST/auth/forgot-passwordRequest password reset
POST/auth/reset-passwordReset password
GET/auth/googleGoogle OAuth redirect
GET/auth/google/callbackGoogle OAuth callback

Users#

MethodEndpointDescription
GET/users/meGet current user
PUT/users/meUpdate current user
GET/usersList users (admin)
GET/users/:idGet user by ID
PUT/users/:idUpdate user (admin)
DELETE/users/:idDelete user (admin)

Groups#

MethodEndpointDescription
GET/groupsList groups
POST/groupsCreate group
GET/groups/:idGet group
PUT/groups/:idUpdate group
DELETE/groups/:idDelete group
GET/groups/:id/membersGet group members
POST/groups/:id/membersAdd member
DELETE/groups/:id/members/:userIdRemove member

Items#

MethodEndpointDescription
GET/groups/:groupId/itemsList items
POST/groups/:groupId/itemsCreate item
GET/groups/:groupId/items/:idGet item
PUT/groups/:groupId/items/:idUpdate item
DELETE/groups/:groupId/items/:idDelete item

Item Types#

MethodEndpointDescription
GET/groups/:groupId/item-typesList item types
POST/groups/:groupId/item-typesCreate item type
GET/groups/:groupId/item-types/:idGet item type
PUT/groups/:groupId/item-types/:idUpdate item type
DELETE/groups/:groupId/item-types/:idDelete item type

Scripts#

MethodEndpointDescription
GET/groups/:groupId/scriptsList scripts
POST/groups/:groupId/scriptsCreate script
GET/groups/:groupId/scripts/:idGet script
PUT/groups/:groupId/scripts/:idUpdate script
DELETE/groups/:groupId/scripts/:idDelete script
POST/groups/:groupId/scripts/:id/runRun script manually

Pages#

MethodEndpointDescription
GET/groups/:groupId/pagesList pages
POST/groups/:groupId/pagesCreate page
GET/groups/:groupId/pages/:idGet page
PUT/groups/:groupId/pages/:idUpdate page
DELETE/groups/:groupId/pages/:idDelete page

Forms#

MethodEndpointDescription
GET/groups/:groupId/formsList forms
POST/groups/:groupId/formsCreate form
GET/groups/:groupId/forms/:idGet form
PUT/groups/:groupId/forms/:idUpdate form
POST/forms/:id/submitSubmit form

Comments#

MethodEndpointDescription
GET/groups/:groupId/items/:itemId/commentsList comments
POST/groups/:groupId/items/:itemId/commentsAdd comment
DELETE/groups/:groupId/items/:itemId/comments/:idDelete comment

Query Parameters#

Pagination#

ParameterDescriptionDefault
pagePage number1
per_pageItems per page20

Filtering#

ParameterDescriptionExample
queryTimill query syntaxtype:task status:open
sortSort fieldcreatedDate:desc
fieldsFields to includetitle,status,assignee

Request Format#

Creating Resources#

{
    "title": "New Item",
    "description": "Item description",
    "status": "open",
    "assignee": "userId123",
    "customFields": {
        "priority": "high",
        "estimate": 8
    }
}

Updating Resources#

{
    "status": "in-progress",
    "assignee": "userId456"
}

Response Format#

Single Resource#

{
    "id": "item-uuid",
    "groupId": "group-uuid",
    "title": "New Item",
    "status": "open",
    "assignee": "userId123",
    "createdAt": "2026-04-19T12:00:00Z",
    "updatedAt": "2026-04-19T12:00:00Z"
}

List Response#

{
    "data": [...],
    "meta": {
        "page": 1,
        "perPage": 20,
        "total": 100,
        "totalPages": 5
    }
}

Error Handling#

Error Response#

{
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "Invalid input",
        "details": [
            {
                "field": "title",
                "message": "Title is required"
            }
        ]
    }
}

HTTP Status Codes#

CodeDescription
200Success
201Created
400Bad Request
401Unauthorized
403Forbidden
404Not Found
422Validation Error
429Rate Limited
500Internal Server Error

Rate Limiting#

LevelLimit
Per user100 requests/minute
Per IP1000 requests/minute
SSE connections10 per user

Webhooks#

Configuring Webhooks#

POST /groups/:groupId/webhooks
Content-Type: application/json

{
    "url": "https://your-app.com/webhook",
    "events": ["item.created", "item.updated"],
    "secret": "webhook-secret"
}

Webhook Payload#

{
    "event": "item.created",
    "timestamp": "2026-04-19T12:00:00Z",
    "data": { ... }
}

Verifying Signatures#

const crypto = require('crypto');
const signature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

SDK Examples#

JavaScript#

const response = await fetch('/api/v1/items', {
    method: 'POST',
    headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        title: 'New Item',
        status: 'open'
    })
});

cURL#

curl -X POST https://your-domain.com/api/v1/items \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"title": "New Item", "status": "open"}'

See also: