Quickstart
The API is part of Pro and Lifetime (and the 14-day trial). Create a token in Settings → Data → Personal API, keep it in an environment variable, and add your first task. Needt schedules it into free time and returns it with its slot.
export NEEDT_TOKEN="needt_…"curl -X POST https://use.needt.app/api/connect/tasks \
-H "Authorization: Bearer $NEEDT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"title": "Send the August report",
"estimatedMinutes": 30,
"deadline": "2026-10-16T17:00:00Z",
"priorityLevel": "HIGH"
}'Authentication
Every request carries your personal token as a bearer header. Tokens act as you, in your workspace, with your plan’s limits. Revoke them in the same settings screen.
Authorization: Bearer needt_…Endpoints
Base URL: https://use.needt.app/api/connect. Requests and responses are JSON; times are ISO 8601.
| Method | Path | What it does |
|---|---|---|
| GET | /tasks | List your tasks. |
| POST | /tasks | Create a task and schedule it. Returns 201 with the task. |
| GET | /schedule | Read the current schedule. |
| POST | /schedule | Run the scheduler over open tasks, then return the schedule. |
| POST | /reschedule | Re-plan after a change. Returns { "tasks": [...] }. |
| POST | /control | Projects, task updates, calendars and events, by action. |
Tasks
Fields for POST /tasks. Only title is required.
| Field | Type | Notes |
|---|---|---|
title | string | Required. |
description | string | Notes, Markdown welcome. |
estimatedMinutes | number | How long it takes. Used to find a slot. |
deadline | string | ISO 8601. Also used as the due date. |
priorityLevel | enum | LOW, MEDIUM, HIGH, URGENT |
energyRequired | enum | LOW, MEDIUM, HIGH — matched to your energy curve. |
contextTag | string | Free label, e.g. calls or errands. |
curl https://use.needt.app/api/connect/tasks -H "Authorization: Bearer $NEEDT_TOKEN"Schedule
curl -X POST https://use.needt.app/api/connect/schedule -H "Authorization: Bearer $NEEDT_TOKEN"curl -X POST https://use.needt.app/api/connect/reschedule -H "Authorization: Bearer $NEEDT_TOKEN"Control
One endpoint, many actions. Start with overview to see projects, calendars and ids.
| action | Fields |
|---|---|
overview | — |
create_project | name, description, color |
update_project | id + fields to change |
update_task · complete_task | id (+ fields, incl. projectId) |
create_calendar | name |
create_event · update_event | feedId, title, start, end (update: id) |
delete_task · delete_project · delete_event · delete_calendar | id and "confirm": true |
curl -X POST https://use.needt.app/api/connect/control \
-H "Authorization: Bearer $NEEDT_TOKEN" -H "Content-Type: application/json" \
-d '{ "action": "complete_task", "id": "tsk_…" }'Errors
400— a required field is missing; the body says which:{ "error": "title is required" }.401— no token, a wrong one, or a revoked one.- Plan limits apply as in the app: on Free, auto-scheduling stops at 15 tasks a month.
Apple Shortcuts
- New shortcut → Ask for Input (Text, “What needs doing?”).
- Add Get Contents of URL: URL
https://use.needt.app/api/connect/tasks, Method POST. - Headers:
Authorization=Bearer needt_…. Request Body JSON:title= Provided Input,estimatedMinutes= 30. - Name it “Add to Needt”. Now “Hey Siri, add to Needt” works on iPhone, Watch and Mac.
n8n, Zapier, Make
Every automation tool has a generic HTTP step. Point it at POST https://use.needt.app/api/connect/tasks with the bearer header and map your fields to title, description and deadline.
- n8n — HTTP Request node, Authentication Generic → Header Auth, body JSON.
- Zapier — Webhooks by Zapier → Custom Request, method POST, data as JSON.
- Make — HTTP → Make a request, body type Raw / JSON.
