External API

The External API is designed for CRMs, chat bots, automation scripts, and custom integrations. It is separated from internal application client routes.

Base URL: https://api.planovik.pro/api/v1/developer.

API Key & Scopes

Create a personal key in Account Settings ➔ API. The full secret is displayed once. Always send it from your backend integration server:

curl 'https://api.planovik.pro/api/v1/developer/workspaces' \
  -H 'Authorization: Bearer plk_your_secret_key'

X-API-Key header is also supported, but Authorization: Bearer is the recommended standard contract.

Scope	Permission
workspaces:read	View accessible workspaces
projects:read	View projects (task lists)
projects:write	Create, edit, and delete projects
tasks:read	View tasks
tasks:write	Create, edit, and delete tasks

API keys can be restricted to specific workspaces and expiration dates. Revoking a key returns 401 Unauthorized for all requests.

Workflow Example

1. Fetch available workspaces.
2. Fetch projects in target workspace.
3. Create tasks.

# 1. Workspaces
curl 'https://api.planovik.pro/api/v1/developer/workspaces' \
  -H "Authorization: Bearer $PLANOVIK_TOKEN"

# 2. Projects in workspace
curl "https://api.planovik.pro/api/v1/developer/projects?workspaceId=$WORKSPACE_ID" \
  -H "Authorization: Bearer $PLANOVIK_TOKEN"

# 3. Create task (Idempotency-Key recommended for safe retries)
curl -X POST 'https://api.planovik.pro/api/v1/developer/tasks' \
  -H "Authorization: Bearer $PLANOVIK_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7d50e5d3-7f16-4f5a-bbd1-5ea88a8b9bf9' \
  -d "{\"projectId\":\"$PROJECT_ID\",\"content\":\"Call client\",\"priority\":2}"

Tasks Endpoints

GET /tasks?workspaceId=<uuid>&limit=50 returns data array and pagination.nextCursor. Max limit is 100.

POST /tasks requires projectId and content. Optional fields: description, priority (0–2), startAt, dueAt, labels, subtasks, assigneeId, recurringSettings.

PATCH /tasks/:id requires current version parameter. Concurrent modifications return 409 Conflict with server state.

DELETE /tasks/:id performs soft deletion.

Projects Endpoints

• GET /projects?workspaceId=<uuid>
• POST /projects — fields: workspaceId, name, optional color
• PATCH /projects/:id — version, name, color
• DELETE /projects/:id

Retries & Error Handling

Include an Idempotency-Key (up to 128 chars) for write operations. Retrying identical requests within 24 hours returns cached original response.

Status Code	Meaning
400	Invalid request payload
401	Key missing, revoked, or expired
403	Insufficient key permissions or workspace access
404	Resource not found
409	Version conflict or reused Idempotency-Key
429	Rate limit exceeded (check Retry-After header)

Rate limit: 600 requests per 15 minutes per API key.