# OrgOrg API v1 — Tasks — instructions for AI agents

This document describes the Tasks endpoints of the OrgOrg v1 REST API. Fetch it from https://orgorg.com/docs/api/v1/tasks/agents.md. The full API is documented at https://orgorg.com/docs/api/v1/agents.md.

## Basics

- Base URL: `https://orgorg.com`. All endpoint paths below are relative to it.
- Every request requires an `Authorization: Bearer <token>` header.
- `GET` endpoints take parameters in the URL query string. `POST` endpoints take a JSON body with a `Content-Type: application/json` header.
- All responses are JSON. A non-2xx status means the request failed; the body describes the problem.
- Endpoints are stable, but new response fields may be added without notice — ignore fields you do not recognize.

## Getting a token

Tokens are created by a signed-in user at https://orgorg.com/docs/credentials and inherit that user's permissions in their organization. If you do not have a token, ask your user to create one there. Verify a token works with:

```sh
curl "https://orgorg.com/api/v1/auth/test" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN"
```

A valid token returns `{ "ok": true, ... }`.

## Tasks

Manage tasks and the projects that hold them: create, update, complete, and delete tasks and projects. Human-readable docs: https://orgorg.com/docs/api/v1/tasks

### List projects

`GET /api/v1/projects/list`

List the projects visible to the token owner. Archived projects are hidden by default. Requires tasks:read (or :write).

Parameters:

- `includeArchived` (boolean, optional) — Set to true to include archived projects.
- `q` (string, optional) — Only projects whose name or description contains this text.

Example request:

```sh
curl -X GET "https://orgorg.com/api/v1/projects/list" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN"
```

Response shape:

```ts
{
  data: {
    id: string;
    name: string;
    description: string;
    ownerProfileId: number | null;
    personal: boolean;
    archived: boolean;
    createdAt: number;
    updatedAt: number;
  }[]
}
```

### Get project

`GET /api/v1/projects/get`

One project by id, with its tasks. Requires tasks:read (or :write).

Parameters:

- `id` (string, required) — Project id (from /api/v1/projects/list).

Example request:

```sh
curl -X GET "https://orgorg.com/api/v1/projects/get?id=PROJECT_ID" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN"
```

Response shape:

```ts
{
  data: {
    id: string;
    name: string;
    description: string;
    ownerProfileId: number | null;
    personal: boolean;
    archived: boolean;
    createdAt: number;
    updatedAt: number;
    tasks: Task[]; // same shape as /api/v1/tasks/get
  }
}
```

### Create project

`POST /api/v1/projects/create`

Create a project, owned by the token owner. Requires tasks:write.

Parameters:

- `name` (string, required) — Name of the project.
- `description` (string, optional) — What this project is about.

Example request:

```sh
curl -X POST "https://orgorg.com/api/v1/projects/create" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Website refresh",
    "description": "Everything for the marketing site relaunch"
  }'
```

Response shape:

```ts
{
  data: {
    id: string;
    name: string;
    description: string;
    ownerProfileId: number | null;
    personal: boolean;
    archived: boolean;
    createdAt: number;
    updatedAt: number;
  };
  created: true;
}
```

### Update project

`POST /api/v1/projects/update`

Update a project by id. Only the fields you send change. Set archived to true to archive, false to restore. Requires tasks:write.

Parameters:

- `id` (string, required) — Project id.
- `name` (string, optional) — New name.
- `description` (string, optional) — New description.
- `archived` (boolean, optional) — true archives the project; false restores it.

Example request:

```sh
curl -X POST "https://orgorg.com/api/v1/projects/update" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "PROJECT_ID",
    "archived": true
  }'
```

Response shape:

```ts
{
  data: {
    id: string;
    name: string;
    description: string;
    ownerProfileId: number | null;
    personal: boolean;
    archived: boolean;
    createdAt: number;
    updatedAt: number;
  };
  updated: true;
}
```

### Delete project

`POST /api/v1/projects/delete`

Delete a project by id. Its tasks are kept and become projectless. Prefer archiving (update with archived: true) when the history matters. Requires tasks:write.

Parameters:

- `id` (string, required) — Project id.

Example request:

```sh
curl -X POST "https://orgorg.com/api/v1/projects/delete" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "PROJECT_ID"
  }'
```

Response shape:

```ts
{
  data: { id: string };
  deleted: true;
}
```

### List tasks

`GET /api/v1/tasks/list`

Paginated tasks, newest-updated first. Returns all statuses by default; filter with the optional parameters. Requires tasks:read (or :write).

Parameters:

- `page` (number, optional) — 1-based page number. Defaults to 1.
- `pageSize` (number, optional) — Rows per page, 1-200. Defaults to 50.
- `projectId` (string, optional) — Only tasks in this project.
- `status` (`NotStarted` | `InProgress` | `Blocked` | `Complete` | `WontFix`, optional) — Only tasks with this status.
- `ownerProfileId` (number, optional) — Only tasks owned by this profile.
- `q` (string, optional) — Only tasks whose description or note contains this text.

Example request:

```sh
curl -X GET "https://orgorg.com/api/v1/tasks/list?status=InProgress" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN"
```

Response shape:

```ts
{
  data: {
    id: string;
    projectId: string | null;
    description: string;
    note: string;
    status: 'NotStarted' | 'InProgress' | 'Blocked' | 'Complete' | 'WontFix';
    complete: boolean;
    priority: 0 | 1 | 2 | 3 | null; // 0=P0 (highest)
    due: number | null;
    creatorProfileId: number | null;
    ownerProfileId: number | null;
    ccProfileIds: number[];
    createdAt: number;
    updatedAt: number;
  }[];
  page: number;
  pageSize: number;
  totalRows: number;
}
```

### Get task

`GET /api/v1/tasks/get`

One task by id. Requires tasks:read (or :write).

Parameters:

- `id` (string, required) — Task id.

Example request:

```sh
curl -X GET "https://orgorg.com/api/v1/tasks/get?id=TASK_ID" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN"
```

Response shape:

```ts
{
  data: {
    id: string;
    projectId: string | null;
    description: string;
    note: string;
    status: 'NotStarted' | 'InProgress' | 'Blocked' | 'Complete' | 'WontFix';
    complete: boolean;
    priority: 0 | 1 | 2 | 3 | null; // 0=P0 (highest)
    due: number | null;
    creatorProfileId: number | null;
    ownerProfileId: number | null;
    ccProfileIds: number[];
    createdAt: number;
    updatedAt: number;
  }
}
```

### Create task

`POST /api/v1/tasks/create`

Create a task, created by the token owner. An unowned task falls to its creator. The owner and each cc'd person are notified, exactly as in the app. Requires tasks:write.

Parameters:

- `description` (string, required) — What the task is.
- `projectId` (string, optional) — Project to create the task in.
- `note` (string, optional) — Free-form note.
- `status` (`NotStarted` | `InProgress` | `Blocked` | `Complete` | `WontFix`, optional) — Initial status. Defaults to NotStarted.
- `priority` (number, optional) — 0 (P0, highest) through 3 (P3).
- `due` (number, optional) — Due date, as a Unix timestamp in milliseconds.
- `creatorProfileId` (number, optional) — Profile id of the task creator (see /api/v1/profiles). Defaults to the token owner. History and notifications name this person.
- `ownerProfileId` (number, optional) — Profile id of the task owner (see /api/v1/profiles). Defaults to the creator.
- `ccProfileIds` (object, optional) — Profile ids to copy on the task, as a number array.

Example request:

```sh
curl -X POST "https://orgorg.com/api/v1/tasks/create" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Draft the launch announcement",
    "priority": 1
  }'
```

Response shape:

```ts
{
  data: {
    id: string;
    projectId: string | null;
    description: string;
    note: string;
    status: 'NotStarted' | 'InProgress' | 'Blocked' | 'Complete' | 'WontFix';
    complete: boolean;
    priority: 0 | 1 | 2 | 3 | null; // 0=P0 (highest)
    due: number | null;
    creatorProfileId: number | null;
    ownerProfileId: number | null;
    ccProfileIds: number[];
    createdAt: number;
    updatedAt: number;
  };
  created: true;
}
```

### Update task

`POST /api/v1/tasks/update`

Update a task by id. Only the fields you send change. Set status to Complete or WontFix to close a task; closing notifies the owner and each cc'd person. Requires tasks:write.

Parameters:

- `id` (string, required) — Task id.
- `description` (string, optional) — New description.
- `note` (string, optional) — New note.
- `projectId` (string, optional) — Move the task into this project.
- `status` (`NotStarted` | `InProgress` | `Blocked` | `Complete` | `WontFix`, optional) — New status.
- `priority` (number, optional) — 0 (P0, highest) through 3 (P3).
- `due` (number, optional) — New due date, as a Unix timestamp in milliseconds.
- `ownerProfileId` (number, optional) — Reassign the task to this profile.
- `ccProfileIds` (object, optional) — Full replacement cc list, as a number array. An empty array clears it.

Example request:

```sh
curl -X POST "https://orgorg.com/api/v1/tasks/update" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "TASK_ID",
    "status": "Complete"
  }'
```

Response shape:

```ts
{
  data: {
    id: string;
    projectId: string | null;
    description: string;
    note: string;
    status: 'NotStarted' | 'InProgress' | 'Blocked' | 'Complete' | 'WontFix';
    complete: boolean;
    priority: 0 | 1 | 2 | 3 | null; // 0=P0 (highest)
    due: number | null;
    creatorProfileId: number | null;
    ownerProfileId: number | null;
    ccProfileIds: number[];
    createdAt: number;
    updatedAt: number;
  };
  updated: true;
}
```

### Delete task

`POST /api/v1/tasks/delete`

Delete a task by id. This is permanent; to close a task instead, use tasks/update with status Complete or WontFix. Requires tasks:write.

Parameters:

- `id` (string, required) — Task id.

Example request:

```sh
curl -X POST "https://orgorg.com/api/v1/tasks/delete" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "TASK_ID"
  }'
```

Response shape:

```ts
{
  data: { id: string };
  deleted: true;
}
```