Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ptshen/timeful-plus/llms.txt

Use this file to discover all available pages before exploring further.

The Timeful backend exposes a REST API rooted at /api. The server is built with Go and the Gin web framework, and it runs on port 3002 by default (overridable via the PORT environment variable). Interactive documentation is available at /swagger/index.html whenever the backend is running.

​
Base URL

All API endpoints live under the /api prefix: 
http://localhost:3002/api
ResourceExample path
Events/api/events
Auth/api/auth/sign-in
User/api/user/profile
Folders/api/user/folders

​
Authentication

Timeful uses session-based authentication via cookies. Signing in through /api/auth/sign-in sets an encrypted session cookie; subsequent requests from the same browser or HTTP client automatically include that cookie. Routes that require authentication are protected by the middleware.AuthRequired() middleware, which responds with 401 when no valid session is present. See the Authentication page for a full walkthrough.

​
Content-Type

All request bodies must be sent as JSON: 
Content-Type: application/json

​
HTTP Methods

The API uses standard HTTP methods:
MethodTypical use
GETRetrieve a resource
POSTCreate a resource or trigger action
PUTReplace a resource entirely
PATCHPartially update a resource
DELETERemove a resource

​
Health Check

A lightweight health endpoint requires no authentication and is suitable for container health checks (Railway, Docker, etc.): 
GET /api/health
Response 200 OK: 
{ "status": "ok" }

​
Response Format

Successful responses return JSON objects or arrays: 
{ "eventId": "64b3f1a2c9e77f001234abcd", "shortId": "abc123" }

​
Error Format

All errors follow a consistent shape: 
{ "error": "event-not-found" }
Common error strings (defined in errs/errors.go):
StringMeaning
not-signed-inRequest requires authentication
user-does-not-existSession references a deleted account
event-not-foundEvent ID does not match any record
user-not-event-ownerCaller does not own the event
invalid-credentialsApple calendar credentials rejected

​
Swagger UI

When the backend is running locally, the full OpenAPI specification is browsable at: 
http://localhost:3002/swagger/index.html

​
CORS

CORS is configured in main.go. The following origins are always allowed:
  • http://localhost:3002
  • http://localhost:8080
Additional origins can be added at runtime via the CORS_ALLOWED_ORIGINS environment variable (comma-separated). When that variable is not set, the default Timeful production domains (timeful.app, schej.it) are also permitted. Allowed methods: GET, POST, PATCH, PUT, DELETE
Allowed headers: Content-Type
Exposed headers: Content-Length
Credentials: true (required for cookie-based sessions)

​
Endpoint Groups

Events

Create, fetch, edit, respond to, and delete availability polls.

User

Profile management, calendar accounts, and event listings.

Folders

Organize events into named folders with optional color labels.

Auth Endpoints

Sign in (web & mobile), sign out, and session status.

Build docs developers (and LLMs) love

Get started for freeTalk to us