One Tasks API Documentation

Introduction

https://api.onetasks.app/v1

Authentication

All API requests require authentication using an API key. Pass your key in the Authorization header as a Bearer token.

Authorization: Bearer ot_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

curl -H "Authorization: Bearer ot_live_xxxx" \
     -H "Content-Type: application/json" \
     https://api.onetasks.app/v1/projects

API Keys

Manage your API keys from the One Tasks admin panel (Admin → API → Keys). API keys are available from the Scale plan onwards.

Key Management Endpoints

{
  "name": "Integration Zapier",
  "scopes": ["projects:read", "tasks:write", "time:read"],
  "expires_at": "2027-01-01"  // optional
}

{
  "id": "key_abc123",
  "name": "Integration Zapier",
  "key": "ot_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "scopes": ["projects:read", "tasks:write", "time:read"],
  "created_at": "2026-03-13T10:00:00Z",
  "expires_at": "2027-01-01T00:00:00Z"
  // ⚠ The key is only shown once. Store it securely.
}

Available Scopes

Rate Limits

Requests are rate-limited per API key. Limits vary by plan.

Rate limit info is returned in every response header:

X-RateLimit-Limit:     60
X-RateLimit-Remaining: 58
X-RateLimit-Reset:     1710330060

Error Handling

The API uses conventional HTTP response codes. Errors follow a consistent structure.

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The title field is required.",
    "details": {
      "title": ["required"],
      "due_date": ["must_be_future_date"]
    },
    "request_id": "req_abc123xyz"
  }
}

Projects

Create and manage your workspaces and projects.

{
  "data": [
    {
      "id": "proj_abc123",
      "name": "One Tasks Landing",
      "description": "Rediseño web Q1 2026",
      "status": "active",
      "members_count": 4,
      "tasks_count": 17,
      "color": "#2563EB",
      "created_at": "2026-01-15T09:00:00Z"
    }
  ],
  "meta": { "total": 12, "page": 1, "per_page": 20 }
}

Tasks

Full CRUD for tasks, assignees, subtasks and comments.

{
  "title": "Diseñar pantalla de onboarding",
  "description": "Incluir los pasos 1-3 del flujo",
  "priority": "high",  // low | medium | high | urgent
  "status": "pending",  // pending | in_progress | review | done
  "due_date": "2026-04-01",
  "assignees": ["usr_abc", "usr_xyz"],
  "estimated_hours": 4,
  "tags": ["design", "frontend"]
}

Time Tracking

Log, update and query time entries by task, user or project.

Webhooks

Receive real-time HTTP notifications when events occur in your workspace.

{
  "event": "task.completed",
  "timestamp": "2026-03-13T15:30:00Z",
  "workspace_id": "ws_abc123",
  "data": {
    "task": {
      "id": "task_xyz",
      "title": "Diseñar pantalla de onboarding",
      "completed_by": "usr_abc",
      "project_id": "proj_abc123"
    }
  }
}

SDKs & Code Examples

Official SDKs and community libraries for popular languages.

import OneTasks from '@onetasks/sdk';

const client = new OneTasks({
  apiKey: 'ot_live_xxxxxxxxxxxx'
});

// Create a task
const task = await client.tasks.create({
  project_id: 'proj_abc123',
  title: 'Fix mobile nav bug',
  priority: 'high',
  assignees: ['usr_abc']
});

console.log(task.id); // task_xyz789

<?php
use OneTasks\Client;

$client = new Client('ot_live_xxxxxxxxxxxx');

// List projects
$projects = $client->projects()->list();

// Create a task
$task = $client->tasks()->create([
    'project_id' => 'proj_abc123',
    'title'      => 'Fix mobile nav bug',
    'priority'   => 'high',
]);

echo $task->id; // task_xyz789