Documentació de l'API One Tasks

Introducció

https://api.onetasks.app/v1

Autenticació

Totes les peticions a l'API requereixen autenticació mitjançant una API Key. Passa la teva clau a la capçalera Authorization com 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

Gestiona les teves API Keys des del panell d'administrador de One Tasks (Admin → API → Claus). Les API Keys estan disponibles a partir del pla Scale.

Endpoints de Gestió de Claus

{
  "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.
}

Àmbits Disponibles

Rate Limits

Les peticions estan limitades per API Key. Els límits varien per pla.

La informació de rate limit es retorna a totes les capçaleres de resposta:

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

Gestió d'Errors

L'API utilitza codis de resposta HTTP convencionals. Els errors segueixen una estructura consistent.

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

Projectes

Crea i gestiona els teus espais de treball i projectes.

{
  "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 }
}

Tasques

CRUD complet per a tasques, assignats, subtasques i comentaris.

{
  "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"]
}

Registre de Temps

Registra, actualitza i consulta entrades de temps per tasca, usuari o projecte.

Webhooks

Rep notificacions HTTP en temps real quan es produeixen esdeveniments al teu espai de treball.

{
  "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 i Exemples de Codi

SDKs oficials i biblioteques de la comunitat per als llenguatges més populars.

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