churchtools-api
Apply when making API calls to ChurchTools, using churchtoolsClient methods, handling API responses, or working with Tags API. Covers correct HTTP method names, parameter structure, and response handling patterns.
When & Why to Use This Skill
This Claude skill provides standardized patterns and best practices for integrating with the ChurchTools API. It ensures developers use correct HTTP method naming conventions, proper parameter structures, and specific data handling logic for the Tags API to prevent common integration errors and improve code reliability.
Use Cases
- Case 1: Implementing DELETE operations correctly by using the specific 'deleteApi' method instead of the standard 'delete' method to avoid runtime exceptions.
- Case 2: Structuring API requests with direct parameter passing to ensure compatibility with ChurchTools endpoints, avoiding the common mistake of nesting parameters in a 'params' object.
- Case 3: Managing Tags API interactions by correctly handling direct array responses and ensuring all mandatory fields like 'description' and 'color' are provided during updates.
- Case 4: Standardizing error handling and loading states across a ChurchTools-based application using the recommended try-catch-finally boilerplate.
| name | churchtools-api |
|---|---|
| description | Apply when making API calls to ChurchTools, using churchtoolsClient methods, handling API responses, or working with Tags API. Covers correct HTTP method names, parameter structure, and response handling patterns. |
ChurchTools API Patterns
Client HTTP Methods
Use the correct method names - delete is NOT available:
churchtoolsClient.get() // GET requests
churchtoolsClient.post() // POST requests
churchtoolsClient.put() // PUT requests
churchtoolsClient.deleteApi() // DELETE requests - NOT .delete()!
churchtoolsClient.patch() // PATCH requests
Parameter Structure
Pass parameters directly as the second argument, NOT nested in a "params" object:
// Correct
churchtoolsClient.get('/api/endpoint', { param1: 'value1', param2: 'value2' })
// Wrong - will fail
churchtoolsClient.get('/api/endpoint', { params: { param1: 'value1' } })
Tags API
The Tags API returns data directly as an array, not nested in a "data" property:
// Correct
const response = await churchtoolsClient.get<Tag[]>('/tags/person')
const tags = Array.isArray(response) ? response : []
// Wrong - response.data is undefined
const tags = response.data
Supported tag domains: 'person' | 'song' | 'group' (NOT 'appointment')
Tag updates require ALL fields:
const tagData = {
name: tag.name,
description: tag.description || '', // Required, use empty string
color: tag.color || 'basic' // Required, use default color
}
await churchtoolsClient.put(`/tags/${tagId}`, tagData)
API Documentation
Check your ChurchTools instance OpenAPI spec at /system/runtime/swagger/openapi.json for correct endpoints, methods, and schemas.
Standard API Pattern
try {
loading.value = true
const response = await churchtoolsClient.get('/api/endpoint', {
param1: 'value1',
param2: 'value2'
})
// Handle response
} catch (err) {
error.value = 'Error message'
console.error('API Error:', err)
} finally {
loading.value = false
}