API Overview

The Softly API is a Rails 8.1 JSON API. All endpoints are namespaced under /api/v1.

Base URL

https://api.softly.app/api/v1

For local development:

http://localhost:3000/api/v1

Authentication

Most endpoints require a JWT access token in the Authorization header:

Authorization: Bearer <access_token>

Tokens are obtained via the signup or login endpoints. Access tokens expire after 1 hour and can be refreshed using the refresh endpoint.

Error Format

Errors follow a consistent format:

{
  "error": "Human-readable error message"
}

Validation errors return an array:

{
  "errors": ["Email has already been taken", "Password is too short"]
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created
204	No Content (successful delete)
400	Bad Request (missing required params)
401	Unauthorized (invalid or expired token)
403	Forbidden (tier limit reached)
404	Not Found
422	Unprocessable Entity (validation failed)
503	Service Unavailable (external service down)

Common Parameters

Several endpoints accept a user_date parameter (format: YYYY-MM-DD) representing the user's local date. This ensures timezone-correct filtering for due dates, overdue detection, and AI date parsing.

Pagination

Pagination is not yet implemented. All list endpoints return the full result set. This will be added when task volumes warrant it.

Health Check

GET /up

Returns 200 if the app is running. Used by load balancers.