Skip to main content
The Flowtask REST API gives you programmatic access to tasks, projects, tags, and user operations. All communication is over HTTPS, all request and response bodies are JSON, and every data request requires an active session established through the authentication endpoints.

​
Base URL

All API endpoints are relative to your Flowtask instance URL: 
https://your-flowtask-instance.com/api
Replace your-flowtask-instance.com with the domain of your Flowtask deployment. Every path in this documentation is shown relative to this base URL — for example, /v2/todo maps to https://your-flowtask-instance.com/api/v2/todo.

​
API Versions

Flowtask’s API is split across two versions, each responsible for a distinct set of resources:
VersionScope
v1Authentication and user operations — sign-up, sign-in, session check (GET /api/v1/auth-check), and logout
v2Data operations — tasks, projects, and tags
Use v2 for all task, project, and tag operations. The v1 prefix covers all authentication flows documented in Authentication, including the session-check endpoint GET /api/v1/auth-check.

​
Request Format

All request bodies must be JSON. Set the Content-Type header on any request that includes a body: 
Content-Type: application/json
Every request to a protected endpoint must also include your session cookie. After you sign in, the cookie is set automatically in browser environments. For non-browser clients, capture the Set-Cookie header from the sign-in response and forward it on all subsequent requests.

​
Response Format

All responses are JSON. A successful response returns either the requested resource object or an array of resources. Error responses follow a consistent shape: 
{
  "message": "A human-readable description of the error"
}
Some error responses may include additional fields alongside message to give more context about what went wrong.

​
Error Codes

HTTP StatusMeaning
200 / 201Success
400Bad request — check your request body for missing or invalid fields
401Unauthorized — you are not signed in or your session has expired
403Forbidden — you do not have access to this resource
404Not found — the requested resource does not exist
429Too many requests — you have been rate limited
500Internal server error — something went wrong on our end

​
Example Request

The following example fetches your task list using the browser fetch API. Notice credentials: 'include' — this is required on every request so the session cookie is sent automatically. 
const response = await fetch('https://your-instance.com/api/v2/todo', {
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' }
});
const tasks = await response.json();
All API requests must include your session cookie. Authenticate first using POST /api/v1/user/signin, then include credentials: 'include' (or your cookie jar) on all subsequent requests.