REST API v1.0 Scale+

Documentación de la API One Tasks

Integra One Tasks en tus flujos de trabajo. Gestiona proyectos, tareas, usuarios y registro de tiempo de forma programática.

https://api.onetasks.app/v1
Estado API: Operativo

Introducción

La API de One Tasks es una interfaz RESTful que permite interactuar programáticamente con todas las funciones de la plataforma. Utiliza verbos HTTP estándar, devuelve respuestas JSON y usa API Keys para la autenticación.

REST

Verbos HTTP estándar (GET, POST, PUT, PATCH, DELETE)

JSON

Todas las respuestas en formato JSON con estructura consistente

HTTPS

Todas las peticiones deben usar TLS. HTTP no aceptado

URL Base 
https://api.onetasks.app/v1

Autenticación

Todas las solicitudes a la API requieren autenticación mediante una API Key. Pasa tu clave en el header Authorization como Bearer token.

Cabecera 
Authorization: Bearer ot_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
cURL 
curl -H "Authorization: Bearer ot_live_xxxx" \
     -H "Content-Type: application/json" \
     https://api.onetasks.app/v1/projects
Nunca expongas tu API Key en código del lado del cliente o repositorios públicos. Rota tus claves inmediatamente si sospechas que han sido comprometidas.

API Keys

Gestiona tus API Keys desde el panel de administrador de One Tasks (Admin → API → Claves). Las API Keys están disponibles desde el plan Scale.

ot_live_... Producción

text-emerald-400

ot_test_... Prueba

text-amber-400

Endpoints de Gestión de Claves

GET /api-keys
POST /api-keys
DELETE /api-keys/{id}
POST /api-keys — Crear Clave 
{
  "name": "Integration Zapier",
  "scopes": ["projects:read", "tasks:write", "time:read"],
  "expires_at": "2027-01-01"  // optional
}
201 Created 
{
  "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.
}

Ámbitos Disponibles

Scope Descripción
projects:read Read projects and their settings
projects:write Create and update projects
tasks:read Read tasks and their data
tasks:write Create, update and complete tasks
users:read Read workspace users
users:write Invite and manage users
time:read Read time entries
time:write Create and edit time entries
sprints:read Read sprints
sprints:write Create and manage sprints
webhooks:manage Create and manage webhooks
* Full access (all scopes)

Rate Limits

Las solicitudes están limitadas por API Key. Los límites varían según el plan.

Plan Peticiones/min Peticiones/día Burst
Scale 60 10,000 100
Enterprise 300 100,000 500

La info de rate limit se devuelve en cada cabecera de respuesta: 

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

Manejo de Errores

La API usa códigos de respuesta HTTP convencionales. Los errores siguen una estructura consistente.

200
OK
201
Created
400
Bad Request
401
Unauthorized
403
Forbidden
404
Not Found
422
Unprocessable
429
Rate Limited
422 Ejemplo de Respuesta de Error 
{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The title field is required.",
    "details": {
      "title": ["required"],
      "due_date": ["must_be_future_date"]
    },
    "request_id": "req_abc123xyz"
  }
}

Proyectos

Crea y gestiona tus espacios de trabajo y proyectos.

GET /v1/projects
POST /v1/projects
GET /v1/projects/{id}
PUT /v1/projects/{id}
DELETE /v1/projects/{id}
GET /v1/projects/{id}/members
POST /v1/projects/{id}/members
GET /v1/projects — Ejemplo de Respuesta 
{
  "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 }
}

Tareas

CRUD completo para tareas, asignados, subtareas y comentarios.

GET /v1/projects/{id}/tasks
POST /v1/projects/{id}/tasks
GET /v1/tasks/{id}
PATCH /v1/tasks/{id}
DELETE /v1/tasks/{id}
POST /v1/tasks/{id}/assignees
POST /v1/tasks/{id}/complete
GET /v1/tasks/{id}/subtasks
POST /v1/tasks/{id}/subtasks
GET /v1/tasks/{id}/comments
POST /v1/tasks/{id}/comments
POST /v1/projects/{id}/tasks — Cuerpo de petición 
{
  "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"]
}

Registro de Tiempo

Registra, actualiza y consulta entradas de tiempo por tarea, usuario o proyecto.

GET /v1/time-entries
POST /v1/time-entries
PATCH /v1/time-entries/{id}
DELETE /v1/time-entries/{id}
POST /v1/tasks/{id}/timer/start
POST /v1/tasks/{id}/timer/stop
GET /v1/reports/time

Webhooks

Recibe notificaciones HTTP en tiempo real cuando ocurran eventos en tu espacio de trabajo.

task.created
task.updated
task.completed
time_entry.created
project.archived
sprint.started
Ejemplo de Payload Webhook 
{
  "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 y Ejemplos de Código

SDKs oficiales y librerías de la comunidad para los lenguajes más populares.

JavaScript / Node.js
npm install @onetasks/sdk
PHP
composer require onetasks/sdk
Python
pip install onetasks
JavaScript / Node.js 
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 
<?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
One Tasks

© 2026 One Tasks · Nex Group Agency

← Volver al inicio Soporte API