The Time-Check API provides privacy-preserving calendar availability sharing through a RESTful interface. All sensitive data is encrypted end-to-end, ensuring zero-knowledge architecture where servers cannot access personal calendar information.
Time-Check uses anonymous authentication with cryptographic keys instead of traditional user accounts.
Each client generates a unique anonymous device identifier:
Each availability request uses unique encryption keys:
https://prod.api.time-check.com/api/v1/
https://staging.api.time-check.com/api/v1/
All requests must use JSON content type:
Content-Type: application/json
Required headers for all requests:
Content-Type: application/json
User-Agent: TimeCheck/1.0 (iOS; Device)
Requests include anonymous device ID:
X-Device-ID: 550e8400-e29b-41d4-a716-446655440000
{
"success": true,
"data": {
// Response data
},
"metadata": {
"request_id": "req_123456789",
"timestamp": "2024-01-15T10:30:00Z",
"version": "v1"
}
}
{
"success": false,
"error": {
"code": "INVALID_REQUEST",
"message": "The request is malformed or missing required fields",
"details": {
"field": "email_address",
"reason": "Invalid email format"
}
},
"metadata": {
"request_id": "req_123456789",
"timestamp": "2024-01-15T10:30:00Z",
"version": "v1"
}
}
Rate limit information is included in response headers:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642248600
Submit a request to check someone’s calendar availability.
Endpoint: POST /requests
Request Body:
{
"email_address": "joe@company.com",
"requestor_id": "alex_device_123",
"public_key": "base64_encoded_public_key",
"start_date": "2024-01-15",
"end_date": "2024-01-19",
"time_zone": "America/New_York"
}
Response:
{
"success": true,
"data": {
"request_id": "req_7f8a9b2c3d4e5f6g",
"status": "pending",
"expires_at": "2024-01-16T10:30:00Z",
"estimated_response_time": "2-5 minutes"
}
}
Clients check in to receive pending availability requests.
Endpoint: POST /checkin
Request Body:
{
"device_id": "device_456789",
"capabilities": ["calendar_access"],
"last_checkin": "2024-01-15T10:25:00Z"
}
Response:
{
"success": true,
"data": {
"pending_requests": [
{
"request_id": "req_7f8a9b2c3d4e5f6g",
"encrypted_request": "base64_encoded_encrypted_data",
"public_key": "base64_encoded_public_key",
"priority": "normal"
}
],
"next_checkin": "2024-01-15T10:35:00Z"
}
}
Submit an encrypted availability response for a request.
Endpoint: POST /responses
Request Body:
{
"request_id": "req_7f8a9b2c3d4e5f6g",
"encrypted_response": "base64_encoded_encrypted_availability_data",
"response_hash": "sha256_hash_of_plaintext_response"
}
Response:
{
"success": true,
"data": {
"response_id": "resp_1a2b3c4d5e6f7g8h",
"status": "delivered",
"timestamp": "2024-01-15T10:32:00Z"
}
}
Retrieve the encrypted availability response for a request.
Endpoint: GET /requests/{request_id}/response
Query Parameters:
requestor_id: The original requestor device IDResponse:
{
"success": true,
"data": {
"request_id": "req_7f8a9b2c3d4e5f6g",
"encrypted_response": "base64_encoded_encrypted_availability_data",
"response_hash": "sha256_hash_of_plaintext_response",
"responded_at": "2024-01-15T10:32:00Z",
"expires_at": "2024-02-14T10:32:00Z"
}
}
Check API service health and status.
Endpoint: GET /health
Response:
{
"success": true,
"data": {
"status": "healthy",
"version": "v1.2.3",
"uptime": 86400,
"features": {
"encryption": "enabled",
"rate_limiting": "enabled",
"monitoring": "enabled"
}
}
}
{
"request_id": "string",
"email_address": "string (email)",
"requestor_id": "string (UUID)",
"public_key": "string (base64)",
"start_date": "string (YYYY-MM-DD)",
"end_date": "string (YYYY-MM-DD)",
"time_zone": "string (IANA timezone)",
"status": "pending|processing|completed|expired",
"created_at": "string (ISO 8601)",
"expires_at": "string (ISO 8601)"
}
{
"response_id": "string",
"request_id": "string",
"encrypted_response": "string (base64)",
"response_hash": "string (SHA256)",
"status": "pending|delivered|expired",
"responded_at": "string (ISO 8601)",
"expires_at": "string (ISO 8601)"
}
The decrypted availability response contains a compressed bitmap:
{
"start_date": "2024-01-15",
"end_date": "2024-01-19",
"time_zone": "America/New_York",
"granularity_minutes": 15,
"availability_bitmap": "base64_encoded_compressed_bitmap",
"busy_periods": [
{
"start": "2024-01-15T09:00:00Z",
"end": "2024-01-15T10:30:00Z"
}
]
}
{
"code": "string",
"message": "string",
"details": {
"field": "string",
"reason": "string",
"allowed_values": ["array"]
}
}
package main
import (
"github.com/zoratu/time-check-go-sdk"
)
func main() {
client := timecheck.NewClient("https://prod.api.time-check.com/api/v1/")
request := &timecheck.AvailabilityRequest{
EmailAddress: "joe@company.com",
RequestorID: "alex_device_123",
StartDate: "2024-01-15",
EndDate: "2024-01-19",
TimeZone: "America/New_York",
}
response, err := client.SubmitRequest(request)
if err != nil {
log.Fatal(err)
}
// Wait for response...
availability, err := client.GetResponse(response.RequestID, request.RequestorID)
if err != nil {
log.Fatal(err)
}
// Decrypt and process availability...
}
Note: This API reference covers the Time-Check REST API. For client implementation examples, see our GitHub repository. For iOS-specific integration, see the iOS App documentation.