---
url: /api/examples.md
description: >-
  End-to-end API walkthroughs — authentication, task management, recurring
  tasks, and common workflows.
---

# API Examples

Complete walkthroughs using `curl`. All examples use `https://api.hule-do.com/api` as the base URL.

***

## 1. Register and get tokens

```bash
# Request signup
curl -X POST https://api.hule-do.com/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "alex@example.com", "password": "mySecret123", "name": "Alex"}'
# → 201, confirmation email sent

# Confirm with token from email
curl -X POST https://api.hule-do.com/api/auth/register/confirm \
  -H "Content-Type: application/json" \
  -d '{"token": "abc123def456..."}'
# → 200 { "accessToken": "...", "refreshToken": "...", "user": { ... } }
```

Save the tokens:

```bash
ACCESS_TOKEN="eyJhbGciOiJ..."
REFRESH_TOKEN="dGhpcyBpcyB..."
```

***

## 2. Login (existing user)

```bash
curl -X POST https://api.hule-do.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "alex@example.com", "password": "mySecret123"}'
```

***

## 3. Refresh an expired access token

```bash
curl -X POST https://api.hule-do.com/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d "{\"refreshToken\": \"$REFRESH_TOKEN\"}"
# → { "accessToken": "...", "refreshToken": "..." }
# Update your variables with the new tokens
```

***

## 4. List workspaces

```bash
curl https://api.hule-do.com/api/me/workspaces \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

***

## 5. Create a space

```bash
curl -X POST "https://api.hule-do.com/api/workspaces/$WORKSPACE_ID/spaces" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Engineering"}'
```

***

## 6. Create a task

```bash
curl -X POST "https://api.hule-do.com/api/workspaces/$WORKSPACE_ID/tasks" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Implement user onboarding flow",
    "listId": "667f...",
    "priority": "high",
    "dueDate": "2026-06-10T00:00:00.000Z"
  }'
```

Save the returned task ID:

```bash
TASK_ID="667f..."
```

***

## 7. Search tasks

```bash
curl "https://api.hule-do.com/api/workspaces/$WORKSPACE_ID/tasks/search?q=onboarding&page=1&limit=10" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

***

## 8. Query tasks with filters

```bash
# Tasks assigned to a specific user, grouped by priority
curl "https://api.hule-do.com/api/workspaces/$WORKSPACE_ID/tasks/query?assigneeId=$USER_ID&groupBy=priority" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

***

## 9. Change task status (move it)

```bash
curl -X PATCH "https://api.hule-do.com/api/workspaces/$WORKSPACE_ID/tasks/$TASK_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"statusId": "667f..."}'
```

Find available statuses from the list's status template.

***

## 10. Move task to another list

```bash
curl -X POST "https://api.hule-do.com/api/workspaces/$WORKSPACE_ID/tasks/$TASK_ID/move" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"listId": "667f..."}'
```

***

## 11. Create a recurring task series

```bash
curl -X POST "https://api.hule-do.com/api/workspaces/$WORKSPACE_ID/recurring-tasks" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Daily standup",
    "listId": "667f...",
    "interval": {
      "frequency": "day",
      "every": 1,
      "timeOfDay": "09:00",
      "timezone": "Europe/London"
    },
    "endCondition": {
      "type": "never"
    }
  }'
```

***

## 12. Skip the next occurrence

```bash
curl -X POST "https://api.hule-do.com/api/workspaces/$WORKSPACE_ID/recurring-tasks/$JOB_ID/skip" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

***

## 13. Edit a single instance ("this" mode)

```bash
curl -X POST "https://api.hule-do.com/api/workspaces/$WORKSPACE_ID/recurring-tasks/$JOB_ID/instances/$TASK_ID/edit-mode" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "this",
    "updates": {
      "title": "Sprint retro (rescheduled)"
    }
  }'
```

***

## 14. Export your data (GDPR)

```bash
curl https://api.hule-do.com/api/account/export \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

***

## 15. Delete account

```bash
curl -X DELETE https://api.hule-do.com/api/auth/me \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"password": "mySecret123"}'
```

***

## Error handling example

```bash
curl -X POST https://api.hule-do.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "not-an-email", "password": ""}'
# → 400
# {
#   "error": "ValidationError",
#   "issues": [
#     { "path": "email", "message": "email must be a valid email address" },
#     { "path": "password", "message": "password must be at least 8 characters" }
#   ]
# }
```

***

## Common patterns

### Pagination

All list endpoints support `page` and `limit` query parameters:

```bash
curl "https://api.hule-do.com/api/workspaces/$WORKSPACE_ID/tasks/query?page=2&limit=50" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

**Note:** `limit` is clamped server-side to a maximum value (default 100).

### Token lifecycle

1. Login/register → get `accessToken` + `refreshToken`.
2. Use `accessToken` for all requests (it expires in ~15 minutes).
3. When you get a `401`, call `/auth/refresh` with the current `refreshToken`.
4. Update both tokens from the response.
5. If the refresh also fails, the user needs to log in again.

## Related

* [API — Authentication](/api/auth) — all auth endpoints.
* [API — Tasks](/api/tasks) — task CRUD reference.
* [API — Recurring tasks](/api/recurring-tasks) — recurring job reference.