Vectal Public API v1

API Documentation

Your tasks, projects, notes, and habits are open to AI agents through one REST API. It is free on every plan.

1.Authentication

All API requests require a Vectal API key. Generate one from Settings → API Keys inside the app.

Pass your key in the Authorization header:

curl -H "Authorization: Bearer vec-YOUR_API_KEY" \
  https://api.vectal.ai/api/v1/tasks

API keys use the format vec-{uuid}. Keep them secret. They grant full access to the account.

2.Base URL

https://api.vectal.ai/api/v1

All endpoints are prefixed with /api/v1. Responses are JSON.

3.Tasks

GET

/api/v1/tasks

List all tasks. Supports ?project_id, ?status, ?limit filters.

GET

/api/v1/tasks/{task_id}

Get a single task by ID.

POST

/api/v1/tasks

Create a new task.

PATCH

/api/v1/tasks/{task_id}

Update a task. Only send fields you want to change.

DELETE

/api/v1/tasks/{task_id}

Archive (soft-delete) a task.

POST

/api/v1/tasks/{task_id}/complete

Complete a task. Handles recurring tasks automatically.

POST

/api/v1/tasks/batch

Up to 500 creates, updates, completes and deletes in one all-or-nothing call. Counts as one request.

Create a task

curl -X POST https://api.vectal.ai/api/v1/tasks \
  -H "Authorization: Bearer vec-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Review pull request",
    "importance": 80,
    "due_date": "2026-03-20T09:00:00Z",
    "context": "Review the auth refactor PR before release",
    "project_id": "optional-project-uuid"
  }'

Task fields

Field	Type	Description
name	string	Task name (required)
importance	int	Priority 1-100 (higher = more important)
due_date	string	ISO 8601 datetime
context	string	Description or notes
project_id	string	Assign to a project
status	string	active, completed, archived
kanban_column	string	to-do, in-progress, testing, completed
recurrence_text	string	e.g. "daily", "weekly", "every monday", "every 3 days"
timezone	string	IANA timezone, e.g. "America/New_York"

4.Projects

GET

/api/v1/projects

List all projects. Supports ?status filter.

GET

/api/v1/projects/{project_id}

Get a single project by ID.

POST

/api/v1/projects

Create a new project.

PATCH

/api/v1/projects/{project_id}

Update a project.

DELETE

/api/v1/projects/{project_id}

Archive a project.

Project fields

Field	Type	Description
name	string	Project name (required)
description	string	Short project description
color	string	Project color for display
context	string	Project context (max 16,000 chars)
status	string	active, archived

5.Notes

GET

/api/v1/notes

List all active notes.

GET

/api/v1/notes/{note_id}

Get a single note by ID.

POST

/api/v1/notes

Create a new note.

PATCH

/api/v1/notes/{note_id}

Update a note.

DELETE

/api/v1/notes/{note_id}

Soft-delete a note.

Note fields

Field	Type	Description
name	string	Note title (required)
context	string	Note content (supports markdown)
importance	int	Priority 1-100 (default: 50)
project_id	string	Assign to a project
is_pinned	boolean	Pin to the top

6.Habits

GET

/api/v1/habits

List habits with streaks and recent activity. Supports ?days and ?timezone.

POST

/api/v1/habits

Create a habit.

PATCH

/api/v1/habits/{habit_id}

Update a habit. Only send fields you want to change.

DELETE

/api/v1/habits/{habit_id}

Archive (soft-delete) a habit.

POST

/api/v1/habits/{habit_id}/complete

Mark a habit done for today, or for ?date. Safe to repeat.

DELETE

/api/v1/habits/{habit_id}/complete

Undo a completion for today, or for ?date. Safe to repeat.

7.Search and account

GET

/api/v1/search?q={query}

Full-text search across tasks, notes, and projects.

GET

/api/v1/me

Get the account that owns the API key. Use it to verify a key.

8.Response Format

All responses follow a consistent structure.

Single item

{
  "data": { "id": "...", "name": "...", ... }
}

List

{
  "data": [ ... ],
  "pagination": { "page": 1, "per_page": 100, "total": 42 }
}

Error

{
  "detail": {
    "error": { "message": "Task not found", "code": "not_found" },
    "status": 404
  }
}

9.CLI

The vectal CLI wraps the same API. It is the fastest way for an agent with a terminal to use Vectal.

npm install -g vectal          # or run it without installing: npx vectal
vectal login --key vec-YOUR_API_KEY
vectal task add "Ship pricing update" --due 2026-10-09
vectal task list --json        # raw API output for agents

Every command supports --help. The full command list is in the Agent Skill below.

10.Agent Skill

Vectal ships an official agent skill so AI agents (Claude Code, Cursor, and any tool that supports skills) can manage your tasks, projects, notes, and habits directly.

The skill is public at vectal.ai/skill. Install it into your agent's skills folder:

# Download the skill into your Claude skills directory
mkdir -p ~/.claude/skills/vectal-api
curl -sL https://www.vectal.ai/skill -o ~/.claude/skills/vectal-api/SKILL.md

Then set your API key as an environment variable:

export VECTAL_API_KEY="vec-YOUR_API_KEY"

Once installed, your agent will automatically use the Vectal API when you ask it to manage tasks, create projects, or take notes.