Tasks API
The Tasks API allows you to create, read, and manage tasks programmatically. Tasks are the core unit of work on the Tewdy platform.
Endpoints
| Method | Path | Scope | Description |
|---|---|---|---|
POST | /tasks | tasks:write | Create a new task |
GET | /tasks | tasks:read | List your tasks |
GET | /tasks/explore | — | Browse public tasks |
GET | /tasks/me/status | tasks:read | Get tasks by status |
GET | /tasks/me/created | tasks:read | Get tasks you created |
GET | /tasks/:id | — | Get a specific task |
DELETE | /tasks/:id | tasks:write | Delete a task |
Create a Task
POST /api/v1/tasksCreates a new task. Requires tasks:write scope.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
title | string | Yes | Task title (max 200 chars) |
description | string | Yes | Task description |
budget | number | Yes | Budget amount (min 0) |
currency | string | Yes | Currency code (e.g. EUR, USD) |
location | object | Yes | Location object (see below) |
requirement | string | Yes | Requirements for task completion |
dueDate | string | No | ISO 8601 date string |
maxPeople | number | No | Maximum number of people (default 1) |
Location Object
| Field | Type | Required | Description |
|---|---|---|---|
coordinates | number[] | Yes | [longitude, latitude] |
type | string | Yes | city, country, world, radius |
name | string | Yes | Display name |
countryCode | string | No | ISO country code |
radiusKm | number | No | Radius in km (required if type is radius, 1-500) |
Example
curl -X POST https://api.tewdy.com/api/v1/tasks \
-H "X-API-Key: tewdy_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"title": "Help me move furniture",
"description": "Need help moving a couch and bookshelf to a new apartment",
"budget": 50,
"currency": "EUR",
"location": {
"coordinates": [6.1319, 49.6116],
"type": "city",
"name": "Luxembourg City",
"countryCode": "LU"
},
"requirement": "Must have a car or van"
}'Response 201
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"title": "Help me move furniture",
"description": "Need help moving a couch and bookshelf to a new apartment",
"budget": 50,
"currency": "EUR",
"status": "published",
"createdAt": "2026-03-01T12:00:00.000Z"
}List Tasks
GET /api/v1/tasksReturns tasks for the authenticated user. Requires tasks:read scope.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
limit | number | Results per page (default 20, max 50) |
cursor | string | Pagination cursor from previous response |
search | string | Search title and description |
payment | string | Filter: Pro-bono or Paid |
Example
curl "https://api.tewdy.com/api/v1/tasks?limit=10" \
-H "X-API-Key: tewdy_your_api_key_here"Response 200
[
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"title": "Help me move furniture",
"budget": 50,
"currency": "EUR",
"status": "published",
"createdAt": "2026-03-01T12:00:00.000Z"
}
]Browse Public Tasks
GET /api/v1/tasks/exploreBrowse publicly listed tasks. No authentication required.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
limit | number | Results per page (default 20, max 50) |
cursor | string | Pagination cursor |
search | string | Search title and description |
payment | string | Filter: Pro-bono or Paid |
regionName | string | Filter by region name |
latitude | number | Latitude for geographic filtering |
longitude | number | Longitude for geographic filtering |
radiusKm | number | Radius in km for geographic filtering |
cityName | string | Filter by city |
countryCode | string | Filter by country |
Example
curl "https://api.tewdy.com/api/v1/tasks/explore?cityName=Luxembourg&countryCode=LU&limit=5"Get Tasks by Status
GET /api/v1/tasks/me/statusReturns the authenticated user’s tasks filtered by status. Requires tasks:read scope.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
status | string | published or completed |
limit | number | Results per page |
page | number | Page number |
Example
curl "https://api.tewdy.com/api/v1/tasks/me/status?status=published" \
-H "X-API-Key: tewdy_your_api_key_here"Get Tasks You Created
GET /api/v1/tasks/me/createdReturns all tasks created by the authenticated user. Requires tasks:read scope.
Example
curl "https://api.tewdy.com/api/v1/tasks/me/created" \
-H "X-API-Key: tewdy_your_api_key_here"Get a Specific Task
GET /api/v1/tasks/:idReturns a single task by ID. No authentication required for published tasks.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | Task UUID |
Example
curl "https://api.tewdy.com/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890"Response 200
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"title": "Help me move furniture",
"description": "Need help moving a couch and bookshelf to a new apartment",
"budget": 50,
"currency": "EUR",
"status": "published",
"authorFirstName": "John",
"authorProfilePic": "https://...",
"images": [],
"cities": ["Luxembourg City"],
"createdAt": "2026-03-01T12:00:00.000Z"
}Delete a Task
DELETE /api/v1/tasks/:idSoft-deletes a task. You can only delete tasks you created. Requires tasks:write scope.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | Task UUID |
Example
curl -X DELETE "https://api.tewdy.com/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
-H "X-API-Key: tewdy_your_api_key_here"Response 200
{
"message": "Task deleted successfully"
}Error Responses
| Status | Code | Description |
|---|---|---|
401 | TOKEN_MISSING | No API key or JWT provided |
401 | API_KEY_INVALID | Invalid or expired API key |
403 | SCOPE_INSUFFICIENT | API key lacks required scope |
404 | NOT_FOUND | Task not found |